local-knowledge

用途

Local Knowledge 用于检索开发者本地的个人笔记、文档或本地知识库，为 AI 编程智能体提供与具体上下文相关的信息。当用户提到“我的笔记”“我的文档”，询问“我通常怎么做 X”“我们 Y 的模式是什么”，或引用此前记录过的解决方案和收藏资源时，都可以使用该技能。常见的触发说法包括：检查我关于……的笔记、在我的文档中搜索……、我关于……有什么、找到我关于……的笔记，以及各类领域特定问题（如 Rust 异步、前端模式）。

主要能力

该技能通过 Terraphim 的“基于角色的 haystack”来搜索本地知识。不同角色可访问不同的知识域：

Terraphim Engineer：架构、系统设计，数据源为本地文档加知识图谱。
Rust Engineer：Rust 模式、异步、WASM，数据源为本地笔记加 Query.rs API。
Frontend Engineer：JavaScript、TypeScript、React，数据源为 GrepApp（GitHub 代码搜索）。

搜索支持以下能力：基础搜索（使用当前角色）、指定角色搜索、限制结果数量、语义搜索（使用知识图谱）以及基于概念的搜索。搜索结果通常包含 title（文档/笔记标题）、url（文件路径或来源 URL）、body（内容摘录）、description（若启用 LLM 摘要则有）以及 rank（相关性评分）。

使用方式

首先构建带 REPL 功能的 terraphim-agent：

cd /path/to/terraphim-ai
cargo build -p terraphim_agent --features repl-full --release

启动 REPL：

./target/release/terraphim-agent

在 REPL 中可执行的主要命令：

# 列出可用角色
/role list

# 切换角色
/role select rust-engineer

# 查看当前角色
/role current

# 基础搜索（使用当前角色）
/search "query string"

# 指定角色搜索
/search "async patterns" --role rust-engineer

# 限制结果数量
/search "error handling" --limit 5

# 语义搜索（使用知识图谱）
/search "error handling" --semantic

# 基于概念的搜索
/search "error handling" --concepts

# 查看知识图谱词条
/graph

# 查看前 K 个词条
/graph --top-k 20

智能体的搜索模式包括：针对特定领域，先选择合适角色再搜索；对一般问题，使用带 expanded_docs 的 Terraphim Engineer 角色；需要前端代码示例时，使用 GrepApp 集成。

配置

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

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

带本地笔记的 Rust Engineer 配置示例：

{
  "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 配置示例：

{
  "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" }
      }
    ]
  }
}

添加自己的笔记：创建笔记目录（例如 ~/notes/rust/），加入 markdown 知识文件，在角色配置中把该目录作为 Ripgrep haystack 加入，可选地创建知识图谱以进行语义词条扩展。

知识图谱格式

知识图谱文件用于语义词条扩展，格式为：

# term_name

可选词条描述。

synonyms:: synonym1, synonym2, synonym3

Rust 异步词条示例：

# async_iterator

Rust 中使用 Stream trait 与 async/await 的异步迭代器。

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

错误处理

当 terraphim-agent 不可用或执行失败时，支持优雅降级：继续运行但不做本地搜索；提示用户“Local knowledge search unavailable, using general knowledge”；回退到网络搜索或内置知识。示例检测方式：

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

适用场景

需要检索个人笔记与文档中的领域模式、架构说明或此前记录过的解决方案时使用；适合 Rust、前端等有明确角色划分的开发场景。

限制

搜索结果取决于本地 haystack 路径是否存在且包含 .md 文件；搜索过慢时可减少 --limit 或使用更具体的查询；知识图谱若未加载，需检查配置中的路径与 markdown 格式；若找不到 terraphim-agent，需使用 cargo build -p terraphim_agent --features repl-full --release 构建。相关技能包括 terraphim-hooks（使用知识图谱做文本替换）、session-search（搜索 AI 编程会话历史）和 rust-development（Rust 特定模式）。