code-review-graph —— 本地优先的代码智能图，用于MCP和CLI

这是什么

code-review-graph 是一个基于 Tree-sitter 的开源 Python 工具（GitHub 星标 19613），可为代码仓库构建结构化的知识图谱。它利用 AST 解析将代码转化为节点（函数、类、导入声明）和边（调用、继承、测试覆盖）组成的图，并借助 MCP（Model Context Protocol）为 AI 编程助手（如 Cursor、Claude Code、GitHub Copilot 等）提供精准的上下文，从而在代码审查、变更影响分析等场景中大幅减少 AI 读取的 token 量。

项目通过 pip install code-review-graph 安装，提供 install、build 等 CLI 命令，并可作为 GitHub Action 在 CI 中运行。

解决的问题

现代 AI 代码辅助工具（如 Cursor、Copilot、Claude Code）在执行代码审查或回答问题时，往往需要重新读取整个项目或大量文件，这导致 token 消耗巨大、响应速度慢，且容易引入无关信息。code-review-graph 的核心痛点正是 token 浪费：当文件发生变更时，AI 助手可能扫描整个代码库，而实际受影响的只有少数文件。

该工具通过实时构建增量更新的代码图谱，精确定位变更的“影响半径”（blast radius），只向 AI 暴露真正相关的函数、类、调用链和测试文件。例如，在 27,700+ 文件的巨型 monorepo 中，工具可将审查上下文压缩到仅约 15 个文件，token 中位数减少约 82 倍（基于 6 个开源仓库的基准测试，范围 38x–528x）。

核心功能

1. 自动安装与配置
   code-review-graph install 会自动检测用户已安装的 AI 编程工具（如 Codex、Cursor、Claude Code、Gemini CLI、Kiro、GitHub Copilot 等），为每个工具写入正确的 MCP 配置，并在支持的平台安装原生钩子/技能。同时根据安装方式（uvx、pip、pipx）生成相应配置。

2. 增量构建与图查询
   code-review-graph build 利用 Tree-sitter 解析仓库为 AST，存储为图结构。当文件保存或提交时，通过 SHA-256 哈希比较只重新解析变更部分，2,900 文件的项目重建时间不到 2 秒。支持树梢监视模式（watch mode）和 Git 钩子驱动的增量更新。

3. 多语言解析支持
   覆盖 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、ReScript、GDScript、Nix、Verilog/SystemVerilog、SQL、Vue/Svelte SFC、Astro、Jupyter Notebook 等。对于未内置的语言，用户可通过 languages.toml 自定义映射（提供语法名和节点类型），无需修改代码。

4. GitHub Action 集成
   作为 composite Action 运行，在 PR 上自动发布一个粘性评论，列出风险评分函数、受影响的执行流和测试缺口。支持 fail-on-risk 参数将审查变为合并门禁。所有代码分析在 CI runner 上本地完成，源代码不发送到外部服务。

5. Token 节省度量
   工具在每次调用时输出 context_savings 估计，CLI 中展示带框的 Token Savings 面板。使用 --verify 可交叉验证与 OpenAI cl100k_base 分词器的差异（实验中 222 个样本聚合误差 ~1%）。

亮点 / 与同类相比

• 极致 token 效率：中位数 82x 的 token 减少（最大 528x，测试于 fastapi 仓库），且通过严格可复现的基准测试（固定 SHA、Leiden 社区检测种子、确定性 CPU 嵌入）验证。与纯 grep 基线（agent_baseline）相比，图谱查询仍显著更优。
• 增量性与实时性：不同于传统全量代码分析工具，code-review-graph 支持增量构建，大型项目秒级完成。Git 钩子和监视模式确保图谱始终最新。
• MCP 原生集成：直接通过 MCP 协议与主流 AI 编辑器/CLI 工具交互，无需手动配置上下文窗口。install 命令自动完成所有配置，用户只需重启编辑器。
• 本地优先与隐私友好：无论是 CLI 还是 GitHub Action，所有解析和图计算均在本地运行，不泄露源代码。Action 仅需要一个 GitHub Token 来发布评论。
• 可扩展语言支持：通过自定义 languages.toml 即可支持社区未覆盖的语言，依赖 tree_sitter_language_pack 中的任意语法，无需修改核心代码。

适合谁用 / 上手

适合场景：

• 使用 AI 编程助手（Cursor、Claude Code、Copilot 等）进行代码审查或问答的开发团队，尤其关注 token 成本和响应速度。
• 维护大型 monorepo 的工程师，需要快速定位变更影响范围。
• 在 CI 中自动执行代码审查、合并门禁、风险分析的组织。
• 希望减少 AI 模型调用成本（token 计费）的个人或企业。

上手步骤：

1. 确保 Python 3.10+，推荐安装 uv（MCP 配置优先使用 uvx）。
2. 安装：pip install code-review-graph 或 pipx install code-review-graph。
3. 在项目根目录执行：code-review-graph install 自动配置已安装的 AI 工具。
4. 重启编辑器/工具，然后向 AI 提出请求：“Build the code review graph for this project”。
5. 初始构建约 10 秒（500 文件项目），此后增量更新自动生效。
6. 如需 CI 集成，在 .github/workflows/code-review-graph.yml 中添加 Action 步骤即可。