一句话总结:CodeGraph 是一个构建在 Rust 之上的本地预索引代码知识图谱,它为 Claude Code、Cursor、Copilot 等 AI 编码代理提供语义级的代码理解能力——零配置、零网络调用、零遥测数据离开你的机器。

01 · 痛点:AI 代理每天都在"重新发明轮子"
每次你在 Claude Code 或 Cursor 里问一个关于代码库的问题时,代理在幕后做什么?它用 grep 扫一遍目录,打开几个文件,凭猜测去找路径——每问一次就要从头重复一遍。
结果就是:工具调用爆炸、token 浪费、响应慢,而且AI 经常找不到那些被动态分派(dynamic dispatch)跨文件关联的调用路径——grep 天然追踪不到这类关系。
CodeGraph 的作者 Colby McHenry 在 7 个真实开源项目上做了严格的 A/B 基准测试(2026-08-05 重新测量,Claude Opus 4.8,--strict-mcp-config,每条手臂跑 4 次取中位数),结果触目惊心:
无 CodeGraph vs 有 CodeGraph,中位数对比
| Codebase | 语言 | 工具调用 | 耗时 | 文件读取 | Token | 花费 |
|---|---|---|---|---|---|---|
| VS Code | TypeScript · ~11k 文件 | 2 vs 28 | 58s vs 2m10s | 0 vs 12 | ↓ 77% | ↓ 71% |
| Excalidraw | TypeScript · ~640 | 2 vs 43 | 45s vs 2m42s | 0 vs 18 | ↓ 84% | ↓ 78% |
| Django | Python · ~3k | 3 vs 14 | 54s vs 1m23s | 0 vs 8.5 | ↓ 41% | ≈持平 |
| Tokio | Rust · ~790 | 3 vs 29 | 1m3s vs 2m43s | 0 vs 19 | ↓ 65% | ↓ 64% |
| OkHttp | Java · ~645 | 1 vs 6 | 33s vs 58s | 0 vs 2 | ↓ 54% | ↓ 21% |
| Gin | Go · ~110 | 1 vs 7 | 28s vs 46s | 0 vs 4 | ↓ 52% | ≈持平 |
| Alamofire | Swift · ~110 | 4 vs 33 | 54s vs 2m22s | 0 vs 16.5 | ↓ 59% | ↓ 57% |
全部 7 个仓库、7 种语言,文件读取统一归零。综合统计:工具调用 ↓ 88%、速度提升 53%、token ↓ 62%、成本 ↓ 44%。
02 · CodeGraph 是什么?
一句话:把你的代码库提前索引成一个 SQLite 知识图谱,AI 代理通过 MCP 协议直接"问图谱"而不是"扫目录"。
它不是模糊的向量语义搜索(那种你永远不知道它为什么返回这个结果的"黑盒"),而是基于精确的树-sitter 解析的符号级图:函数调用点、类继承、接口实现、导入导出关系、URL 路由绑定、Swift ↔ ObjC 桥接——全部静态分析、精确、可审计。
架构概览
03 · 核心特性拆解
3.1 100% 本地,没有任何灰色地带
- 数据存储在本地 SQLite(
.codegraph/目录) - 无任何 API Key、无外发连接、无遥测(命令名统计可通过开关关闭)
- MIT 开源协议——审查每一行图构建逻辑
3.2 20+ 编程语言全支持
TypeScript、JavaScript、Python、Go、Rust、Java、C#、C++、Swift、Kotlin、PHP、Ruby、Scala、Dart、Lua、Solidity、Terraform、Svelte、Vue、Astro、COBOL、Pascal/Delphi……
每种语言的图谱都经过与 WASM 参考引擎逐字节比对后才发布——从小型库到 Linux 内核真实仓库,确保一致性。
3.3 代理生态即插即用
自动检测并配置以下代理的 MCP 服务端:
| 生态 | 代理 |
|---|---|
| Anthropic | Claude Code、Claude Copilot CLI |
| OpenAI | Codex CLI |
| GitHub | GitHub Copilot(VS Code / CLI / JetBrains) |
| 独立 IDE | Cursor、Gemini CLI、Antigravity、Kiro |
| 开源 CLI | opencode、Hermes Agent |
一份图谱,所有代理共享,不需要重复索引。
3.4 自动同步,静默工作
文件监听 + 2 秒防抖 + 300ms 级增量更新。编辑完不到 2 秒,下一轮对话的 AI 就能看到你刚写的代码。而且还有个额外保障:在防抖窗口期间,MCP 响应里如果引用了还没同步完的文件,会附加 ⚠️ banner 让 AI 直接 Read 原文件,不存在"静默返回过期数据"的问题。
3.5 Framework-aware Routes
不只是符号级别——它理解路由。17 个框架的路由解析,将 URL 模式与处理函数直接关联:
| 框架类别 | 支持 |
|---|---|
| Python | Django、Flask、FastAPI |
| Node.js | Express、NestJS |
| Go | Gin / chi / gorilla / mux |
| Rust | Axum / actix / Ruby on Rails |
| Java/Scala | Spring、Play |
| PHP | Laravel、Drupal |
| Swift | Vapor |
| 其他 | ASP.NET、Astro |
查询某个 View/Controller 的调用方时,直接得到暴露它的 URL。
3.6 跨语言桥接(iOS / RN / Expo)
静态分析的最大盲区就是跨语言调用。CodeGraph 额外捕捉:
- Swift ↔ Objective-C bridging
- React Native legacy bridge + TurboModules + Fabric view components
- native → JS event emitters
- Expo Modules
这些跨越语言边界的调用流,grep 完全束手无策,CodeGraph 通过统一图谱直接关联。
3.7 性能自适应
Worker 池、并行分辨率、分析缓存都按实际硬件配置动态调整——包括容器/cgroup 感知(只使用分配到的核心数,而非宿主机核数)。
04 · 安装和配置:三条命令
# 1. 安装 CLI(无需 Node.js,自带运行时)
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Windows: irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
# 2. 连接代理(自动检测并配置 MCP)
codegraph install
# 3. 进入项目目录,构建图谱
cd your-project && codegraph init
如果你已有 Node.js:npm i -g @colbymchenry/codegraph
后续什么都不用做——监听 + 增量同步全自动。升级 codegraph upgrade,卸载 codegraph uninstall。
05 · 边界与注意事项
不能回避的几个事实:
1. 上下文窗口足迹增加。
CodeGraph 减少的是"处理 token"(代理不再遍历文件),但它返回的密集有效载荷会留在上下文窗口中——同批测试中 CodeGraph 会话结束时的残余上下文大约是纯文本代理的 1.8 倍(VS Code 测试:67k vs 18k tokens)。长会话 + 小窗口用户需注意预算。
2. 不是银弹。
对于完全新颖的代码探索、或需要变量级别精确语义理解的场景,仍需代理自行 Read 源文件。CodeGraph 优化的是"在哪里找到答案“这一步——找到之后,理解代码仍然靠 AI。
3. 当前只支持 SQLite。
未来计划支持更多后端,目前单一项目对应一个 .codegraph/ 目录。
4. 公众号和 RSS 注意。
Mermaid 图在微信公众号里不会渲染。如果你需要同步此类文章到公众号,应提前把 Mermaid 导出为 PNG 再上传。
06 · 安装验证(Windows 11 实测)
PS> npm.cmd install -g @colbymchenry/codegraph
added 2 packages in 1m
PS> codegraph.cmd --version
1.6.2
通过 PowerShell 一键脚本(会下载自带 Node 运行时的 bundle 版本):
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
⚠️ PowerShell 脚本执行策略:本机默认禁用了
.ps1脚本加载(Restricted策略),此时只能通过.cmd后缀的命令运行(codegraph.cmd)。如果想直接执行 PS1 脚本,需先设置执行策略:Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned。
07 · 总结
CodeGraph 解决了一个真问题:AI 编码代理在面对真实代码库时的高成本低效率。它不是又一个"让 AI 帮你写代码"的噱头产品,而是一个让现有 AI 代理真正理解代码的工程基础设施。
核心差异化在于:
- 不是语义搜索,是精确的符号图。grep 跟不上的分派调用、跨语言桥接、路由绑定,它都能追踪。
- 不是在线服务,是本地引擎。SQLite + Rust,数据全程不离开你的机器。
- 不是 beta 级玩具,是实测数据。7 个真实仓库 × 4 次运行的严格 A/B,工具调用 ↓ 88%,文件读取归零。
如果你日常使用 Claude Code、Cursor 或 Copilot,并且项目规模超过几个文件,CodeGraph 值得一试。安装三条命令,卸载一条命令,零风险。
项目地址:https://github.com/colbymchenry/codegraph 开源协议:MIT 当前版本:1.6.2(2026-10-24)