lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

mkt-full-video-with-11-hyperframe-heygen

端到端编排器：脚本 → 最终的 TikTok/Reels 9:16 MP4。

管线包含 2 个用户检查点：

1. MP3 检查点（编排器）——第一阶段后，用户试听配音。
2. 场景大纲检查点（第三阶段子 Agent）——用户查看场景结构及变体，然后才能展开内容编写。如果用户传递了 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 字符 → 按语义拆分后，对每个片段分别调用管线

管线概览

Script (text + optional b-roll + tts_provider)
    │
    ▼
Phase 1 ── TTS (elevenlabs | minimax) ──► voiceover.mp3
    │                                         │
    │                                         ▼
    │                              CHECKPOINT #1 — user nghe + duyệt MP3
    │                                         │
    │                                         ▼ (OK)
Phase 2 ── heygen-mp3-to-mp4 ──────────► source.mp4 (9:16 lip-sync)
    │
    ▼
Phase 3 ── spawn agent mkt-full-video-phase3-packager (isolated context)
            │
            ├─ transcribe + clean + group captions
            ├─ detect scene boundaries + classify mockup_variant
            ├─ CHECKPOINT #2 — user duyệt scenes outline
            ├─ FAN-OUT N general-purpose sub-agents (1 per scene) parallel
            │   → mỗi sub-agent build content JSON theo variant schema
            ├─ merge → scenes.json
            ├─ parallel: scaffold sub-comps + copy SFX + inject captions
            ├─ generate root index.html
            └─ lint + preview Studio
    │
    ▼
User duyệt preview → "render" → final MP4

检查点规则： 编排器管理检查点 #1（MP3）。第二阶段 → 第三阶段自动运行。检查点 #2（场景大纲）由第三阶段子 Agent 管理。最终渲染门控在 Studio。

输入

输入	必填	格式 / 示例
脚本文本	是	文件路径 (.txt/.md) 或内联字符串。 ≤ 5000 字符。
项目 Slug	否	自动从脚本前 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}。
头像外观	否	1 个从 HEYGEN_AVATAR_LOOKS 环境变量（.env，逗号分隔）中获取的 ID。如果未选择则随机。
auto_scenes	否	默认 false。设为 true 可跳过第三阶段的场景大纲检查点。

工作区布局

workspace/content/YYYY-MM-DD/<slug>/
├── script.txt              # Phase 0
├── voiceover.mp3           # Phase 1
├── source.mp4              # Phase 2
├── broll/                  # User-provided b-roll (copy)
├── transcript.json         # Phase 3
├── caption-groups.json     # Phase 3
├── scenes-outline.json     # Phase 3 — pre-checkpoint outline
├── scenes/                 # Phase 3 — fan-out per-scene content writes here
│   ├── scene-1.json
│   └── ...
├── scenes.json             # Phase 3 — merged final
├── compositions/           # Phase 3 — HF sub-comps
├── sfx/                    # Phase 3 — 6 SFX
└── index.html              # Phase 3 — root composition

YYYY-MM-DD = 今天（UTC+7）。

工作流

第 0 步 — 设置

1. 验证 len(script_text) <= 5000。如果超出 → 停止，要求用户进行语义拆分。
2. 如果缺少 slug 则派生：前 5 个单词 → 小写 → 去重音 → 空格转中划线。
3. 解析 TTS 提供商 — 从用户输入读取 tts_provider（默认 elevenlabs）。如果用户说“用 minimax”/“切换到 minimax” → minimax。如果用户说“用 eleven”/“elevenlabs” → elevenlabs。验证对应的 API 密钥是否在 .env 中：
   • elevenlabs → 需要 ELEVENLABS_API_KEY（可选 ELEVENLABS_VOICE_ID 以覆盖默认的 K7ewtjKRNtwwt3lKQ6M0）。
   • minimax → 需要 MINIMAX_API_KEY（可选 MINIMAX_VOICE_ID 以覆盖默认的 moss_audio_c56d6120-ef9c-11f0-9649-8ee40147f116）。 缺少密钥 → 停止，通知用户将其添加到 .env。
4. 创建 workspace/content/YYYY-MM-DD/<slug>/。保存 script.txt。
5. 如果用户有 B-roll：创建 <folder>/broll/，复制文件，保持原名。
6. 通知用户：“工作区已创建在 <folder>。TTS 提供商：<elevenlabs|minimax>。开始第一阶段。”

