codegraph

codegraph

将本地代码图作为 8 个 MCP 工具提供。通过 O(1) SQLite 查找和 FTS5 搜索加快代码探索，减少为了解熟悉代码库而反复执行 grep + Read 的次数。

它不能替代 grep。Codegraph 是基于 tree-sitter 的调用图近似结果，不是编译器级别的调用图：它速度快、消耗的 token 少，但不健全（会漏报）。将它作为熟悉代码结构和遍历代码的加速工具，并继续以 grep 作为确保完整性的事实来源。请参阅下文的 健全性与限制——这一区别至关重要，并非脚注。

适用场景

• 结构不直观的棕地代码库
• 任务涉及：“哪里用了 X”“如果更改 Y 会有什么影响”“追踪从 A 到 B 的流程”
• 长时间运行的会话——冷启动成本可由多次查询分摊

不适用场景

• 修改单个文件或进行简单查找
• 会话可能短于冷启动所需时间（每个代码库的数据请参阅 references/spike.md）
• 代码库尚未初始化、没有缓存的 .codegraph/，且会话时间较短

健全性与限制——信任结果前请先阅读

Codegraph 基于 tree-sitter 构建，而非编译器，因此其调用关系和引用关系边只是近似结果。已确认它会以三种方式出错。由此得出的总原则是：

grep 是确保完整性的事实来源。Codegraph 是加速熟悉代码结构和遍历代码的工具。切勿颠倒二者的作用。

不对称性正是关键：重构时，漏报很危险（漏掉一个调用方，导致发布版本出错）；误报则只是令人烦恼（看一眼后忽略即可）。Codegraph 会漏报；grep 不会。因此，Codegraph 可以提出候选项并排序，但只要答案必须完整，就应由 grep 确认。

三种失效模式（在一个约有 580 个 Rust 和 TS 文件的代码库中测得）：

1. 边不健全 → 漏报。 当无法仅凭语法解析接收者类型时（对局部变量、泛型、trait 对象的调用），callers/callees/impact 会漏掉实际调用位置。测量结果：一个方法实际有 8 个调用方，结果只返回 2 个——漏掉的 5 个调用方位于 local.method() 和泛型分派位置，且没有警告。对于唯一的自由函数和直接调用，结果准确（验证结果为 1/1、2/2）；对于方法分派，结果不可靠。
2. 名称解析模糊，且无法区分重载。 仅提供名称的查询会进行前缀匹配（查询 useWorkspace 时，返回了 useWorkspacesQuery——这是一个不同的符号），还会混淆重载（execute 有 19 个定义，却返回了 sqlx 的 .execute() 数据库调用，而不是 trait 方法）。对于定义不止一个的名称，应改用 codegraph_node 并指定具体的符号 ID；仅提供名称的 callers/callees 结果无法归属到具体定义。
3. 索引滞后于磁盘。 在运行 codegraph sync（约 0.3s）之前，CLI 查不到任何内容；MCP 文件监视器会将延迟缩短到约 1–2s。编辑后，索引会立即出错——在索引赶上之前，grep/Read 才是事实依据。

决策矩阵

任务	工具	原因
了解方向／“解释子系统 X”／首次调研	codegraph explore	一次调用即可获得排序结果和原文——比 grep+Read 占用的上下文少得多
查找名称唯一的自由函数的调用方	codegraph callers（可信任）	对名称唯一的函数和直接调用能准确匹配
修改签名／重命名前查找所有调用方	grep 为准；仅用 codegraph 预先排序	codegraph 在此场景下并不可靠——完整性不能依赖它
涉及重载名称（execute、lookup、run、new）的任何操作	grep，或对特定 id 使用 codegraph node	仅凭名称查询 codegraph 会将结果混在一起／无法确定地漏掉部分结果
评估核心类型的影响	用 codegraph impact --depth 1 预先排序，再用 grep 确认	默认深度 2 会夸大结果（测试函数 + 每个文件一个 file 条目），且不会按深度排序
刚编辑过的代码	grep（或先运行 codegraph sync）	重新索引前，索引数据会过时
Trait 分派／泛型调用点	grep + 阅读代码	两者都不够可靠；codegraph 会静默漏掉，grep 至少会显示文本

**工作流：**先用 explore 绘制概览，再用 callers／impact 确定方向——但只要答案必须完整（例如重命名、“是不是一个都没漏？”），就用 grep 确认，并将 codegraph 与 grep 的任何差异视为“codegraph 漏掉了”，而不是“grep 匹配过多”。

前置条件

• PATH 中有 Node 18+
• 项目包含 .codegraph/（如果没有，运行 codegraph init）
• 对于云端会话：根据目标仓库的 references/spike.md 验证冷启动开销

文件

• references/install.md — 本地／Claude Code Cloud／devcontainer 的安装说明
• references/usage.md — 何时使用 8 个 MCP 工具中的哪一个，以及主会话与子 Agent 的使用规则
• references/spike.md — 冷启动测量流程；每个新的目标仓库都要运行一次，之后才能在云端会话中依赖 codegraph

已知集成目标

已在本地测量冷启动（Node 22，4 核）。云端冷启动仍待测量——在云端会话中依赖这些数据前，请重新运行 references/spike.md。

仓库	已索引文件	节点／边	数据库大小	冷启动初始化 + 索引	查询耗时
onsager-ai/onsager	578（rust + tsx/ts）	8.6k / 20k	24 MB	12s	~0.9s
crawlab-team/crawlab	644（go）	6.8k / 15k	11 MB	6s	~0.9s
codervisor/leanspec	695（tsx/rust/ts）	8.9k / 21k	23 MB	10s	~0.9s

每次查询的耗时主要由 Node 启动导致——SQLite 操作本身只需几毫秒。对于此规模的仓库，包含一次性 npx install 的端到端冷启动约为 13–19s。