上周我让 Claude Code 改一个支付回调的 bug。它先grep了一遍payment读出 12 个文件。然后发现回调逻辑在OrderService里又顺着 import 读了 8 个。改完跑测试挂了因为它漏看了一个被继承的基类方法。接着它把整个service/目录都读了进来。等它终于改对我看了一眼 token 用量单次会话烧掉 18 万 input token。问题改对了但我心里在滴血。这不是 Claude 不够聪明是它没有「地图」。它像一个被蒙着眼塞进陌生城市的快递员只能挨家挨户敲门问路。今天要聊的code-review-graph就是给 AI 配一副 GPS。GitHub 30,608 stars2,787 forksMIT 协议项目创建于 2026 年 2 月 26 日半年冲到 30K star。最新版本 v2.3.72026 年 7 月 18 日发布。它的口号很直接Stop burning tokens. Start reviewing smarter.我实测了一周把安装、使用、原理、benchmark 猫腻、适用边界全摸了一遍。这篇不做 README 翻译只讲我真正跑过之后的判断。它到底解决什么问题先说结论code-review-graph 不是又一个 RAG 代码搜索工具。它做的事情是用 Tree-sitter 把你的代码库解析成一张「结构图谱」节点是函数、类、文件边是调用、导入、继承、测试覆盖关系。这张图存在本地 SQLite 里。AI 通过 MCP 协议按需查询比如「这个函数被谁调用了」「改了这个文件会波及哪些测试」而不是把整个文件塞进 context。官方在 6 个真实仓库上跑了基准测试中位数 token 减少 65 倍范围从 36 倍到 376 倍。我知道你看到这个数字第一反应是「吹的吧」。我也是。所以后面会专门拆 benchmark 是怎么测的baseline 是什么哪些地方有水分。但先让它跑起来。手把手实战环境准备需要 Python 3.10 或更高版本。我用uvx跑不污染全局环境。你也可以用pipx效果一样。# 方式一uvx推荐零安装 uvx code-review-graph --version # 方式二pipx pipx install code-review-graph # 方式三pip 全局装 pip install code-review-graph如果要用语义搜索功能需要额外装 embeddings 扩展。pip install code-review-graph[embeddings]默认不带 embedding 是刻意的因为本地模型首次使用会从 HuggingFace 下载几百兆不是每个人都需要。安装到 Claude Code一条命令自动检测平台并写入 MCP 配置。code-review-graph install --platform claude-code它支持 14 个以上的平台Claude Code、Cursor、Codex、Windsurf、Zed、Continue、OpenCode、Antigravity、Gemini CLI、Qwen、Kiro、Qoder、Copilot、CodeBuddy。装完要重启编辑器MCP 服务才会拉起。MCP 绑定的是localhost数据全在本地零遥测。这一点对代码隐私敏感的团队很重要后面原理部分还会讲。构建图谱进到你的项目根目录执行。code-review-graph build它会用git ls-files列出所有被 git 跟踪的文件gitignore 的自动跳过。500 个文件的项目首次构建大约 10 秒。3000 个文件的项目增量更新大约 2.5 秒其中 1.4 秒是 Python 进程启动开销。构建完你会发现项目根目录多了一个.code-review-graph/文件夹里面是graph.db就是那张三张表撑起来的 SQLite 图谱。记得把它加进.gitignore。在 Claude Code 里用重启 Claude Code 后你会多出一组斜杠命令。/code-review-graph:build-graph /code-review-graph:review-delta /code-review-graph:review-prreview-delta是我用得最多的。它会检测你当前工作区相对 git 的改动沿着图的边追踪影响半径然后告诉 AI「只看这些文件就够了」。我改完一个函数直接在 Claude Code 里敲/code-review-graph:review-delta它返回的不是整个 diff而是一份结构化的审查简报包含变更了哪些节点这些节点被哪些上游调用哪些测试覆盖了这些节点一个 0 到 100 的风险评分建议的最小审查文件集整个过程 AI 读入的 token 从「整个仓库」降到「两三千 token 的结构化摘要」。Token Savings 面板detect-changes --brief命令会输出一个 Token Savings 面板长这样。Files changed: 3 Nodes impacted: 47 Review set: 8 files (2,840 tokens) Full corpus: 142,356 tokens Savings: 50.1x这里的 token 估算是用chars/4算的。我一开始担心这个估算不准专门翻了REPRODUCING.md官方用 222 个文件做了校准chars/4跟 tiktokencl100k_base的偏差在正 0.5% 以内。也就是说它稍微高估一点点节省但偏差可以忽略。watch 模式开发时不想每次手动 build可以开监听。code-review-graph watch文件保存时它自动增量更新。增量靠 SHA-256 hash 比对只重新解析内容真正变化的文件然后沿边更新受影响的节点关系。实际体验几乎无感。visualize 交互式图谱code-review-graph visualize它会起一个本地 web 服务在浏览器里画出交互式的依赖图谱。你可以点节点看上下游可以按社区着色可以看到哪些是 hub 节点哪些是 bridge 节点。这个功能对 onboarding 新同事或者理解遗留系统特别有用比在 IDE 里点「find usages」一个个看直观太多。.code-review-graphignore有些目录你不想索引比如生成的代码、migrations、前端构建产物。在项目根目录建一个.code-review-graphignore语法跟 gitignore 一样。**/generated/** **/migrations/versions/** frontend/dist/GitHub Action 集成它还提供了 GitHub Action可以在 PR 上自动发风险评分评论甚至可以设置fail-on-risk作为合并门禁。name: Code Review Graph on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: tirth8205/code-review-graph-actionv2 with: fail-on-risk: 70 github-token: ${{ secrets.GITHUB_TOKEN }}风险分超过 70 就阻止合并。这个分数不是拍脑袋的它综合了变更节点的 hub 程度、影响半径内的测试覆盖率、以及边的置信度。Benchmark 数字怎么来的好到了最关键的部分65 倍这个数字能不能信。官方在 6 个真实开源仓库上测的我把原始数据拉出来。仓库全量语料 token图谱返回 token节省倍数fastapi948,7932,653375.6 倍flask143,5942,19671.0 倍code-review-graph 自身208,8213,19068.1 倍gin166,8682,76661.9 倍httpx142,3562,66160.6 倍express136,0523,93636.0 倍中位数 65 倍。fastapi 那个 375.6 倍是极端案例因为 fastapi 的__init__.py和applications.py集中导出了大量符号全量喂入时这些文件反复出现在 context 里而图谱只返回真正相关的调用链。但这里有个你必须知道的 caveat。baseline 是「全量语料」也就是把整个仓库所有源码文本都塞给 AI。这不是一个聪明的 baseline。现实中一个有经验的 Claude Code 用户会用 grep、glob、find references来缩小范围不会真的把 fastapi 全部 94 万 token 塞进去。所以 65 倍是跟「最粗暴的做法」比不是跟「熟练工程师手动筛选」比。这一点官方没有藏着掖着写在REPRODUCING.md里了但它不在 README 的显眼位置。我的判断是即便跟聪明的 grep 策略比图谱依然有明显优势因为 grep 只能做文本匹配它不知道调用关系和继承链。但优势肯定没有 65 倍那么夸张我自己体感在 5 到 15 倍之间取决于代码库的耦合度。再看准确性数据。影响分析的 F1 是 0.69precision 0.546recall 1.0。recall 1.0 看起来完美但 ground truth 是从同一张图导出来的属于循环论证这个数字不能当真。真正诚实的 co-change 模式对比 git 历史中实际共同修改的文件目前预测为 0官方自己标了「还不可用」。多跳检索基准是 0.909 分测的是 11 个手工任务跨 6 个仓库这个数据相对可信因为它测的是「沿图的边遍历能不能找到正确答案」不依赖循环论证。所以我的结论是token 节省的方向是对的数量级可信但别把 375 倍当成你每天都能看到的数字。中位数 65 倍是跟全量喂入比的乐观值。原理拆解Tree-sitter 解析出节点和边核心是 Tree-sitter一个增量解析库GitHub 自己的 Atom 编辑器当年搞出来的现在几乎是所有代码结构分析工具的事实标准。它把每个文件解析成 AST抽象语法树然后从中提取节点函数定义、类定义、方法、导入声明、文件本身边CALLS函数 A 调用了函数 BIMPORTS文件 A 导入了文件 BINHERITS类 A 继承自类 BTESTED_BY函数 A 被测试文件 T 覆盖每条边还带一个置信度标签EXTRACTED表示从 AST 直接提取的确定性高INFERRED表示通过命名约定或导入路径推断的AMBIGUOUS表示有多个可能的解析目标。AI 拿到这些标签可以判断哪些关系值得信任。为什么不用 LSP你可能会问LSPLanguage Server Protocol不是也能做这些事情吗find references、go to definition都是编译器前端做精确类型推导出来的。区别在于精度和广度的取舍。LSP 精确但重。每个语言一个 daemonPython 要起 pyrightGo 要起 goplsJava 要起 jdtls吃内存吃 CPU。而且 LSP 的引用列表是「100% 精确或 nothing」对于动态语言或者 monkey patch 的场景经常直接罢工。Tree-sitter 是启发式的 AST 解析不做类型推导一个进程覆盖 35 种以上语言Python、JavaScript、TypeScript、Go、Rust、Java、C/C、C#、Ruby、Kotlin、Swift、PHP、Scala、Solidity、Dart一直到 Zig、Nix、Verilog、Terraform、Vue SFC、Jupyter notebook。它不保证 100% 精确但它保证「不会漏掉可能受影响的文件」。Code review 场景要的恰恰是后者。你宁愿多看两个文件也不想漏掉一个导致线上事故。这是工程上的务实取舍。影响半径分析这是整个工具最核心的算法。你改了一个函数它做的事情是找到变更文件对应的图节点沿CALLS和IMPORTS边反向遍历找到所有依赖这个节点的上游沿TESTED_BY边找到覆盖这些节点的测试对遍历到的节点按距离和边置信度加权输出一个最小但充分的审查文件集这个过程叫 blast radius analysis爆炸半径分析。传统的静态分析工具也做类似的事情但它们通常输出几百个文件让你自己筛。CRG 的不同在于它把结果裁剪到 AI context window 能舒服处理的体量通常是两三千 token。增量更新首次全量构建后每次更新只做三步。用git diff拿到变更文件列表对每个文件算 SHA-256 hash跟上一次的 hash 比对只重新解析 hash 变化的文件删除旧节点和边插入新的然后沿边更新引用关系MCP 协议30 个工具AI 不是拿到整张图而是通过 MCP 工具按需查询。CRG 暴露了 30 个 MCP 工具和 5 个 prompt 模板。工具包括查询节点详情、找调用者、找被调用者、影响半径分析、搜索符号、获取社区结构、获取 hub 节点、获取风险评分等等。5 个 prompt 模板是review、architecture、debug、onboard、pre-merge对应不同的审查场景。关键设计是AI 决定查什么图返回什么。AI 不会一次性拿到全部数据而是像查数据库一样先查一个节点根据结果决定下一步沿哪条边走。这就是多跳检索也是它比 RAG 强的地方。为什么它不是 RAG这是最多人误解的点。RAG检索增强生成把代码切成文本块做向量化查询时用余弦相似度找最接近的块。它回答的问题是「哪些文本里提到了 X」。CRG 存的是 AST 解析出的结构边回答的问题是「谁调用了 X」「X 的子类有哪些」「改了 X 哪些测试会挂」。embedding 在 CRG 里只是可选的辅助用来找到遍历的起始节点。一旦起始节点确定后续完全沿真实的结构边走不涉及向量相似度。打个比方RAG 像在书里搜关键词CRG 像看目录和交叉引用。搜关键词能找到提到的地方但目录能告诉你「这一章影响了哪三章」。官方在多跳检索任务上拿了 0.909 分而纯 RAG 方案在这类需要沿关系链推理的任务上普遍表现差因为向量相似度不传递A 跟 B 相似B 跟 C 相似不代表 A 跟 C 有结构关系。Leiden 社区检测和风险评分图谱还跑了 Leiden 社区检测算法把高度互连的节点聚成社区这对应代码里的模块或子系统。hub 节点是被大量其他节点依赖的节点改它们风险高。bridge 节点是连接两个社区的节点改它们可能产生跨模块影响。风险评分综合了这几个因素变更节点的 hub 程度影响半径内的节点数量边的置信度社区跨越数测试覆盖率。输出一个 0 到 100 的分数给人类 reviewer 和 CI 门禁一个快速判断依据。跟其他工具怎么选我在之前的 073 篇文章里对比过 sense、codegraph、CodeGraph 三个工具。这次加上 CRG再补两个常被拿来比的。Serena走的是 LSP 路线语义精确但每个语言要起 language server重资源占用高。适合需要精确重命名、类型推导的场景。CRG 走 Tree-sitter 路线轻量语言覆盖广适合 review 和影响分析这种「宁滥勿缺」的场景。repomix做的是把整个仓库打包成一个大文本文件喂给 AI。它解决的是「怎么把代码塞给 AI」CRG 解决的是「该把哪些代码塞给 AI」。两者可以配合repomix 打包的同时用 CRG 筛选文件。claude-context类 RAG 工具做向量检索适合「找哪里提到了某个概念」的模糊查询。CRG 适合「找这个函数被谁调用了」的结构化查询。一个找文本一个找关系。sense / codegraph073 篇聊过sense 偏向 IDE 内的实时可视化codegraph 偏向生成静态架构图。CRG 是唯一一个深度集成 MCP、以「给 AI 消费」为第一目标的图谱工具它输出的不是给人看的图而是给 AI 读的结构化 JSON。简单的选择建议代码库超过 500 个文件AI 经常读太多无关代码上 CRG需要精确的类型感知重构用 Serena只是想把仓库一次性喂给 AI 做总结repomix 够用想找「哪里提到了 XXX」的模糊搜索RAG 类工具更直接什么时候不该用这篇文章不是软文有些场景 CRG 反而帮倒忙。小项目别装。几百个文件以下的项目AI 本来就能把相关代码读进 context。CRG 的结构元数据本身有开销小改动时 graph response 可能比原始 diff 还大。官方文档明确写了这个限制。琐碎改动别用。改个文案、调个 CSS、加个日志直接让 AI 看 diff 就行绕一圈查图谱纯属浪费。JavaScript 和 Go 的流检测目前较弱。官方 benchmark 里 JS/Go 的数据流检测 recall 只有 33%意味着三分之二的数据流关系会漏掉。这两个语言的动态分发和接口隐式实现让 Tree-sitter 级别的启发式分析很吃力。如果你的核心诉求是追踪 JS 或 Go 的数据流目前要降低预期。搜索功能本身不强。符号搜索的 MRR 只有 0.35Mean Reciprocal Rank一个衡量搜索结果质量的指标0.35 意味着正确结果平均出现在第三个位置左右。它不是搜索引擎别指望它当 Sourcegraph 用。它的强项是找到起点之后沿边遍历不是找到起点本身。co-change 预测还不可用。就是「改了这个文件历史上通常还会一起改哪些文件」这个功能基于 git 历史挖掘目前预测准确率为 0官方自己标了 experimental。别用它做决策。FAQQ它会把我的代码传到云端吗。不会。图谱存在本地 SQLiteMCP 绑定 localhost零遥测不发任何网络请求。唯一的网络行为是可选的 embedding 模型从 HuggingFace 下载下载完也全本地跑。Q支持私有仓库和 monorepo 吗。支持。它只看git ls-files不关心仓库在哪。monorepo 可以在根目录 build也可以在子包目录分别 build。大 monorepo 建议分模块建图避免单张图过大。Q跟 Claude Code 内置的代码搜索有什么区别。Claude Code 内置的是 glob 和 grep基于文件名和文本匹配。CRG 给的是结构关系「谁调用了这个函数」「这个类被谁继承了」「改了这个文件影响哪些测试」grep 答不了这些问题。两者是互补的不是替代关系。Q构建图谱会不会很慢。500 文件首次约 10 秒3000 文件增量约 2.5 秒其中 1.4 秒是 Python 启动。日常开发开watch模式文件保存自动更新体感是秒级。Q30 个 MCP 工具会不会让 AI 选择困难。实际不会。AI 通过工具描述选择而且大部分场景用的是review-delta和review-pr这两个封装好的 prompt 模板不需要手动挑工具。30 个工具是给高级场景用的比如调试某个函数时手动沿调用链查。写在最后我用了一周最大的感受不是「省了多少 token」而是 review 质量确实变了。以前 Claude Code review 代码时它只会看你给它的 diff最多 grep 一下相关引用。现在它会顺着图查「你改了这个函数但它的子类重写了这个方法你没改」「这个函数被三个上游调用其中一个没处理你新加的错误码」。这种 review 是以前做不到的不是因为模型变聪明了是因为它终于有了地图。Token 经济学里有个常被忽略的点context window 越大越有人觉得「全塞进去就行」。但大 context 有两个隐性成本一是钱input token 按用量计费二是质量lost in the middle 效应模型对 context 中间位置的信息关注度显著下降。把 94 万 token 塞给模型效果未必好过精准的 2600 token。code-review-graph 证明了这件事。它不是让 AI 更聪明是让 AI 少走弯路。