第 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，以便第二阶段（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 Brand Voice của Hoàng (K7ewtjKRNtwwt3lKQ6M0)>` 或 `<MiniMax speech-2.8-hd (moss_audio_…)>`（如果用户覆盖，则从 `.env` 中获取语音 ID）

打开文件试听。回复下列之一：
- **`OK`** / **`继续`** → 我将运行第二阶段（HeyGen 头像唇形同步）
- **`重新生成`** + （可选）原因 → 我将调整语音设置并重新生成 MP3
- **`修改脚本`** + 新内容 → 我将保存新脚本并重新运行第一阶段

停止工具调用。 等待用户明确回复。

当用户回复 OK → 进入第二阶段。 当用户回复 重新生成 → 使用新设置重新运行当前提供商的 TTS 脚本，返回检查点。如果用户说“切换到 minimax”/“试试 eleven” → 交换 tts_provider，重新运行第一阶段。 当用户修改脚本 → 覆盖 script.txt，从头重新运行第一阶段（使用相同提供商）。

第 3 步 — 第二阶段：MP3 → HeyGen MP4（自动）

根据子技能 heygen-mp3-to-mp4：

1. 选择头像 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 前通知用户选择。

2. 上传 MP3 到 HeyGen 通过 MCP（upload_asset，资产类型 audio）。不要使用 curl 到 https://upload.heygen.com/...。

3. 创建头像视频 通过 MCP（generate_avatar_video）：

   character: { type: avatar, avatar_id: <picked>, scale: 1.0 }
   voice:     { type: audio, audio_asset_id: <from upload> }
   dimension: { width: 720, height: 1280 }   # 9:16
   title:     "<slug>-<timestamp>"
   

4. 轮询状态 每隔约 10 秒 → completed（最长 10 分钟）。failed → 停止，显示错误。

5. 下载 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"
   

6. 通知用户一行：“第二阶段完成 — <path>（头像 <id>， 秒， MB）。正在生成第三阶段打包器…”

这里不停止。 自动流转到第三阶段。

第 4 步 — 第三阶段：生成打包器子 Agent

使用 Task 工具，设置 subagent_type: "mkt-full-video-phase3-packager"。传递一个自包含的提示，包含 Agent 所需的输入。示例：

Workspace: workspace/content/2026-05-03/hom-nay-minh-chia-se/
Slug: hom-nay-minh-chia-se
Script: <full script text>
B-roll: [
  {"path": "workspace/content/2026-05-03/hom-nay-minh-chia-se/broll/alphabet.png", "purpose": "Bài học 1"},
  ...
]
auto_scenes: false
header_label: "3 BÀI HỌC AI"
footer_handle: "@tranvanhoang.com"

Run the full Phase 3 packaging pipeline per your agent definition. Return Studio URL when preview is open.

子 Agent 会：

• 转写 source.mp4，构建场景大纲
• 除非 auto_scenes: true，否则停下来询问用户批准大纲（检查点 #2）
• 并行派发 N 个场景内容编写者
• 合并 + 脚手架 + 代码检查 + 打开预览
• 返回 Studio URL

当子 Agent 正在运行时，编排器唯一的工作是将用户的回复转发给子 Agent（场景大纲检查点处的用户回复将出现在此对话中；如果子 Agent 仍处于活动状态，则将其路由给子 Agent；否则将其视为后续指令）。

第 5 步 — 移交

当子 Agent 返回 Studio URL 时，格式化最终报告：

## 完整视频管线完成 — 预览已就绪

**工作区：** `workspace/content/YYYY-MM-DD/<slug>/`

**第一阶段（`<elevenlabs|minimax>`）：** voiceover.mp3 — <D1> 秒，<S1> MB（语音 ID `<id>`）
**第二阶段（HeyGen）：** source.mp4 — 头像 `<avatar_id>`，<D2> 秒，<S2> MB
**第三阶段（HyperFrames）：** <N> 个场景（<列出变体>），<K> 个字幕组，6 个音效

**Studio URL：** http://localhost:3002

打开浏览器浏览时间线。确认后说 **`渲染`** → 我将运行 `npx hyperframes render` 输出 1080×1920 30fps 的 MP4。

在此停止。 不要自动渲染。用户确认后才调用 npx hyperframes render。

关键编排规则

1. 2 个用户检查点，1 个编排器门控 — 编排器仅在 MP3 处停止（第 2 步）。场景大纲检查点由第三阶段子 Agent 管理。渲染门控在 Studio，由用户控制。

2. 路径约定不可更改 — 配音必须命名为 voiceover.mp3，说话头视频必须命名为 source.mp4。HF 子技能期望文件名 source.mp4。

3. 仅使用 HeyGen MCP — 永远不要 curl https://api.heygen.com/...。这是 heygen-mp3-to-mp4 的硬性约束。

4. 语音 ID 存储在 .env 中，不硬编码在技能里。 ElevenLabs 读取 ELEVENLABS_VOICE_ID（回退 K7ewtjKRNtwwt3lKQ6M0）。MiniMax 读取 MINIMAX_VOICE_ID（回退 moss_audio_…）。每次调用可通过 --voice_id 覆盖。管线在第 0 步和检查点 #1 时明确报告已选择的提供商和语音 ID。

5. 脚本长度硬上限 5000 字符 — 在第 0.1 步快速失败。

6. MP3 时长 ≤ 300 秒 — HeyGen 单视频时长上限。在第一阶段后立即检查。

7. 预览优先 — 第三阶段不要自动渲染。记忆 feedback_hyperframes_workflow.md。

8. 第三阶段隔离 — 第三阶段在独立的子 Agent 上下文中运行。HF 技能主体和 4 个参考文档（约 40KB）加载到子 Agent 中，而不是主编排器。

故障模式与备用方案

症状	操作
脚本 > 5000 字符	停止，要求用户进行语义拆分
ElevenLabs API 失败	报告错误，建议检查 .env 中的 ELEVENLABS_API_KEY（可选 ELEVENLABS_VOICE_ID）。或者切换到 tts_provider=minimax 重新运行第一阶段
MiniMax API 失败	报告错误，建议检查 .env 中的 MINIMAX_API_KEY（可选 MINIMAX_VOICE_ID）。或者切换到 tts_provider=elevenlabs 重新运行第一阶段
MP3 > 300 秒（第一阶段后）	停止管线，建议使用 heygen-short-video（分块）
HeyGen MCP 未连接	停止，提示运行 claude mcp list 进行验证
HeyGen 渲染失败	显示错误，建议通过 mcp__heygen__get_current_user 检查配额
第三阶段子 Agent 失败	读取错误跟踪，建议用户使用 mkt-hyperframe-talking-head-video 技能单独重新运行第三阶段
场景编写者返回格式错误的 JSON	子 Agent 自动为该场景重新生成（不归编排器处理）
用户拒绝 MP3 语音	返回第一阶段，调整语音设置

端到端示例

用户：

我有一个脚本，运行完整管线生成 TikTok 视频。附带 2 张第 1 课和第 2 课的 B-roll 图片。 脚本：“今天我要分享来自 Anthropic 的 3 课。第一课是 Alphabet ship beta。第二课是 24h…” B-roll: alphabet.png（第 1 课），clock.png（第 2 课）

管线：

1. 第 0 步 — slug hom-nay-minh-chia-se。文件夹 workspace/content/2026-05-03/hom-nay-minh-chia-se/。保存 script.txt，复制 B-roll。
2. 第 1 步 — text_to_mp3.py → voiceover.mp3（45 秒，0.7 MB）。
3. 第 2 步 — 检查点 #1 — 通知用户路径和时长。等待回复。
4. 用户：OK。
5. 第 3 步 — 选择头像（从 HEYGEN_AVATAR_LOOKS 中随机，例如 66e75e22…）。上传 MP3 → asset_id。生成视频 → 轮询 → 下载 source.mp4（45 秒，7.5 MB）。
6. 第 4 步 — 生成 mkt-full-video-phase3-packager 子 Agent。
7. 子 Agent 转写（35 秒），构建大纲（3 课 + 总结 + CTA），显示大纲 → 检查点 #2。
8. 用户：OK。
9. 子 Agent 并行派发 5 个场景编写者（墙钟时间约 8 秒 vs 串行约 40 秒）。
10. 子 Agent 合并 → scenes.json → 脚手架 + 音效 + 字幕并行

…

[为翻译进行了截断]