大家用 Cursor、Claude Code 这些 AI 编程助手的时候，有没有遇到过这样的情况：问一个代码结构的问题，它要先 grep 搜半天，再一个文件一个文件地读，来回折腾十几二十次才给你答案。 Token 哗哗地烧，时间也耗进去了。有没有办法解决这个“本地索引缺失导致的 Token 浪费”问题呢？
针对这个痛点，最近发现了一个相当能打的开源项目—— CodeGraph。用了一段时间，确实值得推荐。
CodeGraph 干的事情很直接：提前把你整个项目的代码结构建成一张知识图谱，存在本地 SQLite 数据库里，然后通过 MCP（Model Context Protocol）协议暴露给 AI 代理。AI 不用再去翻文件了，一次调用就能拿到完整的符号关系、调用链和影响范围。
它到底解决了什么问题
没有 CodeGraph 的时候，AI 代理理解代码全靠“手工搜索”。 grep 关键词、glob 找文件、Read 读内容，一个循环下来少说十几次工具调用。项目越大，这个开销越夸张。
CodeGraph 的思路是：既然代码结构是确定的，那就提前建好索引，让 AI 直接查表。
它做的事情分三步。第一步，用 Rust 写的原生解析内核加上 tree-sitter，把代码里的函数、类、方法、接口这些符号全部提取出来，连同它们之间的调用关系、继承关系、导入关系一起存进 SQLite。第二步，做跨文件引用解析，把函数调用指向定义、把 import 指向源文件。第三步，起一个 MCP Server，AI 代理通过 codegraph_explore 这个工具直接查询。
整个过程完全在本地跑，不联网，不传代码，不依赖任何外部服务。
省 Token 的效果有多明显
这是大家最关心的部分。CodeGraph 官方在 7 个真实开源项目上做了基准测试，对比同一个 AI 代理回答同一个架构问题，有 CodeGraph 和没有 CodeGraph 的差别。测试模型是 Claude Opus 4.8，每组跑 4 次取中位数。
直接看数据：
平均算下来，Token 消耗降低 62%，成本降低 44%，工具调用次数降低 88%。
为什么能省这么多？因为 AI 代理不再需要反复搜索和读文件来“发现”代码结构了。没有 CodeGraph 的时候，代理要调用 6 到 43 次工具才能回答一个架构问题；有了之后，1 到 4 次就够了，文件读取直接降到 0。
有一个细节值得注意：Token 处理量降低了，但会话结束后残留在上下文窗口里的内容反而多了大约 80%。因为 CodeGraph 返回的是一整块密集的代码上下文，比零散的 grep 结果更占窗口。如果你用的模型上下文窗口比较小，这一点要留意。
支持哪些语言和工具
语言覆盖面很广，目前支持 34 种编程语言。主流的 TypeScript、JavaScript、Java、Python、Go、Rust、C#、PHP、Ruby、Kotlin、Scala、Dart 都有完整支持。C 家族的 C、C++、Objective-C、Metal、CUDA 也覆盖了。移动端有 Swift、Kotlin、ArkTS。Web 框架方面 Svelte、Vue、Astro 都能识别。
甚至连 COBOL、Erlang、Solidity、Terraform、Nix 这些冷门语言都支持了，确实有点离谱。
每种语言都经过小、中、大三档真实仓库验证，跨文件覆盖率普遍在 85% 到 100% 之间。
AI 代理这边，支持 Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro、GitHub Copilot（VS Code / CLI / JetBrains）。基本上你能叫得出名字的 AI 编程工具都覆盖了。
官方推荐的是主流的这些，但只要 Agent 支持 MCP 接入，就可以配置接入。本质上这个服务就是一个 MCP Server。
安装和使用
安装很简单。如果你本地有 Node.js（版本 20 到 24 之间），直接 npm 装：
npm i -g @colbymchenry/codegraph
没有 Node.js 也没关系，一键脚本安装自带运行时的版本（需要网络可访问 github）：
# 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
装完之后，连接你的 AI 代理：
codegraph install
这条命令会自动检测你装了哪些 AI 工具，把 MCP 配置写进去。检测方式很朴素——就是看各个工具的配置目录存不存在，比如 ~/.claude/ 存在就认为装了 Claude Code，~/.cursor/ 存在就认为装了 Cursor。
然后在你的项目目录下初始化索引：
cd your-project
codegraph init
我拿自己的项目试了一下，2344 个文件，19 秒建完索引，生成了 46639 个符号节点和 183526 条关系边。数据库大小 227MB，存在项目根目录的 .codegraph/codegraph.db 里。
初始化完成后就完事了。文件变更会自动同步，不需要手动重新索引。
手动配置 MCP
如果你用的 AI 工具不在自动检测列表里，手动加一条 MCP 配置就行。核心内容就这几行：
{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "codegraph",
"args": ["serve", "--mcp"]
}
}
}
本质上 CodeGraph 就是一个本地的 MCP 服务。codegraph serve --mcp 启动后，AI 代理通过标准输入输出跟它通信。跟 context7、playwright 这些 MCP 服务一样的使用方式，代理按需拉起，不需要你手动管理。
电脑重启了也不用管，下次打开 AI 代理的时候它会自动启动 MCP Server。索引数据保存在磁盘上，重启不丢。
如果项目路径不在当前目录，加一个 --path 参数指定一下：
{
"mcpServers": {
"codegraph": {
"type": "stdio",
"command": "codegraph",
"args": ["serve", "--mcp", "--path", "/path/to/your/project"]
}
}
}
命令速查
日常用得到的命令不多，列一下：
| 命令 |
用途 |
codegraph init |
初始化项目索引，每个项目跑一次就行 |
codegraph status |
查看索引状态和统计信息 |
codegraph ui |
打开浏览器可视化查看器 |
codegraph query 符号名 |
搜索符号 |
codegraph callers 函数名 |
查看谁调用了这个函数 |
codegraph callees 函数名 |
查看这个函数调用了谁 |
codegraph impact 符号名 |
分析修改影响范围 |
codegraph explore 问题 |
语义探索代码关系 |
codegraph ui 会在 http://127.0.0.1:4747 起一个本地服务，浏览器打开后能看到完整的代码图谱可视化。左边是调用者，中间是源码，右边是被调用者，还能看影响半径和调用路径。不过界面目前是纯英文的，没有中文设置。
我的使用感受
最大的感受是：AI 回答代码结构类问题的速度快了很多，而且答案更准确。
以前问它“这个请求是怎么从入口走到数据库的”，它要搜半天，有时候还会漏掉中间环节。现在一次 codegraph_explore 就能把完整的调用链拉出来，包括一些 grep 跟不到的动态分发，比如回调、事件总线、React 的 re-render。
它还有一个设计哲学我觉得很对：一个强工具比一堆窄工具好用。默认只暴露 codegraph_explore 一个 MCP 工具，其他工具（node、search、callers 等）都藏在 CLI 里。这样 AI 代理不会纠结该调哪个工具，一个 explore 解决大部分问题。
项目是 MIT 协议开源的，GitHub 仓库在 colbymchenry/codegraph，npm 包名是 @colbymchenry/codegraph。目前版本 1.6.0，更新挺活跃的。
如果你平时用 AI 编程助手比较多，尤其是项目体量不小的话，推荐装一个试试。Token 省下来是实打实的，响应速度也有明显提升。
发表于 4 天前
|
查看: 0|
回复: 0
