CodeGraph 使用指南:让 AI 编程助手看懂代码库

1. CodeGraph 是什么

CodeGraph 是一款本地优先的代码智能工具。它用 tree-sitter 解析代码库，把符号、关系和文件存入本地 SQLite，再通过 MCP、CLI 和 TypeScript API 暴露为可查询的知识图谱。

简单说，它把「在代码里到处 grep、glob、Read」这件事提前做成索引，让 AI 助手用几次查询就能回答结构性问题。

项目已发布到 npm：@colbymchenry/codegraph，支持 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI 等主流 AI 编程工具。

项目仓库：https://github.com/colbymchenry/codegraph
官方文档：https://colbymchenry.github.io/codegraph/

2. 为什么需要它

AI 编程助手探索陌生代码库时，大部分时间花在发现上：先找文件，再读文件，再拼出调用关系。这个过程会产生大量 grep / glob / Read 调用，消耗 token，也拖慢响应。

CodeGraph 的思路是：在 agent 提问之前，结构已经建好。符号关系、调用图、继承链、路由绑定等信息都在索引里，查询是亚毫秒级的。

没有 CodeGraph，agent 要自己「扫文件」；有了 CodeGraph，agent 直接「查图谱」。

3. 有/无 CodeGraph 对比

3.1 同一个问题，两条路径

假设你问 agent：「请求是怎么走到数据库的？」

不使用 CodeGraph：

提问 → grep 关键词 → glob 找目录 → Read 多个文件     → 再 grep 调用关系 → 再 Read → 可能 spawn 子 agent 继续扫     → 拼出答案（10～20+ 次工具调用，大量 token）

使用 CodeGraph：

提问 → codegraph_explore（一次返回相关符号源码 + 调用路径）     → 必要时再 codegraph_node 深挖（共 1～4 次调用，通常 0 次 Read）     → 给出答案

维度	不使用 CodeGraph	使用 CodeGraph
找符号定义	grep 文本，易漏重名、误匹配	FTS5 符号搜索，带类型、位置、签名
调用关系	多次 grep + Read 手工追踪	callers / callees / explore 路径一键展开
影响分析	几乎无法系统做	impact 计算修改的传播半径
跨文件流程	容易在语言/模块边界断链	框架路由 + 动态派发合成边桥接
大文件	整文件 Read，token 爆炸	只返回相关符号片段
数据隐私	无额外依赖	100% 本地 SQLite，不出机器
首次成本	零	需 `codegraph init`建索引（一次性）

3.2 量化基准

测试方法：Claude Code 无头模式，同一架构问题，有/无 CodeGraph MCP，各跑 4 次取中位数。覆盖 7 个开源仓库、7 种语言，规模从 ~110 文件到 ~10k 文件。

汇总（中位数平均）：

指标	改善
成本	约 16% 更低
Token	约 47% 更少
耗时	约 22% 更快
工具调用	约 58% 更少
文件读取	接近 0（无 CodeGraph 时 4～9 次/题）

分仓库对比：

代码库	语言 · 规模	成本	Token	耗时	工具调用
VS Code	TS · ~10k	↓18%	↓64%	↓11%	↓81%
Excalidraw	TS · ~640	持平	↓25%	↓27%	↓40%
Django	Python · ~3k	↓8%	↓60%	↓13%	↓77%
Tokio	Rust · ~790	持平	↓38%	↓18%	↓57%
OkHttp	Java · ~645	↓25%	↓54%	↓31%	↓50%
Gin	Go · ~110	↓19%	↓23%	↓24%	↓44%
Alamofire	Swift · ~110	↓40%	↓64%	↓33%	↓58%

规律很明显：仓库越大、结构性问题越复杂，无 CodeGraph 的 discovery 开销越夸张。

3.3 什么时候不用也行

场景	说明
极小项目（几个文件）	agent 直接 Read 全文比建索引更快
纯文本搜索	找日志字符串、注释、配置项，grep 更合适
非源码文件	README、`.env`、`yaml`配置，CodeGraph 不索引
编译/类型正确性	仍靠编译器、linter、测试
完全动态反射	运行时 eval、重度反射，图谱会标注未覆盖
agent 不用 CodeGraph 工具	装了但 agent 仍走 grep 路径，变成纯开销

4. 工作原理

CodeGraph 把源码变成可查询图谱，经历四个阶段：

文件 → 提取（tree-sitter AST）→ 存储（SQLite + FTS5）              ↓        解析（import、名称匹配、框架模式）              ↓        图查询（callers、callees、impact）              ↓        上下文构建（面向 AI 的 markdown/JSON）

4.1 提取

tree-sitter 把源码解析成 AST，各语言的提取器从中抽取：

节点（Nodes）：函数、类、方法、类型、路由、组件等
边（Edges）：调用、导入、继承、实现、引用等

解析在独立 worker 线程中运行。提取结果来自 AST，不是 LLM 摘要，因此可复现、可信赖。

4.2 存储

所有数据写入项目目录下的 .codegraph/codegraph.db，支持 FTS5 全文搜索。优先使用原生 better-sqlite3，不可用时透明回退到 WASM 后端。

4.3 解析

提取之后，还要把「引用」连到「定义」：

函数调用 → 目标定义
import → 源文件
类继承、接口实现
框架路由（Django urls.py、Express app.get、Spring @GetMapping等）

对于静态解析跟不上的动态派发边界（回调、观察者、React setState→render、JSX 子组件等），CodeGraph 会用合成边桥接，并标注 provenance: 'heuristic'，让 agent 知道这条边是如何推断出来的。

4.4 自动同步

MCP 服务启动后，会用操作系统原生文件事件监听项目变更，防抖后增量更新索引。默认无需手动 sync，图谱会随编码保持新鲜。

