KaranO-Dev/one-take

one-take 是做什麼的？

一次問完所有問題。然後製作完整的影片，所有格式，經過檢查，無需更多問題。

此技能負責編排；HyperFrames 負責渲染。它需要 HyperFrames 技能（hyperframes、hyperframes-core、hyperframes-animation），若有 hyperframes-registry、hyperframes-keyframes、media-use、figma 和 humanizer 則效果更佳。如果缺少 hyperframes-core，請停止並提供安裝指令：npx skills add heygen-com/hyperframes。

下方的 SKILL_DIR 指的是此技能所在的資料夾。腳本是純 Node (≥ 22) 加上 ffmpeg，無需安裝。

約定

1. 單一次詢問環節。 先進行偵測，然後一次性提問（階段 1）。獲得回答後，不再詢問任何問題。唯一的例外是遇到無法預設處理的阻礙，例如不存在的檔案或拒絕載入的網站。此時只能提出那一個確切的問題，然後繼續。
2. 詢問答案授權渲染。 它不會授權發布、上傳、推送或下載使用者未指定的任何內容。這些動作需在報告之後，另行詢問。
3. 事實來自計算，從不手動輸入。 畫面上的每個數字都來自 facts.json 或使用者提供的來源。絕不虛構統計數據、引言、標誌或推薦。
4. 畫面決定聲音。 每個應被聽見的動作，都會在發生時呼叫 T.cue()。配樂根據這些提示點建構，確保聲音與畫面同步。
5. 完成意味著通過 QA。 一個檔案只有在通過 qa.mjs 的檢查，或者失敗原因在報告中說明（且無法在兩次修復中解決）時，才算完成交付。

階段 0：偵測（詢問前，靜默執行）

node SKILL_DIR/scripts/detect.mjs <主體路徑…> --out /tmp/one-take-detect.json

• 在目前的儲存庫以及使用者提到的任何路徑或網站上執行。
• 針對每個來源，它會回傳：README 標題與標語、Git 範圍與提交次數、標誌、字型檔案與系列、色彩記號。它還會回傳工具鏈：node、ffmpeg、快取的 hyperframes 版本、Chrome、heygen CLI，以及音樂 API 金鑰是否已設定。
• 如果目標專案中已存在 take.json，則表示為恢復作業。讀取它，跳過詢問環節，並從缺少輸出的第一個階段繼續。

階段 1：詢問（一個訊息，一輪）

閱讀 references/intake.md。在一個訊息中：

1. 顯示詢問表單：每個欄位都已根據偵測結果或建議的預設值預填，每個欄位佔一行。使用者僅需修改錯誤的部分。

2. 使用 AskUserQuestion 一次，詢問四個對工作影響最大的決策：格式（多選）、長度、聲音、以及配音/字幕。問題文字會指示使用者將對表單的任何修改作為任何答案的備註附上。

   如果 AskUserQuestion 不可用，請將同樣的四個選項作為編號選項放在表單結尾，並要求一次回覆。

然後，無需再次詢問：

• 寫入 take.json（結構：references/take-json.md）。語言代碼、格式 ID、slug 和 output.name 必須符合 [a-z0-9][a-z0-9._-]{0,63}（任何大小寫，不含 ..），否則執行停止。除非使用者要求，否則不設定 hyperframes：預設版本固定在 scripts/lib/platforms.mjs 中（HF_VERSION，0.8.223）。
• 寫入一個 HyperFrames BRIEF.md，其中包含 workflow: general-video、flow: automation、storyboard: no。這表示後續的 /hyperframes 呼叫將恢復此專案，而不是重新進行訪談。
• 將答案記錄在 BRIEF.md 的主體中：格式、聲音、字幕、平台限制。

階段 2：來源

