AI 代码审查的 token 困境：code-review-graph 如何用代码图谱砍掉 98% 的上下文

AI coding agent 在做代码审查时，最浪费的不是算力，是 token。一个中等规模的 Python 项目（比如 Flask）全量喂给模型，消耗 125,022 个 token；而 code-review-graph 这个开源工具给出的答案是：你只需要读 1,986 个 token 的精准上下文就够了。

这个差距是 71.4 倍。在 FastAPI 这种更大规模的项目上，差距拉到 528 倍。

code-review-graph（CRG）在 2026 年 7 月 20 日登上 GitHub Trending 榜首，日增 663 颗星，总星数突破 22,000。它的定位很明确：为 MCP（Model Context Protocol）和 CLI 构建一个本地优先的代码知识图谱，让 AI coding agent 只读该读的代码。

核心问题：为什么 AI 审查代码那么费 token

当前主流的 AI coding agent（Claude Code、Cursor、Copilot、Codex 等）在执行代码审查时，面临一个结构性困境：要判断一处改动的影响范围，agent 需要知道谁调用了这个函数、谁继承了这个类、哪些测试覆盖了这段逻辑。获取这些信息最直接的方式是把整个仓库的源码塞进上下文窗口。

对于一个小项目这不算问题。但当你的 monorepo 有 2,900 个文件、20 万行代码时，每次审查任务都全量读取意味着巨大的 token 开销——按 GPT-4 的定价，一次审查可能花费数美元，而且大部分 token 花在了与本次改动完全无关的文件上。

更隐蔽的问题是：全量上下文反而可能降低审查质量。模型注意力在 20 万 token 的噪声中分散，关键调用链被淹没在无关代码里。

code-review-graph 怎么解决

CRG 的架构是一个五阶段流水线，全部在本地运行，不依赖任何云服务：

第一阶段：Tree-sitter 解析。 用 Tree-sitter 把源码解析为 AST（抽象语法树），提取函数、类、导入、调用点、继承关系、测试覆盖等结构信息。支持 30 多种语言——从 Python、TypeScript、Go、Rust 到 Solidity、Verilog、GDScript，还包括 Jupyter Notebook。

第二阶段：SQLite 图存储。 解析出的结构信息存入本地 SQLite 文件（.code-review-graph/ 目录下），以节点（函数、类、导入）和边（调用、继承、测试覆盖）的形式组织。一个 1,122 文件的 FastAPI 仓库，生成 6,285 个节点和 27,117 条边。

第三阶段：社区检测。 用 Leiden 算法对图做社区聚类，自动发现代码中的逻辑模块。这为架构分析、知识缺口检测、跨社区耦合发现提供了基础。

第四阶段：Blast-radius 分析。 当文件发生变更时，CRG 从变更点出发做 BFS（广度优先）遍历，追踪所有调用者、依赖者和测试——这就是"爆炸半径"。你的 AI agent 只需要读这些文件，而不是整个项目。

第五阶段：最小审查集。 遍历的结果是一个 token 优化的上下文包，包含受影响的函数、执行流和测试缺口，附带风险评分。AI agent 拿到的是"答案形状的上下文"，而不是原始文件堆。

增量更新：2 秒内完成

全量构建一个 500 文件的项目大约需要 10 秒。但真正的价值在于增量更新：当 hooks 或 watch 模式启用时，文件保存和提交钩子会触发增量更新。CRG 对变更文件做 diff，通过 SHA-256 哈希找到依赖者，只重新解析变更的部分。

实测一个 2,900 文件的项目，增量重新索引在 2 秒以内完成。这意味着在你的 AI agent 需要审查之前，图谱已经是最新的。

Benchmark：6 个真实仓库的数据

CRG 的 benchmark 在 6 个开源项目上运行，涵盖 Python（FastAPI、Flask）、Go（Gin）、JavaScript/TypeScript（Express）、以及 CRG 自身：

6 个仓库的每问题 token 缩减中位数约为 82 倍。528 倍是最优情况（FastAPI，语料最大），不是典型值。

全量语料基线是一个理论上限——实际中一个合格的 agent 会先 grep 标识符，只读匹配度最高的文件。CRG 的 agent_baseline 评估就是测量这个更现实的基线。但即便如此，grep 方案无法获取结构化的调用链和影响范围信息，而图谱查询天然携带这些元数据。

影响精度

Blast-radius 分析在 13 个评估提交上达到了 0.714 的平均 F1 分数（精确率 0.578，召回率 1.0）。

这里的"召回率 1.0"有一个前提：评估用的 ground truth（变更文件 + 与之有调用/导入边的文件）本身就是从同一个图中推导的，所以这是一个循环上限，不能简单理解为"100% 召回"。设计上选择宁可多报也不漏报——精确率 0.578 意味着约 42% 的标记文件是误报，但漏报为零。对于代码审查场景，这个权衡是合理的：标记一个不需要审查的文件，成本是多读几百 token；漏掉一个有依赖的文件，成本是上线后出 bug。

构建性能

图查询延迟在毫秒级，对 agent 交互体验没有可感知影响。

MCP 集成：30 个工具，一键安装

