media-use: 在獲取音訊/圖片之前,請先呼叫
/media-use從 HeyGen 目錄中解析 BGM/SFX/圖片。請先執行--adopt註冊現有素材。請參閱/media-use技能。
提交 PR 至 HyperFrames
使用此技能來吸收 GitHub 拉取請求,理解變更內容,規劃程式碼變更解說,並在 HyperFrames 中逐幀建構影片。輸入是程式碼變更(透過 gh 讀取),而非網站 — 沒有擷取步驟且無真實素材,除了貢獻者的頭像之外。
在步驟 0 之前確認路線。 您是協調者。依序執行每個步驟,驗證其關卡,然後再繼續。此技能適用於 GitHub 拉取請求(程式碼變更)。將其他意圖導向別處:產品發布/宣傳 →
/product-launch-video;一般網站導覽 →/general-video;沒有 PR 的主題解說 →/faceless-explainer;現有影片上的字幕 →/embedded-captions;簡短無旁白的動態圖形 →/motion-graphics;整個儲存庫或多個 PR 的發布說明 →/general-video。超出範圍: 即時/渲染時的資料 — PR 事實僅在作者時讀取一次並固定。如果使用者只說「製作影片」或路線不確定,請先閱讀/hyperframes。
您是協調者。在 videos/<project>/ 中工作。依序執行步驟並在繼續前通過每個關卡。使用者關卡為步驟 0、步驟 3 和步驟 6。除步驟 5(您為每幀分派一個子代理)外,請自行執行每個步驟。不要在此處放置設計或動態規則;這些規則位於幀工作子代理 hyperframes-creative 和 hyperframes-animation 中。
工作流程:步驟 0 設定 → hyperframes.json;步驟 1 吸收 → capture/extracted/ + assets/<login>.png;步驟 2 設計系統 → frame.md;步驟 3 分鏡/腳本 → STORYBOARD.md 和 SCRIPT.md;步驟 3.1 音訊 → audio_meta.json;步驟 4 視覺設計 → 豐富的 STORYBOARD.md;步驟 5 幀 → compositions/frames/NN-*.html 和 index.html;步驟 6 最終渲染 → renders/video.mp4。
步驟 0:設定與簡報
目標:鎖定 PR 參考和核心影片簡報,並在需要時建立 HyperFrames 專案。
取得 PR 參考(完整 URL、<owner>/<repo>#<N> 引用,或已簽出儲存庫中的「此 PR」),並在一則訊息中確認簡報 — 首先對每個項目提出建議預設值,並預先填入 /hyperframes 已設定的任何內容:角度(更新日誌 / 功能揭示 / 修正解說 / 重構說明 — 預設:從 PR 推斷)、受眾(預設:開發人員)、長度(預設:根據 PR 的變更規模調整 — 請參閱下方說明)、長寬比(預設 16:9)、語言。風格始終為 claude。僅在使用者回覆後繼續;一個「好」代表接受預設值。
根據 PR 的變更規模建議長度,而非固定猜測。在確認簡報之前,先快速查看 PR 一次 — 這是一個唯讀呼叫,也能確定角度(步驟 1 仍會執行完整的確定性提取):
gh pr view <PR_REF> --json title,additions,deletions,changedFiles
從 additions + deletions 中選擇層級(並視 changedFiles 向上調整),並以此作為預設值提出(使用者可以覆蓋;硬上限約 3 分鐘):
| PR 變更規模 | 建議長度 |
|---|---|
| 微小(約 ≲ 50 行變更) | 約 20–40 秒 |
| 集中(約 50–200 行變更) | 約 40–70 秒 |
| 大量(約 200–600 行變更) | 約 70–110 秒 |
| 大型(約 ≳ 600 行,或 25+ 個檔案) | 約 110–180 秒 |
在提出建議時用一句話說明依據(例如「約 40 秒 — 小變更,+44/−13,共 12 個檔案」)。大型 PR 不意味著長影片 — 如果故事只有一個重點變更,請保持簡潔並說明。
僅在 hyperframes.json 遺失時才初始化。以 kebab-case 格式從 PR 命名 <project>,例如 acme-sdk-pr-1842;切勿使用工作區名稱或時間戳記。
npx hyperframes init "videos/<project>" --non-interactive --example=blank — init 會檢查已安裝的技能是否與 GitHub 上的最新版本一致,並在有任何技能過期時更新全域技能集。
在簡報前顯示登入狀態 — 執行 npx hyperframes auth status 並逐字轉述其輸出(不要改寫或重新描述)。 它會報告語音/BGM 將使用 HeyGen 還是本機引擎,以及當未登入時如何登入。如果未登入,請停止並等待使用者選擇 — 登入,或說「好」/「離線」以繼續使用本機引擎 — 然後再詢問簡報或任何事情。 將其視為一個真實的決策點,而非一個簡單的註記;不要將選擇納入簡報問題中,也不要將金鑰寫入每個儲存庫的 .env 中。(在自主模式下,請注意狀態並離線繼續。)請參閱 ../hyperframes-media → 預檢以獲取標準指南。
關卡: hyperframes.json 存在;PR 參考已擷取;角度、長度、長寬比和語言已鎖定;已顯示登入狀態(已登入,或繼續離線)。
步驟 1:吸收 PR(無擷取)
目標:提取 PR 的事實並將其納入專案中作為資訊來源。沒有網站擷取。fetch-pr.mjs 確定性地執行 gh — 透過分頁的 gh api 完成檔案列表,以便大型 PR 不會在約 100 個檔案處截斷,並且僅寫入 capture/pr.json + capture/diff.patch(無暫存目錄)。然後 ingest.mjs 在離線狀態下將其合併到合成擷取套件中。
PR="<URL | owner/repo#N | N>"
# 確定性地提取 PR:執行 gh,透過分頁的 gh api 完成檔案列表(因此大型 PR 不會在約 100 個檔案處截斷),
# 僅寫入 capture/pr.json + capture/diff.patch — 無暫存目錄。
# gh auth / not-found / private 錯誤在此處以 exit 1 退出。
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# 離線轉換 → capture/extracted/{tokens.json(colors:[] → claude 調色盤),
# visible-text.txt(簡報),people.json(貢獻者,已過濾機器人,avatarFile=assets/<login>.png)}。
(cd "videos/<project>" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# 人物方面的唯一一個網路步驟 — 將每個貢獻者的 GitHub 頭像下載到
# assets/<login>.png 以供可選的致謝結尾使用。盡力而為;始終以 exit 0 退出。
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
如果 fetch-pr.mjs 以 exit 1 退出(gh auth / not found / private),請報告其 stderr 並停止 — 不要偽造 PR 內容。如果 ingest.mjs 以 exit 1 退出,請閱讀其 stderr(通常是格式錯誤的 pr.json),修正後重新執行(確定性)。fetch-people-avatars.mjs 始終以 exit 0 退出;遺失頭像僅表示沒有致謝結尾提供給作者。
關卡: capture/pr.json、capture/diff.patch、capture/extracted/tokens.json、capture/extracted/visible-text.txt 和 capture/extracted/people.json 存在;您可以用一句清晰的句子說明 PR 的變更。assets/<login>.png 是盡力而為 — 其缺失不算是失敗。
步驟 2:設計系統
目標:採用 claude 框架預設設定;一個腳本將其轉換為此影片的 frame.md + 字幕外觀。
風格是固定的 — claude(溫暖的編輯風格;專為差異比較設計的海軍藍程式碼表面)。執行:
node <SKILL_DIR>/scripts/build-frame.mjs --preset claude --hyperframes .
該腳本會將 claude 預設設定的 FRAME.md 複製到 frame.md,並根據 capture/extracted/tokens.json 中的任何品牌標記(PR 沒有這些標記 → colors:[]/fonts:[] 保留 claude 自己的調色盤,一個完整的設計)進行重新混合,將預設的字幕外觀複製到 .hyperframes/caption-skin.html,並自我驗證(在映射損壞時以 exit 1 退出)。一旦它以 exit 0 退出,請繼續 — 無需手動編輯。
關卡: build-frame.mjs 以 exit 0 退出 — frame.md 來自 claude 預設設定,且 .hyperframes/caption-skin.html 作為字幕外觀來源存在。
步驟 3:分鏡與腳本
目標:將 PR 轉換為已核准的逐幀解釋計畫。
閱讀 references/story-design.md、../hyperframes-core/references/storyboard-format.md 和 ../hyperframes-core/references/script-format.md。使用它們來撰寫 STORYBOARD.md,以及(在需要旁白時)SCRIPT.md。
使用 story-design.md 來確定 PR 原型(更新日誌 / 功能揭示 / 修正解說 / 重構說明)、PR 原生幀類型、鉤子、說服力、節拍、每幀字數預算,以及可選的致謝結尾。順序來自敘事設計,而非差異比較的檔案順序 — 解釋變更,而非逐字讀出差異比較。展示 2–4 個真實的差異比較片段(來自 capture/diff.patch),每個都是一個簡短易懂的片段;為幀的 scene 中每個所需的 code-* 區塊命名。幀不攜帶 asset_candidates,除了可選的 credits 結尾(2–6 個 assets/<login>.png 頭像)。使用來自分鏡和腳本參考文的確切必填欄位。
草稿完成後,顯示逐幀摘要。在同一則訊息中,詢問使用者 (a) 批准或要求修改,以及 (b) 他們是否想要一個即時預覽分鏡框架(npx hyperframes preview) — 只有在他們同意時才開啟。重複直到獲得批准;將預覽選擇帶入步驟 6。
關卡: STORYBOARD.md 存在,每幀都有所需的敘事欄位,SCRIPT.md 在需要旁白時存在,並且使用者已批准該計畫。
步驟 3.1:音訊
目標:從已批准的腳本生成旁白、單字時間軸、音樂和音訊元資料。
在步驟 3 批准後開始音訊處理。在背景執行,然後繼續進行步驟 4。
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --hyperframes . --out ./audio_meta.json &
音訊腳本處理旁白、單字時間軸、從 HeyGen 音樂庫查詢 BGM 以及時間軸元資料。BGM 情緒來自分鏡的 music: 欄位。這使用 HeyGen 音訊 API 進行檢索(而非生成),以及與 TTS 相同的 ~/.heygen 憑證。有關提供者的詳細資訊,請閱讀 ../hyperframes-media/references/tts.md。
如果沒有旁白且沒有 SCRIPT.md,則跳過語音生成。如果分鏡有音樂情緒,BGM 仍可能執行。
關卡: 音訊作業已開始,或專案標記為靜音。
步驟 4:幀視覺設計
目標:為每個分鏡幀添加視覺方向、佈局意圖和動態選擇。
原地編輯 STORYBOARD.md。不要建立另一個分鏡。使用 frame.md 作為顏色、字體、佈局氛圍和風格的單一事實來源。
閱讀 references/visual-design.md、references/composition.md、references/motion-language.md、references/code-vocabulary.md 和 ../hyperframes-animation/。使用 visual-design.md 來了解必填的幀欄位和必填的 ## Video direction 區塊,以及程式碼節拍如何將一個 code-* 區塊命名為其 focal。使用 code-vocabulary.md 為每個節拍選擇正確的區塊(diff = code-diff,refactor = code-morph,new code = code-typing,…)。使用 composition.md 來了解佈局/層次/焦點,以及 motion-language.md + ../hyperframes-animation/ 來了解有效的效果和藍圖 ID。不要發明效果名稱或區塊/藍圖 ID。
對於每個幀,添加必填的視覺和動態欄位,包括 effects 以及 focal 和/或 roles。對於程式碼節拍,將 code-* 區塊命名為 focal,並讓 effects 編排周圍的 claude 程式碼表面(而非由區塊擁有的程式碼動畫)。添加一個影片範圍的 ## Video direction 區塊。
不要更改故事、腳本、transition_in、asset_candidates 或 PR 來源。不要在此步驟中撰寫 HTML。沒有素材暫存步驟 — 唯一的真實素材是致謝頭像,已位於 assets/ 中。
關卡: 每個幀都有 effects 加上 focal 和/或 roles;程式碼幀命名了一個 code-* 區塊;## Video direction 存在。
步驟 5:建構幀
目標:將每個分鏡幀建構成一個 HTML 合成畫面並組合可播放的影片。
如果音訊已開始,請等待步驟 3.1 的音訊完成。然後同步持續時間並獲取 SFX;如果靜音則跳過兩者。
node <SKILL_DIR>/scripts/audio.mjs sync-durations --audio-meta ./audio_meta.json --storyboard ./STORYBOARD.md
node <SKILL_DIR>/scripts/audio.mjs fetch-sfx --storyboard ./STORYBOARD.md --hyperframes .
持續時間同步是機械性的:真實語音持續時間優先;靜音幀保留估計值;永遠不要手動編輯同步後的持續時間。
預先安裝 STORYBOARD.md 中命名的所有註冊表區塊,在分派之前一次完成,這樣並行工作者就不會在註冊表上產生競爭:
for b in <分鏡中命名的每個註冊表區塊>; do npx hyperframes add "$b"; done
在分派之前,閱讀 sub-agents/frame-worker.md 和 ../hyperframes-core/references/subagent-dispatch.md。為每個幀分派一個子代理,如果可以的話並行進行;否則以批次方式執行工作者。每個工作者正好獲得一個幀。每個工作者的上下文必須包含 PROJECT_DIR、frame_id、畫布大小、字幕狀態和(如果啟用字幕)保留頻帶、ANIM_DIR(../hyperframes-animation/ 的絕對路徑),以及 references/code-vocabulary.md 的絕對路徑。每個工作者讀取 frame.md、其自己的 ## Frame N 區塊、每個引用的效果/藍圖 ID 的配方主體,以及(對於程式碼節拍)code-vocabulary.md 以獲取命名區塊的輸入。每個工作者僅寫入 compositions/frames/NN-*.html;工作者永遠不會編輯 STORYBOARD.md。
當每個工作者返回時,在 STORYBOARD.md 中將該幀標記為 animated。
在音訊時間軸存在後,在背景建構字幕並組合索引:
node <SKILL_DIR>/scripts/captions.mjs build --storyboard ./STORYBOARD.md --audio-meta ./audio_meta.json --hyperframes . --out ./caption_groups.json &
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard ./STORYBOARD.md --hyperframes .
captions.mjs 使用專案的 .hyperframes/caption-skin.html(步驟 2 中複製的 claude 字型),注入來自 frame.md 的品牌標記;captions: skipped (<reason>) 是有效的輸出。assemble-index.mjs 將 compositions/frames/ 中所有標記為 animated 的幀 HTML 檔案組合成 compositions/index.html,並嵌入 frame.md 的樣式和字型。它會驗證其在 STORYBOARD.md 中找到的每個 frame_id 都存在一個 HTML 檔案,且每個 HTML 都對應一個分鏡條目。
關卡: 持續時間已同步,SFX 已擷取,註冊表區塊已安裝。每個分鏡幀在 STORYBOARD.md 中都有一個對應的 compositions/frames/NN-<frame_id>.html 檔案,並標記為 animated(或 static)。compositions/index.html 存在。
步驟 6:最終渲染
目標:在取得使用者批准後將索引合成畫面渲染為最終影片。
如果繼續離線且使用者想要預覽,請提供它(npx hyperframes preview)—— 一個是時候了的最終檢查。保持開啟直到給出批准決定。使用 STORYBOARD.md 中的 preview_choice:。預覽是選擇性的:繼續進行渲染。
npx hyperframes render ./compositions/index.html ./renders/video.mp4
如果啟用了字幕並且 caption_groups.json 已準備好(步驟 5 中在背景建構),則在渲染影片之前應用它們。
渲染後,在 .hyperframes/signature 中儲存版本鎖定以供後續驗證:npx hyperframes freeze。
關卡: renders/video.mp4 存在且用於稽核的凍結鎖定已就位。
附錄:無旁白模式
如果腳本為空或省略,跳過 STORYBOARD.md 中的 narration 欄位,腳本階段將不會產生 SCRIPT.md。音訊階段將跳過語音生成。BGM 和 SFX 處理保持不變。幀持續時間來自 motion_duration 或預設值。字幕應以 captions: none 明確跳過。分鏡階段應設定 music: 情緒來引導 BGM。
附錄:Pr 未找到 / 異步初始化
fetch-pr.mjs 可能因 gh 未找到錯誤而失敗。如果 gh CLI 不存在,請安裝它。如果 PR 是私有的或未找到,請報告確切的錯誤並停止。不要偽造內容。