local-knowledge

本地知识搜索

当你需要在开发者的个人笔记、文档或本地知识库中搜索特定上下文信息时，使用此技能。

概览

Terraphim 支持 AI 编码 Agent 通过基于角色的知识源搜索本地知识。不同角色可以访问不同的知识领域：

角色	知识领域	知识源
Terraphim 工程师	架构、系统设计	本地文档 + 知识图谱
Rust 工程师	Rust 模式、异步、WASM	本地笔记 + Query.rs API
前端工程师	JavaScript、TypeScript、React	GrepApp（GitHub 代码搜索）

何时使用此技能

当用户执行以下操作时，搜索本地知识：

• 询问个人笔记中的主题（“在我的笔记里”“我的文档”）
• 需要此前记录过的领域特定模式
• 询问“我通常如何做 X”或“我们处理 Y 的模式是什么”
• 提及之前的解决方案或已收藏的资源

触发短语：

• “查看我关于……的笔记”
• “搜索我的文档，查找……”
• “我有哪些关于……的内容”
• “找出我关于……的笔记”
• 任何领域特定问题（Rust 异步、前端模式等）

架构

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code Agent                         │
│  Uses /search and /role commands via terraphim-agent REPL   │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    terraphim-agent REPL                      │
│  /search "query" --role rust-engineer --limit 10            │
└───────────────────────────┬─────────────────────────────────┘
                            │
          ┌─────────────────┼─────────────────┐
          ▼                 ▼                 ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Terraphim Eng   │ │ Rust Engineer   │ │ Frontend Eng    │
│                 │ │                 │ │                 │
│ • Local docs    │ │ • Rust notes    │ │ • GrepApp JS    │
│ • expanded_docs │ │ • Query.rs      │ │ • GrepApp TS    │
│ • Knowledge KG  │ │ • Auto-gen KG   │ │                 │
└─────────────────┘ └─────────────────┘ └─────────────────┘

面向用户

快速入门

# Build terraphim-agent with REPL features
cd /path/to/terraphim-ai
cargo build -p terraphim_agent --features repl-full --release

# Start the REPL
./target/release/terraphim-agent

# In REPL: List available roles
/role list

# Switch to Rust Engineer role
/role select rust-engineer

# Search your notes
/search "async iterator patterns" --limit 5

角色配置

角色定义在 terraphim_server/default/ 下的 JSON 配置文件中：

{
  "roles": {
    "Rust Engineer": {
      "relevance_function": "title-scorer",
      "haystacks": [
        {
          "location": "/path/to/your/notes",
          "service": "Ripgrep",
          "extra_parameters": { "glob": "*rust*.md" }
        }
      ]
    }
  }
}

添加自己的笔记

1. 创建笔记目录（例如，~/notes/rust/）
2. 添加包含知识内容的 Markdown 文件
3. 更新角色配置，将该目录作为 Ripgrep 知识源
4. 可选：创建知识图谱，以扩展语义术语

面向 AI Agent

检测 Terraphim 功能

检查 terraphim-agent 是否可用：

# Find the agent binary
if command -v terraphim-agent >/dev/null 2>&1; then
    AGENT="terraphim-agent"
elif [ -x "./target/release/terraphim-agent" ]; then
    AGENT="./target/release/terraphim-agent"
elif [ -x "$HOME/projects/terraphim/terraphim-ai/target/release/terraphim-agent" ]; then
    AGENT="$HOME/projects/terraphim/terraphim-ai/target/release/terraphim-agent"
fi

REPL 命令参考

搜索命令：

# Basic search (uses current role)
/search "query string"

# Search with specific role
/search "async patterns" --role rust-engineer

# Limit results
/search "error handling" --limit 5

# Semantic search (uses knowledge graph)
/search "error handling" --semantic

# Concept-based search
/search "error handling" --concepts

角色命令：

# List available roles
/role list

# Select a role
/role select rust-engineer

# Show current role
/role current

图谱命令：

# Show knowledge graph terms
/graph

# Show top K terms
/graph --top-k 20

AI Agent 搜索模式

模式 1：领域特定搜索

当用户询问特定领域时，先选择相应的角色：

# User asks about Rust async
/role select rust-engineer
/search "async iterator" --limit 5

模式 2：广泛知识搜索

对于一般问题，使用 Terraphim 工程师角色并启用 expanded_docs：

/role select terraphim-engineer
/search "atomic data server configuration"

模式 3：代码示例

对于前端代码示例，使用 GrepApp 集成：

/role select frontend-engineer
/search "useState useEffect pattern"

解读结果

搜索结果包括：

• title：文档/笔记标题
• url：文件路径或来源 URL
• body：内容摘录
• description：摘要（如果启用了 LLM 摘要）
• rank：相关性分数

输出示例：

Results for "async iterator":

1. [rust-matching-iterators.md]
   Path: /Users/alex/notes/rust-matching-iterators.md
   Async iterator over AWS S3 pagination using State enum...

2. [rust-python-extension.md]
   Path: /Users/alex/notes/rust-python-extension.md
   PyO3/Maturin async patterns for Python extensions...

错误处理

如果 terraphim-agent 不可用或运行失败：

1. 平稳降级：继续操作，但不使用本地搜索
2. 通知用户：“本地知识搜索不可用，将使用通用知识”
3. 回退方案：使用网络搜索或内置知识

# Check if search succeeded
if ! /search "query" 2>/dev/null; then
    echo "Local search unavailable, falling back to general knowledge"
fi

知识图谱格式

知识图谱文件支持语义术语扩展：

# term_name

Optional description of the term.

synonyms:: synonym1, synonym2, synonym3

示例 - Rust 异步术语：

# async_iterator

Async iterators in Rust using Stream trait and async/await.

synonyms:: Stream, AsyncIterator, futures::Stream, tokio::stream

配置示例

配置本地笔记的 Rust 工程师

{
  "Rust Engineer": {
    "shortname": "rust-engineer",
    "relevance_function": "terraphim-graph",
    "kg": {
      "knowledge_graph_local": {
        "input_type": "markdown",
        "path": "docs/src/kg/rust_notes_kg"
      }
    },
    "haystacks": [
      {
        "location": "/Users/alex/synced/expanded_docs",
        "service": "Ripgrep",
        "extra_parameters": { "glob": "*rust*.md" }
      },
      {
        "location": "https://query.rs",
        "service": "QueryRs"
      }
    ]
  }
}

配置 GrepApp 的前端工程师

{
  "Frontend Engineer": {
    "shortname": "frontend-engineer",
    "relevance_function": "title-scorer",
    "haystacks": [
      {
        "location": "https://grep.app",
        "service": "GrepApp",
        "extra_parameters": { "language": "JavaScript" }
      },
      {
        "location": "https://grep.app",
        "service": "GrepApp",
        "extra_parameters": { "language": "TypeScript" }
      }
    ]
  }
}

故障排除

问题	解决方案
未返回结果	检查知识源路径是否存在且包含 .md 文件
当前角色错误	使用 /role select <name> 切换
搜索太慢	减小 --limit 或使用更具体的查询
KG 未加载	检查配置中的路径和 Markdown 格式
未找到 Agent	使用 cargo build -p terraphim_agent --features repl-full --release 构建

相关技能

• terraphim-hooks - 使用知识图谱进行文本替换
• session-search - 搜索 AI 编码会话历史
• rust-development - Rust 专用模式