开发工具

code-review-graph 教程：Codex/Claude Code PR 影响分析与 CI 增量建图

安装 code-review-graph，用 Tree-sitter 和本地 SQLite 为 Codex、Claude Code 提供 PR 影响半径、测试缺口和精简上下文，并安全接入 GitHub Actions 增量建图。

code-review-graph 是一个本地优先的代码结构图工具。它使用 Tree-sitter 解析代码，将调用、导入、继承、测试等关系写入仓库内的 SQLite 图数据库，再通过 CLI 和 MCP 为 Codex、Claude Code 等工具提供结构化上下文。

它解决的不是“让 AI 自动批准 PR”，而是减少 AI 每次审查都重新搜索整个仓库的成本，并帮助审查者定位跨文件调用、潜在影响范围和测试缺口。最终结论仍要回到 Git diff、测试结果和人工判断。

项目地址：tirth8205/code-review-graph

什么时候值得使用

比较适合：

  • 数百到数千文件的仓库；
  • monorepo 或多语言项目；
  • 经常审查跨文件、跨模块修改；
  • 需要追踪调用者、依赖、测试和执行流；
  • 希望核心图数据保留在本地。

不一定适合：

  • 只有少量文件的小项目；
  • 修改集中在单个独立文件；
  • 主要审查文档、配置或图片；
  • 团队不准备维护索引新鲜度；
  • 一次性任务，直接读取 diff 更快。

小 diff 可能出现图查询结果比原 diff 更大的情况。应先用最小上下文和变更检测，再决定是否展开影响半径。

工作原理与数据边界

主要流程是：

1
2
3
4
5
6

Git 跟踪文件
  -> Tree-sitter 解析
  -> 节点与关系
  -> .code-review-graph/ SQLite
  -> CLI / MCP 查询
  -> Codex、Claude Code 或人工审查

核心构图和查询可以在本地完成，不要求把代码上传到云端。可选 embeddings 可能使用本地模型或云提供商；启用云 embeddings 前应确认代码发送边界和团队政策。

在 Git 仓库中，默认只索引 git ls-files 返回的已跟踪文件。要排除仍被 Git 跟踪的生成文件或第三方代码，在仓库根目录创建：

1
2
3
4
5

