filmsmith 是做什麼的？
十種方式為你的程式碼拍攝影片。根據簡報製作一支短技術影片——技術示範、技術報告或解說、技術產品發布——其長度根據內容計算，影片中無任何真人出現：選擇一種模式，複製其模板，填入 content.js，然後渲染。每一幀畫面皆以程式碼繪製，每一段聲音皆以程式碼合成（可替換為生成的音樂音軌），因此一部影片只需要一個能夠執行 shell 指令的編碼代理即可完成。此技能建立在一個品味理論之上（基礎），由此理論及擁有者的判斷衍生出十項核心原則，一個共用的系統（包含顏色、字體、空間與動態），以及十種將這些原則應用於各自視覺語言的模式。
所有模式的共同風格：明快、直接、乾淨——幾乎每個節拍都有變化，每次變化帶來一項新事物，觀眾從不需等待影片——而且乾淨不等於單調：元素精簡，每個元素的移動都足夠流暢以吸引目光（原則 4–6）。
需求
- 任何能執行 shell 指令的編碼代理。以下的
SKILL_ROOT是指包含此SKILL.md的資料夾。 - 需安裝 Node 22 或更新版本，以及位於 PATH 中的
ffmpeg和ffprobe。new-film會檢查這些依賴項，若缺少則會顯示訊息並停止。 - 在影片設置和渲染期間需要網路連線：使用來自固定 google/fonts 提交版本的字體、來自 npm 註冊表的固定 GSAP 版本（兩者皆儲存在影片資料夾中）、首次執行
npx [email protected]（它也會取得無頭 Chrome），以及在渲染時，HyperFrames 編譯器也可能從 Google Fonts 獲取字體。離線渲染未經驗證。請保持模板所固定的 hyperframes 版本；不要在影片內部升級它。 - 此版本的螢幕文字為英文；當使用者要求中文或其他文字時，請告知模板尚未支援。
模式
| 模式 | 中文 | 外觀風格 | 型態變體 | 適用於 |
|---|---|---|---|---|
| thread | 一線 | 一條線變成一切，無剪輯 | thread：均勻規則或膨脹線條 | 影片、動態或渲染工具鏈的展示影片 |
| ink | 落墨 | 每個節拍重擊粗體文字，墨點綻放為色彩 | typeWidth：壓縮或延伸字體 | 名稱揭示、發布片頭、單行宣言 |
| plakat | 招貼 | 動態的國際風格海報，一種信號色 | form：方形或對角線區域 | 一項主張加上步驟，以及做出決定的人 |
| blueprint | 藍圖 | 一張張繪製的工程圖，琥珀色印章 | linework：墨水或鉛筆 | 包含零件和簽核的系統與工作流程 |
| phosphor | 熒屏 | 夜間終端機，一種磷光強調色，發射 HUD | screen：CRT 掃描線或平面 | CLI 與開發者工具 |
| tally | 算籌 | 每個項目一個方塊，圖表間重新分組 | mark：方塊、圓點或 Isotype 圖示 | 計數、佔比、資料集故事 |
| trace | 演算 | 演算法狀態的暗色即時圖表 | stroke：向量或草圖 | 說明機制或演算法運作方式 |
| morph | 一筆 | 一個墨水形狀，依序攀升：點 → 線 → 面 → 立體 → 介面 → 標記，無剪輯 | corners：圓角或切角 | 開發者工具與介面產品：一個源頭成為所有表面 |
| halftone | 網點 | 雙色印刷：標記的一部分靜止不動，每個世界在其周圍印刷，然後拉回至整個標記 | dot：圓點、方點或線性網屏 | 模型與產品發布：幾項功能、一個數字、名稱 |
| pulse | 節拍 | 一個問題以查詢方式演出：一個節拍一個單詞，背景沿著一個色相翻轉，答案出現時全白閃爍 | aperture：切口或圓形 | 版本發布與基準測試答案：一個經過測量的結論 |
每種模式都有顏色預設（在其卡片上）和一種型態變體，兩者皆在 content.js 中設定；預設渲染方式與先前相同。每張卡片列出了它的用例與一個實際範例，並標註了最佳適用情況。2026-10-19 之前的模式名稱（thread-reel、ink-beat、swiss-poster、blueprint-drafting、terminal-launch、unit-data、diagram-explainer）在 new-film 中仍然有效。
選擇規則及模式卡片格式：references/modes/README.md。模式之間不得混合。主題（按影片類型劃分的敘事骨架與規則）：tech-product-launch 適用於 thread、ink、plakat、blueprint、phosphor、morph、halftone 和 pulse 模式；tech-explainer 適用於 tally 和 trace 模式。
工作流程
1. 釐清
跳過使用者已提供的資訊；詢問其餘部分，首先詢問模式。以一般對話方式提問，每次最多三個問題；當某個資訊缺口不妨礙開始時，先做假設並告知使用者。所有影片均為 16:9，1920×1080，適用於橫向全螢幕播放；當被要求製作豎屏或方形影片時，請說明此技能無法製作。
| # | 問題 | 原因 |
|---|---|---|
| 1 | 內容是什麼：一個工具、帶有步驟的主張、一個系統、一個名稱、一段展示影片、數字、還是一個機制？ | 決定模式（選擇表）；提出建議並說明原因 |
| 2 | 事實來源為何（倉庫、文件、資料集、演算法）？ | 螢幕上的每個事實都來自於此；每個數字都經過計算 |
| 3 | 平台，以及是否有目標長度？ | 長度根據內容計算（原則 5）；目標長度會在模式範圍內調整節奏，然後增減場景 |
| 4 | 使用哪個調色板預設？ | 僅限預設，模式卡片上列出；不接受自定義十六進制顏色值 |
| 5 | 硬性限制（必須顯示、不得顯示、URL、名稱）？ | 避免重工 |
| 6 | 音樂：此代理能否呼叫音樂生成 API？ | 如果可以，則使用與影片節奏匹配的生成背景音樂來取代合成的背景音樂（系統）；如果不能，則使用合成的背景音樂，並在交接時說明 |
當模式、來源、調色板預設都已指定，音樂來源已知，並且目標長度（如果有的話）也已確定時，即完成此步驟。
2. 搭建
node <SKILL_ROOT>/scripts/new-film.mjs <mode> <film-dir> --palette <id>
此指令會檢查 Node 和 FFmpeg，複製模板，加入共用執行時期作為 lib/（附帶 lib/VERSION 戳記），寫入 PLAN.md 骨架，從一個固定的 google/fonts 提交版本下載模板 fonts.json 中列出的字體，以及將固定的 GSAP 版本下載到 lib/vendor/；如果任何步驟失敗，它會停止，因此影片永遠不會使用備用字體渲染，也不會依賴 CDN。需要可變字體軸的模板會在 fonts.json 中宣告其軸（weight 和 stretch 範圍，請參閱 CONTRACT.md）。然後完整閱讀模式卡片和資料夾中的 TEMPLATE.md：場景註冊表、每個插槽的字元限制以及固定的編排規則都在那裡。當你能夠說出該模式提供的每種場景類型時，即完成此步驟。
3. 概念與節拍規劃
new-film 已在影片資料夾中寫入一個 PLAN.md 骨架。在觸碰 content.js 之前先填寫它；沒有規劃的影片不予渲染（原則 10）：
- 概念句，形式為「在這部影片中，[該產品特有的東西] 變成了 [模式的標誌性裝置]」，以及競爭者測試：將最接近的競爭對手放入句子中，此句必須不再成立。然後是貫穿線（從第一幀到最後一幀引導目光的物體或畫框）。
- 禁用清單：從模式卡片的「出廠預設」和 ai-tells.md 開始；加入任何與最接近的參考影片過於相似的元素。
- 最接近的參考與母題表：命名最接近的參考影片，並列出此影片與之共享的母題；在具有已知參考影片的模式中，共享超過一半的母題將導致 P1 失敗。
- 節拍規劃：每個場景一行——場景類型、螢幕文字（以及哪些是主要文字或一瞥文字）、事實來源、此場景在下一場景中變成什麼、以及音樂在哪裡中斷以供閱讀或在關鍵時刻淡出。不選擇長度：將場景寫入
content.js並執行npm run fit，它會列印每個場景的開始時間、節拍、閱讀需求、轉向前填充以及其在短語捨入中的份額，以及影片總長度，寫入renders/timing.json，並將表格複製到PLAN.md中介於其fit標記之間。當PLAN.md缺失時，npm run fit會停止；當PLAN.md仍有未填寫的<!-- fill -->部分時，它會發出警告。
在撰寫文案之前，請閱讀該模式 TEMPLATE.md 中的長度表：它說明了每個場景的哪些插槽屬於主要文字以及它們如何進入，以便可以預算每個狀態而不是在過程中發現。當每種場景類型都在註冊表中，每個字串都符合其字元限制，每個數字都指定了計算它的程式碼，並且 npm run fit 報告沒有錯誤時，即完成此步驟。字元限制只是第一步篩選：一個插槽的寬度可能取決於其相鄰插槽，因此像素檢查是步驟 4 中的紅色橫幅。對於宣告使用計時 API 3 的模板，錯誤意味著影片違反了四層變化的其中一層（原則 5）：超過五個主要文字單詞同時進入（主張則為八個，在標記的暫停中閱讀）、著陸後持續超過兩個節拍、構圖超過 6 秒、超過四個節拍無變化間隔、或表達性轉場與高峰的數量或位置錯誤。首先將長行拆分為一個接一個進入的短語，然後將重複的標籤設為一瞥文字，最後拆分場景；切勿縮小字體或加快速度超過閱讀下限。在計時表下方，npm run fit 會列印層級衡量指標；仍在使用 API 2 的模板會保留其頁面限制（十二個主要單詞，一個步驟的停留為一個小節，最後一個步驟為一個半小節，一個頁面為四個小節），並將層級顯示為 INFO 註解。
4. 先填充與取景
編輯 content.js（以及模式使用的 data/ 或 run.js）；永遠不要輸入 duration 或場景 bars 來達到某個長度。然後渲染關鍵幀的靜止畫面，並在動畫化之前查看它們（腳本會先執行 fit，因此靜止畫面使用當前的長度）：
npm run snapshot -- --at <t1>,<t2>,<t3>
靜止畫面中的紅色橫幅會指出文字超出其方框的插槽名稱：縮短該文字。修正任何違反核心原則或模式原則的幀：資訊文字小於 25 像素、無法閱讀的文字、超過三個字體層級、兩個主角、第二個強調色、裁剪或溢出的文案、或來自 ai-tells.md 的任何內容。當每個關鍵幀都通過模式卡片的 P0 檢查時，即完成此步驟。
5. 渲染
npm run film # fit → audio → check → render, writes renders/film.mp4
npm run check 必須報告 0 個錯誤。其警告會根據清單進行判斷：只有當文字仍在進入（打字、淡入）且著陸後被閱讀一次時，對比度警告才是可接受的；任何其他警告都必須修正或列在「已知問題」下。聲音遵循與 content.js 相同的節拍網格；若要使用生成的音樂，請以影片的節奏和長度（renders/timing.json）渲染它，將其儲存在 assets/audio/ 下，並設定 content.bed = { file, offset }（請參閱該模式的 TEMPLATE.md）。
6. 測量與審查
node <SKILL_ROOT>/scripts/check-film.mjs renders/film.mp4 --film-dir .
sh <SKILL_ROOT>/scripts/contact-sheet.sh renders/film.mp4 renders/contact-sheet.jpg 20
check-film 讀取 renders/timing.json 並將其與渲染結果進行比較：格式與長度、響度（含短期和瞬時跳躍）、黑幀、按區域計算的閃爍、節拍上的關鍵事件（2 幀內，包含畫面事件和聲音起始（≥ 3 dB，1 幀內））、每個場景在內容遮罩內的靜止拉伸（相對於顆粒感知噪聲底限）、節奏（無長時間的近靜止節拍序列，近靜止部分不超過影片一半）、停留穩定度、交接、等長場景序列，以及宣告事件上的四層變化（T0 間隙、T1 構圖長度、T2 表達性轉場、T3 高峰、停留長度），僅對使用計時 API 3 的模板判定 FAIL；畫面起始、大面積變化和最大聲的時刻是像素和訊號估計值，附於其旁。最小文字、文字對比度、字體層級、強調色面積、八度平衡、四小節重複和限制是像素或訊號估計值，以 INFO 報告。無資料可衡量的項目報告為 N/A，而非 PASS；--json 會給出每個結果及其對應的清單項目。
然後瀏覽 references/checklist.md 和模式卡片的檢查項目：從金字塔底部向上的 P0，然後從上到下進行判斷（契合度、新鮮度、質感）。在更改任何內容之前先進行測量；修正原因，然後重新測量。當所有 P0 都通過，並且所有 P1/P2 的缺失都已修正或寫入影片 README 的「已知問題」下時，即完成此步驟。
7. 交接
提供 MP4 路徑、連環畫，以及一個包含規劃、模式與預設、音樂來源（合成或生成）、指令、check-film 報告和已知問題的 README；除非有人聽過，否則加上「尚未經聽覺確認」。要求使用者的評語，並原樣引用回來並附上日期；當使用者無法提供時，寫上「評語待定」並停止。
維護者：從評語到規則
僅供維護此技能原始碼的人使用；影片製作者在步驟 7 完成後即可停止。評語不會直接編輯模式卡片或原則。首先將其置於金字塔的某一層，並根據 foundations.md 進行檢查：在第 1–2 層，由標準決定；在第 3–4 層，由領域共識決定，除非偏離背離並附有理由；在第 5–6 層，由擁有者在理論判定為同等優秀的候選方案中選擇。一個傾向在經過兩次一致的評語後會成為一條規則。