mkt-full-video-with-11-hyperframe-heygen
端到端協調器：腳本 → 最終 TikTok/Reels MP4 9:16。
管線包含 2 個使用者檢查點：
- MP3 檢查點（協調器）— 在第 1 階段後，使用者審核旁白。
- 場景大綱檢查點（第 3 階段子代理）— 使用者在扇出內容編寫者之前，審核場景結構和變體。如果使用者傳入
auto_scenes=true，則可跳過。
使用時機
- 使用者有少於或等於 5000 個字元的越南文/英文腳本，並希望產出完整的 TikTok 影片
- 有（可選的）圖片或影片 B-Roll 及其使用目的
- 希望從腳本一路完成到 Studio 預覽
請勿在以下情況使用此技能：
- 使用者已有 MP3 → 直接使用
heygen-mp3-to-mp4 - 使用者已有說話頭部 MP4 → 直接使用
mkt-hyperframe-talking-head-video - 使用者需要 HeyGen 自行朗讀文字（不經由 ElevenLabs）→ 使用
heygen-script-to-mp4 - 腳本超過 5000 個字元 → 以語義進行分割，然後為每個區段調用管線
管線概覽
腳本（文字 + 可選 B-Roll + tts_provider）
│
▼
第 1 階段 ── TTS (elevenlabs | minimax) ──► voiceover.mp3
│ │
│ ▼
│ 檢查點 #1 — 使用者聆聽並批准 MP3
│ │
│ ▼ (確定)
第 2 階段 ── heygen-mp3-to-mp4 ──────────► source.mp4 (9:16 嘴型同步)
│
▼
第 3 階段 ── 生成代理 mkt-full-video-phase3-packager（隔離環境）
│
├─ 轉錄 + 清理 + 分組字幕
├─ 偵測場景邊界 + 分類 mockup_variant
├─ 檢查點 #2 — 使用者審核場景大綱
├─ 扇出 N 個通用子代理（每個場景一個）並行
│ → 每個子代理根據變體模式建立內容 JSON
├─ 合併 → scenes.json
├─ 並行：搭建子組件 + 複製音效 + 注入字幕
├─ 生成根目錄 index.html
└─ 語法檢查 + 預覽 Studio
│
▼
使用者審核預覽 → "渲染" → 最終 MP4
檢查點規則： 協調器管理檢查點 #1 (MP3)。第 2 階段 → 第 3 階段自動執行。檢查點 #2（場景大綱）由第 3 階段子代理管理。最終的渲染閘門在 Studio。
輸入
| 輸入 | 必要 | 格式 / 範例 |
|---|---|---|
| 腳本文字 | 是 | 檔案路徑 (.txt/.md) 或內嵌字串。少於或等於 5000 個字元。 |
| 專案 Sluf | 否 | 自動從腳本前 5 個字衍生。小寫、ASCII、連字號。 |
| B-Roll 列表 | 否 | 陣列 [{path: "...", purpose: "課程 1 — 說明 X"}, ...]。 |
tts_provider | 否 | elevenlabs（預設 — Hoàng 的聲音，富有表現力）或 minimax（speech-2.8-hd，較便宜，越南語更自然）。使用者說「用 minimax」/「用 eleven」→ 據此設定。 |
| 語音 ID 覆蓋 | 否 | 覆蓋 .env 的預設值。ElevenLabs 讀取 ELEVENLABS_VOICE_ID，MiniMax 讀取 MINIMAX_VOICE_ID。CLI 標誌 --voice_id 同時適用於兩者。 |
| 語音設定覆蓋 | 否 | ElevenLabs：{stability, similarity_boost, style}。MiniMax：{speed, vol, pitch}。 |
| 虛擬角色外觀 | 否 | 從 HEYGEN_AVATAR_LOOKS 環境變數中取一個 ID（.env 檔案，以逗號分隔）。如果未選擇，則隨機選取。 |
auto_scenes | 否 | 預設 false。設為 true 可跳過第 3 階段的場景大綱檢查點。 |
工作區佈局
workspace/content/YYYY-MM-DD/<slug>/
├── script.txt # 第 0 階段
├── voiceover.mp3 # 第 1 階段
├── source.mp4 # 第 2 階段
├── broll/ # 使用者提供的 B-Roll（複製）
├── transcript.json # 第 3 階段
├── caption-groups.json # 第 3 階段
├── scenes-outline.json # 第 3 階段 — 檢查點前的大綱
├── scenes/ # 第 3 階段 — 每個場景的扇出內容在此寫入
│ ├── scene-1.json
│ └── ...
├── scenes.json # 第 3 階段 — 合併後的最終版本
├── compositions/ # 第 3 階段 — HF 子組件
├── sfx/ # 第 3 階段 — 6 個音效
└── index.html # 第 3 階段 — 根組件
YYYY-MM-DD = 今天日期 (UTC+7)。
工作流程
步驟 0 — 設定
- 驗證
len(script_text) <= 5000。超過 → 停止，要求使用者以語義分割。 - 如果缺少 Slug，則衍生：取前 5 個字 → 轉小寫 → 移除變音符號 → 空格轉連字號。
- 解析 TTS 提供者 — 從使用者輸入讀取
tts_provider（預設elevenlabs）。如果使用者說「用 minimax」/「換成 minimax」→minimax。如果使用者說「用 eleven」/「elevenlabs」→elevenlabs。驗證.env中是否存在對應的 API 金鑰：elevenlabs→ 需要ELEVENLABS_API_KEY（可選ELEVENLABS_VOICE_ID來覆蓋預設值K7ewtjKRNtwwt3lKQ6M0）。minimax→ 需要MINIMAX_API_KEY（可選MINIMAX_VOICE_ID來覆蓋預設值moss_audio_c56d6120-ef9c-11f0-9649-8ee40147f116）。 缺少金鑰 → 停止，通知使用者將其加入.env。
- 建立
workspace/content/YYYY-MM-DD/<slug>/。儲存script.txt。 - 如果使用者有 B-Roll：建立
<folder>/broll/，複製檔案並保留原始檔名。 - 通知使用者：「工作區已建立在
<folder>。TTS 提供者：<elevenlabs|minimax>。開始第 1 階段。」
步驟 1 — 第 1 階段：腳本 → MP3 (TTS)
根據 tts_provider 執行恰好一個分支：
分支 A — ElevenLabs（預設）：
uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
--file workspace/content/YYYY-MM-DD/<slug>/script.txt \
-o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3
語音 ID：自動從 .env 讀取 ELEVENLABS_VOICE_ID（若無則使用預設的 Hoàng 品牌聲音）。CLI 覆蓋：--voice_id <id>。
語音設定：如果使用者要求調整，則加入 --stability / --similarity_boost / --style。
分支 B — MiniMax：
uv run .claude/skills/mkt-video-script-to-mp3/scripts/text_to_mp3.py \
--file workspace/content/YYYY-MM-DD/<slug>/script.txt \
-o workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3
語音 ID：自動從 .env 讀取 MINIMAX_VOICE_ID（若無則使用預設值 moss_audio_…）。CLI 覆蓋：--voice_id <id>。
語音設定：--speed（預設 1.08）、--vol、--pitch、--language_boost Vietnamese。
輸出檔名不可變更：兩個分支皆為 voiceover.mp3，以便第 2 階段 (HeyGen) 找到正確路徑。
完成後，檢查時長（兩個提供者通用）：
uv run .claude/skills/heygen-mp3-to-mp4/scripts/check_duration.py \
workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3
TOO_LONG → 停止，通知使用者 MP3 超過 HeyGen 的 5 分鐘限制，要求精簡腳本。
步驟 2 — 檢查點 #1：使用者聆聽 MP3
由協調器管理的唯一停止點。 以如下格式通知使用者：
## 旁白準備就緒 — 請幫助審核
**檔案：** `workspace/content/YYYY-MM-DD/<slug>/voiceover.mp3`
**時長：** <X.X> 秒
**大小：** <Y.Y> MB
**提供者：** <`elevenlabs` | `minimax`>
**語音：** <`ElevenLabs 品牌聲音 - Hoàng (K7ewtjKRNtwwt3lKQ6M0)`> 或 <`MiniMax speech-2.8-hd (moss_audio_…)`>（如果使用者覆蓋，則從 `.env` 的語音 ID 取得）
請開啟檔案試聽。回覆下列其中一項：
- **`OK`** / **`繼續`** → 我將執行第 2 階段 (HeyGen 虛擬角色嘴型同步)
- **`重新生成`** +（可選）原因 → 我將調整語音設定並重新生成 MP3
- **`修改腳本`** + 新內容 → 我將儲存新腳本並重新執行第 1 階段
停止工具呼叫。 等待使用者明確回覆。
當使用者說 OK → 執行第 2 階段。
當使用者說 重新生成 → 以新的設定重新執行目前提供者的 TTS 腳本，返回檢查點。如果使用者說「換成 minimax」/「試試 eleven」→ 切換 tts_provider，重新執行第 1 階段。
當使用者修改腳本 → 覆寫 script.txt，從頭開始重新執行第 1 階段（使用相同提供者）。
步驟 3 — 第 2 階段：MP3 → HeyGen MP4（自動）
根據子技能 heygen-mp3-to-mp4：
-
選擇虛擬角色 ID — 從
.env讀取HEYGEN_AVATAR_LOOKS（逗號分隔），如果使用者未指定則隨機選取：HEYGEN_AVATAR_LOOKS=$(grep '^HEYGEN_AVATAR_LOOKS=' .env | cut -d'=' -f2- | tr -d '"' | tr -d "'") echo "$HEYGEN_AVATAR_LOOKS" | tr ',' '\n' | awk 'BEGIN{srand()} {a[NR]=$0} END{print a[int(rand()*NR)+1]}'如果環境變數缺失/為空 → 停止並通知使用者將
HEYGEN_AVATAR_LOOKS=<id1>,<id2>加入.env。在呼叫 MCP 前通知使用者選擇哪個。 -
上傳 MP3 到 HeyGen（透過 MCP
upload_asset，資產類型audio）。不要使用curl https://upload.heygen.com/...。 -
建立虛擬角色影片（透過 MCP
generate_avatar_video）：character: { type: avatar, avatar_id: <選擇的>, scale: 1.0 } voice: { type: audio, audio_asset_id: <上傳結果> } dimension: { width: 720, height: 1280 } # 9:16 title: "<slug>-<時間戳記>" -
輪詢狀態 每約 10 秒 →
completed（最多 10 分鐘）。failed→ 停止，顯示錯誤。 -
下載 MP4 →
workspace/content/YYYY-MM-DD/<slug>/source.mp4（檔名不可變更）：uv run .claude/skills/heygen-mp3-to-mp4/scripts/download_video.py \ "<video_url>" "workspace/content/YYYY-MM-DD/<slug>/source.mp4" -
通知使用者一行：「第 2 階段完成 —
<路徑>（虛擬角色<id>，<時長> 秒，<大小> MB）。正在生成第 3 階段的封裝器…」
此處不停止。 自動進入第 3 階段。
步驟 4 — 第 3 階段：生成封裝器子代理
使用 Task 工具，設置 subagent_type: "mkt-full-video-phase3-packager"。傳遞一個包含子代理所需輸入的獨立提示。範例：
工作區：workspace/content/2026-05-03/hom-nay-minh-chia-se/
Slug：hom-nay-minh-chia-se
腳本：<完整腳本文字>
B-Roll：[
{"path": "workspace/content/2026-05-03/hom-nay-minh-chia-se/broll/alphabet.png", "purpose": "課程 1"},
...
]
auto_scenes：false
header_label："3 個 AI 課程"
footer_handle："@tranvanhoang.com"
根據您的代理定義執行完整的第 3 階段封裝管線。預覽開啟時回傳 Studio URL。
子代理：
- 轉錄
source.mp4，建立場景大綱 - 除非
auto_scenes: true，否則停止要求使用者批准大綱（檢查點 #2） - 並行扇出 N 個場景內容編寫者
- 合併 + 框架組裝 + 語法檢查 + 開啟預覽
- 回傳 Studio URL
當子代理運行時，協調器的唯一工作是將使用者回覆轉發給子代理（場景大綱檢查點的使用者回覆將到達此對話；如果子代理仍在活動，則將其路由到子代理，否則視為後續指示）。
步驟 5 — 交接
當子代理回傳 Studio URL 時，格式化最終報告：
## 完整影片管線完成 — 預覽已就緒
**工作區：** `workspace/content/YYYY-MM-DD/<slug>/`
**第 1 階段 (`<elevenlabs|minimax>`):** voiceover.mp3 — <D1> 秒, <S1> MB（語音 ID `<id>`）
**第 2 階段 (HeyGen):** source.mp4 — 虛擬角色 `<avatar_id>`, <D2> 秒, <S2> MB
**第 3 階段 (HyperFrames):** <N> 個場景（<列出變體>）, <K> 個字幕組, 6 個音效
**Studio URL:** http://localhost:3002
請開啟瀏覽器查看時間軸。當一切沒問題時，說 **`渲染`** → 我將執行 `npx hyperframes render` 輸出 1080×1920 30fps 的 MP4。
此處停止。 不要自動渲染。使用者確認後才呼叫 npx hyperframes render。
關鍵協調規則
-
2 個使用者檢查點，1 個協調器閘門 — 協調器僅在第 2 步驟 (MP3) 停止。場景大綱檢查點由第 3 階段子代理管理。渲染閘門在使用者端的 Studio。
-
路徑約定不可變更 — 旁白必須是
voiceover.mp3，說話頭部必須是source.mp4。HF 子技能預期檔名source.mp4。 -
僅限 HeyGen MCP — 絕不要使用
curl https://api.heygen.com/...。這是heygen-mp3-to-mp4的硬性限制。 -
語音 ID 儲存在
.env，而非硬編碼在技能中。 ElevenLabs 讀取ELEVENLABS_VOICE_ID（若無則使用K7ewtjKRNtwwt3lKQ6M0）。MiniMax 讀取MINIMAX_VOICE_ID（若無則使用moss_audio_…）。每次呼叫可透過--voice_id覆蓋。管線在第 0 步驟和檢查點 #1 明確報告已選擇的提供者和語音 ID。 -
腳本長度硬上限 5000 個字元 — 在第 0 步驟迅速失敗。
-
MP3 時長少於或等於 300 秒 — HeyGen 單一影片上限。第 1 階段後立即檢查。
-
預覽優先 — 第 3 階段 不會 自動渲染。請參考
feedback_hyperframes_workflow.md。 -
第 3 階段隔離 — 第 3 階段在獨立的子代理環境中運行。HF 技能主體 + 4 個參考文件（約 40KB）會載入到子代理，而非主協調器中。
失敗模式與備援方案
| 症狀 | 處理方式 |
|---|---|
| 腳本 > 5000 個字元 | 停止，要求使用者以語義分割 |
| ElevenLabs API 失敗 | 報告錯誤，建議檢查 .env 中的 ELEVENLABS_API_KEY（可選 ELEVENLABS_VOICE_ID）。或切換至 tts_provider=minimax 重新執行第 1 階段 |
| MiniMax API 失敗 | 報告錯誤，建議檢查 .env 中的 MINIMAX_API_KEY（可選 MINIMAX_VOICE_ID）。或切換至 tts_provider=elevenlabs 重新執行第 1 階段 |
| MP3 在第 1 階段後 > 300 秒 | 停止管線，建議使用 heygen-short-video（分段處理） |
| HeyGen MCP 未連接 | 停止，通知執行 claude mcp list 以驗證 |
| HeyGen 渲染失敗 | 顯示錯誤，建議透過 mcp__heygen__get_current_user 檢查額度 |
| 第 3 階段子代理失敗 | 讀取錯誤追蹤，建議使用者使用 mkt-hyperframe-talking-head-video 技能單獨重新執行第 3 階段 |
| 場景編寫者回傳格式錯誤的 JSON | 子代理會自動為該場景重新生成（非協調器需處理的問題） |
| 使用者否決 MP3 語音 | 返回第 1 階段並調整語音設定 |
端到端範例
使用者：
這裡有腳本，執行完整管線產出 TikTok 影片。附上 2 張 B-Roll 圖片，用於課程 1 和課程 2。 腳本：「Hôm nay mình chia sẻ 3 bài học từ Anthropic. Bài học đầu tiên là Alphabet ship beta. Bài học thứ 2 là 24h…」 B-Roll：alphabet.png（課程 1），clock.png（課程 2）
管線：
- 步驟 0 — slug
hom-nay-minh-chia-se。資料夾workspace/content/2026-05-03/hom-nay-minh-chia-se/。儲存script.txt，複製 B-Roll。 - 步驟 1 —
text_to_mp3.py→voiceover.mp3（45 秒, 0.7MB）。 - 步驟 2 — 檢查點 #1 — 通知使用者路徑和時長。等待回覆。
- 使用者：
OK。 - 步驟 3 — 選擇虛擬角色（從
HEYGEN_AVATAR_LOOKS隨機選取，例如66e75e22…）。上傳 MP3 → asset_id。生成影片 → 輪詢 → 下載source.mp4（45 秒, 7.5MB）。 - 步驟 4 — 生成
mkt-full-video-phase3-packager子代理。 - 子代理轉錄（35 秒），建立大綱（3 個課程 + 回顧 + 結尾行動呼籲），顯示大綱 → 檢查點 #2。
- 使用者：
OK。 - 子代理並行扇出 5 個場景編寫者（約 8 秒牆壁時間 vs 約 40 秒序列化）。
- 子代理合併 → scenes.json → 框架組裝 + 音效 + 字幕
…
[為翻譯而截斷]