code-review-graph 接取 GitHub Actions：增量建圖、PR 審查與快取排錯

code-review-graph 的這個教程只處理標題中的具體任務。專案以 Tree-sitter 建立本地結構圖，並透過 MCP 縮小程式碼審查上下文；CI 的關鍵是增量建圖、快取邊界和最小權限。

以下所有操作都先放在測試儲存庫、測試帳號或僅回環監聽的服務中。指令中的網域名稱、使用者名稱、路徑與金鑰是佔位符，執行前需要替換。

PR 審查為什麼需要持久化程式碼圖

這一節解決的是「PR 審查為什麼需要持久化程式碼圖」。先記錄目前狀態，再執行最小動作，最後用獨立證據確認結果。

對 code-review-graph 而言，判斷依據是：專案用 Tree-sitter 建立本地結構圖，並透過 MCP 縮小程式碼審查上下文；CI 的關鍵是增量建圖、快取邊界和最小權限。不要在這個階段順手打開更多權限。

1
2

python --version
pipx --version

執行後保留命令輸出和時間戳記。若輸出依賴目前終端機裡的臨時變量，開啟新終端複查一次。

Python 3.10 與 pipx 環境準備

按下面順序處理：

1. 讀取實際版本和目前配置。
2. 只改變與本節相關的一項設定。
3. 執行一個唯讀或可撤銷的請求。
4. 檢查日誌、退出碼和最終檔案。
5. 失敗時恢復剛才那一項修改。

1

pipx install code-review-graph

這裡的完成標準不是介面出現，而是「Python 3.10 與 pipx 環境準備」有可重複結果。

首次 build 要在什麼目錄執行

1

code-review-graph build

表格中的停止訊號一旦出現，先撤銷本節改動，不要繼續後面的自動化。

只為 Codex 安裝 MCP 配置

圍繞「只為 Codex 安裝 MCP 配置」準備一個成功樣本和一個失敗樣本。成功樣本驗證正常路徑，失敗樣本驗證限制是否真的生效。

1

code-review-graph install --platform codex

建議記錄以下四項：

• 執行前的版本或 Git 提交。
• 實際輸入，不記錄秘密值。
• 可觀察的輸出、狀態碼或 diff。
• 恢復動作以及恢復後的複查結果。

如果失敗原因仍不清楚，每次只修改一個變數；不要同時更換連接埠、執行時間、Provider 和代理程式。

檢查生成圖是否覆蓋目標語言

這一節解決的是「檢查生成圖是否覆蓋目標語言」。先記錄目前狀態，再執行最小動作，最後用獨立證據確認結果。

對 code-review-graph 而言，判斷依據是：專案用 Tree-sitter 建立本地結構圖，並透過 MCP 縮小程式碼審查上下文；CI 的關鍵是增量建圖、快取邊界和最小權限。不要在這個階段順手打開更多權限。

1

code-review-graph build

執行後保留命令輸出和時間戳記。若輸出依賴目前終端機裡的臨時變量，開啟新終端複查一次。

設計 GitHub Actions 的觸發條件

按下面順序處理：

1. 讀取實際版本和目前配置。
2. 只改變與本節相關的一項設定。
3. 執行一個唯讀或可撤銷的請求。
4. 檢查日誌、退出碼和最終檔案。
5. 失敗時恢復剛才那一項修改。

1

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

這裡的完成標準不是介面出現，而是「設計 GitHub Actions 的觸發條件」有可重複結果。

快取鍵應該綁定哪些文件

1

git rev-parse HEAD

表格中的停止訊號一旦出現，先撤銷本節改動，不要繼續後面的自動化。

來自 Fork 的 PR 如何降低權限

圍繞「來自 Fork 的 PR 如何降低權限」準備一個成功樣本和一個失敗樣本。成功樣本驗證正常路徑，失敗樣本驗證限制是否真的生效。

1

git status --short

建議記錄以下四項：

• 執行前的版本或 Git 提交。
• 實際輸入，不記錄秘密值。
• 可觀察的輸出、狀態碼或 diff。
• 恢復動作以及恢復後的複查結果。

如果失敗原因仍不清楚，每次只修改一個變數；不要同時更換連接埠、執行時間、Provider 和代理程式。

圖譜失效時退回普通 git diff

這一節解決的是「圖譜失效時退回普通 git diff」。先記錄目前狀態，再執行最小動作，最後用獨立證據確認結果。

對 code-review-graph 而言，判斷依據是：專案用 Tree-sitter 建立本地結構圖，並透過 MCP 縮小程式碼審查上下文；CI 的關鍵是增量建圖、快取邊界和最小權限。不要在這個階段順手打開更多權限。

