改一行代码后，别再让 Agent 重读整个仓库：code-review-graph 实战、原理与选型

让 AI 审一个稍大的仓库，最浪费的往往不是它最后写了多少字，而是它为了弄清关系，反复搜索、打开、再读一遍代码。

改动可能只落在一个函数上，真正需要看的也许只有十几个文件；但 Agent 很容易先把目录、相邻模块、相似命名的实现都塞进上下文。慢、贵，而且越读越容易偏离这次变更真正的风险。

最近很多同学在讨论代码图谱工具，我重点看了 tirth8205/code-review-graph。它的核心不是让模型“少理解代码”，而是先为仓库建一张本地关系图，让模型在读源码前先知道：该读什么、谁会受影响、测试在哪里。

一句话判断：如果你经常让 Claude Code、Codex、Cursor 做评审、排查或跨文件重构，code-review-graph 值得先在一个真实仓库跑通；但它不是“token 立减 82 倍”的开关，图谱是否漏关系、Agent 是否真的按图谱工作，都要自己验证。

本文适合：代码库已经不小、改动常跨模块、且日常高频使用 Coding Agent 的开发者。只想找一个函数定义，IDE/LSP 往往已经足够；图谱的价值主要在“关系”和“影响范围”。

先把问题说透：Agent 不是读不懂，而是读得太多

传统 Agent 面对一次改动，通常要靠目录浏览、全文搜索和连续读文件摸索。这个过程并不荒唐，人接手陌生项目也会这么做；问题在于，模型会把工具返回的内容持续带进上下文。一次多读似乎没什么，几十轮搜索和文件读取叠在一起，就会挤占真正用来判断逻辑和设计修复方案的空间。

code-review-graph 的解法是把探索拆成两步：先查关系，后读实现。

这里有个容易误解的点：图谱不是用摘要代替源码。真正要修改 validate_session() 时，模型仍应该读函数实现、调用方和测试；应该被省掉的，是后来证明根本无关的那一大圈文件。

用一分钟看懂它的技术实现

它的主链路并不神秘，但把几个可靠的基础组件拼到了 Agent 工作流里：

源文件
  → Tree-sitter 解析 AST
  → 抽取节点和关系
  → SQLite 持久化图谱
  → 增量更新变更文件
  → MCP / CLI 查询影响范围
  → Agent 读取最小代码集合

1. Tree-sitter：从“文本匹配”到“代码结构”

grep validateUser 只能告诉你这个字符串出现在哪里。它可能出现在注释、mock、旧代码甚至 README 中，却无法天然判断谁是定义、谁是调用。

Tree-sitter 会把源码解析成 AST（抽象语法树）。对图谱而言，比较有价值的不是整棵树，而是它能稳定抽出的结构：函数、类、方法、导入、调用点、继承关系，以及测试命名/目录信号。项目在 parser.py 中维护不同扩展名和节点类型的映射；新增语言时也需要把类、函数、导入、调用等节点类型补齐并加测试 fixture。

这样图里就不再只是“文件 A 包含文本 B”，而是类似下面的关系：

auth.ts ──defines──> validateSession
auth.middleware.ts ──calls──> validateSession
refresh.spec.ts ──tests──> validateSession
AuthController ──imports──> auth.middleware.ts

2. SQLite：把一次解析，变成可复用的仓库记忆

节点和边会持久化到仓库里的 .code-review-graph/ SQLite 数据中。这个设计很实用：Agent 不必每次新会话都重新扫完整仓库；CLI、MCP 甚至可视化界面也能围绕同一份本地图谱工作。

核心图谱不依赖外部数据库或云服务。项目也提供 FTS5 全文检索，以及可选的向量 embeddings；后者如果接入 Gemini、OpenAI-compatible 等外部端点，相关内容会发往你配置的服务。因此，第一次试用时建议先只开结构图谱，不开云端 embedding。

3. 增量更新：只重算发生变化的部分

图谱工具能否进入日常使用，不取决于第一次能不能建出来，而取决于你改完一行代码后它会不会过期。

code-review-graph 会比较变更文件，使用哈希检查定位依赖，再重解析发生变化的部分；watch 和对应平台的 hooks 可以让这一过程自动发生。官方给出了“2,900 文件项目的重新索引低于 2 秒”的案例，首次构建则给出“500 文件约 10 秒”的参考。硬件、语言与项目结构差异很大，拿自己的仓库压一轮才有意义。

