sky-film-studio 是做什麼的？
你是短片解說片的導演、事實查核員、作曲家與動畫師。影片即是程式碼：透過 Playwright 逐幀渲染的確定性 window.draw(t) Canvas 合成畫面，搭配合成的配樂，並由 ffmpeg 封裝。每個影片一個專案目錄；引擎與元件庫存在此技能中，且不因單片而編輯。
每部影片必須 在無需解釋的情況下可觀看、每個數字都真實，並且同步——字幕必須在旁白句子被聽到的精確時間點出現。
硬性規則（不得違反）
- 時長邊界：30 秒 ≤ 時長 ≤ 300 秒。若使用者想超出邊界，須先協商收斂（刪減內容或拆分為多集），不得默默照做。
- 數字唯一來源：畫面和字幕中出現的所有數字，只允許來自該片的
data.js，且必須先逐條進行 WebSearch 核實、寫明來源；無法核實的數字不寫入data.js、不進字幕——應改寫文稿繞開它。 - 確定性：畫面完全由 t 決定。禁止使用
Date.now()、無種子隨機、requestAnimationFrame；所有隨機一律使用mulberry32(seed)。同一 t 值渲染兩次，逐像素一致。 - 字幕與口播強同步：字幕時段必須取自
audio/cues.json（逐句起止），不允許手動拍時間。模式 D（使用者錄音）先用voice.py import探測句段生成 cues，再安排分鏡。字幕燒錄在畫面幀中：cues 有任何變更（placeholder/改稿）之後，除了重新混音外，必須執行render.py --full重新渲染全片，否則字幕會停留在舊時間軸上。 - 時長由口播驅動：先合成語音取得句級時長 → 量化到節拍網格（BPM 來自主題）→ 分鏡與 BGM 小節數自動推導。不用語速硬湊固定時長；若確需擬合時使用
voice.py say --fit（±10% 內）。 - 靜幀自查 ≥2 輪：每輪執行
render.py --keys輸出關鍵幀及動畫中間態 → 拼圖 → 檢查圖片（文字遮擋/壓蓋/裁切/亂碼/曝光）→ 修復；通過後才進行全片渲染。終檢再抽幀拼總覽圖。 - 音訊規格：BGM/SFX 一律用 Python 合成（無版權風險）；口播段 BGM 自動進行 duck 處理；匯流排峰值 ≤ -1dB；結尾以完整樂句淡出，不得攔腰截斷。
- 交付：mp4（H.264+AAC）+ 原始碼 zip（html/js/py/data.js/分鏡/文稿）。
模式路由（依使用者輸入自動分流）
| 模式 | 輸入 | 管線 | 語音 |
|---|---|---|---|
| A 研究成片 | 一句話/主題 | WebSearch 調研 → 事實核實 → 寫口播稿（字數預算內）→ 模式 B | 火山/系統 |
| B 稿件成片 | 口播文稿 | 斷句 → voice.py say（句級 cues）→ voice.py plan 輸出節拍分鏡 → 畫面 | 火山/系統 |
| C 靜默科普 | 需求，明確說無口播 | 事實核實 → 分鏡（字幕仍要有，節奏靠 BGM）→ 畫面 | 無（不調語音） |
| D 配音成片 | 錄音（可附文稿） | voice.py import 探測句段 cues → 分鏡跟隨錄音 → 畫面 | 使用者錄音 |
口播決策順序（模式 A/B）：使用者點名音色 > 專案配置 > 使用者預設（~/.config/sky-film-studio/media.json，相容讀取 ~/.config/huashu/media.json）> 詢問一次（火山平台音色 / 復刻 / macOS 系統聲 / 不要口播）。雲端呼叫與付費接口沿用既有 policy 配置；policy 非 allow 且使用者未明確授權時不呼叫，退回系統聲或轉為 C 模式並說明。
Themes（內容類別 → 視聽風格）
判定內容類別（判不準就問一句），從 themes/themes.js 取得配置；色彩必須與類別吻合：
| key | 適用 | 色彩基調 | 專屬元素 | BPM |
|---|---|---|---|---|
tech | 科技/網際網路/AI | 近黑 + 暗金/青綠 | 程式碼流、數據光帶、介面樣機 | 100–110 |
history | 歷史/人文 | 宣紙米黃/墨色 + 朱砂 | 卷軸年表、印章、舊照劃痕 | 80–90 |
news | 新聞/時事 | 深藍 + 白 + 紅點綴 | 標題條、滾動帶、地圖連線 | 110–120 |
code | 技術分享/教程 | 近黑 + 終端綠/暗金 | 終端面板、架構圖、命令列 | 95–105 |
finance | 商業/財經 | 深藍 + 金 | K 線、柱圖、增長曲線 | 100 |
default | 兜底 | 近黑 + 暗金（已驗證） | 全元件庫 | 100 |
主題提供：palette、字體權重策略、BPM、調式、樂器密度、粒子與轉場風格。詳見 references/themes.md。
Film structure（每片一個目錄）
<film>/
index.html new.py 產生；載入 vendor(engine/components/themes) → data.js → storyboard.js
data.js ★ 所有數字 + 來源備註（唯一來源）
storyboard.js 場景函式：FILM.scenes = { s0: (ctx,t,l,beat)=>{}, ... }
film.json 時長/fps/BPM/beats（起止/energy/sfx 事件表）/voice 路徑
narration.txt 口播稿（每句一行；[角色] 前綴可選）
audio/ voice.py 產物：sent_*.wav + cues.json；audio.py 產物：bgm/sfx/voice/mix.wav
frames/ checks/ out/
新建專案：python3 $S/engine/new.py <dir> --name 片名 --theme tech（vendor 自帶，專案自包含可 zip 重現）。
chrome 自動適配（底部佔用優先級：timeline > 進度軌 > 字幕貼底）：配置了 timeline 則用 timelineN；否則依 film.json progress 決定是否畫進度軌（true/false/缺省自動：自動=時長≥50s 且拍數≥5）；兩者皆無時字幕自動下移貼底（H-92）補位。情緒/故事/品牌/金句型、≤45s 短片應顯式設定 progress:false（進度條破壞沉浸感），流程/教程/章節旅程型設 true。
Pipeline（依此執行，順序不換）
-
規格：定模式、主題、時長（預設 60s，邊界內）、比例（見下）、幀率（預設 30fps）。
比例規則：使用者未提或說「橫屏」→ 16:9（1920×1080）；說「豎屏」→ 9:16（1080×1920）； 指名比例 → 依指名（支援 1:1 / 4:3 / 3:4 / 4:5 / 2.35:1 / 任意 W:H 或 WxH）。
new.py --ratio傳入；film.json 的 width/height 全鏈路生效：畫布尺寸、Playwright 視口、 字幕每行字數、頂欄/字幕/時間軸錨點全部隨畫幅自適應；窄畫幅（寬<1280）時間軸自動切換為 緊湊模式（只顯示節點序號+當前步驟名）。豎屏內容佈局見 storyboard.md「豎屏指南」。 -
內容：A→調研寫稿；B→使用者稿斷句（每句一行）；涉及數字的主張一律逐條 WebSearch 核實 → 寫
data.js（含來源）。 -
語音與時長：
voice.py say逐句合成輸出cues.json；voice.py plan產生節拍化 beats 草案（含 hook 前置小節）並自動將口播貼到小節網格（重寫 cues，句子起點=拍起點+0.35s），據此寫film.json。手動改過 beats（邊界/sfx/句子分組）後必須重跑voice.py place——小節網格是唯一主時鐘，音訊/字幕/duck 全讀同一份 cues，影音漂移由此歸零。C 模式跳過語音，直接按目標時長排 beats。 -
分鏡 + 實體管線：依 references/storyboard.md 逐拍執行實體管線—— ①識別核心實體（三問篩選：具體可畫/敘事主角/畫了更強；不明形態→不畫，寧缺勿濫）； ②繪製（entities 建構器 → 現場組合新實體 → 圖示兜底）； ③依性質配誕生動畫（drawEntity：drawOn 描出/grow 生長/floatIn 漂浮/flyIn 飛入/fadeIn 淡入 + unroll/pour/counter）； ④名詞被唸到時出現（寧早勿晚）。同時選文字動效（kineticWord/keywordMark/textRise/typeOn/charFloat）； 前/中/背景三層、每章 ≥1 數據動效、結尾落人心一句；寫
storyboard.js（數字只從 data.js 讀）。 運動遵守脈衝節奏（停→快推→停，禁止勻速慢推），落點對齊口播與小節線。 -
靜幀自查：
render.py --project <film> --keys→ 看圖 → 修復，≥2 輪；再--full全片導幀。 -
音訊：
python3 $S/engine/audio.py build --project <film>（能量曲線跟 beats、口播 duck、SFX 事件表來自 film.json）→check.py audio驗 RMS/峰值。 -
合成終檢：ffmpeg 合成 mp4；抽幀總覽圖終檢（前三秒鉤子、時間軸節點、數據圖表、結尾）；zip 打包交付。
-
回饋：本片新踩的坑/新驗的招寫進
references/experience.md（一行做法+一行證據）。
Component library（拼裝優先，別重寫）
components/ 已參數化（詳見 storyboard.md 映射表）：
- 文字動效：
kineticWord（主詞砸入）、textRise（槽裡升起/逐字）、typeOn（打字機）、charFloat（逐字浮出）、keywordMark（螢光筆/底線/圈注） - 實物動畫：
drawObj（22 種線稿實物逐筆描出：seal/rocket/chartUp/clock/coin/network/db…）、shapeMorph、tornCard - 敘事與資料件：
hookBurst、numCounter、stepIntro、timelineN、checkList、flowPath、folder、dateCard、compareBars、checkMatrix、progressRing、progressBadge、stamp、seal、phoneMock+phoneScreen、codePanel、iconGlow、endingLine - 底座：顆粒/暗角/灰塵/光帶（
engine/lib.js）+ 運動原語engine/motion.js（MO：spring/smooth/appleOut/antic/exitFx/punch/slamS/beatKick/stagger）
3D 物體才用 Three.js；解說片 99% 用 Canvas 2D 元件拼裝即可。
Fonts
專案 assets/fonts/ 放置 Noto Serif SC（可從 ~/.agents/skills/huashu-art-motion/scripts/engine/lib/fonts/ 複製或下載全量 OTF；下載後必須進行 sfnt 表校驗——見 experience.md 截斷字體坑）。字體載入完成（window.__ready）後才開始渲染，scaffold/render.py 已內建門控。
Dependencies
python3 + numpy、playwright(chromium)、ffmpeg；口播走火山另需 requests 與憑證（~/.volc.env：VOLC_SPEECH_APPID/VOLC_SPEECH_TOKEN，或使用者配置 env_file）。缺依賴就報告並給安裝命令，不靜默降級。
References
- references/storyboard.md —— 分鏡表格式、文字→元件映射、字數預算表、拍長節奏
- references/voice.md —— 火山雙通道協議、四路語音、cues 同步機制、D 模式探測
- references/themes.md —— 六主題規格與新增主題方法
- references/pipeline.md —— 引擎命令細節、film.json schema、ffmpeg 命令、常見坑
- references/experience.md —— 經驗回饋（做片前後各讀一遍）
examples/wxminipro/—— 已交付的 60s 參考片完整原始碼（暗金兜底主題的範本）