code-review-graph 怎麼用：給 Codex 和 Claude Code 新增 PR 影響分析

code-review-graph 是一個本地優先的程式碼知識圖譜工具，目標是減少 AI 程式碼審查時反覆讀取整個倉庫的問題。它使用 Tree-sitter 解析函式、類、匯入、呼叫、繼承和測試關係，將結果儲存到專案內的 SQLite 資料庫，再透過 MCP、CLI、Skills 和鉤子提供給 Codex、Claude Code、Cursor 等 AI 程式設計工具。

它尤其適合大型倉庫、monorepo 和跨檔案 PR：當某個函式發生變化時，圖譜可以沿呼叫與依賴關係計算影響半徑，告訴 AI 哪些呼叫者、測試和執行流更值得檢查。

快速結論

需要 Python 3.10 或更高版本。
安裝後執行 code-review-graph install，工具會檢測已安裝的 AI 程式設計平臺並寫入對應 MCP 配置。
首次使用要執行 code-review-graph build，之後可用 update、watch 或平臺鉤子增量維護圖譜。
資料預設儲存在專案的 .code-review-graph/，核心構圖和查詢不要求把原始碼傳送到外部服務。
簡單的單檔案修改不一定省 Token；跨檔案呼叫、測試影響和大型倉庫審查更能體現圖譜價值。

安裝 code-review-graph

推薦使用獨立的 Python 工具環境，避免汙染專案依賴：

1

pipx install code-review-graph

也可以直接使用 pip：

1

pip install code-review-graph

進入需要分析的 Git 倉庫後執行：

1
2
3


code-review-graph install
code-review-graph build
code-review-graph status

install 會檢測 Codex、Claude Code、Cursor、Windsurf、Zed、Continue、OpenCode、Gemini CLI、GitHub Copilot 等受支援平臺，生成合適的 MCP 配置和平臺規則。完成後需要重啟編輯器或 AI 程式設計工具。

如果只想配置一個平臺，可以指定名稱：

1
2
3
4


code-review-graph install --platform codex
code-review-graph install --platform claude-code
code-review-graph install --platform cursor
code-review-graph install --platform gemini-cli

使用 uvx、pip 或 pipx 安裝時，install 會盡量識別實際入口並生成對應配置。若 MCP 啟動失敗，應先確認終端裡可以直接執行：

1
2


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

它如何縮小程式碼審查上下文

構圖流程可以簡化為：

1

代码仓库 -> Tree-sitter AST -> SQLite 图谱 -> 影响半径 -> 最小审查文件集

圖中的節點包括函式、類、檔案和匯入，邊則表示呼叫、繼承、測試覆蓋等關係。PR 修改一個檔案後，工具會查詢：

哪些函式和類直接發生變化；
哪些呼叫者或依賴可能受影響；
哪些執行流經過這些節點；
是否存在對應測試，以及測試覆蓋是否有缺口；
AI 審查時最值得讀取哪些檔案。

這樣，AI 不必只依賴檔名搜尋，也不必預設掃描整個倉庫。對於跨模組呼叫和不熟悉的程式碼庫，這比單純把 PR diff 丟給模型更容易發現間接影響。

如果你想了解通用程式碼知識圖譜與架構分析，可對比 CodeGraph 原生代碼知識圖譜教程和 Graphify 的 Claude Code 圖譜工作流。code-review-graph 的定位更偏向變更影響、風險評分和 PR 審查。

在 Codex 或 Claude Code 中使用

完成安裝和構圖後，可以直接向 AI 助手提出任務：

1

Build the code review graph for this project

專案還提供 3 個常用斜槓命令：

1
2
3


/code-review-graph:build-graph
/code-review-graph:review-delta
/code-review-graph:review-pr

一個實用的審查流程是：

在倉庫根目錄確認 code-review-graph status 正常；
修改程式碼或切換到待審查分支；
執行 code-review-graph update 更新變化部分；
在 Codex 或 Claude Code 中執行 review-delta 或 review-pr；
先看影響半徑、風險函式和測試缺口，再讓 AI 閱讀必要原始碼；
最後執行專案原有測試，而不是把圖譜結果當成測試替代品。

CLI 也提供對應的日常命令：

1
2
3
4
5
6


code-review-graph build
code-review-graph update
code-review-graph status
code-review-graph watch
code-review-graph detect-changes
code-review-graph visualize

watch 適合持續開發；detect-changes 用於分析當前變更；visualize 會生成互動式 HTML 圖，便於檢視程式碼社群、Hub、Bridge 和異常耦合。

MCP 工具應該先呼叫哪個

專案提供多種 MCP 查詢工具。日常對話不必一次取回完整圖譜，建議從最小上下文開始：

目的	建議工具
先取得極簡入口	`get_minimal_context_tool`
檢視某個變更的影響範圍	`get_impact_radius_tool`
獲取審查所需上下文	`get_review_context_tool`
查詢呼叫者、測試、匯入或繼承	`query_graph_tool`
檢視受影響的執行流	`get_affected_flows_tool`
檢查風險與測試缺口	`detect_changes_tool`
理解整體架構	`get_architecture_overview_tool`

