CodeGraph 把代码库从文件集合变成知识图谱
你让 Claude Code 帮你重构一个函数。它读了 5 个文件，找到调用关系，改了代码。然后你问："这个改动会影响哪些测试？"它沉默了——因为它不知道哪些测试调用了这个函数，除非它再读 50 个测试文件。
CodeGraph：把代码库从"文件集合"变成"知识图谱"
场景开篇
你让 Claude Code 帮你重构一个函数。它读了 5 个文件，找到调用关系，改了代码。然后你问："这个改动会影响哪些测试？"它沉默了——因为它不知道哪些测试调用了这个函数，除非它再读 50 个测试文件。
这就是当前 AI 编码代理的根本困境：代码是图结构，但代理在读文件。
文件是线性组织——一个目录下一个 .ts 文件，旁边一个 .py 文件。但代码的语义是图——函数 A 调用函数 B，类 C 继承类 D，模块 E 导入模块 F。人类程序员靠 IDE 的跳转、查找引用、调用层次图来导航这个图。AI 代理没有这些工具，只能一个文件一个文件地读。
CodeGraph 做的事情很简单：在代码和代理之间放一张图。
它是什么
CodeGraph 是一个本地优先的代码知识图谱工具。核心组件：
- Rust 内核：解析代码、构建图、响应查询。不是 Python 脚本，是编译好的 Rust 二进制。
- MCP 服务器：把图查询能力暴露给 AI 代理。代理不读文件，改查图。
- 自动同步：文件改动时图自动更新。不需要重新索引，不需要
codegraph rebuild。 - 30+ 语言支持：TypeScript、Python、Go、Rust、Java、C#、Swift、Kotlin、Ruby、PHP、C/C++、Scala、Dart、Lua、COBOL、Erlang、Solidity、Terraform……甚至 Delphi 和 CFML。
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
codegraph install # 自动检测并配置你的 Agent
cd your-project
codegraph init # 构建图
之后代理问"谁调用了 processPayment"，CodeGraph 直接返回图查询结果，不需要读 50 个文件。
为什么这比 RAG 更适合代码
当前 AI 编码代理的上下文管理有两条路线：
路线一：RAG（检索增强生成）。把代码切成块，嵌入向量，代理提问时检索最相关的块。问题：代码的语义关系不是"文本相似度"。调用关系、继承关系、类型约束——这些是结构化关系，不是语义相似性。RAG 检索"和 processPayment 最相似的代码"，可能返回一个名字像但功能完全不同的函数。
路线二：长上下文窗口。把整个代码库塞进上下文。问题：200K token 听起来很多，但一个中型项目可能 5M token。而且即使塞得进去，代理也得在 5M token 里找调用关系——这是 O(n) 的搜索，图查询是 O(1)。
CodeGraph 是路线三：结构化索引。不嵌入文本，不塞上下文，而是解析代码的 AST，提取调用图、类型图、导入图，存成本地图数据库。代理查询时直接走图遍历。
这更接近人类程序员的工作方式。你不会把整个代码库读进脑子里，你用 IDE 的"查找引用"和"调用层次"来导航。CodeGraph 给 AI 代理装了一个 IDE 级别的导航能力。
自动同步：最难的部分
静态索引不难——tree-sitter 解析 AST，提取符号和关系，存进数据库。难的是增量同步。
你改了一个函数签名，所有调用这个函数的地方都受影响。CodeGraph 需要检测改动、更新图、保持一致性。这是数据库的增量更新问题，不是简单的"重新解析这个文件"。
CodeGraph 的方案是文件监听 + 增量更新：文件保存时触发解析，只更新受影响的节点和边。README 声称"索引永远不会过时，不需要重新运行"。
这个承诺很硬。如果真做到了，意味着 CodeGraph 解决了代码索引最痛的问题—— staleness（过期）。大多数代码索引工具（包括 Sourcegraph、ctags）都需要手动刷新，开发者经常忘记，导致索引和代码不一致。
"100% 本地"的含金量
CodeGraph 反复强调"100% local"。这不只是隐私话术，是工程选择。
- 不依赖云服务：不需要把代码上传到某处做嵌入。对于闭源项目、企业代码、合规要求严格的场景，这是硬需求。
- 不依赖 Node.js：Rust 内核打包成单二进制，不需要先装 Node.js、Python 或 JVM。
curl | sh一行安装。 - 不依赖网络：离线环境也能用。飞机上、内网里、客户现场。
MCP 工具暴露
CodeGraph 作为 MCP 服务器运行，暴露图查询工具给代理。代理可以：
- 查询符号定义和引用
- 查询调用关系（谁调用了 X，X 调用了谁）
- 查询类型层次（类 C 继承自哪些类，被哪些类继承）
- 查询导入关系（模块 M 导入了什么，被谁导入）
- 跨文件追踪数据流
A()"这样的文本匹配。和其他工具的区别
- ctags / cscope：前辈工具，做符号索引但不做关系图。CodeGraph 做完整的关系图。
- Sourcegraph：云端代码搜索，需要上传代码。CodeGraph 是本地的。
- GitHub Copilot 的代码库索引：闭源、云端、不透明。CodeGraph 开源、本地、可审计。
- aider / Claude Code 的文件读取：线性读文件。CodeGraph 是图查询。
数据
- 仓库：colbymchenry/codegraph
- 语言：Rust 内核 + Node.js 分发层
- 协议：MIT
- 今日 stars：159
- 支持 30+ 编程语言
- 支持 10+ AI 代理（Claude Code、Cursor、Codex、OpenCode、Gemini、Antigravity、Kiro、Copilot 等）
适合谁
- 用 Claude Code / Cursor / Codex 做大型代码库重构的团队
- 需要理解调用关系、类型层次、导入依赖的场景
- 闭源项目或合规要求严格的企业——100% 本地，不上传代码
- 多语言混合项目——30+ 语言统一索引
收尾
CodeGraph 代表了 AI 编码工具的一个方向转变：从"给代理更多上下文"到"给代理更好的查询接口"。
当前主流思路是扩大上下文窗口——200K、1M、10M token。但上下文越大，代理在上下文里找信息的成本越高。CodeGraph 的思路是：不扩大上下文，而是让代理用更少的 token 获取更精确的信息。一次图查询返回 3 个相关函数的签名，比读 5 个文件找到这 3 个函数省 100 倍 token。
这个思路和数据库的发展历史一致。早期数据库把所有数据塞进内存扫描；后来发明了 B+ 树索引，查询从 O(n) 变成 O(log n)。CodeGraph 给代码库装了一个索引层，让 AI 代理的代码导航从"全量扫描"变成"索引查询"。
当所有人都在追逐更大的上下文窗口时，CodeGraph 提醒我们：问题不是上下文不够大，是查询不够精确。