CRG 的核心交付是一个 MCP 服务器，暴露 30 个工具供 AI agent 调用。安装过程高度自动化：

pip install code-review-graph
code-review-graph install    # 自动检测并配置所有支持的 AI 工具
code-review-graph build      # 解析你的代码库

install 命令会检测你安装了哪些 AI coding 工具，自动写入正确的 MCP 配置，安装平台原生 hooks，并把图谱感知的指令注入你的平台规则文件。支持的平台包括 Codex、Claude Code、Cursor、Windsurf、Zed、Continue、OpenCode、Gemini CLI、GitHub Copilot 等十多种。

安装完成后，你只需对 AI 助手说"Build the code review graph for this project"，agent 会自动调用 MCP 工具构建图谱，之后所有审查请求都会先经过图谱查询。

30 个 MCP 工具覆盖了从基础查询到高级分析的完整工作流：

• 上下文优化：get_minimal_context（~100 token 的超紧凑上下文）、get_impact_radius（blast radius）、get_review_context（token 优化的审查上下文）
• 图遍历：query_graph（调用者/被调用者/测试/导入/继承查询）、traverse_graph（带 token 预算的 BFS/DFS）
• 架构分析：get_architecture_overview、get_hub_nodes（最连接节点）、get_bridge_nodes（架构瓶颈）、list_communities
• 风险检测：detect_changes（风险评分的变更影响分析）、get_affected_flows（受影响的执行流）、get_knowledge_gaps（结构性弱点和未测试热点）

Token Savings 面板

每次 detect-changes 或 update 命令会输出一个紧凑的面板，直观显示节省了多少 token：

┌─────────────────────── Token Savings ────────────────────────┐
│ Full context would be:     12,921 tokens                     │
│ Graph context used:           762 tokens                     │
│ Saved:                     12,159 tokens (~94%)              │
│ Breakdown: Functions 244 · Tests 1919 · Risk 244 · Other 83  │
└──────────────────────────────────────────────────────────────┘

从 v2.3.4 起，这个 context_savings 估算值会附加到相关 MCP 工具的 JSON 响应中，AI agent 可以直接在对话中向用户展示节省效果。用 OpenAI cl100k_base tokenizer 做对比测试，估算值与真实 token 数的偏差在 1% 以内。

GitHub Action：CI 中的风险评分审查

同样的分析能力也打包为 GitHub Composite Action。在 CI runner 上本地构建和查询图谱——源码不会发送到任何外部服务。每个 PR 会在一个 sticky 评论中展示风险评分函数、受影响的执行流和测试缺口，并在每次推送时原地更新。

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: tirth8205/[email protected]
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

可选的 fail-on-risk 输入会把审查变成合并门禁——高风险变更自动阻止合并。

自定义语言支持

如果你的仓库用了 CRG 尚不支持的语言，不需要 fork。在 .code-review-graph/ 目录下放一个 languages.toml，映射文件扩展名到 tree_sitter_language_pack 中的任意语法，再指定 tree-sitter 的节点类型：

[languages.erlang]
extensions = [".erl"]
grammar = "erlang"
function_node_types = ["function_clause"]
class_node_types = ["record_decl"]
import_node_types = ["import_attribute"]
call_node_types = ["call"]

内置语言不会被覆盖，通用 tree-sitter walker 会处理后续的节点提取。

局限性

CRG 在文档中坦诚列出了已知弱点：

• 搜索质量（MRR 0.35）：关键词搜索能在前 4 个结果中找到正确答案，但排名需要改进。Express 查询因模块命名模式返回 0 个结果。
• 流检测（33% 召回率）：框架和约定入口模式对 Python 和 PHP/Laravel 最强，JavaScript 和 Go 的流检测需要改进。
• 小改动开销：对于单文件微小编辑，图上下文可能超过直接读文件的 token 消耗——额外的结构元数据是多文件分析的基础，但在琐碎变更上显得冗余。
• 精确率/召回率权衡：影响分析刻意保守，在大型依赖图中会产生一些误报。

它解决了什么真问题

AI coding agent 的 token 消耗不仅是成本问题，更是能力瓶颈。上下文窗口有限，每多读一个无关文件，模型对真正相关代码的注意力就稀释一分。CRG 的价值在于把"找相关代码"这个任务从语言模型拿走，交给确定性算法——Tree-sitter 解析是精确的，图遍历是可复现的，blast-radius 计算是 O(边数) 的。

这个思路和 RAG（检索增强生成）解决知识问答的思路一致：不要让模型自己找信息，给它结构化的检索结果。区别在于 RAG 用向量相似度检索文本块，CRG 用静态分析构建代码结构图。对于"一处改动会影响哪些代码"这类问题，结构图比向量相似度靠谱得多——调用关系是确定性的语义，不是概率性的相似度。

22,000 颗星的增长曲线说明开发者确实需要这个东西。AI coding 工具的用户体验瓶颈已经从"模型够不够聪明"转移到"上下文够不够准"，而后者是工具链问题，不是模型问题。code-review-graph 代表了 AI 开发工具栈的一个新方向：在模型和代码库之间，插入一个确定性的知识层。