快速開始

情境

你剛接手一個別人的 legacy 專案，壓根不懂它的結構，但明天就要上線一個功能。你想在動任何東西之前，先知道「這個 repo 現況的風險水位」。這是「審陌生 codebase」的典型開場——先摸底、再決定動刀。

Step 1 — 先看會審什麼：--preview 是安全網

ocr review --preview

但注意：如果這是「整個 repo 的現況」，ocr review（工作區模式）可能因為「沒有變更」而零檔可審。陌生 repo 正確的摸底工具是 ocr scan：

ocr scan --preview

Step 2 — 分層掃描：先掃核心目錄

ocr scan --path src,internal --exclude '**/generated/**,*.pb.go' \
  --format json --audience agent > audit.json

用 --path 限定到「你打算動的地方」，--exclude 擋掉生成碼——陌生 repo 最容易混入大量生成檔。

Step 3 — 看發現分級，決定動刀順序

jq -r '.comments[] | "\(.severity // "UNK") \(.path)"' audit.json | sort | uniq -c | sort -rn

Step 4 — 對高風險檔做單檔深度 scan

ocr scan --path internal/auth,internal/payment --max-tokens 150000 \
  --format json --audience agent

為什麼選這條審查路徑

陌生 repo 的關鍵是「不要一頭栽進 diff」——你連 baseline 都沒有。先用 ocr scan --preview 確認掃描範圍（避免把生成的、vendor 的、含 secrets 的目錄掃進去），再從核心目錄開始分層審。比起「先看懂全部再動手」，「先用 scan 摸出風險水位、再對熱點加深」是接手 legacy 最低成本且最安全的開場。

預期產出

audit.json: 23 files scanned, 8 comments
  → 5 條落在 internal/payment（熱點）
  → 3 條落在 src/legacy（遷移風險）
深掃 internal/payment → 追加 4 條（含 2 條安全）
→ 動手前你就知道：別碰 payment，先補測試再遷移

情境

你是工程主管，要把 OCR 從「個人玩具」升級成全公司共用的 code review 平台。這不是「跑一條命令」——是「設定規則 → AI review → CI 整合 → 指標追蹤」四階段、跨多個 repo 的完整導入專案。下面是一條可複製的路徑。

Phase 1 — 平台設定：規則與配置先於所有人上線

# 1a. 建立團隊規則（版本化、可 review）
mkdir -p .opencodereview
cat > .opencodereview/rule.json << 'EOF'
{
  "include": ["src/**/*.{go,ts,tsx,py}"],
  "exclude": ["**/*.test.*", "**/generated/**", "**/vendor/**"],
  "rules": [
    { "path": "**/*", "rule": "Check for hardcoded secrets, SQL injection, and missing auth checks." },
    { "path": "src/api/**/*.go", "rule": "Go-specific: defer tx.Rollback() after db.Begin(); check error wrapping." }
  ]
}
EOF
# 1b. 確認規則層正確（逐檔驗證）
ocr rules check src/api/handler.go

Phase 2 — AI review：先在一顆試行 repo 跑通工作區模式

cd pilot-service
ocr config provider              # TUI 選 provider + model
ocr llm test                     # 確認連通
ocr review --preview             # 確認過濾範圍（不花 token）
ocr review --format json --audience agent > review.json
jq '.summary' review.json        # files_reviewed / comments / total_tokens

Phase 3 — CI 整合：複製到全部 repo 並加「合併門檻」

# 3a. 下載官方 GitHub Actions workflow
curl -o .github/workflows/ocr-review.yml \
  https://raw.githubusercontent.com/alibaba/open-code-review/main/examples/github_actions/ocr-review.yml
# 3b. 設定 secrets: OCR_LLM_URL / OCR_LLM_AUTH_TOKEN / OCR_LLM_MODEL
# 3c. 加一道「註記檢查」當合併門檻（見 cicd.html 的挑戰三）
#     → 沒有 OCR 註記的 PR 不能 merge

Phase 4 — 指標追蹤：用 telemetry 建立「導入成效」儀表板

# 4a. 在 CI 啟用遙測（OTLP/gRPC → collector:4317）
env:
  OCR_ENABLE_TELEMETRY: "1"
  OTEL_EXPORTER_OTLP_ENDPOINT: collector:4317
# 4b. Grafana 追蹤: 每週評論數、每 PR token 成本、平均時長、工具錯誤率
# 4c. 用 ocr.session 留存「每顆 PR 的審查軌跡」當品質稽核證據

為什麼選這條導入路徑

導入失敗九成不是工具問題，而是「設定、規則、門檻、指標」各自為政。把規則與配置先版本化（Phase 1），是為了讓「改規則」本身走 code review；先試行單 repo（Phase 2），是為了在放大規模前發現「規則太鬆/太嚴」；CI 門檻（Phase 3）確保「AI review 真的被用」；指標（Phase 4）讓你能跟老闆說「省了多少工時、擋了多少缺陷」——這是導入專案能持續的理由。

預期產出

Day 1:  pilot-service 跑通，平均 4 條評論/PR、1.2 萬 token/PR
Week 2: 規則 v2 上線（補 React hooks 規則），偽陽性降 30%
Week 4: 12 個 repo 全接 CI，合併門檻生效
Month 2: 儀表板顯示「擋下 47 條 high-severity 缺陷」→ 導入報告可交差