assafkip/claude-video-editor

製作影片 — 從新手到完成 MP4 的技能

兩個階段，八個循序關卡。每個關卡都會產出一個具體的產物，供下一個關卡使用。請勿跳過任何關卡。

何時使用此技能 — 以及何時轉交

請在以下情況使用此技能：

• 使用者是 HyperFrames 新手，且從一個概念、腳本或大綱開始
• 他們想要一個從頭到尾的逐步引導，而非框架參考資料
• 他們尚未決定影片格式

請在以下情況轉交：

• 使用者貼上一個網址，並希望從該網站製作影片 → 呼叫 /website-to-hyperframes
• 使用者明確想要一個含人臉攝影機與場景疊加的 9:16 直式人物影片 → 在此處執行關卡 1–4，然後從關卡 5 開始呼叫 /short-form-video
• 使用者詢問的是框架規則，而非影片 → 呼叫 /hyperframes

兩個階段

• 階段 1 — 訪談（關卡 1–4）： 在碰觸任何程式碼之前，透過一次對話訪談蒐集所有資訊。意圖、格式、腳本、語音、風格、素材、節奏。彙整成一份 BRIEF.md 並等待明確批准。
• 階段 2 — 建置（關卡 5–8）： 搭建骨架 → 腳本板 → 構圖 → 語法檢查 → Studio 預覽 → 草稿渲染 → 視覺驗證 → MP4 預覽 → 最終渲染。

---

關卡 1 · 意圖與格式

透過 AskUserQuestion 一次問一個問題，盡可能提供選擇題選項。

1. 這個影片的用途是什麼？（宣傳 · 社交廣告 · 上市預告 · 產品示範 · 教學 · 解說 · 開頭/結尾卡片 · 其他）
2. 目標觀眾是誰？（開放式問題）
3. 目標長度？（10–20 秒短 · 20–45 秒宣傳 · 45–90 秒解說 · 1.5–3 分鐘課程 · 自訂）
4. 寬高比？（16:9 1920×1080 · 9:16 1080×1920 · 1:1 1080×1080）
5. 影格率？（30 預設 · 60 用於清晰 UI · 24 電影感）
6. 平台或交付限制？（檔案大小 · 截止日期 · 播放平台）

關卡門檻： 六個問題全部收集完畢。如果答案是 9:16 加上人臉攝影機，請規劃在關卡 5 轉交給 /short-form-video。

完整問題庫：Read: references/interview-questions.md

---

關卡 2 · 腳本與語音

1. 腳本來源？（貼上 · 大綱 → 我來起草 · 我將錄製 · 從文字轉語音 · 無旁白）
2. 如果是 TTS：語音偏好。從 npx hyperframes tts --help 提供選項。同時記錄語速。
3. 如果是人臉攝影機：錄製路徑 · 全螢幕或角落放置 · 是否需要逐字稿？（npx hyperframes transcribe <file> --model small.en --json）
4. 字幕？（關閉 · 炫目 · 企業風格 · 逐字卡拉 OK · 極簡）

關卡門檻： 腳本已獲取（或已起草），音訊計畫已獲取，字幕計畫已獲取。

---

關卡 3 · 風格收集

在詢問使用者任何問題之前，先盤點現有素材。 檢查 <workspace-root>/assets/ 以及任何專案 assets/ 資料夾。不要詢問已經存在的東西。

然後逐步詢問 — 他們不需要回答所有問題：

1. 風格指南或品牌文件？（貼上路徑 · 沒有）
2. 色板？（十六進位色碼 · 無 — 使用 MOTION_PHILOSOPHY 預設值）
3. 字型？（Google Fonts 名稱 · 檔案路徑 · 無 — 使用 Inter 和 JetBrains Mono 預設值）
4. Logo 檔案？（路徑 · 無 — 改用文字標誌）
5. 參考影片的氛圍？（網址/路徑 · 無）
6. 其他素材？（螢幕截圖 · 產品照片 · B-roll · 音樂 — 列出路徑）
7. MOTION_PHILOSOPHY 美學（黑色畫布 · 金屬字體 · 透視線網格 · 鞭子轉場）或不同風格？
8. 節奏？（快速 1–2 秒 · 平衡 2–3 秒 · 放鬆 3–5 秒）
9. 音樂？（無 · 環境鋪墊 0.15 · 音樂背景 0.4 · 全音量 0.8 — 如果有檔案則提供路徑）
10. 結尾或行動呼籲文字？

切勿對使用者強加品牌。 僅在使用者明確拒絕提供風格時，才回退使用 MOTION_PHILOSOPHY 預設值。

完整風格流程與 MOTION_PHILOSOPHY 預設值：Read: references/style-intake.md

