CodeGraph：用预索引代码知识图谱，给 AI 编程 Agent 省下 88% 的工具调用
当 AI 编程 Agent（Claude Code、Codex、Cursor 这类）要回答"这段代码怎么改、改了会牵连哪里"时，它的默认做法很笨：用 grep 搜、用 glob 列文件、一个文件一个文件地 Read，手动把调用关系、依赖路径一点点拼出来。在真正动手干活之前，它已经把预算烧在了"搞清楚代码长什么样"上。
CodeGraph 的思路是把这一步提前做完，而且只做一次。它是一个预索引的代码知识图谱，仓库地址 colbymchenry/codegraph，内核用 Rust 写成，目前约 6.8 万 star。它把整个代码库的符号、调用边、依赖关系预先建成一张图，Agent 不再逐文件翻找，而是一次调用拿到它需要的精确代码片段、调用路径和改动影响范围。官方称这为"外科手术式上下文"，而非"一个文件一个文件地搜"。
核心机制：预建图，单次调用取上下文
CodeGraph 通过 MCP 协议接入 Agent，暴露的核心工具是 codegraph_explore。Agent 问一次，就返回相关源码、符号之间的调用路径（包括 grep 追不到的动态分发跳转），以及一次改动的影响半径。整个过程完全在本地完成——数据不出机器、不需要 API key、不依赖外部服务，底层只是一个 SQLite 数据库。
官方基准：调用变少，成本下降
作者在 7 个真实开源代码库上做了对照测试（每臂各跑 4 次取中位数，模型为 Claude Opus 4.8）。官方公布的结果是：使用 CodeGraph 后 88% 更少的工具调用、53% 更快、62% 更少的 token、44% 更低的成本，且 7 个仓库的 文件读取次数全部归零。
以 VS Code 代码库（TypeScript，约 1.1 万个文件）为例：带 CodeGraph 时 Agent 用 2 次工具调用、58 秒作答；不带时要 28 次调用、2 分 10 秒。差距最大的是 Excalidraw：2 次对 43 次调用，3.6 倍速度差。需要说明的是，这些数字来自项目作者自己发布的基准测试，属于单一来源数据，实际收益仍会因模型和代码库而异。
20+ 语言，和能跨语言边界的桥接
CodeGraph 的解析引擎是原生 Rust 写的，覆盖 20 种语言——TypeScript、JavaScript、Python、Go、Rust、Java、C/C++、C#、Swift、Kotlin 等，金属可编程（Metal/CUDA）走 C++ 路径。作者称每种语言的图在真实仓库上验证过、与参考引擎逐字节一致。
它还能识别 17 种 Web 框架的路由文件，把 URL 模式连到对应的 handler；并处理静态解析抓不到的跨语言流程——Swift ? Objective-C 桥接、React Native 的 legacy bridge / TurboModules / Fabric 视图、Expo Modules 等。
自动同步，索引不会过期
CodeGraph 默认开启文件监听，用系统原生事件（FSEvents / inotify / ReadDirectoryChangesW）捕捉每次建删改，debounce 后增量重建，只同步变动的部分。在 4400 个文件的项目上，保存一次文件引发的同步约 0.3 秒。Agent 改代码的间隙，图会自己跟上；即使某次编辑尚未入库，响应里也会带一条"陈旧文件"提示，让 Agent 直接读源文件而非拿到过期的错误答案。
上手只需三步
先装 CLI（不依赖 Node，一条命令抓对应平台的构建产物）：
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# 或 npm
npm i -g @colbymchenry/codegraph
然后 codegraph install 自动检测并接入你用的 Agent，最后对每个项目跑一次 codegraph init 建图。装完即忘——之后不需要手动 codegraph sync。
结论
CodeGraph 解决的是 AI 编程 Agent 里一类很具体的浪费：花太多调用和 token 去"发现"结构，而不是"回答"问题。它的答案是把这份发现工作预编译成一张本地图，用一次调用换掉几十次翻找。如果你日常工作里 Agent 频繁在 grep 和逐个 Read 上消磨预算，这个 6.8 万 star 的项目值得在自己的代码库上实测一轮——它的收益对大型、多文件、跨语言的项目最明显，小型单文件项目则未必有落差。前提也别忘了：基准数据来自作者自测，落地效果要靠你自己的仓库来验证。