外掛安裝： 在執行設定或更新命令之前，若此技能位於 HyperFrames 外掛中，請遵循外掛執行規則。獨立安裝則保留以下更新說明。
首先，保持此技能最新 — 在執行前請先與使用者確認：
npx hyperframes skills update pr-to-video。若所有內容皆為最新，則此操作快速且無變化；否則它會更新此技能及其所依賴的核心領域技能，然後才能放心使用。
media-use：在開始取得音訊/圖片/標誌之前，請呼叫
/media-use以從 HeyGen 目錄解析背景音樂/音效/圖片，並從其官方來源解析品牌標誌。先執行--adopt以註冊現有資產。詳見/media-use技能。
PR 轉 HyperFrames
使用此技能來攝取 GitHub 拉取請求、理解變更、規劃程式碼變更解說，並在 HyperFrames 中逐幀建構影片。輸入是程式碼變更（透過 gh 讀取），而非網站 — 除了貢獻者的頭像外，沒有網頁擷取步驟和真實資產。
入口是
/hyperframes。 你是協調者。依序執行每個步驟，驗證其關卡，然後才繼續。此技能適用於 GitHub 拉取請求（程式碼變更）。任何其他意圖、單純的「製作影片」、或不確定事項 → 先閱讀/hyperframes— 意圖層擁有所有路線決策，若沒有BRIEF.md的新創建請求直接到達此處，仍會透過它（設定的開場規則）。
你是協調者。在解析後的外部 PROJECT_DIR 中工作，預設不進入呼叫者的倉庫。依序執行步驟並在繼續之前通過每個關卡。使用者關卡為步驟 0、步驟 3 和步驟 6。在步驟 0 之前閱讀 ../hyperframes/references/brief-contract.md — 它定義了關卡類型以及 BRIEF.md 的 flow/storyboard 如何衍生出管理步驟 3/4/6 關卡的模式。除步驟 5 外，自行執行每個步驟；在步驟 5 中，你會分派一個有限制的影格工作者池。不要在此處放置設計或動態規則；這些規則存在於影格工作者子代理、此技能的本地 ../hyperframes-animation/rules/ + ../hyperframes-animation/blueprints/ 以及 hyperframes-creative 中。
工作流程：步驟 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 參考（完整 URL、<owner>/<repo>#<N> 參照，或已 checkout 的倉庫中的「this PR」）— 建立 HyperFrames 專案，並使簡要說明持久化。風格永遠是 程式碼編輯風格（在步驟 2 固定，無需詢問）。
簡要說明由意圖層確認，而非在此處提問。 開場規則，依序：(1) BRIEF.md 已存在 → 閱讀它且不問任何問題 — 簡要說明已確定，其 flow/storyboard 衍生出模式（簡要合約 § 1）。(2) 沒有 BRIEF.md 但專案已存在（磁碟上有 hyperframes.json / STORYBOARD.md）→ 從分鏡的前置資料和記錄的偏好恢復；切勿重新盤問一個半完成的專案。(3) 兩者皆無 — 一個直接到達此處的新創建請求 → 閱讀 /hyperframes 並執行其意圖層（references/intent-interview.md）：它會檢查配方和記住的預設值，並進行此路線的提問 — 包括 PR 大小 → 長度準則，該準則完整存在於 ../hyperframes/references/routes/pr-to-video.md — 然後交出鎖定的簡要說明。編輯請求跳過所有這些 — 直接進行編輯。
在進行任何其他工作之前，先解析專案目錄。保留使用者提供的專案目錄；否則使用解析器列印的持久化外部快取位置。切勿在呼叫者倉庫中建立 videos/：
PR="<url | owner/repo#N>"
if [ -n "${EXPLICIT_PROJECT_DIR:-}" ]; then
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR" --project-dir "$EXPLICIT_PROJECT_DIR")"
else
PROJECT_DIR="$(node <SKILL_DIR>/scripts/project-dir.mjs --pr "$PR")"
fi
echo "PR 轉影片專案：$PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
能力預檢在提取、分鏡工作、音訊或影格分派之前執行。如果安裝的命令列工具無法執行此技能所需的驗證命令，則停止並顯示其升級說明，而不是先消耗本次執行的上下文。
僅在 $PROJECT_DIR/hyperframes.json 遺失時才初始化。其基底名稱來自於 PR，例如 acme-sdk-pr-1842；切勿使用工作區名稱或時間戳。
npx hyperframes init "$PROJECT_DIR" --non-interactive --example=blank --skill=pr-to-video — init 會檢查已安裝的技能與 GitHub 上的最新版本，並在有任何技能過期時更新全域集合。
以下所有相對路徑命令都以 $PROJECT_DIR 作為其工作目錄來執行。沒有明確子 shell 的範例意味著 (cd "$PROJECT_DIR" && …)；切勿變更呼叫者倉庫的工作樹。
初始化後立即寫入 BRIEF.md（切勿在此之前 — init 拒絕非空目錄）：意圖層鎖定的簡要說明，格式依據 ../hyperframes/references/brief-format.md。將 <MEDIA_DIR> 解析為已安裝的 /media-use 技能目錄。然後使用 node <MEDIA_DIR>/scripts/prefs.mjs record --hyperframes .（brief-format.md 指定了子集）記錄每個偏好支持的答案。如果意圖層採用了配方，請執行 node <MEDIA_DIR>/scripts/recipe.mjs use --hyperframes . --name <name>；它會將配方的 frame.md 複製到專案中（然後跳過步驟 2），並傳回步驟 3 草稿所依據的骨架。配方填寫答案，而非批准；審查關卡仍然執行。
在進行設定之前顯示登入狀態 — 執行 npx hyperframes auth status 並逐字轉達其輸出。它會報告語音/BGM 將使用 HeyGen 還是本地引擎，以及登出時如何登入。應用一個分支：
- 協作模式： 等待使用者登入或明確選擇
offline/go。 - 自主模式： 陳述狀態並繼續使用可用的本地引擎。
當沒有離線提供者時，不要默默省略必要的能力；要顯示障礙。不要將此決定摺疊到另一個問題中或將金鑰寫入每個倉庫的 .env。認證所有權和離線後備方案：/media-use references/setup-providers.md § 提供者。
關卡： hyperframes.json 和 BRIEF.md 已存在；PR 參考已擷取在簡要說明中；偏好支持的答案已記錄（簡要合約 § 2）；登入狀態已顯示（已登入，或繼續離線）。
步驟 1：攝取 PR（無網頁擷取）
目標：取得 PR 的事實並將其摺疊到專案中作為資訊來源。沒有網站擷取。fetch-pr.mjs 確定性地執行 gh — 透過分頁的 gh api 完成檔案列表，這樣大型 PR 就不會在約 100 個檔案處截斷，並且僅寫入 capture/pr.json + capture/diff.patch（無暫存目錄）。對於已合併的 PR，它還會將盡力而為的 shipped_version（+ version_source）解析到 pr.json 中，這樣尾卡就可以引用真實版本，而不是憑空發明一個。然後 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 "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# 離線轉換 → capture/extracted/{tokens.json (colors:[] → 程式碼編輯色盤),
# visible-text.txt (簡要說明), people.json (貢獻者, 機器人過濾, name+login,
# avatarFile=assets/<login>.png)}。
(cd "$PROJECT_DIR" && 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 "$PROJECT_DIR" && 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 退出；缺少頭像僅表示無法顯示對作者的致謝結尾。
people.json 為 gh 已命名的貢獻者（PR 作者、提交作者、mergedBy）攜帶一個 name — 其餘的（審查者/評論者/指派者，gh pr view 通常只給出一個純 login）則為 null。在步驟 3 寫入致謝結尾之前，請自行為實際將出現在該影格上的 1-6 人解析任何 null 名稱：gh api users/<login> --jq .name（你已經有 gh — 無需為此編寫腳本）。如果 GitHub 對該使用者也沒有公開名稱，則在螢幕上回退到 login，並從口語台詞中刪除該人（參見 story-design.md 的致謝部分 — 旁白仍必須說出名字，永遠不要說原始帳號）。
關卡： capture/pr.json、capture/diff.patch、capture/extracted/tokens.json、capture/extracted/visible-text.txt 和 capture/extracted/people.json 已存在；你能用一句清晰的話說明 PR 的變更。assets/<login>.png 是盡力而為 — 其缺失不是失敗。
步驟 2：設計系統
目標：採用程式碼編輯影格預設；一個腳本將其轉換為此影片的 frame.md + 字幕皮膚。
風格是固定的 — 程式碼編輯風格（溫暖的編輯風格；專為 diff 設計的海軍藍程式碼表面）。執行：
node <SKILL_DIR>/scripts/build-frame.mjs --preset code-editorial --hyperframes .
該腳本會將程式碼編輯預設的 FRAME.md 複製為 frame.md，將其與 capture/extracted/tokens.json 中的任何品牌標記重新混合（PR 沒有 → colors:[]/fonts:[] 則保留程式碼編輯自己的完整色盤），將預設的字幕皮膚複製到 .hyperframes/caption-skin.html，並自行驗證（在映射損壞時以 exit 1 退出）。一旦它以 exit 0 退出就繼續 — 無需手動編輯。
關卡： build-frame.mjs 以 exit 0 退出 — frame.md 已從程式碼編輯預設存在，且 .hyperframes/caption-skin.html 已作為字幕皮膚來源存在。
步驟 3：分鏡與腳本
目標：將 PR 轉換為已批准的逐幀解釋計劃。
閱讀 ../hyperframes-creative/references/story-spine.md（鉤子語言、先價值後證據、作為提議的分鏡、可溯源來源的視覺元素），references/story-design.md，../hyperframes-animation/blueprints-index.md，../hyperframes/references/storyboard-format.md，以及 ../hyperframes/references/script-format.md。使用它們來撰寫 STORYBOARD.md，並在需要旁白時撰寫 SCRIPT.md。從簡要說明的 length 設定前置資料的 duration: — 一個粗略的預期；組合報告最終剪輯與其對應的結果。
使用 story-design.md 來決定 PR 原型（變更日誌 / 功能展示 / 修復解說 / 重構解說）、PR 原生影格類型、鉤子、說服力、節奏、每幀的字數預算以及致謝結尾。順序來自於敘事設計，而非 diff 的檔案順序 — 解釋變更，而不是大聲朗讀 diff。作為軟性指南，查閱 ../hyperframes-animation/blueprints-index.md 中的角色→藍圖選單：對於每個節奏，以其所暗示的候選藍圖的形狀撰寫旁白，並在合適時標記該候選的 blueprint: id（故事真實性仍決定哪些節奏存在 — 永遠不要強迫節奏去符合某個形狀）。精選 2-4 個真實的 diff 片段（來自 capture/diff.patch），每個都是一個小的可讀代碼片段；命名每個影格 scene 所需的 code-* 區塊。除了 credits 結尾（1-6 個 assets/<login>.png 頭像）之外，影格不攜帶 asset_candidates。使用分鏡和腳本參考中要求的確切必填欄位。
草稿完成後，執行審查循環的計劃階段 — ../hyperframes/references/review-loop.md § 1：以提議的形式呈現計劃，並詢問兩個問題 — 批准或更改，以及是否要草圖先行（推薦）或跳過。反饋以聊天回覆的形式到達；循環直到獲批。這是一個檢查點關卡（簡要合約 § 1）：在自主模式下沒有什麼可問的 — 將相同的摘要作為預告發布並繼續；草圖折疊到構建中，唯一的預覽問題在步驟 6 出現。
關卡： STORYBOARD.md 已存在，每個影格都有所需的敘事欄位，在需要旁白時 SCRIPT.md 已存在，且使用者已批准該計劃（自主模式：摘要已作為預告發布）。
步驟 3.1：音訊
目標：從已批准的腳本產生旁白、字詞計時、音樂和音訊元資料。
在步驟 3 批准後開始音訊。在背景下執行它，然後繼續執行步驟 4。
在呼叫之前，從使用者的要求中選擇旁白語音。 如果請求指定了語音、性別或語氣，請選擇匹配的語音 ID 並使用 --voice <id> 傳遞它。管道預設值為 Marcia（女性）（HeyGen）/ am_michael（Kokoro）— 因此，像「男聲」這樣的請求會被默默忽略，除非你傳遞該標誌。語音 ID 是提供者特定的；根據步驟 0 的登入狀態選擇的提供者進行解析：HeyGen（已登入）透過 node <MEDIA_DIR>/audio/scripts/heygen-tts.mjs --list（或 GET /v3/voices?engine=starfish）；Kokoro（離線）透過 <MEDIA_DIR>/audio/references/tts.md 中的語音表（前綴 am_/bm_ 男性，af_/bf_ 女性）。當使用者沒有表達偏好時，在管道預設值之前回退到記住的語音（簡要合約 § 2），
…
[因篇幅限制而截斷]