media-use:在獲取音訊/圖片前,請先呼叫
/media-use以從 HeyGen 目錄中解析背景音樂/SFX/圖片。先執行--adopt以註冊現有素材。請參閱/media-use技能。
PR 到 HyperFrames
使用此技能來匯入 GitHub 拉取請求,理解變更,規劃程式碼變更解說影片,並在 HyperFrames 中逐幀建構。輸入是程式碼變更(透過 gh 讀取),而非網站——沒有捕捉步驟,也沒有真實素材,除了貢獻者的頭像之外。
在步驟 0 之前確認路由。 您是協調者。依序執行每個步驟,驗證其關卡,然後才繼續。此技能適用於 GitHub 拉取請求(程式碼變更)。將其他意圖路由到別處:產品發布/宣傳 →
/product-launch-video;一般網站導覽 →/website-to-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、<擁有者>/<倉庫>#<編號> 引用,或已檢出倉庫中的「此 PR」),並在一則訊息中確認簡報——為每個項目提出建議預設值,並預先填入 /hyperframes 已設定的內容:角度(變更日誌 / 功能展示 / 錯誤修正解說 / 重構逐步解說——預設:從 PR 推斷)、觀眾(預設:開發者)、長度(預設:根據 PR 的變更規模縮放——請見下方)、畫面比例(預設 16:9)、語言。風格始終為 claude。僅在使用者回覆後繼續;「開始」代表接受預設值。
根據 PR 的變更規模推薦長度,而不是固定的猜測。在確認簡報前,先快速查看 PR 一次——這是一個唯讀呼叫,同時也能確定角度(步驟 1 仍會執行完整的確定性擷取):
git pr view <PR_REF> --json title,additions,deletions,changedFiles
從 additions + deletions 中選擇等級(根據 changedFiles 微調),並以此作為預設值提出(使用者可以覆寫;硬上限約 3 分鐘):
| PR 變更規模 | 建議長度 |
|---|---|
| 微不足道(≲ 50 行變更) | ~20–40s |
| 重點明確(~50–200 行) | ~40–70s |
| 大量(~200–600 行) | ~70–110s |
| 龐大(≳ 600 行,或 25+ 個檔案) | ~110–180s |
在提出建議時用一句話說明依據(例如「~40 秒——小變更,+44/−13 跨 12 個檔案」)。一個龐大的 PR 並不意味着長影片——如果故事只有一個重點變更,請保持簡潔並說明原因。
僅在 hyperframes.json 缺失時初始化。以 kebab-case 命名 <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)
# people 前端的一個網路步驟——將每個貢獻者的 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 驗證 / 找不到 / 私有),請回報其 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(溫暖的編輯風格;深藍色程式碼表面,專為 diff 設計)。執行:
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 原生影格類型、鉤子、說服力、節奏、每個影格的單字預算,以及可選的致謝結尾。順序來自敘事設計,而非 diff 的檔案順序——解釋變更,不要逐字朗讀 diff。展示 2–4 個真實的 diff 區塊(來自 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 Audio 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,重構 = code-morph,新程式碼 = 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(claude 的,在步驟 2 中複製),注入來自 frame.md 的品牌代幣;captions: skipped (<原因>) i
…
[因翻譯而截斷]