4.5 图谱能回答什么

问题类型	对应能力
X 在哪里定义？	符号搜索（FTS5）
谁调用了 Y？	callers 遍历
Y 调用了什么？	callees / node 源码
改 Z 会影响什么？	impact 影响半径
X 怎么走到 Y？	explore 中的调用路径
这个 URL 对应哪个 handler？	框架路由解析

节点类型包括 file、module、class、function、method、interface、route、component等 20+ 种；边类型包括 contains、calls、imports、extends、implements、references、returns等。

5. 快速上手

5.1 安装 CLI

无需 Node.js（自带运行时）：

# macOS / Linuxcurl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh# Windows (PowerShell)irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

已有 Node 也可用：

npm i -g @colbymchenry/codegraph

安装后新开一个终端，确保 codegraph命令可用。

5.2 接入 AI 工具

codegraph install

安装器会自动检测已安装的 agent（Claude Code、Cursor、Codex 等），把 CodeGraph MCP 服务写入对应配置。只装 CLI 还不够，这一步是把 CodeGraph 真正连上 agent 的关键。

非交互式安装：

codegraph install --yes

┌  CodeGraph v1.0.1│◆  Claude Code: Updated ~/.claude.json│◆  Claude Code: Updated ~/.claude/settings.json│◆  Claude Code: Created ~/.claude/CLAUDE.md│◆  Cursor: Updated ~/.cursor/mcp.json│●  Cursor: Restart Cursor for MCP changes to take effect.│◆  Codex CLI: Updated ~/.codex/config.toml│◆  Codex CLI: Created ~/.codex/AGENTS.md│◇  Quick start ───────╮│                     ││  cd your-project    ││  codegraph init -i  ││                     │├─────────────────────╯codegraph collects anonymous usage stats (no code, paths, or names) — "codegraph telemetry off" or CODEGRAPH_TELEMETRY=0 disables. Details: https://github.com/colbymchenry/codegraph/blob/main/TELEMETRY.md│└  Done! Restart your agents to use CodeGraph.

5.3 初始化项目

cd your-projectcodegraph init

┌  Initializing CodeGraph│◆  Initialized in /Users/shaowenchen/Code/github/your-project││  ◆ Scanning files — 249 found│  ◆ Parsing code — done│  ◆ Resolving refs — done│◆  Indexed 249 files│●  4,076 nodes, 16,629 edges in 2.1s│└  Done

会在项目下创建 .codegraph/并构建完整索引。之后文件变更会自动同步，不用重复 init。

5.4 重启 agent

重启 Cursor / Claude Code 等，让 MCP 配置生效。当项目存在 .codegraph/目录时，agent 会自动获得 CodeGraph 工具。

5.5 卸载

codegraph uninstall          # 从所有 agent 移除 MCP 配置codegraph uninit             # 删除单个项目的 .codegraph/ 索引

6. MCP 工具说明

CodeGraph 通过 MCP 暴露以下工具：

工具	用途
`codegraph_explore`	主力工具，一次返回多个相关符号的源码、调用路径、影响范围
`codegraph_search`	按名称查找符号
`codegraph_callers`	查找所有调用点（含回调注册）
`codegraph_callees`	查找被调用方
`codegraph_impact`	分析修改某符号的影响半径
`codegraph_node`	获取单个符号详情、完整源码、调用链
`codegraph_files`	查看已索引的文件结构
`codegraph_status`	检查索引健康状态

按意图选工具：

「X 是怎么工作的？」「X 怎么走到 Y？」→ codegraph_explore（通常一次就够）
「X 在哪？」→ codegraph_search
「谁调用了这个函数？」「改了会坏什么？」→ codegraph_callers
「这个函数内部调了什么？」→ codegraph_node（includeCode: true）
读某个源文件 → codegraph_node传 file路径（等同 Read，还带依赖信息）

7. 使用建议

结构性问题直接用 CodeGraph，不要再用 grep + Read 重建索引已有的信息
信任 AST 解析结果，不必用 grep 二次验证
编辑后注意陈旧提示——若响应开头有 ⚠️ Some files referenced below were edited since the last index sync…，列出的文件需用 Read 确认最新内容
未索引的项目：CodeGraph 会告知 inactive，需用户自行运行 codegraph init

几个设计原则值得了解：

本地优先：索引存在 .codegraph/的 SQLite 里，不需要 API Key，不依赖外部服务
确定性优于猜测：图谱来自 tree-sitter AST，合成边会明确标注为启发式推断
一次调用返回足够上下文：codegraph_explore的设计目标是一次调用就给出答案
框架感知：支持 17+ Web 框架的路由解析（Django、Flask、FastAPI、Express、Spring、Gin、Rails 等）

8. CLI 常用命令

codegraph init          # 初始化并构建索引codegraph status        # 查看索引状态、待同步文件codegraph sync          # 手动同步（通常不需要）codegraph query ...     # 命令行查询codegraph upgrade       # 检查并升级codegraph serve --mcp   # 手动启动 MCP 服务（agent 会自动拉起）

9. 小结

CodeGraph 把 AI 编程助手从「在文件海洋里捞针」，变成「直接查询一张预先建好的代码知识图谱」。

对比：无 CodeGraph 时 agent 靠 grep/Read 做发现（10～20+ 次调用）；有 CodeGraph 时通常 1～4 次查询、接近零文件读取
原理：tree-sitter 解析 → SQLite 存储 → 引用解析 + 框架感知 → MCP 暴露给 agent
使用：安装 CLI → codegraph install接入 agent → 项目里 codegraph init→ 重启 agent

如果你已经在用 Cursor 或 Claude Code 写代码，花两分钟跑一遍安装流程，就能让 agent 在结构性问题上明显更高效。