• Git 事實。 執行 node SKILL_DIR/scripts/facts.mjs --repo <路徑> [--repo …] [--since …] --out <專案>/facts.json。它會收集提交次數、時間範圍、活躍天數、最長連續天數、最忙日期、各語言行數、新增與刪除行數、以及最常出現的提交用詞，以及第一個和最後一個提交的主旨。作者姓名和電子郵件永遠不會被記錄。僅使用使用者允許的事實。
• 網站。 對於要顯示的 URL，執行 npx hyperframes capture <url> -o <專案>/src/assets/cap。如果遇到 ok:false 或 BLOCKED.md 則停止：這是一個阻礙。
• 參考資料。 對於每個參考資料，在 STORYBOARD.md 中寫一行，說明你從中汲取了什麼：節奏、類型、顏色、轉場。對於 Figma 連結，先執行 /figma。
• 品牌。 將標誌 SVG 和字型檔案複製到 src/assets/brand 和 src/assets/fonts，在 take.json 的 fonts 中宣告它們，並將色彩記號提升到模板的 :root 中。

階段 3：方向與故事板

在編寫任何視覺內容之前，請先閱讀 references/direction.md。寫入 STORYBOARD.md：

• 方向，一個段落：一個核心概念、招牌動作、字型搭配、色板、每個選擇所參考的來源。
• 先確定節奏。 選擇 BPM，使目標長度為整數小節數（4/4）。然後為每個場景指定小節長度、energy（0–1，驅動配樂的編排），以及它如何進入（in）。
• 場景表格： ID、小節數、能量、畫面內容、動作、提示點、文案。
  • 最後一個場景是結束卡，end: true，有足夠的小節使其保持完整3 秒或更久。
  • 標記可以在剪輯版本中使用的場景為 optional（1–9，數字越高優先級越高）。
• 文案 存放在 copy/<lang>.json 中，每個按鍵對應一行文字。如果可用，透過 /humanizer 處理。確保標題足夠短，能在螢幕顯示時間內被閱讀兩次。

階段 4：建置

• 將 SKILL_DIR/templates/index.html 複製到 <project>/src/index.html，並根據故事板改寫其場景。
• 閱讀 references/kit.md（T.* API）和 hyperframes-core 的強制規則。關於動畫，閱讀 hyperframes-animation 規則和藍圖。在手動建置任何命名效果之前，先搜尋 hyperframes-registry。

確保所有格式和 QA 正確的規則：

• 場景是頂層的 <section class="clip scene" data-scene="id">，不可嵌套，不可使用內聯 style。
• 透過 --u（短邊的 1%）來設定設計尺寸（px）。可讀文字絕不可低於 --t-min（在 1080p 解析度下約為 3.4u ≈ 37 像素）。
• 將可讀文字保持在 .safe（該格式的平台 UI 區域）內。
• 使用 .f-tall、.f-wide、.f-square、.f-portrait 規則來重新佈局每種格式，而不是透過縮放一個佈局。
• 在下一個場景的轉場覆蓋目前場景的文字之前，清除該場景的文字（在 s.end 附近使用 T.sink/T.leave）。在揭示效果下的文字會導致佈局檢查失敗。
• 每個場景都要有動態：使用 T.drift 讓鏡頭橫掃場景。在結束卡之前，沒有任何畫面是靜止的。
• 在結束卡完成的那一刻使用 T.endCard(t)。最後一幀仍必須顯示結束卡：在保持期間不要淡出到黑色。
• 提示所有應該被聽到的內容（references/sound.md 列出了類別）。大多數工具包助手預設會發出提示；傳遞 cue: false 以保持某個時刻靜默。
• 數字來自 T.facts 或文案。T.count 需要一個有限的數字，如果沒有則會拋出錯誤，因此缺少事實會停止探查，而不是在畫面上顯示一個虛構的數字。
• 以 window.__timelines["main"] = T.done(); 結束腳本。T.done() 在添加所有補間動畫之後註冊一次時間軸，模板會在該行重複它。先建置所有補間動畫，而不是在字型就緒或其他非同步回呼內部：HyperFrames 佈局檢查會拒絕過早的註冊。

階段 5：草稿通過

node SKILL_DIR/scripts/run.mjs <專案> --draft

這會針對每個格式 × 語言執行：建置 → 探查（提示點、文字大小、來自無頭 Chrome 的結束卡標記） → 配樂 → hyperframes check → 草稿渲染 → 編碼 → QA → REPORT.md。

