用代码图谱压缩 AI 审查上下文

别再浪费 token。开始更智能地审查代码。

English | 简体中文 | 日本語 | 한국어 | हिन्दी

用法 · 命令 · 常见问题 · 故障排除 · GitHub Action · 复现基准测试 · 路线图

AI 编程工具在执行代码审查任务时，可能会反复读取代码库中的大部分内容。code-review-graph 解决了这个问题。它使用 Tree-sitter 构建代码的结构化映射，以增量方式跟踪变更，并通过 MCP 为 AI 助手提供精准的上下文，使其只读取真正相关的内容。

pip install code-review-graph                     # or: pipx install code-review-graph
code-review-graph install          # auto-detects and configures all supported platforms
code-review-graph build            # parse your codebase

一条命令即可完成全部设置。install 会检测你安装了哪些 AI 编程工具，为每个工具写入正确的 MCP 配置，在受支持的平台上安装平台原生的 hooks/skills，并将能够感知图谱的指令注入平台规则中。它还会自动检测你是通过 uvx 还是 pip/pipx 安装，并生成相应的正确配置。安装后请重启编辑器或工具。

如需指定特定平台：

code-review-graph install --platform codex       # configure only Codex
code-review-graph install --platform cursor      # configure only Cursor
code-review-graph install --platform claude-code  # configure only Claude Code
code-review-graph install --platform gemini-cli   # configure only Gemini CLI
code-review-graph install --platform antigravity   # configure only Antigravity
code-review-graph install --platform windsurf     # configure only Windsurf
code-review-graph install --platform zed          # configure only Zed
code-review-graph install --platform continue     # configure only Continue
code-review-graph install --platform opencode     # configure only OpenCode
code-review-graph install --platform qwen         # configure only Qwen
code-review-graph install --platform qoder        # configure only Qoder
code-review-graph install --platform kiro         # configure only Kiro
code-review-graph install --platform copilot      # configure only GitHub Copilot (VS Code)
code-review-graph install --platform copilot-cli  # configure only GitHub Copilot CLI
code-review-graph install --platform codebuddy    # configure only CodeBuddy Code

需要 Python 3.10 或更高版本。为了获得最佳体验，请安装 uv（如果 uvx 可用，MCP 配置会使用它；否则会回退为直接使用 code-review-graph 命令）。

要从 Git 或 SVN 项目中移除 CRG，请在其工作树内的任意位置使用对应的 uninstall 命令。目标路径会被规范化为工作树根目录，非仓库目录将被拒绝。该命令只会删除 CRG 自己创建的文件和配置项；无关的 MCP 服务器、hooks、skills 和 JSONC 注释不会受到影响。共享配置的修改采用原子替换，因此即使写入失败，原始文件也会保持完整。

code-review-graph uninstall --dry-run    # preview every action; write nothing
code-review-graph uninstall              # preview, ask for confirmation, then apply
code-review-graph uninstall --yes        # apply without prompting
code-review-graph uninstall --all-repos  # also clean every registered repository
code-review-graph uninstall --keep-data  # remove integrations but keep graph databases
code-review-graph uninstall --keep-user-configs --repo .  # clean this project only

然后打开项目并向 AI 助手提出：

Build the code review graph for this project

对于包含 500 个文件的项目，初次构建大约需要 10 秒。完成后，监听模式和受支持的 hooks 可以自动保持图谱更新。

系统会使用 Tree-sitter 将你的仓库解析为 AST，并将其存储为由节点（函数、类、导入）和边（调用、继承、测试覆盖）构成的图谱。代码审查时，系统会查询该图谱，计算出 AI 助手需要读取的最小文件集合。

影响范围分析

当某个文件发生变更时，图谱会追踪所有可能受影响的调用方、依赖项和测试。这就是该变更的“影响范围”。你的 AI 只需读取这些文件，无需扫描整个项目。

数秒内完成增量更新

启用 hooks 或监听模式后，文件保存和受支持的提交 hooks 会触发增量更新。图谱会对变更文件执行 diff，通过图谱自身的导入边和调用边找出其依赖项，并且只重新解析 SHA-256 哈希值确实发生变化的文件。对于一个约含 3,000 个文件的项目（django），在 hooks 使用的更新路径上，修改两个文件后重新建立索引约需 2.5 秒，其中约 1.4 秒用于启动进程；未产生实际变更的更新只需承担这部分启动开销。完整测量结果请参阅“增量更新延迟”。

整个代码库，还是针对性答案？

仓库越大，浪费 token 带来的影响就越严重。图谱不会把整个代码语料库全部提供给模型，而是返回一个契合问题形态的内容切片：在这个仓库中，每个问题可将 208,821 个源代码 token 缩减至约 3,190 个 token。