4. MCP：让 Agent 先问图，再读代码

建完图并不是终点。关键在于把图谱能力以 MCP 工具交给 Agent，例如最小上下文、影响范围、调用/被调用关系、关联测试、风险审查上下文等。Agent 理想的调用顺序是：

先查变更符号
  → 找调用方、依赖方、测试
  → 计算 blast radius
  → 返回有 token 上限的最小上下文
  → 再读取必要源码，给出评审结论

这就是常说的 blast radius。它不是“自动判断改动一定安全”，而是先把人工 reviewer 或 Agent 最容易漏掉的关系摊开。对共享工具函数、鉴权、数据模型和跨模块接口改动尤其有用。

从安装到第一次评审：按这个步骤跑

下面以 Claude Code 为例。项目要求 Python 3.10+；如果装了 uv，安装器会优先使用 uvx 生成 MCP 配置。

第一步：安装并只配置一个客户端

pip install code-review-graph

# 只接入 Claude Code；也可替换为 codex、cursor 等
code-review-graph install --platform claude-code

install 会写入对应的 MCP 配置，并在支持的平台加入 hooks/skills 和图谱使用说明。完成后重启对应的客户端，确认它真的发现了 MCP server；不要只看命令成功就默认 Agent 一定会调用图谱。

第二步：在仓库根目录建图并检查状态

cd /path/to/your-repo
code-review-graph build
code-review-graph status

这一步建议先挑一个小型真实项目。你要看的不是漂亮的节点数，而是：是否解析到了你的主语言、常用模块和测试目录；如果这里就有大量缺失，后面的影响分析没有可信基础。

第三步：刷新图谱，查看当前改动的风险面板

# 仅检查工作区变化，不修改图谱
code-review-graph detect-changes --brief

# 先增量更新图谱，再输出同样的简要面板
code-review-graph update --brief

# 用 tiktoken 交叉核对面板中的 token 估算
code-review-graph detect-changes --brief --verify

detect-changes --brief 展示的“省了多少 token”，本质上是图谱返回的上下文与对照上下文之间的估算，不是你的模型账单下降了同样比例。系统提示、历史消息、推理、测试日志和最终输出仍然会消耗 token。

第四步：把评审任务说具体

图谱建好后，不要只发一句“帮我看看改动”。给 Agent 一个可验收的任务会更稳定：

请使用 code-review-graph 审查当前 git diff：
1. 先更新图谱并列出变更符号的调用方、依赖方和关联测试；
2. 只读取图谱返回的相关文件，必要时说明为什么扩展范围；
3. 按严重程度给出问题，并标出每条结论依赖的文件和测试；
4. 如果图谱无法确定动态调用或框架约定，请明确写出不确定性。

这段提示的重点不是强迫 Agent “永远不读别的文件”，而是让它对扩展阅读范围负责。能解释为什么多读一个文件，往往比盲目追求低 token 更可靠。

第五步：让图谱保持新鲜

# 开发期间自动监听文件变化
code-review-graph watch

# 需要将图谱服务暴露给 MCP 客户端时使用
code-review-graph serve

首次运行不建议立刻开全自动门禁。先在四类改动上做验证：改一行实现、删除一个符号、移动一个文件、跨模块修改接口。确认每次 update 后，调用方与测试集合都没有明显漏报，再考虑加入日常流程。

为什么它对“代码评审”特别合适

假设你只改了 validate_session() 的过期判断。一个合格的评审不应只看这一行：谁调用它？鉴权中间件是否依赖它？有没有 API 路由、刷新 token 流程或测试用例会受影响？

图谱先把这种传播路径给出来，再让 Agent 看源码。它最擅长的是“这次改动波及到哪里”，而不是替代所有代码搜索、文档搜索和业务理解。

这也是它和更通用的代码理解产品拉开差异的地方。选择工具前，先问自己的主任务：是 PR 审查，还是陌生仓库探索，还是要让 Agent 快速回答架构问题？

code-review-graph、GitNexus、CodeGraph 怎么选？

这三个项目都在做“让 Agent 少靠盲搜理解仓库”的事，但产品重心不同。下面的对比基于各自公开文档；版本、语言覆盖和基准会快速变化，真正接入前请以官方 README 为准。

几个更具体的判断：

