product-launch-video - 分派入口
在步驟0之前確認路徑。 此技能為 正在行銷/發布/推廣的產品 製作影片。如果實際上是一般的(非發布)網站 → 影片(網站導覽/展示,而非銷售產品)→
/website-to-video;一個主題/概念且無產品 →/faceless-explainer;一個GitHub PR →/pr-to-video;一個現有影片要加字幕/包裝 →/embedded-captions·/graphic-overlays。超出範圍(拒絕,不要偽造):即時/渲染時的資料(所有值在作者創作時就已確定),或尚不存在的素材/截圖/頭像(HyperFrames無法錄製或捕捉)。若因模糊的「製作影片」要求而被路由至此,或不確定產品vs主題/發布vs一般網站?先閱讀/hyperframes。
所有成品都寫入 PROJECT_DIR = videos/<專案名稱>/(在步驟0建立)。以下路徑相對於 PROJECT_DIR。您(協調者)執行Bash步驟並分派子代理器;每個階段的詳細資訊位於連結的指南/代理器/腳本中——請勿在此處展開它們。分派與harness可移植:在第一次分派子代理器之前,閱讀 <SKILL_DIR>/../hyperframes-core/references/subagent-dispatch.md 一次——它將分派動詞(平行扇出 / 背景 / 等待)映射到您的harness的基本原語;低於N的並發上限意味著大小為上限的波浪,從不減少場景數量。此文件是具有約束力的運行手冊,而非背景閱讀材料:按順序執行步驟並使用指定的腳本或代理器角色產生每個階段的成品——不要替代為即興流水線(手寫旁白、臨時TTS調用、手動編寫的合成),也不要因為請求看起來很清楚而跳過暫停步驟。無法執行的步驟 → 停止並回報;即興繞過它會破壞所有下游契約。
| 階段 | 執行方式 | 主要成品 | 詳細流程 |
|---|---|---|---|
| init | Bash直接執行 | hyperframes.json | 步驟0 (此文件) |
| capture | Bash直接執行 (hyperframes capture) | capture/extracted/tokens.json | phases/capture/guide.md |
| design-system | 子代理器 | design-system/design.html + chunks/ | agents/design-system.md |
| story-design | 子代理器 | narrator_scripts.json | agents/story-design.md |
| audio | Bash直接執行 (audio.mjs) | audio_meta.json | phases/audio/guide.md |
| visual-design | 子代理器 | section_plan.md | agents/visual-design.md |
| prep | Bash直接執行 (prep.mjs) | group_spec.json | scripts/prep.mjs 標題 |
| captions | Bash直接執行 (captions.mjs group -> html) | caption_groups.json + compositions/captions.html | scripts/captions.mjs 標題 |
| scenes | N x 子代理器 (平行,每個場景一個) | compositions/scene_*.html | agents/hyperframes-scene.md |
| finalize | Bash前奏 (wait-bgm + assemble + transitions + hoist + sfx-verify) -> 最終化子代理器 | renders/video.mp4 | 步驟7 / agents/hyperframes-finalize.md |
先決條件 (首次執行前安裝)
macOS Apple Silicon 或 Linux x64:
brew install [email protected] node ffmpeg # 在Linux上,使用對應的apt/dnf指令
npx hyperframes doctor # 一次性檢查Chrome/依賴項是否就緒
[email protected]— Homebrew Python,而非系統的/usr/bin/python3(否則PEP 668會封鎖pip install);用於MusicGen備援方案node >= 18+ffmpeg(audio.mjs使用ffprobe)- Chrome會在首次執行
npx hyperframes capture時自動下載。hoist-videos.mjs(步驟7,僅當場景宣告要使用素材時執行)會重複使用該快取的Chrome;如果它報告缺少依賴項,請執行node <SKILL_DIR>/scripts/hoist-videos.mjs --ensure-deps一次(約5秒)
可選API金鑰(未設定 -> 使用本地備援方案;在步驟0.5注入;GEMINI_API_KEY ≡ GOOGLE_API_KEY):
| 金鑰 | 用途 | 預設語音 / 備援方案 |
|---|---|---|
HEYGEN_API_KEY (或 hyperframes auth login) | TTS(雲端,含字詞級時間戳) | 語音: auto(第一個英語海星語音;可使用 --voice 覆寫) |
ELEVENLABS_API_KEY | TTS(雲端;需要 pip install elevenlabs) | 語音 21m00Tcm4TlvDq8ikWAM (Rachel) |
| 兩者皆無,且未登入 | TTS | 本地 Kokoro,語音 am_michael(非英語,請傳遞 --voice) |
GEMINI_API_KEY (一個金鑰用於兩個用途) | 擷取視覺標題 + Lyria背景音樂 | 未設定 -> 標題僅使用DOM上下文;背景音樂使用本地MusicGen(首次執行下載約300MB) |
流程
步驟 0.0 - 確認簡報(一輪,然後建置)
在步驟0之前,用一條訊息僅確認那些會實質影響發布影片且您無法推斷的事項——先提供一個推薦的預設值,跳過使用者已提供的內容:角度/焦點(整體產品、主打功能、優惠/行動呼籲)、長度(預設約30-90秒;最多約3分鐘),以及——如果 /hyperframes 尚未設定它們——長寬比(預設16:9;9:16適用於垂直/社群媒體)和語言。預設值源自品牌擷取,無需詢問。對於完全指定的請求,請跳過此步驟直接建置。
步驟 0 - 初始化影片專案
cwd是代理器工作區根目錄;所有影片成品都放在 PROJECT_DIR = videos/<專案名稱>/。
命名 <專案名稱>:使用者明確給定的目錄名優先;否則選擇一個簡短的kebab-case名稱,如 <品牌>-promo(絕對不能是工作區的基礎名稱或時間戳)。如果有URL,則從網域/頁面標題推導出名稱;一旦 capture/ 被寫入,名稱就固定了。
初始化(僅當 $PROJECT_DIR/hyperframes.json 不存在時):
PROJECT_DIR="${LAUNCH_VIDEO_DIR:-videos/<專案名稱>}"
mkdir -p "$(dirname "$PROJECT_DIR")"
npx hyperframes init "$PROJECT_DIR" --non-interactive --skip-skills --example=blank
hyperframes init會在$PROJECT_DIR中放入通用的AGENTS.md/CLAUDE.md;保留它們,但不要將其通用指南視為執行時限制——此技能才是真相來源。
限制(每項違規都會破壞後續階段):
- 請勿在工作區根目錄執行
hyperframes init(或產生AGENTS.md/CLAUDE.md);請勿在PROJECT_DIR內部建立hyperframes/子專案。 - 每個子代理器分派上下文都包含一行
PROJECT_DIR: <path>;子代理器將其視為專案根目錄。 - cwd 紀律(主代理器也一樣):每個Bash指令都以
(cd "$PROJECT_DIR" && ...)子shell執行——絕對不要使用裸露的cd "$PROJECT_DIR" && ...(持續的cwd漂移會導致後續相對路徑錯誤)。
步驟 0.5 - API金鑰指引
跳過當 $PROJECT_DIR/.env 存在或 context.log 非空。否則偵測已配置的項目(HeyGen TTS = $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY / ~/.heygen/credentials;ElevenLabs / Gemini = 它們的環境變數金鑰),然後務必暫停並詢問——不要自行繼續,即使偵測到可行的配置也一樣:
偵測到: <摘要>。雲端金鑰是可選的——沒有它們,未配置的提供者會退回到本地(TTS -> Kokoro,除非配置了HeyGen;背景音樂 -> MusicGen)。請回覆:
- 貼上金鑰 -> 我將把它們寫入到
$PROJECT_DIR/.env- "go" -> 使用目前配置的內容繼續
- "skip" -> 對於任何未配置的項目,使用本地備援方案繼續
貼上的金鑰 -> 寫入/編輯 $PROJECT_DIR/.env,每行一個 KEY=value(覆蓋同名金鑰,不判斷值)。"go" / "skip" -> 步驟1。
步驟 1 - 擷取(階段 1)
- 從提示中解析
SKILL_DIR和任何顯式的TARGET_URL;確保步驟0已執行。 - 如果
$PROJECT_DIR/context.log存在,請閱讀它並使用下方的恢復表來跳過已完成的階段。 - 分類輸入(步驟 1.0)以設定
CAPTURE和VO_MODE,然後執行匹配的路徑。兩個路徑共享相同的下游指令。
步驟 1.0 - 分類輸入(設定 CAPTURE + VO_MODE)
| 輸入形狀 | 要做什麼 |
|---|---|
| 提示中有明確的 URL | TARGET_URL = 該URL;CAPTURE=yes;無需詢問旁白問題(旁白來自擷取的網站)。路徑 (A)。 |
| 使用者貼上/指向了一個腳本或簡報 | (1) 將逐字文字儲存到 $PROJECT_DIR/user_script.txt。(2) 詢問旁白問題一次(如下)→ 設定 VO_MODE。(3) 從腳本解析擷取目標(如下)→ 設定 CAPTURE。 |
| 一個主題/簡報,但無腳本散文,無產品 | CAPTURE=no;無需詢問旁白問題。路徑 (B)。 |
旁白問題(僅當使用者提供了實際的腳本散文時)——問一行簡短問題並等待:
我應該將您的腳本逐字用作旁白,還是重組成更適合畫面的場景旁白?
- 逐字 — 保留原始措辭;我只分割場景和配對視覺。時長根據腳本而定。
- 重組 — 將其視為簡報,並重寫更緊湊的旁白,每個場景1-2句話。
VO_MODE = verbatim | restructure(預設為 restructure);在步驟2中傳遞給story-design。
從腳本解析擷取目標 — 預設為尋找並爬取一個網站(真實的品牌標記勝過預設備援方案);僅在使用者選擇退出時跳過(「無網站/僅文字/不擷取」)。順序為:(1) 腳本中有顯式的 http(s):// URL → 使用它,宣告,CAPTURE=yes;(2) 明確的品牌/產品名稱 → WebSearch 搜尋官方網站,在爬取之前用一行向使用者確認解析出的URL(拒絕/無可信結果 → CAPTURE=no);(3) 無可推斷的內容 → CAPTURE=no。
擷取 + 使用者腳本共存:爬取僅提供品牌標記 + 資產 + 視覺風格;旁白主幹仍使用
user_script.txt(透過VO_MODE來遵循),絕不使用網站自己的文案。
(A) 擷取路徑 (CAPTURE=yes):
(cd "$PROJECT_DIR" && npx hyperframes capture "<TARGET_URL>" -o ./capture)
(B) 無擷取路徑 (CAPTURE=no) — 合成一個最小的擷取套件;下游完全相同。您(主代理器)選擇預設(沒有可推斷的網站;根據使用者意圖從19個預設中挑選,或問一個簡短問題)。完整的腳本/簡報會放入 visible-text.txt;colors:[] 會觸發預設調色板備援方案(僅在使用者提到了品牌顏色時才填入 colors):
(cd "$PROJECT_DIR" && mkdir -p capture/extracted capture/assets)
(cd "$PROJECT_DIR" && cat > capture/extracted/tokens.json <<'JSON'
{ "title": "<品牌/標題>", "description": "<一行簡介>", "colors": [], "fonts": [], "headings": [], "sections": [], "ctas": [], "svgs": [], "cssVariables": {} }
JSON
)
(cd "$PROJECT_DIR" && echo '{}' > capture/extracted/design-styles.json)
(cd "$PROJECT_DIR" && printf '%s\n' "<完整的使用者腳本/簡報>" > capture/extracted/visible-text.txt)
如果使用者已有最終的
narrator_scripts.json,請將其放置於$PROJECT_DIR/;恢復表會跳過story-design。
兩個路徑共用的下游指令(路徑B會附加 --style <選擇的預設> 到build-design;路徑A則省略它以進行自動推斷):
(cd "$PROJECT_DIR" && node <SKILL_DIR>/scripts/derive-context-pack.mjs --capture ./capture)
(cd "$PROJECT_DIR" && node <SKILL_DIR>/phases/design-system/scripts/build-design.mjs ./design-system --no-emit) # 路徑B:附加 --style <選擇的預設>
驗證(如果缺少任何東西,則停止並回報;如果 capture/BLOCKED.md 存在,表示網站封鎖了爬取——請按照其中的指示進行):
[ -`
…
[為翻譯而截斷]