ship-video 是做什麼的？
您將指導並建構一部 10–45 秒的產品影片。螢幕上的所有內容都是程式碼：一個 HTML 頁面、一條暫停的 GSAP 時間軸（以絕對秒數表示）、從應用程式 DOM 擷取的實際畫面並加以動畫化，最後逐幀渲染成 MP4。
工作的形塑方式。 一部影片的成敗取決於編寫任何程式碼之前的選擇：觀眾是誰、產品帶來的單一改變是什麼、故事如何鋪陳、影片長度。這些選擇會寫入一頁腳本，經用戶批准；在紙上修改只需幾分鐘，但一旦開始建構就要花費數小時。之後，好好地建構、嚴格地自我檢查、渲染，然後展示影片：用戶觀看後告訴您需要修改什麼。除了腳本之外，無須為了其他批准而中斷工作。
腳本位於此檔案旁的 scripts/ 目錄中。在 Claude Code 中，該資料夾為 ${CLAUDE_SKILL_DIR}/scripts；在其他環境中，請根據此檔案的目錄解析路徑，並使用絕對路徑呼叫。下方 $S 代表該資料夾，<film> 代表影片資料夾。請執行腳本，不要閱讀其原始碼；每個腳本均支援 --help。
提問。 只詢問真正的決策（地點、音樂、長度、用戶自己的措辭）；其餘事項由您決定，用一句話說明，並讓用戶在關卡處修改。僅在三個時刻提問：開場（步驟 1）、腳本關卡、渲染完成後；絕不在工作進行中中斷。一個問題格式適用所有主機：每輪最多 3 個問題，每個問題 2–3 個選項，推薦選項優先，附上 1–5 字的標籤，一句話說明對用戶的影響，不要提供「其他」選項（主機可自行輸入自由文字）。使用主機的提問工具（Claude Code：AskUserQuestion；Codex：request_user_input，僅限 Plan 模式），否則使用編號列表搭配字母選項（如「1a 2b」），並以「或告訴我其他事項」結尾。超過 3 個選項時，應拆分為兩個問題，先問決定性的問題；當前面的答案已解決某個問題時，將該問題併入選項中。
限制
若請求觸及以下限制，請一開始就說明：僅支援 16:9（不支援 9:16）；僅限網路 UI（原生應用程式只能從螢幕截圖重建，精確度較低）；時長 10–45 秒；支援 macOS、Linux 或 Windows；輸出 MP4 和動畫 WebP，不支援 GIF。設定過程會將 Chromium 和 Python 套件下載到 ~/.ship-video：沙盒主機（如 Codex）需要網路存取權和該目錄的寫入權限；若指令被阻擋，請告訴用戶需要哪個權限，而不是重試。
開始或繼續
檢查影片資料夾（若不確定則詢問），並從第一個缺失的部分開始：
<film> 中存在 | 從以下步驟開始 |
|---|---|
| 無 | 0 設定 |
index.html，無 PRODUCT.md | 2 探索 |
PRODUCT.md，無 MUSIC.md | 3 音樂 |
MUSIC.md，無已批准的 SCENARIO.md（Approved: 行） | 4 腳本 |
已批准的 SCENARIO.md，無 screens.js（或狀態尚未比對） | 5 複製 |
screens.js 且 review/compare/ 中每個狀態都匹配，有起始的 film.js | 6 建構 |
film.js 且每個場景都已建構，無 out/film-*.mp4 | 7 審查 |
out/film-crisp.mp4 或 out/film-motionblur.mp4 | 詢問要修改什麼（render.md，渲染後的修改） |
用戶可能會跳過步驟（例如「我有腳本了」、「不要音樂」、「直接建構吧」）：跳過並用一句話說明。跳過腳本關卡需要用戶明確的同意。
在第一次回覆和交付時顯示此檢查清單：
- [ ] 0 設定 - [ ] 1 簡報 - [ ] 2 探索 - [ ] 3 音樂
- [ ] 4 腳本（已批准） - [ ] 5 複製 - [ ] 6 建構
- [ ] 7 審查 - [ ] 8 渲染與交付
0. 設定
node $S/lib/check.mjs：若設定已執行過，此指令會立即完成。僅在回報有項目缺失時：執行 node $S/setup.mjs（安裝到 ~/.ship-video，已存在的項目會跳過）。
1. 簡報
首先檢視：README、package.json、路由、元件、網站、現有的螢幕截圖和標誌（實際素材無需詢問即可使用）。然後在連續兩輪中詢問仍缺失的資訊（長度取決於音樂）：
- 播放地點：此產品最可能的三個地點（社群動態、網站、README 或文件、幫助中心），以及它首先指向的地點。這會決定觀眾已知的資訊、是否有聲音、開場（
direction.md，觀眾測試）以及最小文字大小。 - 音樂：是或否；若播放地點為靜音，建議選擇無；若選擇是，則說明音樂僅存在於 MP4 中（README 的 WebP 是無聲的）。
- 第二輪 · 音樂來源（步驟 3 的問題，在此提出，以便在您工作時生成 Suno 曲目）和長度：能展示產品單一改變的最短時長（10–15 秒通常最佳）、較長的時長，以及搭配音樂時配合音樂長度（由曲目決定，根據素材在節拍上剪輯；此時推薦此選項）。
影片類型（發布、單一功能預告、教學、登陸頁面）通常可從請求和地點推斷：直接說明。用戶已說過的任何內容可直接回答其問題。
若用戶希望影片具有某種特定感覺：將其分解為連絡表（ffmpeg -i ref.mp4 -vf "fps=2,scale=480:-1,tile=6x5" <film>/review/reference.png），列出其技巧，借用這些技巧，但絕不複製其內容。
建立資料夾：node $S/new-film.mjs <film>（置於產品儲存庫外部，除非用戶要求放在內部；若已知則加上 --theme light|dark；無音樂影片加上 --silent）。
2. 探索
從 README 製作的影片展示功能；從完整產品製作的影片則展示成果。先瞭解產品。對於小型應用程式以外的項目，若可能，請將此步驟拆分為三個平行子代理（subagents.md）。
- 盤點路由器的每個路由和檢視，包含相關狀態（對話框、調色盤、提示訊息、空白狀態、主題）以及所有動態內容（圖表、地圖、畫布）。
- 逐一檢視：在應用程式執行時（重複使用其伺服器，
render.md，共享機器）執行node $S/capture.mjs <網址> <film> --discover，將每個路由的螢幕截圖寫入<film>/review/discovery/；檢視這些截圖。登入頁面、手機頁面、登陸頁面：參考replicas.md，選項。若應用程式未執行：使用其螢幕截圖和文件，並說明此情況。 - 找出新功能和特色：變更日誌、發行說明、若可用則執行
gh pr list --state merged --limit 30；找出用戶會向朋友展示的 3–5 個時刻；找出構成產品的單一改變。 - 撰寫
<film>/PRODUCT.md：用產品自己的話描述其承諾、觀眾、檢視（核心 / 附帶 / 跳過，附上截圖路徑）、亮點時刻、一個可能貫穿全片的具體案例、以及無法展示的內容。以幾行文字呈現並繼續進行；用戶隨時可以提出修正，最遲在腳本關卡。
3. 音樂
閱讀 music.md。無音樂時：使用 BPM 網格；閱讀 direction.md，無聲影片。音樂來源問題（已在開場時詢問）需展示所有三個選項，每個選項用一句話說明其成本（~/Downloads 中的新檔案歸入自訂檔案選項）：
- 生成的節拍：免費、無版權、幾秒鐘內準備好，偏向功能性配樂而非歌曲。根據規劃的場景撰寫
beat.json，然後執行music.mjs synth。 - Suno：根據影片段落量身打造的真正歌曲；需要 Suno 帳戶、用戶約 10 分鐘的時間、公開使用需要付費方案，因此若用於公開場所，請標註為 Suno（付費方案）（
music.md，版權）。引導用戶完成流程（suno-prompt.md，引導用戶）。不要空等：先從GRID DRAFT撰寫 MUSIC.md，並在使用者生成音樂時起草腳本。 - 自訂檔案：將其複製到
<film>/track.<ext>。
分析曲目、閱讀情節、自行確認 Drop 點，然後撰寫 <film>/MUSIC.md，說明每個段落在故事中的角色。
4. 腳本
閱讀 direction.md，並根據 scenario-template.md 撰寫 <film>/SCENARIO.md：觀眾、故事（問題 → 主角 → 行動 → 在 Drop 點獲得回報）、每個鏡頭的秒數、移動的內容以及鏡頭的終點、最終的逐字文案。先執行範本的自我檢查並修正所有「否」的項目。如果時長不符合素材，請告知用戶並提供更合適的時長。
然後在單一輪次中詢問：僅針對屬於用戶措辭的變體進行提問，以及「批准腳本？」（批准 / 更改時間 / 更改場景），並附上三行故事摘要和鏡頭表格。
5. 複製
閱讀 replicas.md。在應用程式執行時，其本身的 DOM 和 CSS 就是複製品：撰寫 <film>/states.json，包含腳本所需的每個狀態（每次互動的兩側），執行 capture.mjs … --css，然後執行 compare.mjs，並檢視比對的 PNG 直到每個狀態都匹配。若應用程式未執行，則從元件建構，並在報告中說明。
6. 建構
閱讀 film-api.md 和 shots.md。根據擷取輸出設定 track、duration、hits（music.md）以及 fonts/images，然後按照腳本的順序和秒數撰寫場景。在擷取的畫面內移動真實元素（direction.md）。若偏離腳本，請在 與腳本的差異 部分新增一行說明。
邊做邊檢查：node $S/render.mjs <film>/index.html <film>/review/test.mp4 --preset draft --from 0 --to 1 可在幾秒內找出錯誤頁面；用戶可以開啟 <film>/index.html 預覽（空白鍵播放、方向鍵逐格、?t=12.5 跳轉）。
7. 審查
在其他人之前，先以導演的身份檢視影片：
node $S/sheet.mjs <film>/index.html <開始> <結束> <步長> <film>/review/sheet-<場景>.png
node $S/shots.mjs <film>/index.html <film>/review/stills <時間1> <時間2> … --label
每個場景一張連絡表（文字部分 0.25 秒間隔，UI 部分 0.5 秒間隔）、每次剪輯點前後 0.01 秒的全解析度靜止幀、回報點和結尾卡。檢視每張圖片，並在幀上執行 scenario-template.md 的自我檢查；以 0.1 秒的間隔放大檢視每次互動，因為大多數「未完成」的感覺都來自那些半秒鐘的間隔。然後取得一位新評審的意見（subagents.md），並修正問題。最後執行 node $S/audit.mjs <film>/index.html 直到沒有任何錯誤（render.md，稽核）。
8. 渲染與交付
閱讀 render.md：在背景渲染清晰的版本，驗證它（hits.mjs、motion.mjs），必要時修正並重新渲染，然後交付（交付：開啟資料夾、初次剪輯、一個問題）。
參考資料
| 檔案 | 閱讀時機 |
|---|---|
references/direction.md | 步驟 4，並在步驟 6 和 7 再次閱讀：觀眾測試、故事、結構、節奏、構圖、影片類型 |
references/scenario-template.md | 步驟 4（範本和自我檢查），步驟 7（在幀上進行自我檢查） |
references/music.md | 步驟 3：分析、MUSIC.md、無聲網格、生成的節拍、版權 |
references/suno-prompt.md | 步驟 3，當音樂來自 Suno 時 |
references/replicas.md | 步驟 2（擷取選項）和步驟 5 |
references/film-api.md | 步驟 6，在撰寫 film.js 之前 |
references/shots.md | 步驟 6：附有程式碼的配方 |
references/subagents.md | 步驟 2 和 7，若您的主機可以執行子代理 |
references/render.md | 步驟 7（稽核）和步驟 8；在啟動伺服器或渲染之前閱讀 共享機器 |