pr-to-video

media-use：在取得音訊/圖片素材前，請先呼叫 /media-use 從 HeyGen 目錄中選取背景音樂/音效/圖片。先執行 --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 參考（完整網址、<owner>/<repo>#<N> 格式，或在已檢出儲存庫中輸入「this 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 不存在時才初始化。以 PR 的名稱命名 <project>，使用 kebab-case，例如 acme-sdk-pr-1842；切勿使用工作區名稱或時間戳。

npx hyperframes init "videos/<project>" --non-interactive --skip-skills --example=blank

在簡報前顯示登入狀態——執行 npx hyperframes auth status 並直接輸出其結果（不要改寫或重新表述）。 它會報告語音/背景音樂將使用 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 / not-found / private 錯誤會在此處退出 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 退出 1（gh auth / not-found / private），報告其 stderr 並停止——不要虛構 PR 內容。如果 ingest.mjs 退出 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，並自我驗證（若映射損壞則退出 1）。一旦退出 0 即可繼續——無需手動編輯。

關卡： build-frame.mjs 退出 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 音樂庫查詢背景音樂，以及時間元資料。背景音樂情緒來自分鏡的 music: 欄位。這使用 HeyGen 音訊 API 進行檢索（而非生成），並使用與 TTS 相同的 ~/.heygen 憑證。有關提供者的詳細資訊，請閱讀 ../hyperframes-media/references/tts.md。

如果沒有旁白且沒有 SCRIPT.md，則跳過語音生成。如果分鏡有音樂情緒，背景音樂仍可能執行。

關卡： 音訊工作已開始，或專案標記為無聲。

---

步驟 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 的音訊完成。然後同步持續時間並取得音效；如果無聲則跳過兩者。

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>) 是有效的。assemble-index.mjs 將 assets/ 中的致謝頭像作為冪等後備機制暫存。

關卡： 每個影格都標記為 animated，index.html 存在，且字幕已建構或明確跳過。

---

步驟 6：最終化

目標：驗證組裝後的影片，取得使用者核准，並渲染最終的 MP4。

注入轉場、執行檢查、暫停供審查，然後渲染。

node <SKILL_DIR>/scripts/transitions.mjs inject --storyboard ./STORYBOARD.md --hyperframes .

node <SKILL_DIR>/scripts/transitions.mjs verify --storyboard ./STORYBOARD.md --index ./index.html

npx hyperframes lint

npx hyperframes validate

npx hyperframes inspect

npx hyperframes snapshot --at <frame-midpoints>

snapshot 將擷取的影格拼接成一張聯絡表（snapshots/contact-sheet.jpg）。快速瀏覽；如果沒有明顯問題，就繼續——不要在此停留。

如果某個命令失敗，顯示 stderr 並停止——不要堆疊恢復命令。自行修復：對 compositions/frames/NN-*.html 進行最便宜的安全編輯，然後重新執行失敗的檢查。

已知的誤報——不要追查。 inspect 可能會報告少數 text_box_overflow 錯誤，約 1–4px，出現在字幕高亮單詞上（選擇器 #caption-word-* / .caption-line）。字幕膠囊使用刻意緊湊的 line-height（在 scripts/captions.mjs 中設定一次），且沒有 overflow:hidden，因此較重的顯示字形的墨水會溢出幾像素到膠囊自己的內邊距中——實際上沒有任何內容被裁剪。將這些視為預期行為並繼續。不要放大字幕的 line-height（這會使膠囊膨脹，更糟）。僅在 text_box_overflow 指向影格元素（#el-NN-*）而非字幕單詞時才採取行動。

檢查通過後，暫停供使用者審查。影片已組裝完成，可在 Studio 中檢視和編輯。在步驟 3 和步驟 6 之間只管理一次預覽：如果使用者之前要求過則開啟，如果之前拒絕過則提供，如果他們已在 Studio 中審查則不再詢問。

預覽：npx hyperframes preview

僅在使用者核准後渲染：

npx hyperframes render --skill=pr-to-video --quality high --output renders/video.mp4

除非使用者要求，否則不要在渲染後重新執行 lint、validate、inspect 或 snapshot。

關卡： lint、validate 和 inspect 在渲染前通過；使用者在審查暫停時核准；renders/video.mp4 存在。最終回覆說明 MP4 路徑和最終長度。

---

快速參考

格式： 預設橫向 1920x1080；直向 1080x1920；正方形 1080x1080。在分鏡的前置資料中設定一次格式。

PR 差異與擷取素材工作流程的比較： 沒有步驟 1 的擷取（gh CLI 將 PR 擷取到合成的 capture/extracted/ 套件中——tokens.json + visible-text.txt + people.json）；唯一的真實素材是貢獻者的 assets/<login>.png 頭像（可選的致謝結尾）；沒有 asset-descriptions.md，沒有素材暫存步驟。程式碼節拍由 code-* 註冊表區塊在 claude 的海軍藍程式碼表面上渲染；風格始終是 claude。

背景腳本： 工作流程在 scripts/ 下提供這些腳本：fetch-pr（PR → capture/pr.json + diff.patch 透過 gh；大型 PR 安全，無暫存）、ingest（→ 合成擷取套件；離線）和 fetch-people-avatars（貢獻者頭像 → assets/）；以及共享引擎——build-frame（採用並重新混合品牌預設到 frame.md + 字幕外觀）、audio（TTS、背景音樂、音效、持續時間同步）、captions、transitions（注入 + 驗證）和 assemble-index。其他一切都是 hyperframes CLI。程式碼區塊透過 npx hyperframes add <name> 安裝。

閱讀	時機
[references/story-design.md](references/story-design.md)	步驟 3：規劃 PR 解說。
[../hyperframes-core/references/storyboard-format.md](../hyperframes-core/references/storyboard-format.md)	步驟 3：撰寫 STORYBOARD.md。
[../hyperframes-core/references/script-format.md](../hyperframes-core/references/script-format.md)	步驟 3：撰寫 SCRIPT.md。
[../hyperframes-media/references/tts.md](../hyperframes-media/references/tts.md)	步驟 3.1：選擇或了解 TTS 提供者。
[references/visual-design.md](references/visual-design.md)	步驟 4：在視覺上豐富分鏡。
[references/code-vocabulary.md](references/code-vocabulary.md)	步驟 4 + 5：為程式碼節拍選擇並填入 code-* 區塊。
[references/composition.md](references/composition.md)	步驟 4：判斷構圖。
[references/motion-language.md](references/motion-language.md)	步驟 4：判斷動畫語言。
[../hyperframes-animation/](../hyperframes-animation/)	步驟 4：引用效果和藍圖 ID。
[sub-agents/frame-worker.md](sub-agents/frame-worker.md)	步驟 5：分派逐幀工作者。
[../hyperframes-core/references/subagent-dispatch.md](../hyperframes-core/references/subagent-dispatch.md)	步驟 5：安全分派子代理。
[../hyperframes-creative/frame-presets/claude/FRAME.md](../hyperframes-creative/frame-presets/claude/FRAME.md)	步驟 2：claude 預設（固定風格）。