如果 MCP 工具沒有出現，可參考 MCP 工具呼叫失敗排查指南，重點檢查配置檔案位置、命令是否在 PATH 中、工作目錄和編輯器是否已經重啟。

讓圖譜保持最新

首次 build 之後，不需要每次重建整個倉庫。可以手動增量更新：

1

code-review-graph update

也可以持續監聽：

1

code-review-graph watch

啟用受支援的平臺鉤子後，儲存檔案或提交時可以觸發增量更新。官方 README 給出的示例中，一個約 2,900 檔案的專案只重新解析少量變更檔案時可在 2 秒內更新，但實際時間仍取決於倉庫大小、語言、磁碟和後處理功能。

如果生成檔案、vendor 或大型目錄已經被 Git 跟蹤，但不希望進入圖譜，可在倉庫根目錄建立 .code-review-graphignore：

1
2
3
4


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

在 Git 倉庫中，工具預設以 git ls-files 為索引範圍，因此 Git 未跟蹤和 .gitignore 排除的檔案通常不會被索引。

接入 GitHub Action 做 PR 風險檢查

code-review-graph 還可以在 GitHub Actions 中執行。官方 README 當前示例為：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


name: Code Review Graph

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: tirth8205/[email protected]
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Action 會在 CI Runner 本地構圖和查詢，並給 PR 寫入風險函式、受影響執行流和測試缺口。正式採用前應檢查倉庫最新 Release 或 README，固定明確版本，不要長期複製可能過期的示例版本。

如果團隊只想觀察結果，可以先讓工作流發表評論；確認誤報率和速度可以接受後，再考慮啟用 fail-on-risk 作為合併門禁。

如何正確理解 Token 節省基準

官方英文 README 報告，在 6 個真實開源倉庫的逐問題測試中，相對於“讀取整個程式碼語料庫”的基線，中位 Token 縮減約為 82 倍，範圍約 38 至 528 倍。528 倍來自單個最佳樣本，不是一般專案都能達到的結果。

閱讀這些數字時要注意：

全量讀取倉庫是偏理想化的上界，成熟 Agent 本來就會先搜尋再讀取少量檔案；
對很小的單檔案修改，圖譜返回的邊、影響範圍和結構摘要可能比直接讀取 diff 更大；
影響分析的部分召回率基準使用同一圖譜派生的 ground truth，存在迴圈性，應視為上界；
搜尋排序、JavaScript 和 Go 執行流檢測仍有已知改進空間；
圖譜傾向多報一些潛在受影響檔案，以降低漏掉依賴的風險。

因此，不要把“最高 528 倍”寫進團隊成本預算。更可靠的方法是在自己的倉庫中對比同一批 PR：記錄 AI 實際讀取檔案數、上下文長度、誤報、漏報和審查耗時。

常見問題排查

安裝後 AI 看不到 MCP 工具

先檢查：

1
2


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

然後重新執行指定平臺安裝並重啟工具：

1

code-review-graph install --platform codex

如果使用虛擬環境安裝，AI 工具啟動時可能找不到同一個 Python 環境。pipx 或 uvx 通常更適合作為全域性 CLI 入口。

圖譜結果沒有包含新程式碼

先執行：

1
2


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

同時確認新檔案已經被 Git 跟蹤，沒有被 .gitignore 或 .code-review-graphignore 排除。必要時執行完整的 build。

小 PR 的上下文反而更多

這是圖譜結構後設資料帶來的固定開銷。對於只改一行且沒有依賴的修改，直接讀 diff 更快。可以讓 AI 先呼叫 get_minimal_context_tool，只有發現跨檔案影響時再展開完整審查上下文。

如何安全解除安裝

先預覽將要刪除的內容：

1

code-review-graph uninstall --dry-run

確認後再執行：

1

code-review-graph uninstall

如果只想移除整合但保留圖譜資料，可使用：

1

code-review-graph uninstall --keep-data

適合哪些專案

比較適合：

有大量跨檔案呼叫的大型程式碼庫；
monorepo、多語言倉庫和多人協作專案；
經常用 Codex、Claude Code 或 Cursor 審查 PR；
需要追蹤呼叫者、測試缺口和執行流；
不希望核心程式碼圖依賴外部雲資料庫。

不一定需要：

只有少量檔案的小專案；
主要審查文件或配置變更；
每次修改都侷限在單個、獨立檔案；
團隊沒有維護索引和處理誤報的意願。

總結

code-review-graph 為 AI 程式碼審查增加了一層可持續更新的結構索引。它可以幫助 Codex、Claude Code 等工具從“搜尋看起來相關的檔案”，進一步走向“沿呼叫、依賴和測試關係分析變更影響”。

實際使用時，先從一個常見 PR 開始：安裝、構圖、執行增量審查，再把結果與人工審查和真實測試對照。若它能穩定找出跨檔案影響並減少無關讀取，再接入 watch、鉤子或 GitHub Action，會比一開始啟用所有功能更容易評估收益。

專案地址：tirth8205/code-review-graph