1

git diff --stat origin/main...HEAD

執行後保留命令輸出和時間戳記。若輸出依賴目前終端機裡的臨時變量，開啟新終端複查一次。

復現本地與 CI 結果差異

按下面順序處理：

1. 讀取實際版本和目前配置。
2. 只改變與本節相關的一項設定。
3. 執行一個唯讀或可撤銷的請求。
4. 檢查日誌、退出碼和最終檔案。
5. 失敗時恢復剛才那一項修改。

1

code-review-graph build

這裡的完成標準不是介面出現，而是「重現本地與 CI 結果差異」有可重複結果。

升級解析器後重建快取

1
2

pipx upgrade code-review-graph
code-review-graph build

表格中的停止訊號一旦出現，先撤銷本節改動，不要繼續後面的自動化。

PR 審查的最終證據應該包含什麼

圍繞「PR 審查的最終證據應該包含什麼」準備一個成功樣本和一個失敗樣本。成功樣本驗證正常路徑，失敗樣本驗證限制是否真的生效。

1

git diff --check

建議記錄以下四項：

• 執行前的版本或 Git 提交。
• 實際輸入，不記錄秘密值。
• 可觀察的輸出、狀態碼或 diff。
• 恢復動作以及恢復後的複查結果。

如果失敗原因仍不清楚，每次只修改一個變數；不要同時更換連接埠、執行時間、Provider 和代理程式。

Monorepo 中縮小建圖目錄

這一節解決的是「Monorepo 中縮小建圖目錄」。先記錄目前狀態，再執行最小動作，最後用獨立證據確認結果。

對 code-review-graph 而言，判斷依據是：專案用 Tree-sitter 建立本地結構圖，並透過 MCP 縮小程式碼審查上下文；CI 的關鍵是增量建圖、快取邊界和最小權限。不要在這個階段順手打開更多權限。

1

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

執行後保留命令輸出和時間戳記。若輸出依賴目前終端機裡的臨時變量，開啟新終端複查一次。

定位 Tree-sitter 解析失敗的文件

按下面順序處理：

1. 讀取實際版本和目前配置。
2. 只改變與本節相關的一項設定。
3. 執行一個唯讀或可撤銷的請求。
4. 檢查日誌、退出碼和最終檔案。
5. 失敗時恢復剛才那一項修改。

1

code-review-graph build

這裡的完成標準不是介面出現，而是「定位 Tree-sitter 解析失敗的檔案」有可重複結果。

把圖譜產物與原始碼版本綁定

1

git rev-parse HEAD

表格中的停止訊號一旦出現，先撤銷本節改動，不要繼續後面的自動化。

比較啟用圖譜前後的上下文開銷

圍繞「比較啟用圖譜前後的上下文開銷」準備一個成功樣本和一個失敗樣本。成功樣本驗證正常路徑，失敗樣本驗證限制是否真的生效。

1

git diff --stat origin/main...HEAD

建議記錄以下四項：

• 執行前的版本或 Git 提交。
• 實際輸入，不記錄秘密值。
• 可觀察的輸出、狀態碼或 diff。
• 恢復動作以及恢復後的複查結果。

如果失敗原因仍不清楚，每次只修改一個變數；不要同時更換連接埠、執行時間、Provider 和代理程式。

code-review-graph 常見問題

是否可以跳過測試環境，直接把 code-review-graph 用到正式專案？

不建議。至少先完成一次最小成功請求、一次故意失敗和一次恢復演練。

code-review-graph 指令能運作但結果不對，先查哪裡？

先查輸入範圍、實際生效的配置和上游響應，再查模型總結。進程正常不代表業務結果正確。

如何避免 code-review-graph 的金鑰或令牌進入 Git？

使用系統環境變數、Secret 管理或專案外設定文件，並在提交前搜尋 diff。發現洩漏後必須輪換密鑰。

升級 code-review-graph 時最容易遺漏什麼？

最容易漏掉配置格式、預設監聽位址、權限範圍和快取相容性。升級前儲存版本與驗證樣本。

code-review-graph 驗收問題

完成後應能回答下面的問題：

• 使用的是哪個確切版本？
• 哪些目錄、連接埠、帳號和外部服務可被存取？
• 成功結果如何回到原始資料或 Git diff？
• 上游失敗時會報錯、重試還是切換？
• 金鑰是否可能出現在日誌或歷史記錄？
• 如何在十分鐘內回到修改前狀態？

如果其中任何一項無法回答，code-review-graph 仍處於試用狀態，不應擴大權限或接取生產自動化。