解說影片
你要製作特定觀眾能理解且正確的解說影片。結果由兩件事決定：
references/STYLE.md 中的規則（來自真實審查意見）以及計算與檢查每個顯示數字的習慣。渲染是最簡單的部分。
Repo 地圖：函式庫 animkit/（API 參考 animkit/README.md）、工具 tools/、範例 examples/、兩個完成的
單集 episodes_example/（複製其分鏡與鏡頭格式；CLAIMS 格式在 references/VERIFY.md 中），你的工作在 episodes/<ID>_<topic>/ 下進行。
0. 開始之前
- 環境是否正常？
python -I -B -X utf8 tools/selftest.py必須輸出all OK。如果缺少config/animkit.json，請執行python -X utf8 tools/setup_config.py（設定檔是每次檢出時獨立：新的 clone 或 git worktree 需要重新設定，或設定ANIMKIT_CONFIG）。問題請參考：SETUP.md。 - 只詢問使用者你無法預設的項目（一則訊息，簡短）：
- 主題與來源資料（講義、論文、網頁）；每個說法都需要來源；
- 觀眾以及他們已經知道的內容（決定深度，
references/STORYBOARD.md§觀眾期望）； - 長度；是否需要翻譯版本 / 旁白 / 配音？
- 是否允許執行真實模型（GPU，下載）？預設：否，使用已知 ground truth 的合成場景。
- 若未回答的預設值：1080×1440，30 fps，僅字幕，無配音，預定一輪審查。
- 建立
episodes/<ID>_<topic>/目錄，包含STATUS.md（階段 / 下一步 / 等待 / 時間，使用date指令）。
1. 管線（詳細資訊與指令：references/PIPELINE.md）
| 階段 | 你產出 | 進入下一階段的閘門 |
|---|---|---|
| A. 研究 | 來源摘要；可選的參考影片分解（references/REFERENCES.md） | 你能將機制表述為：輸入 → 公式 → 形狀 → 小數值範例 → 原因 |
| B. 分鏡 | storyboard.md、CLAIMS_to_verify.md、episode.json（+ 若函式庫缺少某元件則需要 elements_needed.md） | 長單集的使用者確認大綱；完成獨立驗證第一輪並套用修正 (references/VERIFY.md) |
| C. 鏡頭 | shots/sNN_*.py，每個都包含 @shot.check | --check-only 通過；檢查連續畫面；完整渲染；修正 check.json 中的警告 |
| D. 組合 | render/<ID>.mp4 (tools/concat.py)、review/round1/review.html (tools/review_page.py) | 你已仔細檢查每個鏡頭的連續畫面；螢幕上的數字 = CLAIMS |
| E. 審查回合 | review/roundN/feedback.md（使用者的筆記）、review/roundN+1/changes.md、重新渲染 | 每項回饋都有回應；新的 CLAIMS 已驗證（每項目最多 2 輪） |
| F. 可選 | 翻譯版本 (references/I18N.md)、旁白 (references/NARRATION.md)、配音 (references/TTS.md) | 每個都有各自的檢查 |
直接用影片的語言編寫鏡頭（範例為英文）：字幕、標題與標籤在腳本中為純文字字串。--lang 僅用於第二個翻譯版本。
微路徑（≤ 60 秒，1–3 個鏡頭）。 相同階段，但較輕量。episodes/<ID>_<topic>/ 中的最小檔案清單：
storyboard.md：一個表格，每個字幕一行（時間範圍、字幕、螢幕上的變化、計算或說明性質）。骨架：templates/storyboard_skeleton.md。CLAIMS_to_verify.md：螢幕上每個數字/事實一行（說法、來源、如何檢查、測量/計算/推斷/論文）。- 從
templates/shot_template.py建立shots/s01_<name>.py，並加入@shot.check來斷言每個以字串形式顯示的計算數字。 - 驗證：一個新的獨立子代理，搭配
templates/verifier_prompt.md，範圍為所有 CLAIMS 行；套用其修正（舊文字標示刪除線）。 - 渲染：
--check-only→--sheet-only（檢視sheet.jpg）→ 完整渲染。 - 僅在有 2 個以上鏡頭時才需要
episode.json+tools/concat.py；使用tools/review_page.py <EP> --round 1產生審查頁面（一輪）。不要跳過說法表格、@shot.check或連續畫面的檢查。
2. 不可違反的規則
- 每個可計算的視覺元素都必須被計算（投影、注意力權重、重塑、反投影、擬合線條）並在
@shot.check中斷言，包括顯示的字串：ck.eq("depth on screen", f"{z:.3f}", "1.976")。從完整精度格式化；絕不重新四捨五入已列印的值。說明性視覺元素需加上shot.tag("Illustration")；降維的圖示必須說明。 - 每個數字都有來源（論文 § / 表格 / 方程式、官方程式碼檔案 + 行號，或我們自己的腳本），記錄在
CLAIMS_to_verify.md中，標記為 測量 / 計算 / 推斷 / 論文。比較必須說明指標、單位，以及較低或較高哪個更好；百分比必須說明其分母。 - 每個符號在出現處都必須定義，每次出現時；觀眾可能不知道的術語，需要使用彈出式側視窗 (
animkit.Popup) 簡短說明後關閉。 - 一個字幕 = 一個視覺變化，不超過 12 個字且不超出畫面寬度（渲染時會發出警告；在 42 px 字型大小下，通常每行約 8 個較長的單詞，最多 2 行），停留 2–3 秒，不允許靜止畫面。
- 先放圖片，再放公式，逐項點亮公式，每個術語使用顏色標記或連結到圖片的對應部分。
- 我們自己的測試必須標示為我們的（不是論文的實驗），第一次出現時標示，之後每次出現使用相同標籤。
- 獨立驗證：撰寫某個說法的人不得驗證該說法；修正視為一個新的說法；最多兩輪，之後照字面套用並進行抽查。舊文字以刪除線標示（
~~舊文字~~ → 新文字），絕不無聲刪除。 - 翻譯或旁白中不得有虛構的事實：它們只能陳述經過驗證的字幕 / CLAIMS 的內容。
- 完整檢查清單：
references/STYLE.md（§A 內容, §B 節奏, §C 視覺文法, §D 交付前, §E 成為規則的審查者回饋）。在撰寫分鏡前閱讀，並在每個審查回合前再次閱讀。
3. 工作風格
- 閱讀
animkit/README.md中你需要的 API 章節（內容很長：先用 grep 搜尋元素，再閱讀該部分）。從episodes_example/中最接近的鏡頭複製模式，而不是自行發明排版。templates/shot_template.py是一個最小完整的鏡頭範本。 - 使用
--still t1 t2（PNG 畫面）和--sheet-only（12 幀連續畫面）迭代鏡頭；最後才做完整渲染。每次都要自己檢查連續畫面（重疊、文字超出畫布、方框 = 缺少字型、字幕壓在圖片上）。靜止畫面不會被後續渲染更新：每次編輯後都要重新執行--still。 - 3D 場景：
animkit/README.md§3D 場景（PinholeCam, OrbitCam 方位角/仰角慣例：az=90, el=0 是側視圖）。2D 圖示例如針孔側視圖：§2D 側視圖（使用等比例的 Plot2D）。 - 以
python -I -B -X utf8執行 Python；絕不在另一個工作階段正在渲染時編輯函式庫檔案 (references/PITFALLS.md)。 - 保持
STATUS.md簡短且即時；在effort_log.csv中記錄工作量 (item,size,start,end,render_s,iterations,note)。 - 長單集或許多鏡頭：按照
references/DISPATCH.md將工作分攤到多個工作階段/子代理（主工作階段約 300k 上下文預算，一次性子代理 ≤ 150k，切換前使用交接檔案）。
4. 交付
告知使用者：影片路徑、審查頁面路徑（review/roundN/review.html，可在瀏覽器中開啟；它提供每個鏡頭的評論框和「複製全部」按鈕）、哪些是計算出的 vs 說明性的、驗證了哪些內容以及由誰驗證、未解決的問題。當使用者的筆記回來時，逐字儲存為 review/roundN/feedback.md（每行一個鏡頭 ID，例如 E03-02: ...），逐項回覆，並將任何一般性偏好轉換為你的單集本地規則的新的一行（附加到 episodes/ 中的 STYLE_local.md），以便下一集從該規則開始。
參考索引
| 檔案 | 何時閱讀 |
|---|---|
references/PIPELINE.md | 開始時；階段指令、檔案格式、閘門 |
references/STYLE.md | 撰寫分鏡時；每次審查回合前 |
references/STORYBOARD.md | 階段 B：觀眾深度、分鏡 + CLAIMS 格式、故事模式 |
references/REFERENCES.md | 研究參考影片 / 來源論文時 |
references/VERIFY.md + templates/verifier_prompt.md | 建立 CLAIMS 後、模型執行後、旁白/翻譯後 |
references/REVIEW.md | 階段 D–E：審查頁面、回饋檔案、回合 |
references/I18N.md | 為英文單集製作翻譯版本時 (--lang) |
references/NARRATION.md | 為每個視覺片段製作口述腳本時 |
references/TTS.md | 本地 TTS 配音、時間校準、混音時 |
references/DISPATCH.md | 多工作階段/子代理工作、成本、共享機器禮儀 |
references/PITFALLS.md | 某個環節出錯時；修改函式庫前 |
templates/ | 工作階段和子代理的提示、骨架檔案、一個鏡頭範本 |