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 一行安装。
• 不依赖网络：离线环境也能用。飞机上、内网里、客户现场。

代价是没有协作功能。你的图是本地的，团队成员看不到你的查询历史、标注、笔记。CodeGraph 的"平台版"（README 提到的 waitlist）可能解决这个问题，但开源版是纯本地。

MCP 工具暴露

CodeGraph 作为 MCP 服务器运行，暴露图查询工具给代理。代理可以：

• 查询符号定义和引用
• 查询调用关系（谁调用了 X，X 调用了谁）
• 查询类型层次（类 C 继承自哪些类，被哪些类继承）
• 查询导入关系（模块 M 导入了什么，被谁导入）
• 跨文件追踪数据流

这些查询返回的是结构化结果，不是文本块。代理拿到的是"函数 A 被 B、C、D 调用"这样的关系，不是"B 文件里有一行 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+ 语言统一索引

不适合：小型项目（图查询的收益不够明显）、需要协作标注的团队（开源版不支持）、非代码文件（Markdown、配置文件不是 CodeGraph 的目标）。

收尾

CodeGraph 代表了 AI 编码工具的一个方向转变：从"给代理更多上下文"到"给代理更好的查询接口"。

当前主流思路是扩大上下文窗口——200K、1M、10M token。但上下文越大，代理在上下文里找信息的成本越高。CodeGraph 的思路是：不扩大上下文，而是让代理用更少的 token 获取更精确的信息。一次图查询返回 3 个相关函数的签名，比读 5 个文件找到这 3 个函数省 100 倍 token。

这个思路和数据库的发展历史一致。早期数据库把所有数据塞进内存扫描；后来发明了 B+ 树索引，查询从 O(n) 变成 O(log n)。CodeGraph 给代码库装了一个索引层，让 AI 代理的代码导航从"全量扫描"变成"索引查询"。

当所有人都在追逐更大的上下文窗口时，CodeGraph 提醒我们：问题不是上下文不够大，是查询不够精确。