pr-to-video - 排程進入點
輸入是一個 GitHub 拉取請求(程式碼變更),以 PR URL、<擁有者>/<倉庫>#<編號> 參考,或在已檢出含有未關閉 PR 的倉庫時使用「此 PR」。輸出是一個 程式碼變更解說:說明了什麼、為什麼以及如何運作——從差異比較/提交記錄渲染為前後對比、差異高亮、檔案樹和影響場景。預設長度 最長約 3 分鐘(最佳區間約 30-90 秒);真正的長篇或詳盡的每個檔案逐步解說(5 分鐘以上)屬於不同類型,請參閱 /general-video。攝取階段不進行網站爬取,也不使用無頭 Chrome——攝取是透過 gh CLI 進行的。出廠風格預設始終為 claude(溫暖的編輯風格;招牌海軍藍程式碼視窗)。
在第 0 步之前確認路徑。 此技能用於解說 GitHub 拉取請求(透過
gh讀取的程式碼變更)。如果輸入是 行銷/產品網站 →/product-launch-video;一般網站 →/website-to-video;主題/文章(無 PR) →/faceless-explainer;整個倉庫導覽或多 PR 版本發布 →/general-video。超出範圍:即時/渲染時資料——PR 資訊在作者撰寫時讀取一次並固定。如果收到非 PR 的輸入或不確定?請先閱讀/hyperframes。
此工作流程僅負責 PR 專屬的前端部分(攝取 + 故事設計);標記為 共享 的每個階段會直接複用 faceless-explainer 的引擎(它位於此技能的 scripts/ + agents/ + phases/ 目錄下,因此 <SKILL_DIR> 解析為 pr-to-video)。
所有成品都放在 PROJECT_DIR = videos/<專案名稱>/(在第 0 步建立);以下所有路徑都是相對於此目錄。排程機制是可移植的:在首次分派子代理之前,請閱讀 <SKILL_DIR>/../hyperframes-core/references/subagent-dispatch.md 一次——它會將分派動詞(並行扇出 / 背景 / 等待)映射到您工具的原始機制;低於 N 的並行限制意味著每次最多 N 個 worker 的批次,絕不會使用更少的 worker。此文件是具有約束力的操作手冊,而非背景閱讀資料:請依序執行步驟,並使用指定的腳本或代理角色產出每個階段的成品——不要以自由形式的流程替代,也不要因為請求看似明確就跳過暫停步驟。遇到無法執行的步驟 → 停止並回報。
| 階段 | 執行方式 | 主要成品 | 詳細流程 |
|---|---|---|---|
| init | Bash | hyperframes.json | 步驟 0 |
| ingest(專屬) | Bash(gh CLI + ingest.mjs + fetch-people-avatars.mjs,無代理,無爬取) | capture/pr.json + diff.patch + extracted/{tokens.json,visible-text.txt,people.json} + public/avatars/ | 步驟 1 |
| 設計系統(共享) | Bash(無代理,確定性 claude) | design-system/design.html + chunks/ | 步驟 1b |
| 故事設計(專屬) | 子代理 | narrator_scripts.json | agents/story-design.md |
| 音訊(共享) | Bash 中的 audio.mjs | audio_meta.json | phases/audio/guide.md |
| 視覺設計(共享) | 子代理 | section_plan.md | agents/visual-design.md |
| 預處理(共享) | Bash 中的 prep.mjs | group_spec.json | scripts/prep.mjs |
| 字幕(共享,詳細) | Bash 中的 captions.mjs group -> captions.mjs html(無子代理) | caption_groups.json + compositions/captions.html | scripts/captions.mjs |
| 場景(共享) | N 個子代理(並行) | compositions/scene_*.html 或 compositions/group_w*.html | agents/hyperframes-scene.md |
| 最終處理(共享) | Bash 前奏(等待 BGM + 組合 + 注入/驗證轉場 + 提取影片 + SFX 驗證 + 預檢) -> 最終處理子代理(就地修正簡短問題 + 一次精簡的聯絡表單檢視 + 渲染) | renders/video.mp4 | 步驟 7 / agents/hyperframes-finalize.md |
先決條件
macOS Apple Silicon 或 Linux x64。系統工具:brew install [email protected] node ffmpeg(使用 Homebrew Python,不要用 /usr/bin/python3,否則 pip install 會因 PEP 668 而被阻止);然後執行 npx hyperframes doctor 一次(下載 Chrome——用於快照/渲染,而非攝取)。渲染重疊檢測(scripts/check-overlap.mjs,在工作者的自我檢查和預檢中執行)會重複使用同一個快取的 Chrome——它絕不會下載瀏覽器;其唯一依賴是 puppeteer-core npm 模組,在場景扇出之前(步驟 5.5,--ensure-deps,約 5 秒,無需完整安裝 puppeteer)確保一次。CLI 工具:gh(GitHub CLI,已認證——gh auth status 必須通過)和 hyperframes。可選的雲端金鑰(否則使用本地後備方案)——在第 0.5 步注入:
| 金鑰 / 要求 | 用途 | 預設 / 後備方案 |
|---|---|---|
gh auth status 通過 | 讀取 PR(公開或私有) | 必要——若不通過則失敗並顯示認證提示 |
HEYGEN_API_KEY(或 hyperframes auth login) | TTS(雲端,附帶逐字時間戳) | 語音:自動(第一個英文 Starfish 語音;可透過 --voice 覆蓋) |
ELEVENLABS_API_KEY | TTS(雲端;需要 pip install elevenlabs) | 語音 21m00Tcm4TlvDq8ikWAM(Rachel) |
| 兩者皆無且未登入 | TTS | 本地 Kokoro,語音 am_michael(非英文:傳遞 --voice) |
GEMINI_API_KEY / GOOGLE_API_KEY(別名) | Lyria BGM | 未設定 -> 本地 MusicGen(首次執行會下載約 300 MB) |
流程
步驟 0.0 - 確認簡報(始終詢問一輪,然後再建構)
在第 0 步之前,始終暫停並在一次訊息中詢問簡報,然後等待使用者——絕不要跳過此步驟,即使請求看起來很完整。 為每個欄位推薦一個預設值,並預先填入使用者已提供的內容(確認它,而不是盲目地重新詢問):角度(變更日誌 / 功能揭露 / 修正 / 重構——預設:從 PR 推斷)、受眾(開發者 vs 一般使用者——預設:開發者)、長度(預設約 60-90 秒),以及——如果 /hyperframes 沒有設定——畫面比例(預設 16:9)和語言。風格始終為 claude。只有在使用者回覆後才繼續執行步驟 0;「開始」/「使用預設值」是有效的回覆,表示接受所有預設值。
步驟 0 - 初始化影片專案
目前工作目錄為代理工作區根目錄(例如 /tmp/pr-video-...)。將所有影片成品寫入 PROJECT_DIR = videos/<專案名稱>/。
<專案名稱>:使用使用者提供的目錄名稱(例如 Use ./videos/retry-pr),否則從 PR 衍生一個簡短的 kebab-case 名稱(<倉庫>-pr-<編號>,例如 widgets-pr-1187)。不要使用工作區的基本名稱或時間戳記。
僅當 $PROJECT_DIR/hyperframes.json 不存在時:
PROJECT_DIR="${PR_VIDEO_DIR:-videos/<專案名稱>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
hyperframes init會將通用的AGENTS.md/CLAUDE.md放入$PROJECT_DIR;請保留它們——它們是為稍後開啟完成專案的人準備的代理腳手架。
限制: 絕不要在工作區根目錄執行 hyperframes init / 產生 AGENTS.md / CLAUDE.md;絕不要在 PROJECT_DIR 內巢狀另一個 hyperframes/ 目錄;每個 Bash 命令(主代理 + 子代理)都是 (cd "$PROJECT_DIR" && ...) 子 shell——絕不要使用裸的 cd。
步驟 0.5 - API 金鑰引導
如果 $PROJECT_DIR/.env 存在或 context.log 非空(= 不是首次執行),則跳過。否則首先檢測可用的金鑰(如果設定了 $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY 或 hyperframes auth login 產生的 ~/.heygen/credentials 存在,則 HeyGen TTS 啟用;只有當環境金鑰設定時,ElevenLabs / Gemini 才啟用),然後始終暫停並提供選單——等待使用者;即使檢測到可用的設定,也不要自行繼續(使用者可能想要添加像 Gemini 這樣的金鑰)。說明檢測到的內容,然後:貼上金鑰(→ 寫入 $PROJECT_DIR/.env,每行一個 KEY=value,相同名稱會覆蓋)/「開始」(使用已設定的內容繼續——環境變數、.env 或 hyperframes auth login)/「跳過」(對於任何未設定的內容,使用本地後備方案繼續)。然後繼續執行步驟 1。
步驟 1 - 攝取(Bash,無代理,無爬取)
解析 PR 參考並使用 gh 提取結構化資訊,然後將它們摺疊成共享後端期望的綜合擷取套件(類似 faceless-explainer 的無爬取腳手架)。gh 在此處,在協調器中執行,因此認證 / 未找到 / 私有倉庫錯誤會透過 gh 自己的 stderr 顯示;ingest.mjs 是一個純離線轉換。
# PR 參考:完整 URL、「<擁有者>/<倉庫>#<編號>」、或在已檢出的倉庫中使用「<編號>」
PR="<url | 擁有者/倉庫#編號 | 編號>"
# 如果 gh 未認證則快速失敗
gh auth status || { echo "gh 未認證 — 執行: gh auth login"; exit 1; }
(cd "$PROJECT_DIR" && mkdir -p capture/extracted capture/assets)
(cd "$PROJECT_DIR" && gh pr view "$PR" \
--json number,title,body,author,url,baseRefName,headRefName,commits,files,additions,deletions,changedFiles,labels,reviews,latestReviews,comments,assignees,reviewDecision,mergedBy \
> capture/pr.json)
(cd "$PROJECT_DIR" && gh pr diff "$PR" > capture/diff.patch)
# 將 pr.json + diff.patch 轉換為 tokens.json(colors:[] → claude 原生調色板)+
# visible-text.txt(敘述簡報)+ people.json(PR 作者 + 提交作者及其次數 +
# 審查者 / 評論者 / 受指派者,經過機器人過濾和去重,每人含 GitHub 頭像 URL)。
#(PR `author` 僅是開啟者;提交作者來自 commits[].authors[] 也會追蹤。)
# 攝取是離線的。
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/ingest.mjs \
--pr-json ./capture/pr.json --diff ./capture/diff.patch --out-dir ./capture/extracted)
# 網路步驟(people 前端的唯一一個——攝取保持離線):將每個貢獻者的
# GitHub 頭像下載到 public/avatars/<登入名稱>.png,用於可選的致謝 /
# 發布者尾卡。盡力而為——缺少頭像或離線運行絕不會阻塞(exit 0)。
# 頭像 + 該尾卡是 pr-to-video 放寬無面預設的唯一地方。
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/fetch-people-avatars.mjs \
--people ./capture/extracted/people.json)
驗證:
[ -s "$PROJECT_DIR/capture/pr.json" ] && \
[ -s "$PROJECT_DIR/capture/diff.patch" ] && \
[ -s "$PROJECT_DIR/capture/extracted/tokens.json" ] && \
[ -s "$PROJECT_DIR/capture/extracted/visible-text.txt" ] && \
[ -s "$PROJECT_DIR/capture/extracted/people.json" ] && \
[ -d "$PROJECT_DIR/capture/assets" ] && echo ok || echo missing
# public/avatars/ 是盡力而為——其缺失**不是**失敗(沒有解析到頭像 / 離線)。
如果 gh 出錯(認證 / 未找到 / 私有),報告確切的 stderr 並停止——不要虛構 PR 內容。如果 ingest.mjs 退出
…
[因篇幅截斷]