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 编程工具。
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、Expressapp.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（自带运行时）：
| |
已有 Node 也可用：
| |
安装后新开一个终端，确保 codegraph 命令可用。
5.2 接入 AI 工具
| |
安装器会自动检测已安装的 agent（Claude Code、Cursor、Codex 等），把 CodeGraph MCP 服务写入对应配置。只装 CLI 还不够，这一步是把 CodeGraph 真正连上 agent 的关键。
非交互式安装：
| |
| |
5.3 初始化项目
| |
| |
会在项目下创建 .codegraph/ 并构建完整索引。之后文件变更会自动同步，不用重复 init。
5.4 重启 agent
重启 Cursor / Claude Code 等，让 MCP 配置生效。当项目存在 .codegraph/ 目录时，agent 会自动获得 CodeGraph 工具。
5.5 卸载
| |
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 常用命令
| |
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 在结构性问题上明显更高效。
