CLI 參考 · OpenCodeReview 繁中教學站

命令總覽

命令	別名	作用
`ocr review`	`ocr r`	執行評審並輸出評論
`ocr scan`	`ocr s`	不需 Git diff，掃描完整檔案
`ocr rules check <file>`	—	顯示某檔路徑適用哪條規則與來源
`ocr config set/unset/provider/model`	—	寫入 / 刪除設定、互動式 provider / model TUI
`ocr llm test / providers`	—	測試 LLM 連通性 / 列出內建 provider
`ocr session list/show/comments`	`sessions`	列出 / 查看已保存評審會話
`ocr viewer`	—	本機 Web UI（localhost:5483）瀏覽歷史評審
`ocr version`	`-V`	印出版本、commit、平台、建置日期

ocr review 參數

參數	簡寫	預設	說明
`--repo <path>`	—	目前目錄	Git 倉庫根
`--from <ref>`	—	—	diff 起始 ref
`--to <ref>`	—	—	diff 結束 ref（merge-base(from,to)..to）
`--commit <sha>`	`-c`	—	評審單一 commit
`--preview`	`-p`	false	跑過濾管線但跳過 LLM
`--resume <session-id>`	—	—	從之前評審會話恢復
`--format <fmt>`	`-f`	text	text 或 json
`--audience <who>`	—	human	human（串流進度）或 agent（靜默 stdout）
`--background <text>`	`-b`	—	注入需求 / 業務上下文（提升品質最有效的參數）
`--concurrency <n>`	—	8	並行評審的最大檔數
`--timeout <minutes>`	—	10	每檔截止時間（0 關閉）
`--rule <path>`	—	—	自訂規則檔（覆蓋專案/全域）
`--max-tools <n>`	—	30	每檔最大工具呼叫輪數
`--max-tokens <n>`	—	模板預設	每檔 prompt token 上限
`--provider / --model`	—	—	本次執行的 LLM provider / model 覆蓋

模式參數互斥：傳 --from/--to、--commit、或都不傳（工作區）。混用直接報錯。--resume 僅支援區間 / 單 commit 評審，不能與 --preview 並用。

JSON 輸出範例

{
  "status": "success",
  "llm": { "provider": "anthropic", "model": "claude-opus-4-6" },
  "summary": { "files_reviewed": 9, "comments": 1, "total_tokens": 21344 },
  "comments": [{
    "path": "src/foo.go",
    "content": "Concurrent map access without a lock — wrap with sync.RWMutex.",
    "start_line": 42, "end_line": 47,
    "existing_code": "m[k] = v",
    "suggestion_code": "mu.Lock(); defer mu.Unlock(); m[k] = v"
  }]
}

無檔可審時回 skipped 外殼——讓呼叫方區分「無變更」與「無發現」。

退出碼

碼	含義
`0`	評審完成（可能零評論，可能有非致命警告）
`1`	致命錯誤——參數錯誤、無法解析 LLM 端點、所有子 agent 失敗

ocr scan

不需 Git diff 的全檔掃描——直接讀工作樹每檔現況交給 LLM 審。適合審計陌生 codebase 或沒有有意義 diff 的目錄。

ocr scan                            # 掃描整個倉庫
ocr scan --path internal/agent      # 掃描單一目錄
ocr scan --path internal/agent,internal/llm/client.go
ocr scan --exclude '**/generated/*,*.pb.go'
ocr scan --preview                  # 看會掃哪些檔（不花 token）

ocr rules check

ocr rules check src/main/java/com/example/Foo.java
# File: src/main/java/com/example/Foo.java
# Source: System built-in
# Pattern: **/*.java
# Rule: …java.md 內容…

ocr config

ocr config set provider anthropic
ocr config unset custom_providers.my-gateway
ocr config provider                  # 互動式 TUI
ocr config model                     # 互動式 model 選擇

ocr session

ocr session list
ocr session show <session-id>
ocr session comments <session-id>
ocr session comments --severity high --category bug,security <session-id>

ocr viewer

ocr viewer                  # binds localhost:5483
ocr viewer --addr :3000     # bind to all interfaces on port 3000

提示與注意

--audience agent 並不隱含 --format json——前者控 UI、後者控結構，需要兼得時組合使用。
--background 是提升評審品質最有效的參數之一——從其他 agent 呼叫時，永遠傳入需求 / PR 描述。
某檔 diff 單獨超過 MAX_TOKENS 的 80% 會在呼叫 LLM 前被丟棄（記 log 但不失敗）。
變更行數低於 50 時，plan 階段會自動跳過。

📖 教學解說：CLI 實戰指南

三種評審模式的選擇邏輯

不要糾結「該用哪個」——模式由你手上的變更決定：

有 staged/unstaged 變更 → ocr review（工作區模式，最常用）
要審某個 commit → ocr review -c <sha>
要比較兩個 ref 之間 → ocr review --from main --to feature

三種模式互斥，混用直接報錯。這不是限制——是確定性保證。

--audience agent vs --format json 的根本差異

這是最常搞混的：--audience agent 控制的是 UI 輸出（屏蔽進度列），--format json 控制的是 資料結構（text vs JSON）。你需要同時屏蔽 UI 又要 JSON？必須兩個都傳。很多 CI 腳本只傳 --format json 然後抱怨 stdout 有雜訊——就是因為沒傳 --audience agent。

--background：提升品質最有效的參數

如果你只記一個參數，記 --background。它讓 LLM 知道「這段變更在解決什麼問題」，大幅減少無關評論。從 CI 呼叫時，傳 PR 標題或需求摘要。從 Claude Code 呼叫時，傳專案脈絡。這是 token ROI 最高的投資。

🔍 Worked Example：從零跑一次完整評審

Step 1 — 確認 Git repo 狀態

cd /path/to/repo && git status

Step 2 — 預覽會評審哪些檔（不花 token）

ocr review --preview

Step 3 — 加入背景脈絡跑評審

ocr review --background "重構 user service 的錯誤處理" --format json --audience agent > review.json

Step 4 — 查看評審結果

cat review.json | python3 -m json.tool | head -50

Step 5 — 開啟 Session Viewer 看細節

ocr viewer

預期產出

{
  "status": "success",
  "summary": { "files_reviewed": 5, "comments": 2 },
  "comments": [
    { "path": "src/user.go", "content": "缺少 error wrapping...", "start_line": 42 },
    { "path": "src/auth.go", "content": "token 過期未驗證...", "start_line": 18 }
  ]
}

常見錯誤與診斷

錯誤訊息	診斷	修復
`Cannot find merge-base`	淺克隆（shallow clone）	GitHub: 保留 fetch-depth: 0；GitLab: 保留 GIT_DEPTH: 0
`no valid LLM endpoint configured`	端點解析鏈沒找到完整三元組	跑 ocr config set llm.url … 或匯出 env
`Max tool requests reached`	模型 30 輪沒調 task_done	換更強模型、檢查檔案大小、調 --max-tools
`skipped 外殼（零檔案可審）`	所有檔案被過濾	跑 ocr review --preview 看過濾原因

練習 / 驗收清單

能說出三種評審模式與互斥規則
能解釋 --audience agent vs --format json 的差異
能描述 JSON 輸出的 skipped 外殼
能說明 ocr scan 與 ocr review 的根本差異
能列出 ocr review 的所有主要參數

看完這頁你應該能說出：三種評審模式與互斥規則、--audience agent vs --format json、JSON 外殼的 skipped 狀態、以及 ocr scan 與 ocr review 的根本差異。

延伸閱讀：架構總覽 · 設定 · 評審規則