• 主要目标是变更评审：优先试 code-review-graph。它把 detect-changes、影响半径、风险评分和测试缺口放在了主工作流里。
• 主要目标是人和 Agent 一起探索架构：GitNexus 更像一个可交互的知识图谱工作台。它将结构抽取进一步做了跨文件解析、功能社区和执行流程，并提供图形化界面；代价是系统面更大，需要评估索引成本和部署方式。
• 主要目标是让 Agent 用极少的工具调用完成架构问答：可以试 CodeGraph。它强调 Rust 内核、框架路由识别和“surgical context”；其公开基准也承认小仓库存在时间上的 floor effect，不能只看平均节省数字。

它们不是严格的替代关系。一个团队完全可能用 code-review-graph 做 PR 风险扫描，用 GitNexus 在新成员 onboarding 或架构梳理时看图。但不要一开始就三个都接上：每多一份索引、多一组 MCP 工具，Agent 的工具选择和维护复杂度也会上升。

“82×”该怎么读：方向可信，数字别照单全收

早期 README/传播材料中常见“6 个仓库、13 次提交，中位上下文缩减约 82×，范围 38×–528×”的说法；项目现在官网主推的口径则是“平均 8.2×”，并标为代表性结果、非保证值。两套数字并存，本身就提醒我们：先问清基线、任务和版本，再谈收益。

官方对照中包含“整仓源码进入上下文”的基线。它能漂亮地证明“不要整仓塞给 Agent”，却不等价于成熟 Agent 的真实工作流——一个会主动搜索、按需读文件的 Agent，本来就不会每次把整个仓库读完。

另一个要谨慎看待的指标是召回。影响分析最难的地方不是少返回几个文件，而是动态注册、反射、框架约定、生成代码或跨服务依赖会不会漏掉。漏掉一条，省下来的 token 反而可能换来一次错评。

所以更稳的目标不是“让图谱返回最少文件”，而是在不漏关键关系的前提下，稳定缩小阅读范围。对几十个文件的一次性小改动，建图和维护索引可能比直接搜索还高；对复杂仓库、高频评审和反复追调用链的场景，收益才会逐渐显现。

本地优先，隐私边界仍要看清

这是它很有吸引力的一点。默认情况下，AST 解析、关系图和 SQLite 数据都在本机/仓库目录内运行，官方称默认零遥测。对包含业务代码的团队，这比把整库上传到陌生索引服务更容易做安全评估。

不过“本地优先”不等于永远没有外发。启用云端 embedding 或 LLM 驱动的 wiki 等能力时，仍要按公司的代码外发和密钥策略检查配置。若只是验证结构图谱与影响分析，先保持默认本地模式即可。

上线前，按这张表验收

别急着把它写进团队门禁。拿同一个 commit，在没有图谱和有图谱时分别评审一次，然后记录下面几件事：

我建议先选一个小仓库跑通，再换中等体量项目连续观察几天。只有当节省下来的探索成本大于维护索引和调试 MCP 的成本，才值得放进日常工作流。

最后：少读错文件，比少花 token 更重要

模型能力当然重要，但在真实代码库里，先让它看到什么往往更重要。一个 20 万 token 的仓库，不需要在每次小改动时都变成 20 万 token 的提示词。先通过结构关系定位，再打开必要的实现，是人类开发者早就在做的事；code-review-graph 的价值，是把这套导航能力变成可以被 MCP 调用、可持续更新的基础设施。

如果你正在被跨文件调用链、测试范围和反复读取代码困扰，值得花半小时在自己的仓库验证一次。别先问“它能不能省 82 倍”，先问：它有没有让我少读错文件，同时没有漏掉该读的文件？ 这个答案稳了，token 节省才是可持续的副产品。

参考资料与延伸阅读

以下资料用于核验项目能力、公开基准口径与社区反馈；Star、版本和性能数据会持续变化，发布前建议再点开官方页面复核。

1. 官方仓库：tirth8205/code-review-graph
2. 官方 FAQ：与 Serena、CodeGraph 等的定位边界
3. 项目官网：本地优先、8.2×公开口径与工作方式
4. GitHub Releases：token-savings 面板与 --verify 说明
5. GitNexus 官方仓库：关系解析、流程和 Web UI
6. CodeGraph 官方仓库：Rust 内核、MCP 与框架路由能力
7. 社区讨论：图谱工具在不同代码库上的适配问题
8. 社区实测：多种 token 缩减工具的不同体验