CLI 參考

情境

你在 CI 上跑一顆大型 PR 的評審，跑到一半 job 被中斷（runner 超時）。你要：① 確認哪些檔審完了、哪些沒審 ② 從失敗點續跑而不是從頭 ③ 把兩段評審的結果合併成一份報告。

Step 1 — 從 JSONL 找 session id

ocr session list

sessions:
  f3a9c2...  repo=acme/app  started=2026-08-17T10:02:11Z  status=interrupted
  7b1e01...  repo=acme/app  started=2026-08-16T22:40:00Z  status=completed

Step 2 — 確認中斷點：看哪個檔停在錯誤

ocr session show f3a9c2 | jq -r '.events[] | select(.type=="subtask") | {file, status}'

file: internal/auth/handler.go   status: completed
file: internal/upload/store.go    status: error   ← 卡在這
file: web/src/api.ts              status: pending

Step 3 — 用 --resume 從中斷點續跑

ocr review --from main --to feature/upload --resume f3a9c2 \
  --format json --audience agent > review-part2.json

--resume 只支援區間 / 單 commit 評審——它會重讀原 session 的設定與已完成的結果，只重跑失敗與未完成的檔案，避免重複燒 token。

Step 4 — 合併兩段結果

jq -s '[.[] | .comments[]]' <(cat part1.json) <(cat review-part2.json) \
  | jq 'unique_by(.path + ":" + .content)'

為什麼選這條審查路徑

大型 PR + 中斷 = 續跑場景。選 --resume 而不是「重跑整顆」的原因是成本與一致性：重跑整顆會把已完成的檔也重新審一遍（多燒 token、且結果可能因模型非確定性而不同）。--resume 保留已完成的評論，只補失敗的——讓「中斷後續跑」的結果與「沒中斷」的結果儘可能一致。

預期產出

part1: 9 files reviewed, 4 comments
resumed: 2 files re-reviewed, 1 comment recovered + 2 new
merged: 11 files total, 7 unique comments

情境

團隊每個人呼叫 ocr review 的旗標都不一樣——有人忘 --audience agent、有人沒傳 --background、有人用錯模式。你要建立一個團隊 wrapper（tocr），把「團隊最佳實踐」寫進預設值，並統一 session 管理與報告。

Step 1 — 寫 wrapper（把最佳實踐變成預設）

#!/usr/bin/env bash
# tocr —— 團隊統一 OCR wrapper
set -euo pipefail
ARGS=(--format json --audience agent --concurrency 6)
if [[ -z "${PR_TITLE:-}" ]]; then
  ARGS+=(--background "$(git log -1 --format=%s HEAD 2>/dev/null || echo 'no title')")
fi
ocr review "${ARGS[@]}" "$@" > ocr-report.json
python3 -c "
import json,sys
d=json.load(open('ocr-report.json'))
print('status=%s files=%s comments=%s tokens=%s' % (
  d['status'], d['summary']['files_reviewed'],
  d['summary']['comments'], d['summary']['total_tokens']))
"

Step 2 — 統一報告輸出與失敗分級

# 讓 wrapper 的 exit code 有意義（不是一律 0）
# 0 = 審完無 high；1 = 有 high；2 = 執行失敗/零檔可審
tocr 2>/dev/null; echo "exit=$?"

Step 3 — session 管理：壞了可續跑

# wrapper 支援 --resume：遇到 CI 中斷，團隊可以接著跑
tocr --from main --to HEAD
# 中斷後:
SID=$(ocr session list | head -1 | awk '{print $1}')
tocr --from main --to HEAD --resume "$SID"

Step 4 — 版本化 + 測試 wrapper 本身

# tocr 進 repo，並用 shellcheck + 一個「對空 repo 跑 --preview」的冒煙測試
# → 改 wrapper = 開 PR = 走 code review（dogfood 自己的工具）

為什麼選這條路徑

CLI 參數是「團隊紀律的載體」——把最佳實踐寫進 wrapper 預設值，比寫進 wiki 有效。wrapper 統一了「audience/format/background/concurrency」四件事，還把 exit code 從「0=跑完」升級成「分級狀態」，CI 可以直接吃。單一入口也讓「改預設值」變成一次 PR 的事，而不是逐個 repo 改。

預期產出

tocr → status=success files=12 comments=5 tokens=41200
tocr 遇到 high-severity → exit=1 → CI 卡 PR
中斷後 --resume → 只重跑失敗檔，token 省 ~70%