Session Viewer · OpenCodeReview 繁中教學站

是什麼

ocr viewer 是一個小型內嵌 HTTP server，以瀏覽器友好的 UI 渲染歷史評審會話。無外部依賴——直接讀 OCR 每次評審寫到磁碟的 JSONL 檔案。

啟動

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

Server 在前台跑——Ctrl+C 停止。會話每次請求時惰性掃描，另一終端裡跑的評審一旦 JSONL 出現就顯示。

DNS-rebinding 防護：viewer 對照 loopback 白名單檢查 Host 頭。通配綁定（:3000）需設 OCR_VIEWER_ALLOWED_HOSTS 才能從 LAN 存取。

三個頁面

URL	內容
`/`	磁碟上有會話的所有 repo 清單
`/r/{repo}`	單一 repo 的會話清單，最新在前
`/r/{repo}/{sessionID}`	單一會話完整詳情

會話詳情頁

最有用的頁面，顯示：

頭部——diff 範圍、模型、分支、總 token、執行時長。
檔案分組——每個被評審檔案一個區塊，內含五條「任務類型」泳道：

任務類型	何時出現
`plan_task`	跑了 plan 階段（檔案 ≥ 50 行）
`main_task`	每個檔案。主評審迴圈。
`review_filter_task`	跑了評審後評論過濾流程
`memory_compression_task`	active+compress 區超過 60%/80% 預算
`re_location_task`	`code_comment` 無法錨定，回退重新定位

每條泳道是任務卡片的水平條帶——每個 LLM 往返一張，按任務型別著色。

任務卡片

頭部——請求號、模型徽章、token 徽章（P: prompt / C: completion）、時長徽章、錯誤徽章。
Response——原始 assistant 回應，含 thinking 區塊。
Tool calls——每個工具呼叫 + 參數 + 結果（可摺疊）。

使用場景

「模型為什麼這麼說？」

在終端輸出打開一條評論，在 viewer 定位該檔，沿 main_task 泳道往下找包含該 code_comment 的卡片。卡片的 Response 顯示模型推理。

「這個檔案為什麼靜默？」

無評論的檔案只有當模型主動呼叫 task_done 才是成功評審。泳道以錯誤卡片結束 = 偽裝成靜默的失敗。

「壓縮保留/丟棄了什麼？」

memory_compression_task 泳道顯示每次壓縮輪。Response 窗格有摘要；被壓縮的 XML 在該輪 JSONL 的 messages 中。

磁碟儲存佈局

~/.opencodereview/sessions/
└── <path-encoded-repo-path>/
    └── <session-id>.jsonl

JSONL 每行一個事件：llm_request、llm_response、tool_call 等。行是 append-only——不完整的 JSONL 表示會話被中斷，viewer 渲染已寫入的部分。

隱私

JSONL 轉錄包含發給 / 從 LLM 收到的一切（含 diff 中任何程式碼），完全存在你的 ~/.opencodereview/ 內。OCR 不會上傳到任何地方。

📖 教學解說：Session Viewer 深入

五條泳道的實務解讀

每條泳道對應一種任務型別，出現在不同時機：

plan_task——diff ≥ 50 行才出現。看它產出的指引是否合理。
main_task——每個檔案都有。主要評審迴圈，最常看的。
review_filter_task——評審後過濾。如果評論數大幅減少，就是它在工作。
memory_compression_task——超過 60%/80% 預算時出現。看摘要保留/丟棄了什麼。
re_location_task——錨定失敗的回退。如果頻繁出現，可能是 diff 格式異常。

任務卡片的除錯價值

每個任務卡片是一次 LLM 往返的完整記錄：請求號、模型、token、時長、Response（含 thinking）、Tool calls + 結果。除錯時看：

Response 中的 thinking → 模型在想什麼
Tool calls → 模型用了哪些工具、參數是什麼
錯誤徽章 → 哪一步失敗了

JSONL 的 append-only 性質

JSONL 每行一個事件，append-only——不完整的 JSONL 表示會話被中斷。Viewer 會渲染已寫入的部分。實務意義：如果看到不完整的會話，不要慌——可能是 Ctrl+C 中斷或 runner 超時。已寫入的評論仍然是有效的。

🔍 Worked Example：用 Viewer 除錯失敗的評審

Step 1 — 啟動 viewer

ocr viewer

Step 2 — 瀏覽器打開 localhost:5483

→ 看到 repo 列表

Step 3 — 點進目標 repo

→ 看到會話清單，最新在前

Step 4 — 點進目標會話

→ 看到五條泳道

Step 5 — 找到 main_task 泳道中的錯誤卡片

→ 發現模型在第 12 輪報 tool execution error

Step 6 — 檢查 JSONL 原始資料

cat ~/.opencodereview/sessions/.../session.jsonl | jq '.tool_call.error'

預期產出

Task Card #12 (main_task):
  Model: claude-opus-4-6
  Tool: file_read → Error: file not found
  Response: "I'll proceed with the available context..."
  → Agent continued despite error, produced 1 comment

常見錯誤與診斷

錯誤訊息	診斷	修復
`檔案顯示零評論`	模型沒主動呼叫 task_done 或有錯誤	看 main_task 泳道是否以錯誤卡片結束
`start_line: 0 / end_line: 0`	錨定失敗	評論是真的，只是沒自動放置
`DNS-rebinding 防護阻擋存取`	從 LAN 存取需要設定允許主機	設 OCR_VIEWER_ALLOWED_HOSTS

練習 / 驗收清單

能描述 viewer 的三個頁面
能區分五條泳道各對應哪個任務型別
能判斷「檔案為何靜默」的三種可能
能解釋 JSONL 的 append-only 性質

看完這頁你應該能說出：viewer 的三個頁面、五條泳道各對應哪個任務型別、「檔案為何靜默」的三種可能、以及 JSONL 的 append-only 性質與隱私保證。

延伸閱讀：架構（五種任務型別） · 工具 · CLI 參考