feat(C-3): 旁白模型 A/B 比對工具 + 遷移提案（offline 前置，實跑＝本機開額度）

[dofliu]

做什麼

劉老師 2026-06-15 對 C-3（旁白模型遷 2.5→3.x）開額度。但本 routine 環境沒有 GEMINI_API_KEY（你的 key 在你本機，且不該把 key 帶進 session），所以品質 A/B 必須在你本機開額度跑。這個 PR 把「能跑的工具 + 切換步驟」備好（offline 前置）：

1. tools/ab_narration.py — A/B 比對工具：對同一份簡報的同幾頁，用舊模型 vs 候選模型各生一次旁白並排輸出成 Markdown 報告。
   • 只跑旁白生成（不跑章節切分 / TTS / ffmpeg / 完整 render）→ 比「跑兩支完整影片」省很多額度。
   • 注入不同 model 呼叫真實的 narrate_page_with_gemini（prompt、三段式 retry、thinking_budget=0、_clean_narration 全與正式線一致）→ 不會 prompt 漂移。
2. slide_ingest.py — narrate_page_with_gemini 加選填 model 參數（預設仍 MODEL，正式 pipeline 零影響），讓 A/B 能注入不同模型。
3. docs/C3_NARRATION_AB_PROPOSAL.md — 提案：為什麼動 / 怎麼在你本機跑（指令）/ 決策準則表 / 驗過怎麼切（chokepoint 改走 resolve("text.fast")）+ rollback（設定頁覆寫回 2.5、免改 code）/ 3 個待拍板開放問題。
4. tests/test_ab_narration.py — 11 測（全 fake client，不打 API）。
5. docs/PRODUCT_READINESS.md C-3 → [~] 記進度。

怎麼測

在你本機設好 GEMINI_API_KEY 後：

python tools/ab_narration.py 你的簡報.pdf --pages 1,3,5 \
    --models gemini-2.5-flash,gemini-3.5-flash --out ab_narration_report.md

挑有代表性的幾頁（純文字 + 含公式/圖表 + 章節銜接）即可，不必整份跑。看 ab_narration_report.md 兩欄並排比品質，再決定切不切。

CI（裝了字型）為權威；本機全套 2702 passed（剩 1 QR 像素為容器缺 Noto CJK 字型假象）。

Reviewer 決策點（待你拍板，見 proposal §6）

• 這個 PR 不切換任何正式預設（旁白仍 2.5），只備工具——尊重 C-3 gate（品質先由你驗）。
• 跑完 A/B 後請回報：要不要遷移？要的話我開後續一刀把 chokepoint 改走 resolve()。
• 開放問題:① 遷移範圍(只逐頁旁白 vs 連章節切分)② 走 text.fast vs 新增 narration 角色 ③ 候選模型清單。

---

Generated by Claude Code