open-code-review

Open Code Review

一個用於呼叫 open-code-review (ocr) 的技能——這是一個開源的 AI 程式碼審查 CLI，可讀取 Git diff 並產生結構化的逐行審查意見。

前置檢查

開始審查前，請先確認環境：

# 1. 檢查 CLI 是否已安裝
which ocr || echo "NOT INSTALLED"

# 2. 驗證 LLM 連線
ocr llm test

如果 ocr 未安裝，請先安裝：

npm install -g @alibaba-group/open-code-review

如果 ocr llm test 失敗，使用者必須設定 LLM。請引導使用者選擇以下其中一種方式：

選項 A — 環境變數（優先級最高，建議用於 CI）：

export OCR_LLM_URL=https://api.anthropic.com/v1/messages
export OCR_LLM_TOKEN=<api-key>
export OCR_LLM_MODEL=claude-opus-4-6
export OCR_USE_ANTHROPIC=true

選項 B — 永久設定：

ocr config set llm.url https://api.anthropic.com/v1/messages
ocr config set llm.auth_token <api-key>
ocr config set llm.model claude-opus-4-6
ocr config set llm.use_anthropic true

請在此處停止，並要求使用者提供憑證——切勿自行發明或寫死 API 金鑰。

工作流程

步驟 1：收集業務背景

分析審查目標（提交、分支或變更）以提取簡潔的業務背景。透過 --background 傳遞此背景，以提升審查品質。

步驟 2：執行程式碼審查

使用適當的旗標執行 OCR 指令。有業務背景時，務必透過 --background 傳遞：

ocr review --audience agent --background "business context here" [user-args]

參數處理：

• 背景資訊（建議）：使用 --background "context" 或 -b "context" 提供業務背景，以獲得更好的審查品質
• 預設（無使用者參數）：審查暫存、未暫存及未追蹤的變更（工作區模式）
• 特定提交：使用 --commit 或 -c 審查單一提交與其父提交的差異
• 分支比較：使用 --from <ref> 和 --to <ref> 審查兩個參考之間的差異
• 超時：預設每個檔案超時 10 分鐘；可使用 --timeout <minutes> 調整
• 並行數：預設並行處理 8 個檔案；若遇到速率限制，可使用 --concurrency <n> 減少
• 預覽模式：使用 --preview 或 -p 預覽將審查哪些檔案，而不實際執行 LLM
• 安裝：若找不到 ocr 指令，請執行 npm i -g @alibaba-group/open-code-review 安裝

常見呼叫模式：

使用者說	要執行的指令
"review my changes" / "review the working copy"	ocr review --audience agent -b "context"
"review this PR" / "review feature branch"	ocr review --audience agent -b "context" --from main --to <branch>
"review commit abc123"	ocr review --audience agent -b "context" --commit abc123
"what would be reviewed?" (dry-run)	ocr review --preview

輸出模式：

• 一律使用 --audience agent 以隱藏進度 UI，僅輸出最終摘要

步驟 3：分類與回報

針對審查輸出中的每一則意見，依優先級分類並向使用者回報所有問題：

• 高優先級：明顯的錯誤、安全問題、明確的失誤，或附有精確修正建議的合理意見
• 中優先級：合理的疑慮但需視情況而定、風格/效能建議，或需要手動實作的修正
• 低優先級：可能是誤報、缺乏足夠背景、吹毛求疵或無意義的建議

將所有意見按優先級分組回報。

步驟 4：修正

在套用修正前，請確認使用者是否要求自動修正：

• 若使用者明確要求「review and fix」或類似內容，則進行自動修正
• 若使用者僅要求「review」而無修正意圖，請在套用任何變更前取得許可

修正問題與建議時：

• 專注於高優先級和中優先級項目
• 在安全且明確的情況下，直接對程式碼套用修正
• 對於需要手動介入的複雜修正，清楚描述需要進行的操作
• 在提交前務必與使用者確認修正內容

輸出格式

