用 Claude Code 或 Cursor 做大项目时，我最烦的就是看 Agent 在文件海里慢慢爬：grep、ls、Read，一轮又一轮，好不容易找到关键代码，token 已经烧掉几十万。
最近看到 CodeGraph，colbymchenry 开源的，64k+ Star。它做的不是增强模型，而是给 Agent 一张预先生成的代码地图。Agent 不用自己摸索项目结构，直接问图就行。
我把它接进了一个实际项目试了一周。今天说说效果。
一、它解决什么问题
AI 编程 Agent 理解代码的方式通常是这样：
- 用户问"这个请求怎么到达数据库的"
- Agent 先 grep 找关键词
- 发现几个候选文件，逐个 Read
- 根据文件内容再 grep、再 Read
- 慢慢拼出调用链
这个过程中，Agent 花大量时间和 token 在"发现结构"上，而不是真正解决问题。
CodeGraph 的做法是：提前把代码库解析成知识图谱，包含每个符号、调用边、依赖关系。Agent 直接查询这张图，一次返回相关源码和调用链。
Claude Code / Cursor / Codex
│
▼
CodeGraph MCP Server
│
▼
SQLite 知识图谱
symbols · edges · files · FTS5
二、核心数据：省 89% 工具调用，省 69% token
官方 benchmark 在 7 个真实开源仓库上做了测试，对比 Claude Opus 4.8 有图和无图的表现：
| 指标 | 有 CodeGraph | 无 CodeGraph |
|---|---|---|
| 工具调用 | 基线 | 多 89% |
| Token 消耗 | 基线 | 多 69% |
| 成本 | 基线 | 高 60% |
| 文件读取 | 0 次 | 多次 |
具体看几个例子：
| 仓库 | 有图 | 无图 |
|---|---|---|
| VS Code | 41s / 2 调用 / 265k token | 3m24s / 40 调用 / 1.5M token |
| Tokio | 46s / 3 调用 / 386k token | 2m11s / 57 调用 / 4.3M token |
| Excalidraw | 36s / 3 调用 / 324k token | 23s / 55 调用 / 2.9M token |
注意 Excalidraw 那个小仓库，无图反而 wall-clock 更快，因为 Opus 4.8 grep 小项目很快。但代价是 5-10 倍 token 和 4-7 倍成本。大项目上，CodeGraph 在时间、token、工具调用三方面都完胜。
三、Rust 内核 + 20 多种语言
CodeGraph 的解析引擎是 Rust 写的，支持 20 多种语言：
TypeScript、JavaScript、Python、Go、Rust、Java、C#、C、C++、Swift、Kotlin、Scala、Dart、PHP、Ruby、Lua、R、Svelte、Vue、Astro、Solidity、Terraform、Nix 等。
每种语言的图都经过验证：解析结果要和参考引擎在真实仓库上 byte-for-byte 一致，从小项目测到 Linux kernel。没有预编译二进制平台的文件会自动 fallback，保证不崩。
最狠的是性能数据：
- Swift 编译器仓库（27k 文件）冷索引约 100 秒，单文件修改重同步约 4 秒
- Linux kernel（70k 文件、2M 符号、6.4M 关系）在 2 核 6GB 的 VPS 上 12 分钟内完成索引
- 日常保存文件后，图在 300ms 内开始更新，4400 文件项目重同步约 0.3 秒
四、怎么用
安装很简单：
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Windows
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
# 或者 npm
npm i -g @colbymchenry/codegraph
然后接入 Agent：
codegraph install
它会自动检测 Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro，并写入 MCP 配置。
最后初始化项目：
cd your-project
codegraph init
这一步会创建 .codegraph/ 目录并构建完整图。之后文件改动会自动同步，不需要再手动跑命令。
五、一个 MCP 工具，覆盖大部分查询
CodeGraph 的 MCP 服务器默认只暴露一个工具：codegraph_explore。
设计哲学是：一个强大的工具比一堆小工具更好。Agent 不需要在多个工具间做选择，几乎所有结构性问题都丢给 codegraph_explore：
- "X 是怎么工作的"
- "X 如何到达 Y"
- "这个改动会影响哪些代码"
返回的内容包括：相关符号的源码、调用路径、影响范围总结。动态分派（回调、接口实现、React re-render）这些 grep 跟不到的跳转，图也能处理。
CLI 也提供等价命令：
codegraph explore "How does a request reach the database?"
codegraph callers UserService
codegraph impact authMiddleware
codegraph affected src/utils.ts
六、实际体验
我在一个 3 万行左右的 TypeScript 项目里试了 CodeGraph。
场景 1：找入口
问 Agent："用户登录后，token 是怎么存到 cookie 的？"
无图时，Agent 先 grep "cookie"，读了 4 个文件，又问了一个澄清问题，花了大概 2 分钟。
有图时，Agent 直接调用 codegraph_explore，一次返回了相关函数和调用链，40 秒左右给出答案。
场景 2：改代码前做影响分析
我要改一个参数类型，先问："改这个会影响哪里？"
CodeGraph 的 impact 直接给了调用者列表和测试文件建议。这个对避免漏改很有用。
场景 3：框架路由
项目用 Express。问 Agent"哪个 handler 处理 /api/users"，CodeGraph 直接从路由文件链接到 handler 函数，不需要 Agent 自己读 routes.ts 再跟着找 controller。
七、对团队的价值
除了个人省 token，CodeGraph 对团队还有两个好处：
- 统一上下文质量：不管谁问 Agent，拿到的代码理解都基于同一张图，不会因人而异
- CI 集成：
codegraph affected可以接进 pre-commit 或 CI，只跑受影响的测试
# CI 示例
AFFECTED=$(git diff --name-only HEAD | codegraph affected --stdin --quiet)
if [ -n "$AFFECTED" ]; then
npx vitest run $AFFECTED
fi
八、注意事项
100% 本地：图存在项目目录的 .codegraph/codegraph.db 里，不上传任何代码、查询或符号名。对隐私敏感的项目很友好。
首次索引有成本：大项目第一次 codegraph init 需要一些时间，但之后增量同步很快。
不是银弹：它解决的是"结构性理解"，复杂业务逻辑、运行时行为、反射调用这些仍然是静态分析的边界。
WSL 注意：如果项目在 /mnt/c 这种 Windows 挂载路径上，可能遇到 daemon 通信问题。建议放 Linux 本地文件系统，或者设 CODEGRAPH_NO_DAEMON=1。
结语
CodeGraph 代表了一种很务实的 Agent 增强方向：不是换更强的模型，而是给模型更好的上下文基础设施。
当 Agent 不用在文件海里自己摸索时，它能把更多预算花在真正的问题上。对中大型项目来说，这种节省是实实在在的。
如果你经常用 Claude Code / Cursor 维护有一定规模的项目，值得试试。