广泛的语言支持 + Jupyter notebooks

解析器支持当前解析器覆盖范围内的函数、类、导入、调用位置、继承关系和测试检测；在可用时使用 Tree-sitter，并在需要时采用有针对性的后备方案。目前支持 Python、JavaScript/TypeScript/TSX、Go、Rust、Java、C/C++、C#、VB.NET、Ruby、Kotlin、Swift、PHP、Scala、Solidity、Dart、R、Perl、Lua/Luau、Objective-C、Shell 脚本、Elixir、Zig、PowerShell、Julia、ReScript、GDScript、Nix、Verilog/SystemVerilog、SQL、Terraform/OpenTofu 结构（.tf；通用 .hcl 文件会被识别为文件节点）、Ansible playbook/role/task、Vue/Svelte SFC、通过 TypeScript 解析器解析的 Astro 文件、Jupyter/Databricks Notebook（.ipynb），以及 Perl XS 文件（.xs）。通用 YAML 不会被视为源代码。

对于 PHP 项目，还会提供限定在仓库范围内的 Composer PSR-4 解析、Blade 模板引用，以及 Laravel Route/Eloquent 语义边，前提是源码中包含明确的框架导入、模型继承和接收者证据。

添加你自己的语言（无需 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 遍历器便会处理提取工作——无需修改代码，并且内置语言永远无法被覆盖。有关模式参考、验证规则以及完整的端到端示例，请参阅 docs/CUSTOM_LANGUAGES.md。

CI 中带风险评分的 PR 审查（GitHub Action）

同一套分析也以复合 GitHub Action 的形式运行，并且始终坚持本地优先：知识图谱完全在你的 CI runner 上构建和查询，不会将任何源代码发送给外部服务。每次提交拉取请求时，该 Action 都会发布一条固定评论，其中包含带风险评分的函数、受影响的执行流程和测试缺口；每次推送时，这条评论都会原地更新。可选的 fail-on-risk 输入可以将该审查变为合并门禁。

# .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@v7
      - uses: tirth8205/code-review-graph@v2.3.6
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

有关输入项、风险等级和缓存细节，请参阅 docs/GITHUB_ACTION.md；也可以查看本仓库用于自我验证的工作流 .github/workflows/pr-review.yml。

核心数据：在 6 个仓库中，每个问题的 token 用量减少中位数约为 65 倍（完整语料库基线与图查询对比）。376 倍的最高值来自单个表现最佳的仓库（fastapi，语料库规模最大），并非典型结果。

所有数据均来自针对 6 个真实开源仓库（共 13 个 commit）运行的自动化评估程序。每份配置都固定了上游 SHA，Leiden 社区检测器使用固定种子运行，嵌入也在 CPU 上以确定性方式生成——因此在不同机器上运行两次会得到完全相同的数据。包含预期输出的完整复现方法位于 docs/REPRODUCING.md。针对两个最小配置的每周仅报告运行位于 .github/workflows/eval.yml。

对于典型的 AI 智能体问题（“身份验证是如何工作的”“主入口点是什么”等），图谱会返回约 2,000～3,500 个 token 的定向搜索命中结果及邻接边，而不必强制 AI 智能体读取所有源文件。下表的数据是对 code_review_graph/token_benchmark.py 中定义的 5 个示例问题取平均值得出的。

在 6 个仓库中，每个问题的 token 用量减少中位数约为 65 倍。范围为 36～376 倍，其中 376 倍是最佳情况（fastapi，语料库规模最大），而非核心代表值。

这些数据于 2026-08-02 从固定 SHA 的全新克隆中重新采集（crg 2.3.7，使用本地 all-MiniLM-L6-v2 嵌入）。这些数据低于其所取代的 2026-05-25 采集结果：随着节点嵌入文本变得更加丰富，图谱响应也随之增大，因此每个仓库的平均 graph_tokens 均有所上升。fastapi 现在基于当前固定版本 22381558 进行测量，而不再使用已停用的 0227991a。

上面的完整语料库基线是一个实际上没有 AI 智能体会付出的上界：能力合格的 AI 智能体会通过 grep 搜索标识符，并且只读取匹配度最高的文件。agent_baseline 评估基准测量的是这种更符合实际的基线——使用纯 Python 在语料库上执行 grep，按匹配数量选取排名前三的文件，统计 token 数量，并将其与图查询成本进行比较（evaluate/results/<repo>_agent_baseline_*.csv）。

