---
name: video-from-script
description: 素材生产路由。根据用户意图分发到对应子技能：image-generator（生图）、capcut（成片）。支持单图和首尾帧两种视频模式。触发词：做视频、视频素材、生图+成片、图生视频、首尾帧。
---

# 素材生产路由

## 强制规则

1. **工作流不可跳步**：分镜（纯叙事）→ Prompt 生成（分镜+风格）→ Pipeline 执行。每阶段之间必须审查结果
2. **manifest.json 是唯一状态源**：任何操作（生图、上传、替换素材）完成后必须立即回写 manifest
3. **禁止 curl 调用生图/生视频 API**：必须通过 `pipeline.js` 或对应 generator 脚本执行
4. **并行优先**：多个独立子任务必须用子 agent 并行，不要在主对话中串行完成

**禁止**：跳过分镜 / 分镜阶段读风格 / 不更新 manifest 就继续 / 一口气跑完 pipeline 不审查

---

**你（主 Agent）是整个流程的导演。** 子 Agent 是执行者，你负责：理解意图、编排调度、质量卡点、用户沟通、错误恢复。

## 主 Agent 职责

| 职责 | 说明 |
|------|------|
| 意图理解 | 分析用户需求，选择正确的模式、视频模型和帧模式 |
| 编排调度 | 决定 Agent 串行/并行、传递参数、收集结果 |
| 质量卡点 | 每个阶段完成后校验结果，不合格则要求子 Agent 重做 |
| 用户沟通 | 汇报进度、请求用户决策（挑选图片、确认风格） |
| 错误恢复 | API 失败时重试或换模型，质量不达标时补生成 |

---

## 路由规则

| 用户意图 | 执行流程 | 子技能 |
|---------|---------|--------|
| "生图"、"批量图片" | 生图 | `image-generator` |
| "图片成片"、"图片轮播" | 已有图片 → 组装 | `capcut` |
| "图文成片"、"生图+成片" | 生图 → TTS+字幕+组装 | `image-generator` → `capcut` |
| "图生视频"、"图片转视频" | 生图 → AI视频 → 组装 | `image-generator` → Grok/VEO/Kling → `capcut` |
| "首尾帧"、"帧动画"、"关键帧" | 生图(成对) → 视频过渡 → 组装 | `image-generator`(帧对) → VEO/Kling → `capcut` |
| "文案转视频"、"配音视频" | 生图 → TTS+字幕+组装 | `image-generator` → `capcut` |
| 只说"做视频" | **询问**：图文成片 / 图生视频(单图/首尾帧)？ | — |

**"图生视频"的后续追问**：用户说"图生视频"时，追问视频模式：
- **单图模式**：一张图 → 一段视频（Grok / VEO / Kling）
- **首尾帧模式**：起始帧+结束帧 → 一段过渡视频（VEO / Kling）

---

## Pipeline 执行流程

Agent 创建 manifest.json 后，用 `pipeline.js` 分阶段执行。**不要一口气跑完，必须在阶段之间审查结果。**

### 分工

| 角色 | 职责 |
|------|------|
| **Agent**（你） | 读取 account.json + style.md → **分镜规划** → 从分镜生成 imagePrompt/videoPrompt → 写出 manifest.json → 审查每阶段结果 |
| **Pipeline** | 机械执行：生图 → 上传 → 生视频 → TTS → 成片。每完成一个 item 写盘，支持断点续跑 |

### 执行步骤