---

關卡 4 · 簡報彙整（建置前的強制關卡）

1. 如果工作區根目錄存在 MOTION_PHILOSOPHY.md 則必須讀取。若不存在，則使用 references/style-intake.md 中的預設值，並在簡報中註明其缺失。
2. 詢問專案存放位置（如果不明確）：
   • 如果存在 video-projects/ → 使用 video-projects/<slug>/
   • 否則 → 詢問使用者
3. 寫入 <project-folder>/BRIEF.md：
   • 代號 · 意圖 · 觀眾 · 尺寸 · 影格率 · 長度
   • 腳本（完整或大綱）
   • 語音選擇 · 字幕計畫 · 人臉攝影機計畫
   • 風格設定檔：色板（十六進位），字型，logo 路徑，參考影片
   • 節奏
   • 素材清單與路徑
   • 結尾 / 行動呼籲文字
4. 顯示簡報。等待明確批准。 在收到明確的「是，請建置」之前，請勿繼續到關卡 5。

---

關卡 5 · 骨架搭建與腳本板

首先檢查是否需要轉交

如果簡報描述的是含人臉攝影機與場景疊加的 9:16 直式人物影片，請立即呼叫 /short-form-video 並傳遞簡報。其四層骨架專為該格式設計。

否則繼續：

骨架搭建

1. mkdir <project-folder>
2. 如果存在格式相似的兄弟專案，建議複製其 hyperframes.json 和 meta.json 作為範本。否則在資料夾內執行：npx hyperframes init
3. 編輯 meta.json，填入使用者的代號、尺寸、影格率。
4. 將提供的素材複製到 <project-folder>/assets/。
5. 從關卡 3 建立 <project-folder>/assets/style-profile.md — 作為色板/字型/logo 的單一事實來源。

腳本板

使用 references/storyboard-template.md 中的範本產生 <project-folder>/STORYBOARD.md。每個拍點都會得到：

拍點 N — 標題（開始–結束, 長度）— 一句話概念
視覺元素：[每個元素，大小，動畫，時機]
動畫語言：[動畫類型]
使用的緩動函數：[3–4 個不同的 GSAP 緩動函數]
結束：[轉入下一個拍點的轉場]
音訊：[旁白台詞 / 音效 / 音樂層]

檔案頂部：一個包含場景 · 開始 · 長度 · 構圖檔案的時序表。

建議採用三分法結構：

• 第一幕（鉤子）≈ 總長度的 20%
• 第二幕（主體）≈ 55%
• 第三幕（收尾與結尾，保留 4–6 秒）≈ 25%

（MOTION_PHILOSOPHY §0 法則 9, §1。）

將使用者意圖對應到目錄區塊： Read: references/catalog-intent-map.md

關卡門檻： 顯示腳本板與時序表。反覆修改直到使用者批准。

---

關卡 6 · 建立構圖

呼叫 /hyperframes 以取得框架規則。此技能負責骨架搭建與紀律；/hyperframes 負責執行規則。

為每個子構圖搭建骨架

<div data-composition-id="scene-name" data-start="..." data-duration="...">
  <style>[data-composition-id="scene-name"] { /* 作用域限定 */ }</style>
  <!-- DOM -->
  <script>
    (function(){
      const SLOT_DURATION = ...;
      const tl = gsap.timeline({ paused: true });
      // ... 補間動畫 ...
      tl.to({}, { duration: SLOT_DURATION }, 0);   // 錨點 — MOTION_PHILOSOPHY 法則 11
      window.__timelines["scene-name"] = tl;
    })();
  </script>
</div>

完整範本 + 字幕模式 + 環境背景模式：Read: references/composition-scaffold.md

建置規則

• 環境背景 放在 data-track-index="0"，涵蓋整個構圖長度。
• 動態文字開場： 每個單字錯開 0.06–0.10 秒。
• 字幕 作為 index.html 中根構圖的 body 層級兄弟元素，每個帶有 data-track-index ≥ 20。切勿放在場景時間軸內（MOTION_PHILOSOPHY §3.13）。
• 目錄區塊 透過 npx hyperframes add <name> 安裝。立即將區塊的 CSS 作用域限定在 [data-composition-id="..."] — 目錄區塊預設帶有會滲透到父文件的 html, body { ... } 規則。
• 直式 + 人臉攝影機： 將原生 1920×1080 的畫面包裹在一個變形（translate + scale）中，以適應下半部或全螢幕模式。（如果你最後來到這裡而非 /short-form-video，請強烈考慮轉交。）
• 僅套用使用者提供的內容。 使用他們的色板、字型、logo。不要注入任何其他東西。如果他們選擇 MOTION_PHILOSOPHY 預設值，則從 references/style-intake.md 提取色板與字型配對。

