CodeGraph：让你的 AI 编程助手少读 76% 的文件

一个被忽视的 Token 黑洞

你有没有算过，Claude Code 回答一个"这个请求是怎么到数据库的"这种问题，要花多少 token？

实测下来，一个中等规模的项目，光是"找到相关代码在哪"这一步，就可能触发 10 到 20 次工具调用——先 spawn 一个 Explore 子代理，然后这个子代理开始疯狂 grep、glob、find、read，每次调用都把文件内容塞进上下文窗口。

这些 token 全花在了"找路"上，而不是"理解"上。

更扎心的是，这些探索路径几乎每次都一样。Agent 今天问"用户登录怎么走的"，明天问"权限校验在哪做的"，走的都是同一条 grep→read→grep→read 的弯路。代码库的结构明明是静态的，但 AI 每次都要从头摸索。

CodeGraph 就是来干这事的：把代码库的结构提前索引好，让 Agent 直接查询，而不是每次都去翻文件。

CodeGraph 是什么

一句话：给 AI 编程助手用的预索引代码知识图谱。

它用 tree-sitter 解析你的源码，提取出符号（函数、类、方法）、关系（调用、导入、继承、实现），全部存进本地 SQLite 数据库，再通过 MCP（Model Context Protocol）暴露给 Agent。

Agent 想知道"A 方法被哪些地方调用了"，直接查图就行，不用 grep，不用 read，不用 spawn 子代理。

项目地址：github.com/colbymchenry/codegraph^[1]

效果到底有多猛

作者在 7 个真实开源项目上做了对照实验（Claude Opus 4.8，每个项目跑 4 轮取中位数），让 Agent 回答同一个架构问题，对比有没有 CodeGraph 的表现：

平均：成本降 16%、Token 少 47%、速度快 22%、工具调用减少 58%。

还有一个更细的 37 项 A/B 矩阵（覆盖 22 种语言 × 大中小三档），结论是：文件读取次数从 159 降到 38，减少 76%。而且在任何一个测试用例里，CodeGraph 从未导致读取次数增加。

最夸张的单个用例是 ASP.NET 的 Jellyfin（2000+ 文件）：没有 CodeGraph 时，Agent 读 17 个文件、跑了 17 次 shell 命令、甚至 spawn 了一个子代理，耗时 212 秒；有了 CodeGraph 后，只读 3 个文件、4 次 MCP 调用搞定，51 秒收工。

说白了，大仓库里效果最明显。小仓库（百八十个文件那种）优势不大，因为整个流程本来一两个文件就能看明白。

技术原理拆解

CodeGraph 的工作流程分四步：

1. 解析提取

用 tree-sitter 把源码转成 AST（抽象语法树），再用每种语言特定的 query 提取出节点（函数、类、方法）和边（调用、导入、继承）。目前支持 20+ 种语言：TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C/C++、Swift、Kotlin、Scala、Dart、Lua 等等，连 Vue、Svelte、Astro 这些前端框架的文件也能解析。

2. 本地存储

所有数据存在项目根目录的 .codegraph/codegraph.db，底层是 SQLite + FTS5 全文搜索。不需要任何外部服务，不需要 API Key，数据永远不离开你的机器。

3. 引用解析

提取完原始符号后，CodeGraph 还会做一轮引用解析：把函数调用指向定义、把 import 指向源文件、把类继承关系连上。框架特有的路由模式也能识别——比如 Spring 的 @GetMapping、FastAPI 的 @app.get、Express 的 app.get，总共覆盖 17 种 Web 框架的路由约定。

4. 实时同步

MCP server 启动后会监听文件系统事件（macOS 的 FSEvents、Linux 的 inotify、Windows 的 ReadDirectoryChangesW），文件改动后自动增量索引。你不用手动跑 codegraph sync，图永远是最新的。

我们的实际使用

我在两个项目上跑了 CodeGraph（v1.0.1），看看实际索引出来的规模：

项目一：HQAI AI 中台（Java + Vue）

• 1,073 个文件
• 21,204 个节点（含 7,323 条 import、4,118 个方法、1,287 个函数）
• 50,201 条边
• 数据库大小：54.27 MB

项目二：Service Desk 服务台（Python + Vue）

• 222 个文件
• 3,070 个节点
• 7,640 条边
• 数据库大小：6.55 MB

