← 回首頁

文件教學

把官方文件翻譯成中文口語解說（英文原文可展開）

這裡把上游 README 與 docs/ 的官方文件，依「值得教學」原則做中文解說。每個主題一頁，中文為主文，英文原文用可展開的 <details> 保留。

快速開始前置條件、安裝、配置 LLM、第一次評審、JSON 輸出。 運作原理確定性 × Agent 混合設計、為什麼省 token 又精準。 CLI 參考review / scan / rules / config / llm / session / viewer 全部命令與參數。 全檔掃描ocr scan：不需 Git diff 的整檔評審，審計陌生 codebase。 設定18 個內建 provider、環境變數、超時、max_tokens、extra_body。 評審規則四層優先級鏈、五重門過濾、rule.json 格式、配方。 6 個工具task_done / code_comment / file_read / file_read_diff / file_find / code_search。 架構總覽diff provider → 五重門 → per-file 子任務 → 評論流水線 → 持久化。 Benchmark50 repo / 200 PR / 10 語言 / 1,505 條 ground-truth。 MCP 伺服器OCR 作為 MCP client、工具白名單、名稱衝突、排錯。 整合Agent Skill、Claude Code 外掛、OpenCode 工具、CI/CD。 委託模式宿主 Agent 提供 LLM、OCR 只做工程架構。 CI/CDGitHub Actions、GitLab CI 配方與客製化。 Session Viewerlocalhost:5483、五條泳道、任務卡片。 遙測OpenTelemetry span/metric/event，不導出 prompt。 FAQ常見錯誤、過濾與規則、輸出與整合、效能與成本。 實作案例入口graphify 掃描 OCR 自己（dogfooding）的互動知識圖譜。

想看原始碼本身？前往 程式碼對照（逐函數講解）。

📖 教學導覽：如何使用本站

推薦學習路徑

如果你是第一次接觸 OCR，建議按此順序閱讀：

  1. 快速開始——五分鐘跑通第一次評審
  2. 運作原理——理解確定性 × Agent 混合
  3. CLI 參考——掌握所有命令與參數
  4. 設定——配置 provider 與進階選項
  5. 評審規則——自訂評審行為
  6. 6 個工具——理解 Agent 可用的工具

之後按興趣探索：MCP、CI/CD、委託模式、Session Viewer。

每個頁面的「教學增強」

每個頁面底部都有可展開的教學解說區塊，包含：

  • 📖 教學解說——深入導讀，不只是翻譯原文
  • 🔍 真實 Worked Example——含步驟與預期產出
  • ⚠️ 常見錯誤/診斷——表格化的錯誤訊息 + 診斷 + 修復
  • ✅ 練習/驗收清單——確保你真的學會了

① 進階真實情境 Worked Example：用「案例導向」學完整套 OCR

情境

你不想照頁面順序一條條讀——你想用「一個真實任務」當主軸，需要哪頁就跳哪頁。任務：「把 OCR 裝進你同事的團隊，並在 30 分鐘內讓他能自己跑、自己除錯」。這是一張「情境 → 該讀哪頁」的動線。

Step 1 — 讓同事跑通第一次評審

→ 跳 快速開始（安裝 + 配置 + 第一次 ocr review）。

Step 2 — 同事問「為什麼審出來的結果長這樣？」

→ 跳 運作原理 + 架構總覽（plan/main 迴圈、記憶壓縮、評論流水線）。

Step 3 — 同事想把公司規範加進去

→ 跳 評審規則（rule.json + 五重門）→ 6 個工具（理解 Agent 怎麼拿脈絡）。

Step 4 — 同事要接 CI

→ 跳 CI/CD（GitHub Actions / GitLab）→ 設定（env vs config）。

Step 5 — 同事報錯「評論消失了」

→ 跳 FAQ（零評論診斷）→ Session Viewer（看泳道）→ 遙測（追效能）。

為什麼選這條學習路徑

「需求導向」勝過「目錄導向」：你只在真的需要某能力時才讀那頁，知識有錨點（情境）、不易忘。這份教學站的每個「教學解說」都是為了「回答真實操作時的『為什麼』」而寫——所以先操作、再回頭讀原理，才是最高效的順序。

預期產出

30 分鐘後，同事能:
  跑第一次 review + 看懂 JSON 輸出
  對「評論消失」做 3 步診斷
  把公司規範寫成 rule.json
  知道哪裡看工具使用軌跡（viewer）

② 深入原理擴充：教學站的「知識工程」本身也是 code review 的一種

文件與程式碼是同一顆 repo 的兩種投影

這個教學站是「把 OpenCodeReview 的行為變成可教的語言」——它與 graphify 的知識圖譜、OCR 的評審輸出，都是同一顆專案的投影：圖譜投影形狀、評審投影風險、教學投影理解。三種投影互相驗證：如果教學說的機制與 graphify 圖譜的邊不一致，或與 OCR 實際輸出不一致，就代表有一方過期了。

「看起來通過 review 但其實有隱患」的案例

# 教學站說「--resume 只支援 range / single-commit」
# 但上游 main 某天偷偷支援了 workspace 模式
# → 用「舊教學」的人會以為 resume 會失敗，白繞一大圈
# → 或: 教學站沒講某個新參數，讀者根本不知道它存在

隱患是文件漂移（doc drift）：教學站「看起來完整」——每一頁都有教學解說、work example、檢查清單——但內容可能已經跟不上上游。防禦：教學站應該定期對齊上游 commit（本站 header 有「對齊上游 main @ 9148bfd」就是這個標記）；並把「規則/參數變更」當成 code review 來審——用 OCR 審教學站的程式碼範例是否還正確，用 git log 追「上游改了什麼」。

③ 診斷式疑難排解

症狀可能原因解決方案
照教學做但命令不存在你裝的版本比教學新/舊跑 ocr version；對照 header 標記的對齊 commit
教學的參數預設值跟你看到的不一樣上游改了預設值，文件沒同步跑 ocr review --help 看實際值；回報 doc drift
「看完卻不會用」只讀了「教學解說」，跳過 Worked Example 與練習清單照 Worked Example 實際跑一遍；用練習清單自測
不知道從哪頁開始—用上面的「案例導向」動線，或照學習路線
程式碼範例在自家環境報錯環境差異（platform / git 版本 / 目錄結構）比對上游 example 檔；檢查 --preview 輸出

④ 進階挑戰題

  1. 挑戰一：用「案例導向」為「剛接手一個陌生 monorepo 的工程師」設計一條閱讀動線（含跳轉頁面順序與每頁要帶走的 1 個知識點）。
  2. 挑戰二：提出一個「文件漂移偵測」機制：如何自動偵測「教學站講的參數/規則/輸出格式與上游不符」？（提示：有沒有辦法對上游的 --help 或 config 做差異比對？）
  3. 挑戰三：判斷題——「教學站每一頁都有檢查清單，所以它一定是完整的」。這句話為什麼不對？舉一個「有檢查清單但內容過期」的假設案例。