media-use: 在取得音訊/圖片之前,請先呼叫
/media-use,從 HeyGen 目錄中解析 BGM/音效/圖片。先執行--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 外,每個步驟都由你親自執行,步驟 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。僅在使用者回覆後才繼續;「go」表示接受預設值。
根據 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 時初始化。以連字號命名 <project>,例如 acme-sdk-pr-1842;切勿使用工作區名稱或時間戳。
npx hyperframes init "videos/<project>" --non-interactive --example=blank — init 會檢查已安裝技能與 GitHub 上最新的技能,並在有任何技能過期時更新全域集合。
在簡報前顯示登入狀態 — 執行 npx hyperframes auth status 並逐字轉發其輸出 (不要改寫或重新編寫)。 它會回報語音/BGM 將使用 HeyGen 還是本地引擎,以及未登入時如何登入。如果未登入,請停止並等待使用者選擇 — 登入,或說「go」/「offline」以使用本地引擎繼續 — 然後再詢問簡報或任何其他事項。 將其視為真正的決策點,而非次要註解;不要將選擇併入簡報問題中,也不要將金鑰寫入每個儲存庫的 .env 中。(在自主模式下,記錄狀態並以離線模式繼續。) 請參閱 ../hyperframes-media → Preflight 以取得標準指引。
關卡: 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 / 找不到 / 私有錯誤會以 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,用於可選的致謝結尾。盡力而為;始終以 0 退出。
(cd "videos/<project>" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
如果 fetch-pr.mjs 以 exit 1 退出 (gh auth / 找不到 / 私有),請回報其 stderr 並停止 — 不要虛構 PR 內容。如果 ingest.mjs 以 exit 1 退出,請閱讀其 stderr (通常是格式錯誤的 pr.json),修正後重新執行 (確定性)。fetch-people-avatars.mjs 始終以 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 Code Surface (而不是程式碼動畫,由區塊擁有)。加入一個全影片範圍的 ## Video direction 區塊。
不要更改故事、腳本、transition_in、asset_candidates 或 PR 來源。不要在此步驟中撰寫 HTML。沒有資產暫存步驟 — 唯一的真實資產是致謝大頭貼,已存在於 assets/ 中。
關卡: 每個影格都有 effects 加上 focal 及/或 roles;程式碼影格命名了 code-* 區塊;## Video direction 存在。
步驟 5:建立影格
目標:將每個分鏡腳本影格建置為 HTML 合成,並組裝可播放的影片。
如果音訊已啟動,請等待步驟 3.1 的音訊完成。然後同步持續時間並擷取音效;如果為無聲,則兩者都跳過。
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 <each registry block named in the storyboard>; 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 (<reason>) 標記 STORYBOARD.md 為首。使用 ../hyperframes-core/references/captions.md 了解格式。如果開啟了預覽分鏡腳本,則npx hyperframes preview 也應重新組合索引,這會自動觸發。如果關閉,則主動執行上述 assemble-index.mjs 命令。
關卡: 所有影格都存在於 compositions/frames/ 中,都標記為 animated,存在 index.html,且所有必須的音效都已擷取。
步驟 6:渲染與最終交付
目標:將組合的影片渲染為 MP4 檔案,獲得核准,並交付最終輸出。
在渲染前,等待背景字幕工作完成,並在 captions: ... 狀態存在時將其合併到 STORYBOARD.md 中。如果它們未在 60 秒內完成 (這是一種罕見的作業系統級鎖定),記錄警告並繼續不含字幕。
# 等待背景字幕工作完成 (步驟 5)
wait
渲染影片:
npx hyperframes render "videos/<project>" --output renders/video.mp4
渲染會為使用者開啟一個頁面 (如果可用),以便他們可以追蹤進度。在渲染期間,<SKILL_DIR>/references/sync-music.md 中提供了音樂同步的決定性步驟,用於選擇最終 BGM 曲目及其裁切點。
最終使用者核准: 完成後,使用者在繼續之前必須核准渲染。他們可以在本地播放 renders/video.mp4 或將其直接上傳到 YouTube 進行草稿審查。
交付: 使用者核准後,告知他們最終影片位於 renders/video.mp4,並提供其持續時間。
關卡: 影片已渲染 (renders/video.mp4),使用者已核准最終輸出。完成。