外掛安裝: 在執行設定或更新命令之前,如果此技能位於 HyperFrames 外掛內部,請遵循外掛執行規則。獨立安裝則保留下面的更新說明。
首先,保持此技能最新——在執行前與使用者確認:
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> 引用或已檢出儲存庫中的「此 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
能力預檢在擷取、故事工作、音訊或影格分派之前執行。如果安裝的 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 / 未找到 / 私有錯誤在此以 exit 1 退出。
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-pr.mjs --pr "$PR" --out-dir ./capture)
# 離線轉換 → capture/extracted/{tokens.json (colors:[] → code-editorial 調色板),
# 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 / 未找到 / 私有),報告其 stderr 並停止——不要偽造 PR 內容。如果 ingest.mjs 以 1 退出,讀取其 stderr(通常是格式錯誤的 pr.json),修復並重新執行(確定性)。fetch-people-avatars.mjs 始終以 0 退出;缺少頭像僅意味著沒有給作者的致謝結尾。
people.json 為 gh 已命名的貢獻者(PR 作者、提交作者、mergedBy)攜帶一個 name——其餘的為 null(審查者/評論者/受指派人,gh pr view 只會給出純 login)。在步驟 3 中寫入致謝結尾之前,自行為實際會出現在該影格上的 1-6 人解析任何 null 的 name: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 + 字幕 skin。
風格是固定的——程式碼編輯(溫暖的編輯風格;為 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 自身的調色板,一個完整的設計),複製預設的字幕 skin 到 .hyperframes/caption-skin.html,並進行自我驗證(在錯誤的映射上以 1 退出)。一旦它以 0 退出就繼續——無需手動編輯。
關卡: build-frame.mjs 以 0 退出——frame.md 從 code-editorial 預設存在,且 .hyperframes/caption-skin.html 作為字幕 skin 來源存在。
步驟 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-* 區塊。影格不攜帶 asset_candidates,除了 credits 結尾(1–6 個 assets/<login>.png 頭像)。使用故事板和腳本參考中的精確必填欄位。
在草稿之後,執行審查循環的計劃階段——../hyperframes/references/review-loop.md § 1:將計劃作為提案呈現,並問兩個問題——批准或更改,以及先草圖(推薦)或跳過。反饋以聊天回覆形式到達;循環直到批准。這是一個檢查點關卡(簡報合約 § 1):在自主模式下沒有任何要問的——將相同的摘要作為預告發布並繼續;草圖摺疊到建構中,最終預覽及其一個問題在步驟 6 出現。
關卡: STORYBOARD.md 存在,每個影格都有必填的敘事欄位,當需要旁白時 SCRIPT.md 存在,且使用者批准了計劃(自主模式:摘要作為預告發布)。
步驟 3.1:音訊
目標:從已批准的腳本生成旁白、單字時間、音樂和音訊元資料。
在步驟 3 批准後開始音訊。在背景執行它,然後繼續步驟 4。
在調用之前從使用者的要求中選擇旁白語音。 如果要求指定了語音、性別或語氣,選擇一個匹配的語音 ID 並傳遞 --voice <id>。否則,管線預設是 HeyGen 上的 Marcia(女性) / Kokoro 上的 am_michael——因此像「男聲」的要求將被靜默忽略,除非您傳遞標誌。語音 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)。
生成音訊
# 如果需要 HeyGen 音效(BGM 和 SFX 稍後來自 storyboard)
# node <MEDIA_DIR>/scripts/heygen-effects.mjs --out ...
# 生成旁白時間戳記
node <MEDIA_DIR>/audio/scripts/generate-tts.mjs \
--script ./SCRIPT.md \
--voices ./audio_voices.json \
--out-dir ./audio_out
# 生成單字時間(用於字幕同步)
node <MEDIA_DIR>/audio/scripts/generate-word-timings.mjs \
--audio ./audio_out/narration.wav \
--transcript ./SCRIPT.md \
--out ./audio_out/word_timings.json
# 如果使用 HeyGen 生成 BGM/SFX
# node <MEDIA_DIR>/audio/scripts/heygen-effects.mjs --out ...
# 生成 audio_meta.json
node <MEDIA_DIR>/audio/scripts/generate-audio-meta.mjs \
--narration ./audio_out/narration.wav \
--word-timings ./audio_out/word_timings.json \
--out-dir ./audio
關卡: audio_meta.json 存在且包含所有音訊軌道的路徑。
步驟 4:視覺設計
目標:根據故事板和腳本為每個影格指定視覺設計。這是一個對 STORYBOARD.md 的就地增強,添加 scene 規格(包括 code-* 區塊引用、可選的動畫提示、任何所需註釋的頁面位置)。
閱讀 ../hyperframes-animation/rules/ 中的設計規則和 ../hyperframes-animation/blueprints/ 中的藍圖。對腳本中的每個節拍,從其候選藍圖中選擇一個影格佈局(或建立一個新的佈局),並填充 scene 欄位。對於程式碼影格(最常見),指定要顯示的確切程式碼片段以及任何註釋或高亮。對於過渡影格,指定動畫或運動類型。確保每個視覺元素都映射回故事板中建立的敘事節拍。
在步驟 3 的審查循環的設計階段期間展示視覺設計提案——../hyperframes/references/review-loop.md § 2。在自主模式下,這只是一個報告步驟。
關卡: STORYBOARD.md 為每個影格具有已填充的 scene 欄位,且視覺設計已獲批准(自主模式:已報告)。
步驟 5:影格
目標:從已批准的設計為每個影格生成 HTML 檔案。這是一個平行步驟——分派一個有界的影格工作者池,每個工作者構建一個或多個影格。
分派影格工作者
# 為所有影格生成 HTML
npx hyperframes render frames --storyboard ./STORYBOARD.md --out-dir ./compositions/frames
# 建立索引頁面以進行預覽
node <SKILL_DIR>/scripts/build-index.mjs --frames-dir ./compositions/frames --out ./compositions/frames/index.html
工作者有嚴格的輸出合約:每個工作者輸出一個檔案 NN-<slug>.html 到 compositions/frames/,其中 NN 是兩位數影格編號。工作者從 frame.md 讀取以獲取設計標記,從 audio/word_timings.json 讀取以獲取計時資訊,從故事板讀取以獲取每個影格的場景規格。工作者永不修改專案層級的檔案;它們只寫入它們的輸出影格。
關卡: compositions/frames/ 包含每個編號影格的 NN-*.html 和 index.html,且所有影格在瀏覽器中正確渲染(無空白頁面或損壞的資源)。
步驟 6:最終渲染
目標:將所有影格合成為最終影片檔案。
# 將影格渲染為影片
cd "$PROJECT_DIR" && npx hyperframes render video --frames ./compositions/frames --audio ./audio --out ./renders/video.mp4 --config ./hyperframes.json
# 驗證輸出
if [ -f ./renders/video.mp4 ]; then
echo "最終影片已渲染:$PROJECT_DIR/renders/video.mp4"
node <SKILL_DIR>/scripts/verify-render.mjs --video ./renders/video.mp4
else
echo "渲染失敗"
exit 1
fi
在自主模式下,這是最終交付步驟。在協作模式下,這是最終檢查點關卡(簡報合約 § 1):播放影片並問一個批准問題。如果使用者要求更改,返回適當的步驟(通常是步驟 3 或步驟 4)。如果被批准,將最終影片路徑傳遞給輸出處理常式。
關卡: renders/video.mp4 存在,verify-render.mjs 以 0 退出,且影片已獲批准(協作模式)或已交付(自主模式)。