正式的 eval/benchmarks/token_efficiency.py 基准测试衡量的是另一种场景——将完整的 get_review_context() JSON 与某次 commit 中仅发生变更的文件内容进行比较——对于较小的 commit，其报告的比率会低于 1，因为审查上下文响应包含影响半径边和源码片段，体积可能超过一个很小的单文件 diff。这不是 bug；这两个基准测试回答的是不同的问题。完整的方法说明请参阅 docs/REPRODUCING.md。

从 v2.3.4 开始，审查和影响分析工具会附带一个紧凑的 context_savings 估算值，让 MCP 客户端能够查看每次调用大约节省了多少上下文。在 v2.3.5 中，CLI 将该信息显示为上图所示的带边框 Token Savings 面板（参见“Usage”部分中的“Token Savings panel”），并新增 --verify，可使用 OpenAI 的 cl100k_base 分词器进行交叉核验。docs/REPRODUCING.md 中的校准数据显示，在 222 个示例文件上的汇总结果中，该估算值与真实 GPT-4 token 数量的误差约为 1%。

在全部 13 个评估 commit 上，爆炸半径分析都能找回真实值中的每个文件——但应将其理解为上界，而不是“100% 召回率”：在此模式下，真实值（变更文件，以及通过调用边或导入边指向这些文件的文件）派生自预测器所遍历的同一张图，因此从设计上就是循环论证。精确率列中可见的过度预测是一种刻意的权衡：宁可标记过多文件，也不要漏掉已损坏的依赖关系。

该基准测试还运行了一种更可信的共同变更模式：以单个变更文件作为预测器的种子，并以作者在同一 commit 中实际修改的其他文件作为评判依据——这是来自 Git 历史、而不是来自图谱的相对独立证据。这两种模式并排出现在结果 CSV 中（ground_truth_mode 列）。截至 2026-08-02 的采集结果，该模式在每个参与评分的 commit 上都返回 predicted_files = 0，因此目前尚不能作为有效指标，本文也没有引用任何共同变更数据——在该模式能够反映准确性之前，需要先修复测试框架。

局限性和已知缺陷

影响分析的“召回率 1.0”由图谱派生且存在循环论证：历史真实值来自预测器所遍历的同一组图边，因此从设计上只能视为上界。与此同时还测量了更可信的共同变更模式（根据同一 commit 中实际共同变更的文件进行评分）；预计其数据会低得多。

小型单文件变更：对于简单编辑，图谱上下文可能比直接读取文件的内容更多（参见上面的 express 结果）。这些额外开销来自支持多文件分析所需的结构化元数据。

搜索质量（MRR 0.35）：对于大多数查询，关键词搜索都能在前 4 个结果中找到正确结果，但排序仍需改进。由于模块模式的命名方式，Express 查询会返回 0 个命中结果。

流程检测（召回率 33%）：Python 和 PHP/Laravel 对框架入口模式和约定式入口模式的支持最强。JavaScript 和 Go 的流程检测仍需改进。

精确率与召回率的权衡：影响分析有意采取保守策略。它会标记可能受到影响的文件，这意味着在大型依赖图中会出现一些误报。

code-review-graph install          # 自动检测并配置所有平台
code-review-graph install --platform <name>  # 指定特定平台
code-review-graph uninstall --dry-run  # 预览如何安全移除已安装的构件
code-review-graph build            # 解析整个代码库
code-review-graph update           # 增量更新（仅处理已更改的文件）
code-review-graph status           # 图统计信息
code-review-graph watch            # 文件发生变化时自动更新
code-review-graph visualize        # 生成交互式 HTML 图
code-review-graph visualize --format json      # 将本地图数据导出为 JSON
code-review-graph visualize --format graphml   # 导出为 GraphML
code-review-graph visualize --format svg       # 导出为 SVG
code-review-graph visualize --format obsidian  # 导出为 Obsidian 仓库
code-review-graph visualize --format cypher    # 导出为 Neo4j Cypher
code-review-graph wiki             # 根据社区生成 markdown wiki
code-review-graph detect-changes --brief         # 风险面板 + token 节省情况（只读）
code-review-graph update --brief                 # 刷新图并显示同一面板
code-review-graph detect-changes --brief --verify  # 与 tiktoken 交叉核验
code-review-graph register <path>  # 在多仓库注册表中注册仓库
code-review-graph unregister <id>  # 从注册表中移除仓库
code-review-graph repos            # 列出已注册的仓库
code-review-graph daemon start     # 启动多仓库监视守护进程
code-review-graph daemon stop      # 停止守护进程
code-review-graph daemon status    # 显示守护进程状态和仓库
code-review-graph eval             # 运行评估基准测试
code-review-graph serve            # 启动 MCP 服务器

