Sonde：本地代码图谱引擎，让 AI Agent 少调用、少消耗

Sonde 是一款面向 AI 编程 Agent 的本地代码上下文引擎。它将 TypeScript、Python 或 Swift 仓库索引为 SQLite 中的符号级图谱，并对外暴露三个 MCP 工具——find_symbols、query_graph 与 get_impact_radius——让 Agent 能够一次性回答「谁在调用它」「改它会破坏哪些调用」「哪些测试与之相关」，而不必反复检索。工具完全本地运行，不需要账号或托管服务。

基准对比：在真实仓库上跑出的数字

Sonde 的核心主张不是「找到 grep 找不到的东西」，而是「用更少的代价给出相同的答案，且不超预算」。在一个 19,409 行的真实生产 TypeScript 仓库中，作者把 Sonde 与传统 Agentic 搜索循环做了对照：

• 结构化任务召回率：Sonde 与对照均为 1.00；
• 工具调用次数：Sonde 1.0 次，对照 8.0 次；
• 上下文 Token：Sonde 1,262，对照 3,621；
• 端到端延迟：Sonde 263 毫秒，对照 38,602 毫秒；
• 超预算的运行比例：Sonde 0/6，对照 3/6。

即在保持召回不变的前提下，Sonde 大约只用 1/3 的上下文、1/8 的调用次数和 1/147 的耗时；其打包器按调用方预算截断输出，因此天然不会超出 token 上限。数字可通过 npm run bench:fixture 与 npm run bench:large 复现。

它的边界：不擅长「行文类」问题

在没有共同词汇、需要语义理解的行为型查询上（如「重试退避策略是在哪里决定的」），Sonde 的得分是 0.00。作者承认已尝试并测量过本地语义检索，但并未解决问题，因此并未对此能力做承诺。如果工作负载以此类查询为主，作者建议现阶段仍使用 Agentic 搜索循环。

安装与使用

基本流程为：

• npm install -g @cheppulabs/sonde；
• 在目标项目目录下执行 sonde init，会把仓库索引入库，并把 Sonde 作为 MCP 服务器写入项目的 .mcp.json（遇到与现有 Sonde 条目不一致时会主动停下询问，不会静默覆盖）。

对 Python 仓库需要使用 sonde init --resolve，因为默认的 tree-sitter 层级未能通过该项目的结构化查询放置门禁。

边来源分级与架构文档

Sonde 为图谱中每条边打上来源标签，便于评估可靠性：

• COMPILER：由捆绑的类型检查器（TypeScript 用 tsc，Python 用 pyright）精确解析，需要 --resolve 开启；
• LEXICAL：通过 import 绑定或词法作用域解析；
• HEURISTIC：成员访问等需要类型推断才能确定的关系；
• EXTERNAL：目标位于被索引仓库之外；
• UNRESOLVED：确实无法定位，并附原因。

Sonde 不会虚构边：无法解析的引用只能落到 EXTERNAL 或 UNRESOLVED，不会「猜」一个目标，也不会悄悄略过。

此外，sonde doc 会基于图谱生成 ARCHITECTURE.md，描述模块、依赖关系与对外暴露；当代码未变化时重新生成结果字节一致，不会污染 diff；CI 中可用 sonde doc --check 校验是否过期。它明确不绘制没有证据的依赖，不假装图谱完整，并在头部标注所描述的 commit、不一致时给出警告。

精度：与 TypeScript 编译器对账

由于 COMPILER 边直接来自 tsc 自身，再用 tsc 做对照并非独立验证。因此 Sonde 把精度对账聚焦在「零配置」的 tree-sitter 路径上：在一个固定的测试夹具上，把 tree-sitter 的解析结果与 tsc 的解析结果对比，数字（包括不好看的）一并公开在规范 §12 中。需要 tcs 精度时，使用 --resolve 启用 COMPILER 层级即可。