```
Step -1: 意图确认（进入任何步骤前必须完成，逐项确认，缺一不可）

  1. 内容意图：用户要做什么？
     - 生图 / 图生视频 / 图片成片 / 配音视频 / 首尾帧
     - 模糊时追问到明确，不要自己猜

  2. 素材来源：
     - 有现成文案/图片？还是需要 AI 生成文案？
     - 有参考图/风格参考？

  3. 视频模式（涉及视频时必问）：
     - 单图模式：1 张图 → 1 段视频（Grok / VEO / Kling）
     - 首尾帧模式：2 张图 → 过渡视频（VEO / Kling）

  4. 账号确认：
     - 扫描 accounts/*/account.json 获取最新账号列表
     - 展示：ID、名称、风格、画幅
     - 未指定 → 让用户选
     - 指定了但不匹配 → 告知可用账号，问是否新建
     - 确认后记住 account ID

  5. 参数确认：
     - 画幅（9:16 / 16:9）、生图模型（Gemini / MJ）、视频模型（VEO / Grok / Kling）
     - 有账号时从 account.json 继承默认值，只问是否覆盖

  → 以上 5 项全部确认后，agent 写出完整执行计划，让用户最终确认：

  执行计划示例（根据实际任务调整）：
  1. 读取 {account} 账号配置 + 风格文件（style.md）
  2. 根据用户文案生成分镜表（N shot）
  3. 分镜 + 风格 → 生成英文 prompts（imagePrompt + videoPrompt）
  4. pipeline.js init → 创建 manifest.json + 输出目录
  5. pipeline.js run --phase images → 生图 → 人工审查
  6. pipeline.js run --phase upload,videos → 上传 + 生成视频
  7. pipeline.js run --phase tts,assemble → TTS + 成片

  用户确认 "开始" → 进入 Step 0
  用户修改 → 调整计划后重新输出
  → 禁止在用户未确认执行计划的情况下进入 Step 0

Step 0: 前置检查（账号+风格校验）
  - 读取 accounts/{account}/account.json，检查 styles 字段是否配置了风格文件
  - 如果账号不存在或没有风格：
    → 暂停流程，通过 CLI 创建：`pipeline.js create-account --id <id> --name <名称> --references ./ref.png`
    → 然后编辑 `styles/*.md` 完善提示词策略
  - 校验账号完整性：`pipeline.js validate-account --account <id>`
  - 有风格则继续 Step 1

Step 1: 分镜规划（子 Agent 执行）
  - 主 Agent 将用户文案 + 约束交给子 Agent
  - 子 Agent 读取 references/storyboard-rules.md，按要求输出分镜表
  - 主 Agent 审查分镜表（景别交替、hook 设置、时长合理）
  - 展示给用户确认，确认后进入 Step 2

Step 2: Prompt 生成 + Manifest 初始化（分镜 + 风格 → 英文 prompts → pipeline.js init）
  - 输入：分镜表 + style.md + account.json
  - 子 Agent 将每个 shot 的中文画面描述结合风格文件，生成：
    · imagePrompt（英文画面描述，给 Gemini/MJ）
    · videoPrompt（英文运动描述，给 Grok/VEO/Kling）
    · keyword, keywordColor
  - **禁止 AI 手写 manifest.json**，必须通过脚本初始化：
    ```bash
    node pipeline.js init --account <id> --mode <single|framePair> \
      --items '[{"text":"文案","imagePrompt":"...","videoPrompt":"...","keyword":"关键词","keywordColor":"#FF6B35"}]'
    ```
  - 脚本自动从 account.json 继承：imageModel、videoModel、format、references
  - 脚本自动创建目录、校验必填字段、设置 status=pending
  - AI 只负责创意内容（text、imagePrompt、videoPrompt、keyword），不碰结构字段
  - 首尾帧模式额外要求：每个 item 必须有 `lastFramePrompt`（`imagePrompt` 作为第一帧，不需要单独的 `firstFramePrompt`）
  - init 返回 manifest 路径，后续命令使用该路径

Step 3: 生图 → 审查
  跑 images 阶段。完成后：
  - 用户指定"自行选图"→ Agent 自动检查数量对上文案数量就通过继续
  - 否则 → 暂停，等用户审查。不合格则删除/调 prompt 重跑，不进入下一步

  生图模型
  - 支持模型：gemini / mj / kling
  - 降级链：gemini → mj → kling → gemini（循环）
  - 触发：连续失败→ Agent 换下一个模型重跑失败项
  - 操作：`pipeline.js run --manifest <path> --phase images --retry-failed --image-model <新模型>`

Step 4: 上传 + 生视频（可选，图文成片跳过此步）
  跑 upload + videos 阶段。首尾帧模式检查过渡连贯性。

Step 5: TTS + 成片
  跑 tts + assemble 阶段。检查字幕准确、BGM 不盖配音。
```

> 命令语法见下方「CLI 参考」，不在此处重复。

### CLI 参考

```bash
# 创建账号（Step 0：首次使用时）
node pipeline.js create-account --id <id> --name <名称> \
  --desc <描述> --video-model veo3-fast --references ./ref1.png,./ref2.png

# 校验账号完整性
node pipeline.js validate-account --account <id>

# 初始化 manifest（Step 2 使用，AI 只提供创意内容）
node pipeline.js init --account <id> --mode <single|framePair> \
  --items '[{"text":"...","imagePrompt":"...","videoPrompt":"...","keyword":"...","keywordColor":"..."}]'
# 也可从文件读取 items（适合大量数据）
node pipeline.js init --account <id> --mode single --items-file ./items.json

# 校验 manifest 完整性
node pipeline.js validate --manifest <path>

# 跑指定阶段
node pipeline.js run --manifest <path> --phase images
node pipeline.js run --manifest <path> --phase upload,videos

# 断点续跑（跳过已完成阶段和 item）
node pipeline.js run --manifest <path> --resume

# 查看进度
node pipeline.js status --manifest <path>
```

**阶段**: `images` → `upload` → `videos` → `tts` → `assemble`

**Manifest item 状态**: `pending` → `generating` → `done` / `failed`。无 status 字段视为 pending。

---

## 视频模式对比

### 单图模式

```dot
digraph single_image {
  rankdir=LR
  node [shape=box, style=filled, fillcolor="#f5f5f5", fontsize=11]

  img [label="一张图", shape=oval]
  prompt [label="videoPrompt"]
  grok [label="Grok\n6s 视频", fillcolor="#fff3e0"]
  veo [label="VEO\n6-8s 视频", fillcolor="#e8f5e9"]
  kling [label="Kling\n6s 视频", fillcolor="#e1f5fe"]
  result [label="视频输出", shape=oval, fillcolor="#e3f2fd"]

  img -> prompt
  prompt -> grok
  prompt -> veo
  prompt -> kling
  grok -> result
  veo -> result
  kling -> result
}
```

- 每条文案生成 1 张图 + 1 个 videoPrompt
- Grok、VEO 和 Kling 都支持
- 提示词描述运动："slow zoom in on subject"

### 首尾帧模式

```dot
digraph frame_pair {
  rankdir=LR
  node [shape=box, style=filled, fillcolor="#f5f5f5", fontsize=11]

  first [label="起始帧"]
  last [label="结束帧"]
  prompt [label="videoPrompt"]
  veo [label="VEO\n6-8s 过渡视频", fillcolor="#e8f5e9"]
  kling [label="Kling\n6s 过渡视频", fillcolor="#e1f5fe"]
  result [label="视频输出", shape=oval, fillcolor="#e3f2fd"]

  first -> veo
  last -> veo
  prompt -> veo
  first -> kling
  last -> kling
  prompt -> kling
  veo -> result
  kling -> result
}
```

- 每条文案生成 **2 张图**（firstFrame + lastFrame）+ 1 个 videoPrompt
- **VEO 和 Kling 支持**（images 数组传两张图）
- 起始帧和结束帧必须是**同一场景的不同状态**
- 提示词描述过渡："transition from idle machines to active production"

| 对比 | 单图模式 | 首尾帧模式 |
|------|---------|-----------|
| 图片数量 | N 张 | 2N 张 |
| 生图耗时 | 标准 | ~2 倍（可并行） |
| 视频连贯性 | 仅运动 | 场景变化（更强） |
| 可用模型 | Grok + VEO + Kling | VEO + Kling |
| 适用场景 | 风景、人物展示 | 状态变化、叙事过渡 |

---

## 多阶段执行策略

用 Agent 工具串行或并行执行子技能，**阶段间必须通过质量卡点**：

**生图+成片（串行+人工卡点）**：
```dot
digraph image_then_assemble {
  rankdir=LR
  node [shape=box, style=filled, fillcolor="#f5f5f5", fontsize=11]

  agent1 [label="Agent 1\nimage-generator\n生成图片到 output/"]
  gate1 [label="人工卡点\n用户挑选图片\n删除不合格的", shape=diamond, fillcolor="#fff9c4"]
  agent2 [label="Agent 2\ncapcut\n读取精选素材 → 组装"]

  agent1 -> gate1 -> agent2
}
```

**配音+生图（并行+自动校验）**：
```dot
digraph parallel_image_tts {
  rankdir=LR
  node [shape=box, style=filled, fillcolor="#f5f5f5", fontsize=11]

  agent1 [label="Agent 1\nimage-generator\n生图", fillcolor="#e8f5e9"]
  agent2 [label="Agent 2\ncapcut\nTTS 配音", fillcolor="#e8f5e9"]
  validate [label="自动校验\n分辨率>=1024\n画幅匹配\n音频时长匹配", shape=diamond, fillcolor="#fff9c4"]
  agent3 [label="Agent 3\ncapcut\n组装全部素材 → 成片"]

  agent1 -> validate
  agent2 -> validate
  validate -> agent3
}
```

**图生视频 - 单图模式**：
```dot
digraph single_image_video {
  rankdir=LR
  node [shape=box, style=filled, fillcolor="#f5f5f5", fontsize=11]

  agent1 [label="Agent 1\nimage-generator\n生图 + videoPrompt"]
  gate1 [label="人工卡点\n用户挑选图片", shape=diamond, fillcolor="#fff9c4"]
  agent2 [label="Agent 2\nGrok / VEO / Kling\n单图输入，并行生成视频"]
  agent3 [label="Agent 3\ncapcut\n视频片段 + 字幕 → 成片"]

  agent1 -> gate1 -> agent2 -> agent3
}
```

**图生视频 - 首尾帧模式**：
```dot
digraph frame_pair_video {
  rankdir=LR
  node [shape=box, style=filled, fillcolor="#f5f5f5", fontsize=11]

  agent1 [label="Agent 1\nimage-generator\n成对生图\n(firstFrame + lastFrame)\n可并行"]
  gate1 [label="人工卡点\n检查首尾帧连贯性\n同一场景/相似视角", shape=diamond, fillcolor="#fff9c4"]
  agent2 [label="Agent 2\nVEO / Kling\n双图输入\nimages:[first, last]"]
  agent3 [label="Agent 3\ncapcut\n视频片段 + 字幕 → 成片"]

  agent1 -> gate1 -> agent2 -> agent3
}
```

**视频模型选择**：

| 模型 | 时长 | 画幅 | 单图 | 首尾帧 | 特点 | API |
|------|------|------|------|--------|------|-----|
| Grok | 6s | 任意 | ✅ | ❌ | 快、稳定 | yunwu.ai |
| Veo3-fast | ~8s | 16:9, 9:16 | ✅ | ✅ | 超分、中文增强 | jimmyai.cn |
| Veo3-fast-frames | ~8s | 16:9, 9:16 | ✅ | ✅ | 多帧、质量最高 | jimmyai.cn |
| Kling | 6s | 任意 | ✅ | ✅ | 快、首尾帧支持 | yunwu.ai |

图生视频注意事项：
- **并行执行**：先同时提交所有任务（并发 3），再并行轮询结果
- 单个视频生成耗时 60-300 秒
- 脚本内置 3 次重试，每次自动简化提示词
- **videoPrompt 在生图阶段一并生成**
- VEO 独有：`enhance_prompt=true` 中文增强，`enable_upsample=true` 超分
- 配置在 `config.json`

### 视频大小一致性

- **同批次同模型**，不混合 Grok（720P/6s）、VEO（超分/8s）和 Kling（6s）
- 画幅统一跟随 manifest 顶层 `format`（默认 `9:16`）
- 个别 item 降级到备用模型时，在 manifest 中标记 `"videoModel"` 以便追踪

### 视频生成失败降级

**降级链**: `Grok ↔ VEO ↔ Kling`

**触发**: 同一 item 重试 5 次仍失败 → 用备用模型单独补生成

```bash
# Grok 失败 → VEO/Kling 补
node veo-video-generator.js --image <url> --prompt <prompt> -o ./videos
node kling-video-generator.js --image <url> --prompt <prompt> -o ./videos

# VEO 失败 → Grok/Kling 补
node grok-video-generator.js --image <url> --prompt <prompt> -o ./videos
node kling-video-generator.js --image <url> --prompt <prompt> -o ./videos
```

**规则**: 逐 item 降级，不卡整批次。补完后上传 OSS，回写 `videoUrl`，继续 `tts → assemble`。

---

## 目录规范

所有批次的输出遵循统一目录结构。完整规范见 [batch-mode.md](../image-generator/references/batch-mode.md) 的"目录规范"章节。

**核心规则**：

```
output/{account}_{YYYYMMDD}_{NNN}/
├── manifest.json                # 主清单（贯穿全流程）
├── prompts.txt                  # 原始提示词存档
├── images/                      # scene_{NN}_{keyword}.jpeg（首尾帧加 _last 后缀）
├── videos/                      # scene_{NN}_{keyword}.mp4（与图片对应）
└── urls.json                    # OSS 公网 URL 映射
```

**命名对应关系**：图片 `scene_01_觉醒.jpeg` → 视频 `scene_01_觉醒.mp4`；首尾帧尾帧 `scene_01_觉醒_last.jpeg`；MJ 候选 `scene_01_觉醒_cand1.jpeg`

---

## manifest.json 格式

完整字段规范见 [manifest-schema.md](references/manifest-schema.md)（字段权重 P0/P1/P2、读写方、流转关系）。

**核心规则**：
- 脚本检测 `lastFrameUrl` → 首尾帧模式（传 images:[url, lastFrameUrl]）；否则 → 单图模式（传 images:[url]）
- 顶层 `format` 自动传给 VEO/Grok/Kling 作为画幅比例
- `account` 字段驱动 capcut_assemble 读取对应 account.json 的字幕风格配置

---

## 分镜规划规则

完整规则见 [storyboard-rules.md](references/storyboard-rules.md)。由子 Agent 读取并执行，主 Agent 只审查输出。

---

## 提示词生成规则

完整规则见 [prompt-rules.md](references/prompt-rules.md)。由子 Agent 读取并执行，主 Agent 审核提示词质量，不合格则退回重做。

---

## 质量卡点（跨阶段）

多阶段任务中，每个阶段完成后必须校验再进入下一阶段：

### 生图 → 成片 卡点

| 检查项 | 标准 | 不通过处理 |
|--------|------|-----------|
| 图片分辨率 | 短边 >= 1024px | 重新生成 |
| 画幅比例 | 与目标视频一致 (9:16/16:9) | 重新生成 |
| 图片内容 | 无水印、无文字、主体清晰 | 删除，人工补选 |
| 风格一致性 | 同批次风格统一 | 替换偏差大的图 |
| 数量 | 至少 3 张（< 3 张无法成片） | 补充生成 |

**首尾帧额外检查**：

| 检查项 | 标准 | 不通过处理 |
|--------|------|-----------|
| 场景一致性 | 首尾帧是同一场景 | 重新生成 lastFrame |
| 视角匹配 | 构图、角度、距离一致 | 重新生成不匹配的帧 |
| 状态过渡合理 | 结束帧是起始帧的自然延续 | 调整提示词重新生成 |

**自动校验脚本**（在 Agent 间插入）：
```bash
node .claude/skills/video-from-script/scripts/validate_assets.js \
  --dir ./output/batch_xxx \
  --min-resolution 1024 \
  --expected-ratio 9:16
```

### 配音 → 成片 卡点

| 检查项 | 标准 | 不通过处理 |
|--------|------|-----------|
| 音频时长 | 与素材总时长相近（±20%） | 调整语速或素材时长 |
| 音频质量 | 无静音段、无爆音 | 重新生成 |
| 音频数量 | 与素材数量匹配 | 补充或裁剪 |

### AI视频 → 成片 卡点

| 检查项 | 标准 | 不通过处理 |
|--------|------|-----------|
| 视频时长 | 每段 6-8 秒 | 正常，模型固定输出 |
| 视频画质 | 无明显伪影、无黑帧 | 重新生成 |
| 过渡连贯（首尾帧） | 视频从首帧平滑过渡到尾帧 | 优化提示词重试 |
| 视频数量 | 与素材数量匹配 | 补充生成失败的视频 |

### 成片输出 卡点

| 检查项 | 标准 |
|--------|------|
| 字幕准确 | 与原始文案一一对应 |
| 关键词高亮 | 颜色醒目、位置正确 |
| 图片动画 | Ken Burns 流畅无卡顿 |
| BGM 音量 | 不盖过配音（配音为主） |
| 转场 | 无黑帧、无跳帧 |

**任何卡点不通过，必须修复后再进入下一阶段，不可跳过。**

---

## 共享资源

所有子技能共享以下资源（位于本目录）：

- `scripts/` — 共享脚本（gemini-image-generator.js, mj-image-generator.js, grok-video-generator.js, veo-video-generator.js, capcut_assemble.js, sync-to-jianying.js, oss-upload.js）
- `accounts/` — 账号配置（详见 [account-system.md](references/account-system.md)）
- `references/account-system.md` — 账号系统说明

配置统一在 `skills/config.json`（API密钥、路径）。

---

## 子技能

| 技能 | 触发词 | 职责 |
|------|--------|------|
| `image-generator` | 生图、批量出图、MJ、Gemini | 图片生成（双模型、单图/帧对） |
| `capcut` | 成片、组装、剪映、图片轮播 | CapCut 成片组装 |