配置完之后，我的 Hermes Agent 在处理这两个项目的代码问题时，确实少了很多 "让我先 grep 一下" 的操作。Agent 直接调 codegraph_explore 一次就能拿到相关符号的源码和调用链路。

安装：三条命令搞定

第一步：装 CLI

不需要预装 Node.js，CodeGraph 自带运行时：

# macOS / Linux
curl -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：

npm i -g @colbymchenry/codegraph

第二步：配置 Agent

codegraph install

这个命令会自动检测你装了哪些 AI 编程工具（Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro），然后给每个工具配置好 MCP server。

第三步：初始化项目

cd your-project
codegraph init

init 会创建 .codegraph/ 目录并构建完整索引，一步到位。之后文件改动自动同步，不用管了。

Agent 怎么用这些工具

CodeGraph 通过 MCP 暴露了 4 个核心工具：

设计上有个细节值得说：CodeGraph 故意只默认展示 4 个工具。之前有 8 个，但实测发现 Agent 几乎不会主动选另外 4 个（callees、impact、files、status），而且这些信息已经包含在 explore 的返回结果里了。少几个工具定义在上下文窗口里，每个 session 都能省一点 token。

框架路由识别：不仅仅是语法解析

很多代码图谱工具止步于"谁调用了谁"的静态关系。CodeGraph 多走了一步，能识别 Web 框架的路由模式，把 URL 路径和对应的 handler 连起来。

举个例子，你在 Spring 里写了：

@GetMapping("/api/users/{id}")
public User getUser(@PathVariable Long id) { ... }

CodeGraph 会识别出这是一个路由节点，把 /api/users/{id} 和 getUser 方法用 references 边连上。这样你想查"谁会触发这个方法"，答案里直接包含 URL 路径，而不是只有代码内部的调用链。

目前覆盖的框架包括：Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、Axum、ASP.NET、Vapor 等 17 种。

混合语言桥接：跨语言调用不丢链路

如果你做过 iOS 或 React Native 开发，肯定遇到过这个问题：Swift 调 Objective-C，JS 调 Native Module，跨语言的调用关系静态解析根本追不到——tree-sitter 在语言边界就停了。

CodeGraph 做了专门的跨语言桥接：

• Swift ↔ ObjC：按 @objc 自动桥接规则匹配，包括 Cocoa 风格的方法名前缀（With/For/By 等）
• React Native Bridge：解析 RCT_EXPORT_METHOD 宏和 @ReactMethod 注解，建立 JS 名到原生方法的映射
• TurboModules / Fabric：把 Codegen spec 接口当作 ground truth 来连接
• Expo Modules：解析 Expo DSL 字面量来桥接

这些跨语言边在图里会标记 provenance:'heuristic'，让 Agent 知道这条边是怎么来的。

说点实在的：什么时候效果不明显

CodeGraph 没法包治百病。有些场景收益有限，甚至有额外开销：

小仓库不太划算。 如果你的项目就几十个文件，Agent 一次 read 就能看完整个流程。这时候 CodeGraph 的 MCP 开销（工具定义占上下文、索引加载时间）反而是额外成本。benchmark 数据也印证了这点：110 个文件规模的项目，有时代码持平甚至略贵。

短问题不如长调查。 A/B 矩阵显示，单次短问题（"这个函数在哪定义"）的成本基本持平甚至略高，因为 CodeGraph 有固定的 MCP 开销。它的优势在多轮深度调查中才体现出来——Agent 不会反复 grep 同样的东西。

动态调用的天花板。 反射、依赖注入、运行时动态分发，这些静态分析天生追不到。CodeGraph 的跨文件覆盖率在 84%~100% 之间（取决于语言），剩余部分是真实的静态分析盲区。

最后

我自己的体感是：如果你天天用 Claude Code、Cursor 这类工具啃中大型项目，装一个 CodeGraph 比换一个更贵的模型管用。尤其是那种几千个文件的 Java/Python 后端，以前 Agent 翻一遍代码库半分钟就过去了，现在一次 codegraph_explore 就能拿到调用链。

小项目可以不急。但项目一旦超过 500 个文件，或者你经常问 Agent "X 是怎么调用到 Y 的"这种问题，就值得装了。

项目地址：github.com/colbymchenry/codegraph^[2]
文档站：colbymchenry.github.io/codegraph^[3]

引用链接