每則意見包含：

• path：檔案路徑
• content：審查意見文字
• start_line / end_line：行號範圍（兩者皆為 0 表示定位失敗）
• suggestion_code：可選的修正建議
• existing_code：可選的原始程式碼片段
• thinking：可選的 LLM 推理過程

依優先級過濾意見後，使用以下範本呈現結果：

## Code Review Results

**Files reviewed**: N
**Issues found**: X high priority / Y medium priority

### High Priority

- **`path/to/file.java:42`** — Brief description
  > Recommendation: How to fix

### Medium Priority

- **`path/to/file.ts:88`** — Brief description
  > Recommendation: How to fix (if applicable)

若審查後未發現任何問題，直接陳述：「Review complete — no issues found in N files.」

優先級分類：

• 高優先級：明顯的錯誤、安全問題、明確的失誤，或附有精確修正建議的合理意見
• 中優先級：合理的疑慮但需視情況而定、風格/效能建議，或需要手動實作的修正
• 低優先級：直接忽略（可能是誤報、缺乏背景、吹毛求疵或無意義的建議）

處理定位失敗的意見：

當 start_line 和 end_line 皆為 0 時，表示意見未能定位到檔案中的確切位置。在這種情況下：

1. 閱讀意見內容以了解問題
2. 檢查意見中提到的目標檔案
3. 根據意見的上下文找出相關的程式碼區段
4. 將修正或建議套用到正確的位置

自訂審查規則

若使用者想要專案特定的規則，OCR 依以下優先順序解析：

1. --rule <path> 旗標（最高）
2. <repo>/.opencodereview/rule.json
3. ~/.opencodereview/rule.json
4. 內建系統預設值（最低）

預設情況下，第一個符合的使用者規則會取代內建的系統規則。若希望同時包含符合的系統規則和使用者規則，請在規則項目中設定 merge_system_rule: true。

規則檔案格式：

{
  "rules": [
    {
      "path": "**/*.java",
      "rule": "All new methods must validate required parameters for null",
      "merge_system_rule": true
    },
    {
      "path": "**/*mapper*.xml",
      "rule": "Check SQL for injection risks and missing closing tags"
    }
  ]
}

若要在審查前預覽哪條規則適用於某個檔案：

ocr rules check src/main/java/com/example/Foo.java

注意事項

• 必須先設定 LLM — 若無法連線到 LLM，ocr review 會直接報錯。首次審查前務必執行 ocr llm test。
• 工作目錄很重要 — ocr review 會對當前目錄的 Git 倉庫進行操作。若需從其他目錄執行，請使用 --repo /path/to/repo。
• 工作區模式會審查未追蹤的檔案 — 直接執行 ocr review 會包含暫存、未暫存以及未追蹤的變更。若想縮小範圍，請選擇性地暫存檔案。
• 大型 diff 可能超過 token 限制 — 非常大的 diff 檔案可能會被截斷。預設的 MAX_TOKENS 為每次請求 58888。
• 超過 50 行會觸發計劃階段 — 變更行數超過 50 行的 diff 會在主要審查前執行額外的風險分析階段。這會增加延遲，但能提升品質。
• 不要使用 --audience human — 它會串流輸出進度 UI，污染輸出結果。請一律使用 --audience agent。
• 意見語言跟隨設定 — 設定 language 為 English 或 Chinese（預設為 Chinese）以控制審查意見的語言。

驗證

審查完成後，請檢查以下項目以確認成功：

1. 指令以狀態碼 0 結束
2. 已產生意見（或顯示「No comments generated」訊息）
3. 警告（若有）顯示於 stderr

若發生錯誤，請檢查 stderr 中的警告以了解哪些檔案失敗及原因。

參考資料

• 完整文件：https://github.com/alibaba/open-code-review
• NPM 套件：https://www.npmjs.com/package/@alibaba-group/open-code-review
• 問題追蹤：https://github.com/alibaba/open-code-review/issues