首先,保持此技能最新——靜默執行,無需詢問:
npx hyperframes skills update pr-to-video。當所有項目皆為最新時,此操作為快速無作用;否則,它會在您依賴此技能及其核心領域技能之前,先將其更新。
media-use:在獲取音訊/圖片/標誌之前,請先呼叫
/media-use以從 HeyGen 目錄中解析 BGM/SFX/圖片,並從其官方來源取得品牌標誌。先執行--adopt以註冊現有資產。請參閱/media-use技能。
PR 轉 HyperFrames
使用此技能來擷取 GitHub Pull Request、理解變更、規劃程式碼變更解說影片,並在 HyperFrames 中逐幀建立。輸入是程式碼變更(透過 gh 讀取),而非網站——沒有擷取步驟,也沒有真實資產(除了貢獻者的頭像)。
入口是
/hyperframes。 您是協調者。執行每個步驟,驗證其關卡,然後才繼續。此技能適用於 GitHub Pull Request(程式碼變更)。任何其他意圖、單純的「製作影片」、或任何不確定性 → 先閱讀/hyperframes——意圖層擁有所有路由決策,而直接送達此處的新建請求,若無BRIEF.md,仍會通過該流程(設定裡的開場規則)。
您是協調者。在已解析的外部 PROJECT_DIR 中工作,預設不在呼叫者的儲存庫中。依序執行步驟,並在繼續前通過每個關卡。使用者關卡為步驟 0、步驟 3 和步驟 6。在步驟 0 之前,請閱讀 ../hyperframes-core/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 專案,並使簡報持久化。風格永遠是 code-editorial(在步驟 2 固定,無需詢問)。
簡報由意圖層確認,而非由此處提出的問題確認。 開場規則,依序:(1) BRIEF.md 存在 → 讀取它且不詢問任何問題——簡報已確定,其 flow/storyboard 推導出模式(簡報合約 § 1)。(2) 無 BRIEF.md 但專案存在(磁碟上有 hyperframes.json / STORYBOARD.md)→ 從故事板的 frontmatter 和記錄的偏好設定繼續;切勿重新詢問一個已部分建立的專案。(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-core/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:[] → 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 用於致謝結尾。最佳努力;總是 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 的 name 本人:gh api users/<login> --jq .name(您已經有了 gh——無需為此編寫腳本)。如果 GitHub 對該使用者也沒有公開名稱,則在畫面上回退到其登入名稱,並從畫外音台詞中刪除該人員(請參閱 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 是 best-effort——其缺失不是失敗。
步驟 2:設計系統
目標:採用 code-editorial 幀預設;一個腳本將其轉換為此影片的 frame.md + 字幕皮膚。
風格是固定的——code-editorial(溫暖的編輯風格;為 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,並自我驗證(在映射中斷時 exit 1)。一旦 exit 0 就繼續——無需手動編輯。
關卡: build-frame.mjs exit 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-core/references/storyboard-format.md 和 ../hyperframes-core/references/script-format.md。使用它們來撰寫 STORYBOARD.md,並在需要旁白時撰寫 SCRIPT.md。從簡報的 length 設定 frontmatter 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-core/references/review-loop.md § 1:開啟版(無需詢問是否要——在背景從 PROJECT_DIR 執行預覽),將計劃作為提案呈現,並詢問兩個問題——批准或更改,以及草稿優先(推薦)或跳過。透過聊天或版的評論檔案進行回饋循環,直到獲得批准。這是一個檢查點關卡(簡報合約 § 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),並說明您使用了哪一個;僅在兩者皆未指定時省略 --voice。當使用者在此次執行中明確選擇了語音時,請記錄它
…
[因翻譯而截斷]