HyperFrames 使用 scripts/lib/platforms.mjs 中固定的 HF_VERSION（0.8.223）版本運行，或者使用 take.json 中指定的 hyperframes 版本。首次執行時會使用 npx 取得它，建置階段會從 jsDelivr 取得 GSAP 3.14.2 並快取到 ~/.cache/one-take/。下載後以及每次從快取讀取時，都會根據固定的 sha256 檢查 GSAP 檔案。不符合的檔案永遠不會被使用：錯誤的下載不會被快取，快取中錯誤的檔案會被刪除，建置會停止。再次執行以獲取新副本。

然後：

• 打開每個 *.sheet.jpg 聯絡表進行查看。
• 閱讀 REPORT.md。
• 修正失敗和任何看起來不對勁的地方：重疊、裁切、死幀、文字過小、剪輯不順。

最多進行兩次修復。每次修復重新執行 run.mjs --draft；使用 --only <格式>-<語言> 只重新執行修改的部分。

階段 6：最終

node SKILL_DIR/scripts/run.mjs <專案>

這會對每個輸出進行全品質渲染。產出物會放置在 renders/（或 output.dir）中。每個輸出會獲得：

• <名稱>.mp4：x264 CRF 12、AAC 320k、faststart
• .cover.jpg：結束卡
• .sheet.jpg
• .qa.json

配樂的分軌和 marks.json 會保留在 out/<格式>-<語言>/score/ 中。

階段 7：報告

回覆時提供：

• REPORT.md 中的輸出表格（檔案、大小、長度、判定結果）
• 主要格式的聯絡表
• 關於聲音的一行說明
• 待辦事項（如果有的話）

提供下一步選項，但不要執行它們：發布文案、更多語言、剪輯版本、發布。除非使用者要求，否則不會發布或推送任何內容。

聲音模式

sound.mode	作用
score（預設）	score.mjs 根據小節網格上的場景能量合成背景、樂隊和鼓點：根據 mood 和 key 制定和弦計劃，側鏈到大鼓，在每個升段前加入漸強，在每個到達點加入衝擊效果。音效分軌根據提示點建構，根據畫面中發生的位置調整音高和聲像。進行混音、限制處理，然後進行兩遍 loudnorm 達到 lufs（預設 -14），真實峰值 -1.5。原創音樂，因此無需授權。
track	使用使用者的音檔。使用 score.mjs --analyze <file>（或 npx hyperframes beats）取得 BPM 和第一拍，將 bpm 設為該值，並將場景對齊其小節。音效分軌會疊加播放。
library	使用 /media-use resolve --type bgm（需要 heygen CLI）或其生成器。結果作為 track 使用，其授權資訊記錄在 sound.licence 中。
none	完全沒有音訊元素。

對於配音，將其放置在 src/assets/audio/vo.wav，可透過 npx hyperframes tts 使用 Kokoro 生成，或使用使用者的錄音。配樂會在其下方調整音量（duckDb，預設 -9）。對於字幕，根據 npx hyperframes transcribe vo.wav --model <model> 的結果進行時間對齊。燒錄式字幕是放置在 .safe 區域內、字型大小為 --t-cap 或更大的場景文字。對於外部字幕檔案，請在每個輸出檔案旁寫入 <名稱>.srt。

檔案

• scripts/detect.mjs、facts.mjs：偵測環境與統計數字
• scripts/build.mjs：單一來源 → out/<格式>-<語言>/ HyperFrames 專案。填入尺寸、安全區域和場景時間，內聯 TAKE（文案、事實、場景），引入工具包和 GSAP 3.14.2（經 sha256 檢查），為剪輯版本捨棄場景
• scripts/probe.mjs：無頭 Chrome 通過，讀取提示點、文字大小和隨時間變化的位置，以及標記
• scripts/score.mjs：合成配樂、分軌、混音、母帶處理、marks.json；使用 --analyze 分析軌道節奏
• scripts/encode.mjs、qa.mjs、report.mjs、run.mjs：交付、檢查、報告，以及整體執行
• scripts/selftest.mjs：檢查工具鏈，然後證明 QA 會失敗於一個故意設計為失敗的檔案
• scripts/lib/：共享輔助工具（git、包含 HF_VERSION 和名稱檢查的平台、WAV、DSP）
• kit/take.js：動畫工具包（references/kit.md）
• templates/index.html：起始舞台
• references/：intake.md、take-json.md、direction.md、sound.md、formats.md、qa.md、kit.md