確定性

不允許 Math.random()、Date.now() 或渲染時的 fetch()。請使用種子化偽隨機數產生器或和諧正弦雜湊函數（MOTION_PHILOSOPHY §3.10）。

---

關卡 7 · 語法檢查 → Studio 預覽（預覽關卡 1 — 強制執行）

1. npx hyperframes lint — 修復所有錯誤，分類處理警告。
2. 在背景執行 npx hyperframes preview。
3. 等待「Studio running」出現在 http://localhost:3002。
4. 將網址 以及 個別構圖網址（http://localhost:3002/?comp=<id>）交給使用者。如果專案包含 WebGL 著色器區塊，請優先提供個別網址 — 軟體 WebGL 回退可能會導致主構圖卡住。
5. 等待明確的「看起來不錯，渲染一個草稿」 再繼續。沉默不等於批准。

熱重載已啟用 — 編輯會即時顯示。

---

關卡 8 · 草稿渲染 → 視覺驗證 → MP4 預覽 → 最終渲染

草稿渲染

npx hyperframes render --quality draft --output renders/<slug>-draft.mp4

視覺驗證（交付前強制執行）

語法檢查通過 ≠ 設計正常。提取影格並檢視它們。

1. mkdir -p renders/frames
2. 針對每個拍點的關鍵時刻以及每個轉場：

   ffmpeg -y -ss <t> -i renders/<slug>-draft.mp4 -frames:v 1 -q:v 2 renders/frames/t<t>.png
   

3. 對每個 PNG 呼叫 Read 工具。 Read 工具會將圖片載入上下文 — 不要只列出檔案名稱。
4. 逐影格確認：無人臉被裁切，每個場景的人臉模式正確，文字可讀且符合色板，無溢出，轉場落在預期的單字上，無空白影格。
5. 如果任何地方有問題：修正 → 重新渲染 → 重新驗證。切勿交付有缺陷的草稿。

MP4 預覽（預覽關卡 2 — 強制執行）

npx serve renders -p 8080 -n

不要使用 Python 的 http.server — 它不支援 HTTP Range 請求，會導致時間軸拖曳功能失效。

將 http://localhost:8080/<slug>-draft.mp4 交給使用者。等待明確的確認，確認播放與音訊同步正常。

最終渲染

npx hyperframes render --quality standard --output renders/<slug>-final.mp4

報告輸出路徑。完成。

完整預飛行與交付前檢查清單：Read: references/build-checklist.md

---

不可協商的底線（承重結構 — 請勿放鬆）

• 絕對不要跳過預覽關卡 1（Studio）或預覽關卡 2（渲染後的 MP4）。 每次建置都必須通過兩個關卡。
• 絕對不要聲稱渲染完成，直到影格已被提取並透過 Read 工具讀取。
• 絕對不要在專用專案資料夾以外的地方建置。 切勿將 index.html 放在工作區根目錄。
• 絕對不要在盤點工作區之前 向使用者要求素材。
• 絕對不要跳過每個子構圖時間軸結尾的 tl.to({}, { duration: SLOT_DURATION }, 0) 錨點補間。 MOTION_PHILOSOPHY 法則 11。
• 絕對不要在渲染邏輯中使用 Math.random() / Date.now()。 僅使用種子化雜湊。
• 絕對不要對 <video> 標籤添加 class="clip"。 這會破壞它們。
• 絕對不要對使用者強加品牌。 先詢問；僅在使用者明確拒絕時才回退使用 MOTION_PHILOSOPHY 預設值。

---

參考資料

• references/interview-questions.md — 依關卡分類的完整問題庫
• references/style-intake.md — 風格訪談 + MOTION_PHILOSOPHY 預設值
• references/catalog-intent-map.md — 「使用者說 X → 安裝 Y」
• references/storyboard-template.md — 逐拍點範本 + 實例
• references/composition-scaffold.md — 作用域樣式 + IIFE GSAP 範本
• references/build-checklist.md — 預飛行 + 交付前檢查關卡

外部（工作區層級）：

• MOTION_PHILOSOPHY.md — 此技能假設存在的唯一外部參考。美學基準。若檔案遺失，回退選項位於 references/style-intake.md。

相關技能

• /hyperframes — 框架規則，在關卡 6 呼叫
• /hyperframes-cli — init · lint · preview · render · transcribe · tts
• /hyperframes-registry — 安裝目錄區塊
• /gsap — GSAP 動畫參考
• /short-form-video — 若為 9:16 人物影片格式，在關卡 5 轉交
• /website-to-hyperframes — 若起始輸入為網址，在關卡 1 轉交