首先,保持此技能最新——在執行前請先與使用者確認:
npx hyperframes skills update pr-to-video。若一切皆為最新,則快速無操作;否則它會在您依賴此技能及其依賴的核心領域技能之前,先進行更新。
media-use:在取得音訊/圖片/標誌之前,請先呼叫
/media-use從 HeyGen 目錄中解析 BGM/SFX/圖片,並從官方來源取得品牌標誌。請先執行--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(您將調度一個有限制的影格工作池)之外,請自行執行每個步驟。請勿將設計或動態規則放在此處;這些規則位於影格工作者子代理程式、此技能的本地 ../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> 參考,或已簽出儲存庫中的「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-to-video project: $PROJECT_DIR"
node <SKILL_DIR>/scripts/preflight.mjs
能力預檢會在擷取、腳本工作、音訊或影格調度之前執行。如果已安裝的 CLI 無法執行此技能所需的驗證命令,請停止並提供其升級說明,而不是先耗費此執行上下文。
僅在 $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" && …);切勿變更呼叫者儲存庫的工作目錄。
在 init 之後立即寫入 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 錯誤在此處以退出碼 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。盡力而為;始終以退出碼 0 結束。
(cd "$PROJECT_DIR" && 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 結束;缺少頭像僅表示沒有作者片尾名單。
people.json 會為 gh 已命名的貢獻者(PR 作者、提交作者、mergedBy)攜帶一個 name——其餘的(審查者/評論者/指派者,gh pr view 僅提供裸 login)則為 null。在步驟 3 寫入片尾名單之前,請自行為 1-6 位實際會出現在該影格上的人員解析任何 null 的 name:gh api users/<login> --jq .name(您已經有 gh——無需為此編寫腳本)。如果 GitHub 對該使用者也沒有公開姓名,請在螢幕上使用 login,並將該人員從旁白中移除(參見 story-design.md 的 credits 章節——旁白仍必須說出名稱,而非原始帳號)。
關卡: 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 .
該腳本會將 code-editorial 預設集的 FRAME.md 複製為 frame.md,根據 capture/extracted/tokens.json 中的任何品牌代幣進行混音(PR 沒有這些 → colors:[]/fonts:[] 保留 code-editorial 自己的調色盤,一個完整的設計),將預設集的字幕外觀複製到 .hyperframes/caption-skin.html,並自行驗證(在映射損壞時以退出碼 1 結束)。一旦它以退出碼 0 結束,請繼續——無需手動編輯。
關卡: build-frame.mjs 已以退出碼 0 結束——frame.md 已從 code-editorial 預設集存在,且 .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 原型(change-log / feature-reveal / fix-explainer / refactor-walkthrough)、PR 原生影格類型、鉤子、說服力、節拍、每個影格的單詞預算,以及片尾名單。順序來自敘事設計,而非 diff 的檔案順序——解釋變更,而不是大聲朗讀 diff。作為軟性指南,請查閱 ../hyperframes-animation/blueprints-index.md 中的角色→藍圖選單:對於每個節拍,以候選藍圖所隱含的形式撰寫旁白,並在合適時標記該候選 blueprint: id(故事真相仍決定哪些節拍存在——切勿強迫節配合形狀)。精選 2-4 個真實的 diff 區塊(來自 capture/diff.patch),每個都是一小段易於閱讀的片段;在影格的 scene 中指定每個片段所需的 code-* 區塊。影格不攜帶 asset_candidates,除了 credits 片尾名單(1-6 個 assets/<login>.png 頭像)。使用分鏡表和腳本參考中的確切必要欄位。
草稿完成後,執行審查循環的計劃階段——../hyperframes/references/review-loop.md § 1:將計劃作為提案呈現,並詢問兩個問題——核准或變更,以及先看草稿(建議)或跳過。回饋將以聊天回覆形式送達;循環直到核准。這是一個檢查點關卡(簡報合約 § 1):在自主模式下沒有什麼可問的——將相同的摘要作為提醒發布並繼續;草稿將摺疊到建構中,唯一的預覽問題將在步驟 6 進行。
關卡: STORYBOARD.md 存在,每個影格都有必要的敘事欄位,當需要旁白時 SCRIPT.md 存在,且使用者已核准該計劃(自主模式:摘要已作為提醒發布)。
步驟 3.1:音訊
目標:從已核准的腳本生成旁白、單字時間戳、音樂和音訊元資料。
在步驟 3 核准後開始音訊。在背景執行它,然後繼續步驟 4。
在呼叫之前,根據使用者的要求選擇旁白語音。 如果請求指定了語音、性別或語調,請選擇一個匹配的語音識別碼並使用 --voice <id> 傳遞它。管線預設值為 Marcia(女性) (HeyGen) / am_michael (Kokoro)——因此像「男聲」這樣的請求會被靜默忽略,除非您傳遞了該標誌。語音識別碼是提供者特定的;根據步驟 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),並說明您使用了哪一個;僅在兩者都未指定時才省略 --voice。當使用者在此次執行中明確選擇了語音時,請記錄它(prefs.mjs record --key voice)。
node <SKILL_DIR>/scripts/audio.mjs --script ./SCRIPT.md --storyboard ./STORYBOARD.md --frames-dir ./compositions/frames——這會為每個影格生成 .wav 檔案和 .json 時間戳檔案,將它們放置在 compositions/frames/ 中,並建立 audio_meta.json,其中包含整個影片的元資料。該腳本會處理文字到語音的轉換(使用已配置的提供者)、單字層級的時間對齊,以及背景音樂的生成/選擇。它還會更新 STORYBOARD.md 以包含每個影格的音訊時間戳。
關卡: audio_meta.json 存在,且 compositions/frames/ 包含每個影格的 .wav 和 .json 時間戳檔案;使用者可以播放任何一個來驗證(協同模式)或只是繼續(自主模式)。
步驟 4:視覺設計
目標:用視覺設計資訊增強 STORYBOARD.md,確保每個影格都有明確的視覺指示和動態指引。
閱讀 ../hyperframes-animation/blueprints-index.md 和 .hyperframes/caption-skin.html。對於 STORYBOARD.md 中的每個影格,新增一個 visual 區塊,其中包含具體的佈局、配色方案、動畫提示和任何必要的疊加文字。使用 frame.md 中的設計代幣來確保一致性。
對於程式碼影格,指定:
- 要顯示的程式碼片段(從
capture/diff.patch) - 高亮行(diff 新增/刪除)
- 使用的
code-*區塊類型 - 任何註解或標註
對於圖表/架構影格,指定:
- 佈局類型(流程圖、比較、時序圖)
- 要包含的關鍵元素
- 動畫方向
在影格的 duration 欄位中根據腳本內容為每個影格設定持續時間。使用 storyboard-format.md 中定義的確切欄位。
自主模式: 在視覺設計期間檢查一致的違規行為——如果 STORYBOARD.md 中的連續影格在同一位置上顯示程式碼截圖兩次,請在計算機視覺檢查在步驟 6 標記為重複之前重新排列它們。
關卡: STORYBOARD.md 中的每個影格都有一個完整的 visual 塊,每個影格都指定了持續時間,且視覺設計與 frame.md 中定義的設計系統一致。
步驟 5:影格
目標:將每個分鏡影格變成獨立的 HTML 檔案,可以組合起來製作最終影片。
將 STORYBOARD.md 中的影格拆分為獨立的任務。每個影格都將被渲染為 compositions/frames/NN-*.html,其中 NN 是影格編號。您可以並行使用多個工作者。每個工作者都會收到一個影格號碼、視覺區塊、腳本區塊和持續時間,並產生一個完整的 HTML 檔案。
協調工作者。確保:
- 所有影格都已建立
- 它們的編號正確
- 它們都引用相同的設計系統(
frame.md中的 CSS 變數) - 產生了
index.html以按順序列出它們
# 影格工作者的範例命令
node <SKILL_DIR>/scripts/render-frame.mjs \
--frame-num NN \
--storyboard ./STORYBOARD.md \
--script ./SCRIPT.md \
--frame-design ./frame.md \
--caption-skin ./.hyperframes/caption-skin.html \
--out-dir ./compositions/frames
關卡: compositions/frames/index.html 存在且列出所有影格;compositions/frames/NN-*.html 對應於 STORYBOARD.md 中的每個影格。
步驟 6:最終渲染
目標:將所有影格組合起來,製作最終影片,加入音訊並輸出為 renders/video.mp4。
執行最終渲染命令:
node <SKILL_DIR>/scripts/render-video.mjs \
--frames-dir ./compositions/frames \
--audio-meta ./audio_meta.json \
--storyboard ./STORYBOARD.md \
--out-dir ./renders
該腳本會將所有影格拼接成一個連續的影片,同步音訊(旁白和背景音樂),並輸出最終的 MP4 檔案到 renders/video.mp4。
預覽和審查: 渲染完成後,這是最終的使用者關卡(簡報合約 § 1)。向使用者呈現影片以供審查:
- 協同模式: 提供
renders/video.mp4的鏈結,並詢問:「這是您要的嗎?需要修改嗎?」等待回覆。如果他們要求變更,請確定變更範圍(腳本、視覺效果、音訊),循環回相關步驟,然後重新渲染。 - 自主模式: 靜默地最終確定。
關卡: renders/video.mp4 存在,使用者已核准最終影片(協同模式),或已靜默地最終確定(自主模式)。