開發工具

code-review-graph 教學：Codex/Claude Code PR 影響分析與 CI 增量建圖

安裝 code-review-graph，使用 Tree-sitter 與本機 SQLite 分析 PR 影響範圍、找出測試缺口，並為 Codex、Claude Code 提供精簡上下文，再安全接入 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 節省更重要。