code-review-graph：用代码依赖图让 AI 代码审查更精准、更省 Token

code-review-graph：用代码依赖图让 AI 代码审查更精准、更省 Token

一、核心观点

"停止燃烧 Token，开始智能审查。"

AI 编码工具在执行代码审查任务时，往往会重复读取大量无关代码，造成严重的 Token 浪费。code-review-graph 通过构建代码库的结构化依赖图，让 AI 助手只读取真正相关的文件，从而大幅降低 Token 消耗，提升审查效率。

二、关键信息

2.1 项目定位

code-review-graph

2.2 工作原理

代码库文件
    ↓ Tree-sitter 解析
AST（抽象语法树）
    ↓ 图结构化
节点（函数/类/导入）+ 边（调用/继承/测试覆盖）
    ↓ 审查时查询
最小相关文件集合 → 输出给 AI 助手（via MCP）

三个关键机制：

1. 爆炸半径分析（Blast-radius Analysis）
   • 文件变更时，图追踪所有调用者、依赖项和相关测试
   • AI 只读取这些受影响文件，而非扫描整个项目
2. 增量更新（< 2 秒）
   • 文件保存或 commit hook 触发增量更新
   • 通过 SHA-256 哈希差分，只重新解析变更文件
   • 2,900 个文件的项目重建索引 < 2 秒
3. Monorepo 漏斗过滤
   • 大型 Monorepo 中，27,700+ 文件被排除在审查上下文之外
   • 实际只读取约 15 个文件

2.3 支持平台

通过 code-review-graph install 自动检测并配置以下平台：

• Codex / Cursor / Claude Code / Gemini CLI
• Kiro / GitHub Copilot (VS Code) / GitHub Copilot CLI

2.4 语言覆盖范围

支持超过 30 种语言/格式，包括：

Python、JavaScript/TypeScript/TSX、Go、Rust、Java、C/C++、C#、Ruby、Kotlin、Swift、PHP、Scala、Solidity、Dart、R、Perl、Lua/Luau、Objective-C、Shell、Elixir、Zig、PowerShell、Julia、SQL、Vue/Svelte SFCs、Astro、Jupyter Notebooks（.ipynb）、Verilog/SystemVerilog 等

2.5 性能基准（Benchmark）

核心数据：中位数 Token 减少约 82 倍

⚠️ 注意：常被引用的 528x 是最优单案例（fastapi），中位数才是 ~82x，这是更真实的参考值。

• 典型问题的图返回约 2,000–3,500 tokens 精准命中内容
• Token 估算误差在 GPT-4 实际 Token 数的 ~1% 以内
• 影响精准度：平均 F1 = 0.71，Recall = 1.0（注：上界，因为 ground truth 来自同一图，存在循环验证）

三、代码 / 示例

3.1 快速开始

# 安装
pip install code-review-graph
# 或使用 pipx
pipx install code-review-graph
# 自动检测并配置所有支持平台
code-review-graph install
# 解析代码库，构建图
code-review-graph build

3.2 指定平台安装

code-review-graph install --platform cursor        # 仅配置 Cursor
code-review-graph install --platform claude-code   # 仅配置 Claude Code
code-review-graph install --platform copilot       # 仅配置 GitHub Copilot (VS Code)

3.3 自定义语言支持（无需 Fork）

在 .code-review-graph/languages.toml 中添加：

[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"]

3.4 GitHub Action 集成

# .github/workflows/code-review-graph.yml
on:
  pull_request:
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: tirth8205/code-review-graph@v2.3.6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

• 每次 PR 自动发布风险评分评论（含影响函数、执行流、测试缺口）
• 支持 fail-on-risk 参数作为合并门控
• 知识图谱完全在 CI Runner 本地构建，源码不发送到任何外部服务

四、个人启发

1. "只读相关"才是 AI 工具集成的正确姿势：大多数工具默认"给越多上下文越好"，但本项目证明精准的结构化上下文远优于海量的原始文本。这对所有 RAG 和 AI Agent 工程都有借鉴意义。
2. 图结构是代码理解的天然载体：函数调用、继承、测试覆盖本质上就是图关系，Tree-sitter + 图数据库的组合是解析代码语义的强力工具，值得在代码智能方向深入探索。
3. 本地优先（Local-first）是企业采用 AI 工具的关键：该项目强调图的构建和查询完全在本地/CI Runner 完成，源码不离开环境，这对安全敏感的企业场景至关重要，也是开源工具赢得信任的核心策略。
4. 基准测试要诚实：项目主动区分"最优案例 528x"和"中位数 82x"，这种透明度非常值得学习——好的技术文档应该帮助用户建立合理预期，而非只展示最好看的数字。

五、延伸思考

1. 图的更新策略与一致性：增量更新在 2 秒内完成，但在大型团队并发提交时，如何保证图的一致性和并发安全？是否需要类似数据库的 MVCC 机制？
2. AI 依赖图 vs 传统静态分析工具：code-review-graph 与 SonarQube、Semgrep 等静态分析工具的定位有何本质区别？二者是否可以互补——用静态分析找安全漏洞，用依赖图优化 AI 的上下文窗口？
3. "爆炸半径"过度预测的边界在哪里：项目刻意选择"宁可多报、不漏依赖"的策略，但在超大型 Monorepo 中，过度预测是否会抵消精准查询的收益？是否存在一个最优的预测精度与召回率平衡点？