# .code-review-graphignore
generated/**
*.generated.ts
vendor/**
node_modules/**

图数据库通常位于：

1

.code-review-graph/

它属于可重建产物，不应无条件提交到 Git。

安装前准备 Python 环境

项目要求 Python 3.10 或更高版本：

1
2

python --version
git --version

推荐使用 pipx 隔离全局 CLI：

1
2
3

python -m pip install --user pipx
python -m pipx ensurepath
pipx install code-review-graph

也可以直接安装：

1

python -m pip install code-review-graph

安装后验证：

1
2

code-review-graph --help
code-review-graph status

若 shell 找不到命令，优先检查 Python Scripts 或 pipx 的 bin 目录是否进入 PATH，不要反复安装多个副本。

为 Codex 或 Claude Code 配置 MCP

统一安装命令会检测已安装的平台：

1

code-review-graph install

只配置 Codex：

1

code-review-graph install --platform codex

只配置 Claude Code：

1

code-review-graph install --platform claude-code

安装器会写入相应 MCP 配置，并在支持的平台加入 hooks、Skills 或规则说明。执行前备份已有配置，执行后检查 diff，避免误覆盖团队自定义项。

完成后重启 AI 工具。Claude Code 可以通过 /mcp 检查连接；其他客户端应确认 code-review-graph server 已连接并列出工具。

首次构建代码图

进入要分析的仓库根目录：

1
2
3
4

git rev-parse --show-toplevel
git status --short
code-review-graph build
code-review-graph status

status 至少应显示非零文件、节点和边数量，并记录构建分支与提交。若节点为零，常见原因包括：

  • 当前目录不是目标仓库；
  • 文件未被 Git 跟踪；
  • 扩展名未被解析器识别；
  • .code-review-graphignore 排除了全部内容；
  • 构建中途失败。

正式使用前，选一个已知函数测试结构查询，确认调用关系能回到真实文件。

日常更新与变更检测

代码变化后运行增量更新：

1
2

code-review-graph update
code-review-graph status

需要简洁输出和上下文节省信息时：

1
2

code-review-graph update --brief
code-review-graph detect-changes --brief

update 更新变化文件；detect-changes 分析当前 Git 变更和影响。两者含义不同，不应因为 detect-changes 能运行就假设图已经最新。

长时间开发可以使用：

1

code-review-graph watch

但在大型仓库中应观察 CPU、文件监听上限和生成目录噪声；CI 环境通常更适合显式执行 build 或 update。

让 Codex 或 Claude Code 审查 PR

安装 MCP 并完成构图后，可以提出：

1
2
3

使用 code-review-graph 审查当前分支相对 main 的变化。
先检测变更，再给出跨文件影响、调用者、相关测试和测试缺口。
只读取必要上下文；所有结论附上文件路径，并与 git diff 对照。

项目也提供工作流模板，例如：

  • review_changes：审查当前变化；
  • architecture_map：理解架构；
  • debug_issue：沿关系排查故障；
  • onboard_developer：生成上手上下文；
  • pre_merge_check：合并前检查。

无论使用模板还是自由提示，都应保持顺序：

  1. 确认图数据库新鲜；
  2. 读取实际 Git diff；
  3. 查询变化节点；
  4. 展开调用者、依赖和测试；
  5. 运行真实测试；
  6. 人工审查结论。

如何解释 Token 节省

当前 CLI 可以在 detect-changes --brief 和 update --brief 中显示上下文节省面板。默认数字属于项目定义的估算，不等于账单中的精确 Token。

要用 tokenizer 交叉验证，需要额外安装依赖并加 --verify：

1
2

python -m pip install tiktoken
code-review-graph detect-changes --brief --verify

评估时记录：

  • 原始 diff 和仓库规模；
  • 图返回的上下文长度；
  • AI 实际继续读取的文件；
  • 漏报与误报；
  • 审查耗时；
  • 测试是否发现图中未提示的问题。

不要把官方基准中的最高倍数直接套进团队预算。小仓库、单文件修改、语言解析覆盖和提问方式都会改变结果。

GitHub Actions 示例的定位

下面是本站整理的自维护示例，不是项目官方发布的 GitHub Action。它只安装 CLI、恢复本地图缓存、执行增量更新和输出报告，不自动批准 PR，也不把结果写回评论区。

先创建：

1

.github/workflows/code-review-graph.yml

示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

name: code-review-graph

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read

jobs:
  impact:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install
        run: python -m pip install code-review-graph

      - name: Restore graph cache
        id: graph-cache
        uses: actions/cache@v4
        with:
          path: .code-review-graph
          key: crg-${{ runner.os }}-${{ github.event.pull_request.base.sha }}
          restore-keys: |
            crg-${{ runner.os }}-

      - name: Build or update graph
        shell: bash
        run: |
          if [ -d .code-review-graph ]; then
            code-review-graph update --brief
          else
            code-review-graph build
          fi
          code-review-graph status

      - name: Analyze changes
        run: code-review-graph detect-changes --brief | tee crg-review.txt

      - name: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: code-review-graph-report
          path: crg-review.txt
          if-no-files-found: warn

首次启用时建议先去掉缓存步骤，确认干净构建成功，再加入缓存。缓存不是正确性的来源；解析器、schema 或项目结构变化后应允许完整重建。

缓存键与图新鲜度

示例把 PR 基线提交放进缓存键，目的是减少不同基线之间直接复用旧图的概率。还可以加入依赖锁文件摘要：

1

key: crg-${{ runner.os }}-${{ hashFiles('pyproject.toml', 'package-lock.json') }}-${{ github.event.pull_request.base.sha }}

以下情况应删除缓存并重新 build：

  • 升级 code-review-graph 或 Tree-sitter 解析器；
  • 修改排除规则；
  • 大规模重命名目录；
  • 图统计异常下降；
  • 本地和 CI 结果无法复现；
  • schema 或数据库兼容性发生变化。

验收缓存命中不能只看 Actions 显示 cache-hit，还要检查 status 的分支、提交、文件数、节点数和边数。

Fork PR 的权限边界

核心分析只需要读取检出的源码，不需要仓库写权限，也不应使用部署 Secret。推荐保持：

1
2

permissions:
  contents: read

不要在未经审查的 Fork 代码上使用 pull_request_target 检出 PR head 后执行命令；这种组合可能暴露基础仓库权限或 Secret。

若未来要自动发布评论，应拆成独立的受控步骤，并对报告内容、权限和来源进行审查。最安全的首版只上传 artifact，由维护者查看。

Monorepo 与超大变更

monorepo 中可以用 .code-review-graphignore 排除明确不参与审查的生成目录和 vendor。不要为了速度排除共享库，否则影响分析会失去跨包关系。

非常大的 diff 应先取得文件列表：

1

git diff --name-only origin/main...HEAD

如果 MCP 自动检测长时间无响应，可以把明确的变化文件列表传给影响分析工具，避免后端重复执行范围过大的 Git 检测。

项目还提供边界环境变量用于限制超大前沿，例如 CRG_MAX_CHANGED_FUNCS、CRG_MAX_TRANSITIVE_FRONTIER 和 CRG_TOOL_TIMEOUT。调整前先记录默认行为，限制过低会减少召回。

Windows MCP 连接与卡顿排查

CLI 正常但 MCP 报 Invalid JSON: EOF while parsing 或 Connection closed 时：

  1. 升级 code-review-graph；
  2. 重新执行 install 更新配置；
  3. 确认 FastMCP 版本满足项目当前要求；
  4. 让 MCP 直接执行虚拟环境中的 .exe；
  5. 设置 PYTHONUTF8=1；
  6. 重启客户端并查看 MCP 日志。

示意配置：

1
2
3
4
5
6
7

{
  "code-review-graph": {
    "command": "C:\\path\\to\\venv\\Scripts\\code-review-graph.exe",
    "args": ["serve", "--repo", "C:\\path\\to\\project"],
    "env": {"PYTHONUTF8": "1"}
  }
}

CLI 的 status、detect-changes 很快，但 MCP 调用超时时，先把 git diff --name-only 的结果显式传给工具，区分 Git 变化检测慢和图查询慢。

图数据错误时如何恢复

先记录现场：

1
2
3

code-review-graph status
git rev-parse HEAD
git status --short

然后执行增量更新：

1
2

code-review-graph update
code-review-graph status

若结果仍异常，备份或删除可重建的 .code-review-graph 目录，再完整构建。删除前确认目录确实位于目标仓库，避免误删其他数据。

升级后也应重新运行：

1
2
3

python -m pip install -U code-review-graph
code-review-graph install
code-review-graph build

install 用于刷新平台配置，build 用于刷新图数据，两步不要混为一谈。

卸载与回滚

先预览：

1

code-review-graph uninstall --dry-run

确认后卸载：

1

code-review-graph uninstall

只移除集成、保留图数据：

1

code-review-graph uninstall --keep-data

之后检查 Codex、Claude Code 等配置中是否仍有残留 MCP 项，并确认原有配置备份可以恢复。

最终验收清单 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

[ ] Python 版本至少为 3.10
[ ] CLI --help 和 status 可运行
[ ] build 后文件、节点和边数量非零
[ ] .code-review-graph 已加入忽略策略
[ ] Codex 或 Claude Code 能列出 MCP 工具
[ ] update 后图对应当前分支与提交
[ ] detect-changes 结果能回到真实 Git diff
[ ] 影响范围和测试缺口经过人工核对
[ ] Token 节省区分估算与 --verify 结果
[ ] CI 仅有 contents: read 权限
[ ] Fork PR 不接触 Secret
[ ] 缓存失效时可以完整重建
[ ] 卸载和恢复步骤已验证

总结

code-review-graph 适合作为 AI 代码审查的结构索引，而不是自动审批器。稳定流程是：在正确仓库构图，保持增量更新，通过 MCP 取得最小必要上下文，再用 Git diff、测试和人工审查确认结论。

接入 GitHub Actions 时应先保证干净构建可复现，再逐步加入缓存和 artifact。权限保持只读，Fork PR 不使用 Secret，图失效时能够退回普通 diff 和完整重建，这比追求一次基准中的最高 Token 节省更重要。