程序化短片（short-film）
把一個主題變成一部短片：約 30 秒（可 15–90 秒），豎屏 1080×1920、24 fps；手繪墨線風格的紙張底（paper plate）鏡頭，與深藍色藍圖底（blueprint plate）鏡頭交替剪輯；每個事件都落在節拍網格上（bpm → 拍 → 幀）；每一個像素和每一個音頻採樣都用純瀏覽器 JavaScript 計算。交付物是 dist/<slug>.html（自包含播放器）、exports/<slug>.mp4（及其手機版、預覽版轉碼），以及一份發布包：TikTok 封面圖（HTML 截圖）、推薦標題與描述。
這個 skill 封裝了一條已被驗證的流水線。它自帶三樣東西：
foundation/—— 引擎與工具，會被複製進新專案：src/core.js、src/lib.js、src/player.js、src/music.js（引擎 + 一段示例配樂），以及tools/（構建、檢查、截圖、渲染、樁生成、音頻分析、發布包、測試夾具）。一切由src/timeline.js驅動，所以每部片子都不需要改動工具程式碼。templates/—— 每部片子起步時用的四份規劃文件。reference/—— 需要時再讀：鏡頭類型、場景解剖、音樂、平台預設；先看那三張參考圖。
先看 reference/：contact-sheet.jpg 是範例影片（examples/llm-evolution，一套自定義的「地圖冊 ATLAS」風格）的整片接觸表——那個細節密度和完成度就是標準線；paper-frame.jpg 與 blueprint-frame.jpg 是預設既有風格的兩種底各一整幀（由 tools/fixtures 渲染），採用預設風格的片子以它們為視覺目標。
完整範例見 examples/llm-evolution/：一部從神經元講到 AI 大模型的 24 鏡頭影片，包含規劃文件、原始碼、dist/ 與發布包。注意它是一個自訂風格的成品（透過參考分析偏離了預設的紙張×藍圖風格），展示了本 skill 的完整能力。當某個模板讓你不確定填好的文件長什麼樣時，去那裡讀它的對應物。
關卡（The gate）
node tools/check.cjs 就是關卡：六項檢查（媒體掃描、確定性、原始碼掃描、時間軸、繪製、幀耗時），退出碼為 0 即通過。從樁階段開始，只要關卡是紅的，任何步驟都不算完成。對真實場景它用時不到一分鐘——讓它跑完。
流水線
0. 簡報（Brief）
只問一輪問題：主題是什麼，關於它這部片子必須包含什麼，時長（預設 30 秒），以及要發布到哪個平台（決定畫幅與安全區，見 reference/platform-presets.md）。其餘的自己發明，並說明你發明了什麼。
完成標準：主題被寫成了一句用戶已經看過的話，且時長與平台已確定。
1. 初始化（Setup）
創建以片子 slug 命名的專案資料夾，把 foundation/ 複製進去。在 tools/ 裡跑 npm install（Playwright；若瀏覽器缺失，補 npx playwright install chromium），確認 ffmpeg 在 PATH 上，或把 FFMPEG 設為二進位路徑。把模板複製進 docs/，把主題寫進 docs/CONTRACT.md 的 Goal。
完成標準：node tools/smoke.cjs 通過，node tools/check.cjs --fixtures 是綠的，且 node tools/render.cjs --fixtures --scale 0.5 產出帶聲音的 exports/fixtures.mp4。這個 fixtures 迷你片在把精力投進規劃之前，先證明工具鏈是通的。
2. 調研（Research）
列出主題故事的各階段，對每個未決問題各做一次網路搜尋，把兩到四份權威全文來源抓進 .tmp/research/。調研最終只落到兩個下游位置：藝術聖經的主題參考，以及每個鏡頭的 Subject 小節。
完成標準：故事的每個階段都能追溯到一份已抓取的來源。
3. 藝術聖經（Art bible）
按模板填寫 docs/art-bible.md。第 1–9 節是既有風格——已定好；第 2.2 節（主題調色板，每個顏色都是具名 hex，並鏡像到 src/lib.js 標註塊）、2.3 的身份色調與第 10 節（主題參考）每部片子重寫。第 10 節以「要避免的錯誤」結尾，每個錯誤都配上正確畫法。
若用戶想要不同於既有風格的外觀，先按 templates/reference-analysis.md 的方法做一次參考分析，再據此更新第 1–9 節。
完成標準：故事板將繪製的每個元素都有繪製規則和調色板名稱；src/lib.js 與 2.2 節一致；錯誤清單存在；並已看過 node tools/snap.cjs --fixtures --shot palette --samples 5 --sheet。
4. 故事板（Storyboard）
讀 reference/shot-types.md，按模板填寫 docs/storyboard.md：logline；數字（先選 bpm，拍 = 60/bpm 秒，時長落在整數小節上）；彙總表；映射到小節的各幕；一張針對每個跨匹配剪輯存活的形狀的共享幾何表；然後每個鏡頭一條條目——1 到 3 秒，邊界在節拍網格上，兩種底交替——含全部八個小節，Sound 提示按網格打時間戳。
完成標準：各鏡頭恰好無縫鋪滿 [0, duration]；每個鏡頭有全部八個小節；每個匹配剪輯形狀有共享幾何表；文件能經得起以影評人眼光做的自檢（正文數字與各表一致，必讀內容都在安全區內——算術內容也算）。故事板錯誤會複合進每個場景，這是最便宜的抓錯時刻。
5. 時間軸（Timeline）
按故事板編寫 src/timeline.js（形狀見故事板模板）：標題、bpm、時長、shots 陣列（id、file、start、end、mode、title、transitionIn、brief），以及從各 Sound 小節收集的扁平 cues。樁階段就是這一步的測試——時間軸格式錯誤會大聲失敗。
6. 樁階段（Stub pass）
node tools/stubgen.cjs 為每個鏡頭生成佔位場景，跑關卡，然後 node tools/render.cjs --scale 0.5 --out exports/draft-stubs.mp4 並從頭到尾看一遍草稿。這是曳光彈：在任何真實場景被繪製之前，先證明時間軸、場景、關卡、渲染與音頻全都通。
完成標準：關卡是綠的，且草稿 MP4 按順序顯示每個鏡頭、每個切換都在網格上。
7. 場景（Scenes）
每個場景文件一個 agent——文件所有權就是法律（docs/CONTRACT.md）。每個場景 agent 讀 reference/scene-anatomy.md、它的故事板條目、藝術聖經與共享幾何，然後寫 src/scenes/NN-<id>.js，截接觸表（node tools/snap.cjs --shot <id> --samples 6 --sheet）並看每一幀，迭代到符合簡報。snap --only 可以在兄弟文件只寫了一半時渲染單個鏡頭，所以場景 agent 可以自由並行。
鏡頭也可以共享一個繪製模組（集中式佈局，見 docs/CONTRACT.md「場景程式碼的兩種佈局」）——此時每個 src/scenes/NN-*.js 只是幾行的註冊包裝，繪製集中在 FILM.art。範例 examples/llm-evolution 用的就是這種；鏡頭共享同一套幾何、只在參數上不同時它更省事。
完成標準：每個鏡頭的接觸表都被親眼檢查並判定為符合簡報，且關卡是綠的。
8. 音樂（Music）
按 reference/music.md 編寫 src/music.js：保留引擎，替換 CH 和弦表、MIX.ride 自動化與整個 score() 函數，在 FILM.TIMELINE.cues 的精確時間上實現每一條 cue，讓重音落在切換上。
完成標準：node tools/audio/render-audio.cjs 後 node tools/audio/analyze.cjs .tmp/audio/score.wav --cues 顯示起點與提示在 10 ms 內匹配，node tools/audio/peaks.cjs .tmp/audio/score.wav 顯示餘量在限制器上限之下，且關卡是綠的。
9. 影評波次（Critic waves）
先把整片放到一張表上：node tools/snap.cjs --samples 24 --sheet --scale 0.25。在這個尺寸下讀不出來的鏡頭就是 P1——修構圖上改，不是加細節。
然後基於渲染幀審查每個鏡頭：重新截接觸表，用影評子 agent 給構圖、對故事板的忠實度、運動、密度打分。影評人要測量像素級的比例關鍵幾何（band 分數、三分法、安全區算術、共享幾何位置），而不是只憑眼睛；並把每個匹配剪輯兩側都截出來對比。
按波次修復——P1 優先、每條引用證據幀、保持文件所有權（恢復擁有該檔案的 agent）、每次修復後重新截圖。導演在新幀上抽查每個 P1 修復。用兩種不同順序截同樣幀並對比檔案雜湊來抽查確定性。
完成標準：每個 P1 與 P2 修復都在新幀上驗證過，且關卡是綠的。
10. 交付（Deliver）
node tools/render.cjs 寫出母版（crf 16）。然後轉碼：
ffmpeg -i exports/<slug>.mp4 -vf scale=720:1280 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 128k exports/<slug>-phone.mp4
ffmpeg -i exports/<slug>.mp4 -c:v libx264 -crf 23 -preset medium -c:a copy exports/<slug>-preview.mp4
node tools/build.cjs 寫出 dist/<slug>.html。然後帶聲音從頭到尾看一遍母版，並打開一次 HTML 播放器（點擊或空格播放，方向鍵逐幀步進，?shot=<id> 單鏡頭循環）。
寫 exports/<slug>-shots.md：每個鏡頭一行，說明它展示了什麼。
完成標準：母版、手機版轉碼、HTML 檔案與 exports/<slug>-shots.md 都存在，關卡是綠的，最終觀看沒有發現要修的地方。
11. 發布包（Publish pack）
用 tools/publish.cjs 生成適合發布的封面圖與文案腳手架：
node tools/publish.cjs # 預設取第 1 個鏡頭的鉤子幀做封面
node tools/publish.cjs --at 2.5 --title "從一個神經元，到一座語言機器" --platform tiktok
它做兩件事：
- 封面圖（HTML 截圖，預設 1080×1920）：渲染影片在
--at時刻的一幀作為主視覺，疊加標題/副標題/角標，輸出exports/<slug>-cover.png。封面頁允許使用系統字體與圖片，因為它不進入交付的 HTML，不違反「無媒體」規則。 - 文案腳手架
exports/<slug>-publish.md：標題候選、描述、話題標籤、鏡頭清單、時長/畫幅/平台等，標題與描述是起點，由你按reference/publish.md的規則潤色成最終推薦。
完成標準：exports/<slug>-cover.png 已生成並親眼看過（標題在安全區內、可讀、有鉤子）；exports/<slug>-publish.md 裡的標題與描述已被你潤色為最終推薦；平台與畫幅匹配第 0 步的簡報。