JSON 导出文件会保留在本地图数据目录中，Git 默认会忽略该目录。这些文件可能包含绝对路径和代码结构元数据，因此在将导出文件发布到你的机器之外前，请先检查并清理其中的内容。

这两个命令都会输出同一个紧凑面板，显示与直接将已更改文件的原始内容交给 AI 智能体相比，图为你节省了多少 token。两者只有一点不同：是否先刷新图。

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

两者最后都会显示相同的面板，因为它们最终都会调用同一个 analyze_changes() 步骤。区别在于运行该分析前，图本身是否已刷新。

为任一命令添加 --verify，即可使用 OpenAI 的 cl100k_base 分词器（GPT-4 系列）交叉核验显示的数字。需要执行 pip install tiktoken。在典型的变更集中，估算结果与真实 token 数的误差保持在约 1% 以内——校准数据请参阅 docs/REPRODUCING.md。

相同的 context_savings 元数据也会自动附加到 get_impact_radius、get_review_context、detect_changes 和 get_architecture_overview 这些 MCP 工具的 JSON 响应中，因此 AI 智能体无需任何额外提示，就能在聊天中向人类展示节省情况。

如果你的编辑器不支持钩子（例如 Cursor、OpenCode），或者你只是希望图在后台保持最新而不进行任何编辑器集成，那么守护进程正适合你。它会监视仓库中的文件变化并自动重建图——不再需要手动执行 build 或 update 命令。

守护进程已包含在 code-review-graph 中，无需单独安装。

# 1. 注册你想要监视的仓库
crg-daemon add ~/project-a --alias proj-a
crg-daemon add ~/project-b

# 2. 启动守护进程（在后台运行）
crg-daemon start

# 3. 就这样——图会自动保持最新
crg-daemon status                 # 检查守护进程和各仓库监视器的状态
crg-daemon logs --repo proj-a -f  # 持续查看特定仓库的日志
crg-daemon stop                   # 停止守护进程和所有监视器进程

也可以通过 code-review-graph daemon start|stop|status|... 使用这些功能。

在底层，crg-daemon add 会写入位于 ~/.code-review-graph/watch.toml 的 TOML 配置文件。你也可以直接编辑此文件：

[[repos]]
path = "/home/user/project-a"
alias = "proj-a"

[[repos]]
path = "/home/user/project-b"
alias = "project-b"

守护进程会监视此配置文件的变化，并在添加或移除仓库时自动启动或停止监视器进程。每 30 秒执行一次的健康检查会重启已停止运行的监视器。无需外部依赖。

完整的配置参考和所有可用选项请参阅 docs/COMMANDS.md。

图构建完成后，你的 AI 助手会自动使用这些功能。

MCP 提示词（5 个工作流模板）：review_changes、architecture_map、debug_issue、onboard_developer、pre_merge_check

要排除不希望编入索引的路径，请在仓库根目录中创建 .code-review-graphignore 文件：

generated/**
*.generated.ts
vendor/**
node_modules/**

注意：在 git 仓库中，只会索引已跟踪的文件（git ls-files），因此 gitignore 中的文件会被自动跳过。可使用 .code-review-graphignore 排除已跟踪的文件，或者在 git 不可用时排除文件。

可选依赖组：

pip install "code-review-graph[embeddings]"          # 本地向量嵌入（sentence-transformers）
pip install "code-review-graph[google-embeddings]"   # Google Gemini 嵌入
pip install "code-review-graph[communities]"         # 社区检测（igraph）
pip install "code-review-graph[enrichment]"          # Python 调用解析增强（Jedi）
pip install "code-review-graph[eval]"                # 评估基准测试（matplotlib）
pip install "code-review-graph[wiki]"                # 使用 LLM 摘要生成 Wiki（ollama）
pip install "code-review-graph[all]"                 # 所有可选依赖

环境变量

兼容 OpenAI 的嵌入服务（真正的 OpenAI、Azure，或任何自行托管的网关，如 new-api / LiteLLM / vLLM / LocalAI / 采用 openai 模式的 Ollama）无需额外安装——只需设置环境变量，并向 embed_graph 传入 provider="openai"：

export CRG_OPENAI_BASE_URL=http://127.0.0.1:3000/v1     # 或 https://api.openai.com/v1
export CRG_OPENAI_API_KEY=sk-...
export CRG_OPENAI_MODEL=text-embedding-3-small          # 你的网关所提供的任意模型
# 可选：
export CRG_OPENAI_DIMENSION=1536                        # 固定维度（v3 模型支持降维）
export CRG_OPENAI_BATCH_SIZE=100                        # 对限制严格的网关使用较小的值
                                                        #（例如 Qwen text-embedding-v4 的上限为 10）

当基础 URL 指向 localhost（127.0.0.1、l