让 AI Agent 少读 89% 的文件——我试了 CodeGraph 这个代码知识图谱

用 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 / Linuxcurl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh# Windowsirm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex# 或者 npmnpm i -g @colbymchenry/codegraph

然后接入 Agent：

codegraph install

它会自动检测 Claude Code、Cursor、Codex CLI、OpenCode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro，并写入 MCP 配置。

最后初始化项目：

cd your-projectcodegraph 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 UserServicecodegraph impact authMiddlewarecodegraph 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" ]; thennpx vitest run $AFFECTEDfi

八、注意事项

100% 本地：图存在项目目录的 .codegraph/codegraph.db 里，不上传任何代码、查询或符号名。对隐私敏感的项目很友好。

首次索引有成本：大项目第一次 codegraph init 需要一些时间，但之后增量同步很快。

不是银弹：它解决的是"结构性理解"，复杂业务逻辑、运行时行为、反射调用这些仍然是静态分析的边界。

WSL 注意：如果项目在 /mnt/c 这种 Windows 挂载路径上，可能遇到 daemon 通信问题。建议放 Linux 本地文件系统，或者设 CODEGRAPH_NO_DAEMON=1。

结语

CodeGraph 代表了一种很务实的 Agent 增强方向：不是换更强的模型，而是给模型更好的上下文基础设施。

当 Agent 不用在文件海里自己摸索时，它能把更多预算花在真正的问题上。对中大型项目来说，这种节省是实实在在的。

如果你经常用 Claude Code / Cursor 维护有一定规模的项目，值得试试。