video-create/.claude/skills/video-from-script/SKILL.md

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

# 素材生产路由

## 强制规则

1. **工作流不可跳步**：分镜 → 图片提示词 → 生图 → 视频提示词 → 生视频 → TTS+成片。每阶段之间必须审查结果
2. **manifest.json 是唯一状态源**：任何操作（生图、上传、替换素材）完成后必须立即回写 manifest
3. **禁止 curl 调用生图/生视频 API**：必须通过 `pipeline.js` 或对应 generator 脚本执行
4. **并行优先**：多个独立子任务必须用子 agent 并行，不要在主对话中串行完成
5. **prompts/*.md 只被子 Agent 读取**：主 Agent 读 account.json 获取配置信息，不读子 Agent 提示词模板

**禁止**：跳过分镜 / 不更新 manifest 就继续 / 一口气跑完 pipeline 不审查 / 主 Agent 替代子 Agent 生成提示词

---

**你（主 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` |
| "创建账号"、"新账号" | Q&A 收集信息 → 生成 prompts | 见 [account-creation.md](references/account-creation.md) |
| "修改账号"、"改提示词"、"换风格" | 读取现有 prompt → 确认修改范围 → 重写 | 直接编辑 prompts/*.md |
| 只说"做视频" | **询问**：图文成片 / 图生视频(单图/首尾帧)？ | — |

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

---

## Pipeline 执行流程

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

### 分工

| 角色 | 职责 |
|------|------|
| **Agent**（你） | 读取 account.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} 账号配置（id = 目录名）
  2. 子 Agent 读取 prompts/分镜.md → 根据用户文案生成分镜表（N shot）
  3. 子 Agent 读取 prompts/图片提示词.md → 为每个 shot 生成 imagePrompt
  4. pipeline.js init → 创建 manifest.json + 输出目录
  5. pipeline.js run --phase images → 生图 → 人工审查确认（可选）
  6. 子 Agent 读取 prompts/视频提示词.md → 为每个 shot 生成 videoPrompt
  7. pipeline.js run --phase upload,videos → 上传 + 生成视频
  8. pipeline.js run --phase tts,assemble → TTS + 成片

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

Step 0: 前置检查（账号+提示词模板校验）
  - 读取 根目录 accounts/{account}/account.json
  - 检查 prompts/ 目录下的提示词模板是否存在（分镜.md、图片提示词.md、视频提示词.md）
  - 如果账号不存在或缺少模板：
    → 按 [account-creation.md](references/account-creation.md) 的 Q&A 流程创建账号
    → 基于通用模板（`_template/prompts/`）+ 用户回答生成 3 个 prompt 文件
  - 校验账号完整性：`pipeline.js validate-account --account <id>`
  - 全部就绪则继续 Step 1

Step 1: 分镜脚本生成（子 Agent 执行）
  - 读取 account.json 中的 storyboardPrompt 字段，定位分镜模板文件（如 prompts/分镜.md）
  - 主 Agent 将用户文案 + 模板交给子 Agent
  - 子 Agent 按模板要求输出分镜表 JSON：
    ```json
    [{"id":1,"shotDesc":"英文画面描述，40-80词","script":"中文口播文案，≤22字","duration":5,"directorRef":"tarantino"}]
    ```
  - 主 Agent 审查分镜表（时长合理、隐性动势完整、directorRef 已填）
  - 展示给用户确认，确认后进入 Step 2-A

Step 2-A: 生成图片提示词（子 Agent 执行）
  - 读取 account.json 中的 imageStylePrompt 字段，定位图片提示词模板（如 prompts/图片提示词.md）
  - 子 Agent 为每个 shot 生成 imagePrompt：
    - 入参：shotDesc + script（情绪参考）+ directorRef（光影策略）+ 目标模型
    - 出参：imagePrompt（可直接送给图片模型的英文提示词）
  - 主 Agent 审查 imagePrompt 质量（shotDesc 内容完整保留、光影词库对应 directorRef）

Step 2-B: 生成静态分镜图 + Manifest 初始化
  - 组装 items 并初始化 manifest（**不含 videoPrompt**）：
    ```bash
    node scripts/pipeline.js init --account <id> --mode <single|framePair> \
      --items '[{"shotDesc":"...","script":"...","duration":5,"imagePrompt":"...","directorRef":"tarantino"}]'
    ```
  - 脚本自动从 account.json 继承：imageModel、videoModel、format、references
  - 所有 item.confirmed = false
  - 生成分镜图：`pipeline.js run --manifest <path> --phase images`
    - 参考图在此阶段介入（Gemini 图生图 / MJ --sref）
  - 首尾帧模式额外要求：每个 item 必须有 `lastFramePrompt`

Step 2-C: 人工确认（可选卡点）
  - 展示所有分镜图给用户
  - 用户可：确认全部 / 替换 MJ 候选图（改 item.file = item.candidates[N]） / 删除不合格 item / 跳过确认直接继续
  - 用户确认后：`node scripts/pipeline.js confirm --manifest <path> --all`
  - 跳过确认时：批量设置 `confirmed = true`，直接进入 Step 3

Step 3-A: 生成视频提示词（子 Agent 执行）
  - 读取 account.json 中的 videoStylePrompt 字段，定位视频提示词模板（如 prompts/视频提示词.md）
  - 子 Agent 为每个 shot 生成 videoPrompt：
    - 入参：shotDesc + directorRef（运动策略）+ 已确认的分镜图 + 目标模型
    - 出参：videoPrompt（描述镜头运动的英文提示词）
  - Agent 将 videoPrompt 回写到 manifest items（直接编辑 manifest.json 的每个 item）
  - 主 Agent 审查 videoPrompt 质量（描述运动而非内容、字数≤50）

Step 3-B: 生成视频片段
  - 上传 + 生成视频：`pipeline.js run --manifest <path> --phase upload,videos`
  - 跳过确认时由 Step 2-C 自动批量设置 confirmed=true
  - 首尾帧模式检查过渡连贯性

Step 4: TTS + 成片
  - 跑 tts + assemble 阶段：`pipeline.js run --manifest <path> --phase tts,assemble`
  - TTS 使用 script 字段（口播旁白）
  - 检查字幕准确、BGM 不盖配音
```

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

### CLI 参考

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

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

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

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

# 人工确认分镜图（Step 2-C，可选：跳过时 Agent 批量设置 confirmed=true）
node scripts/pipeline.js confirm --manifest <path> --all

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

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

# 查看进度
node scripts/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 |
| 适用场景 | 风景、人物展示 | 状态变化、叙事过渡 |

---

## 视频模型与执行策略

### 视频模型选择

| 模型 | 时长 | 画幅 | 单图 | 首尾帧 | 特点 | 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 次重试，每次自动简化提示词
- 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/{name}_{YYYYMMDD}_{NNN}/
├── manifest.json                # 主清单（贯穿全流程）
├── prompts.txt                  # 原始提示词存档
├── images/                      # scene_{NN}_{slug}.jpeg（slug 从 script/shotDesc 派生，首尾帧加 _last 后缀）
├── videos/                      # scene_{NN}_{slug}.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 的字幕风格配置

---

---

## 质量卡点（Agent 可执行）

每个阶段完成后 Agent 自动校验，不通过的自动修复。需要人工视觉判断的（画质、动画、BGM等）由用户在人工审查步骤处理。

### 生图 卡点

| 检查项 | 标准 | 不通过处理 |
|--------|------|-----------|
| 图片分辨率 | 短边 >= 1024px | 重新生成 |
| 画幅比例 | 与 manifest.format 一致 | 重新生成 |
| 数量 | 与 items 数量匹配 | 补充生成失败项 |

### 配音 卡点

| 检查项 | 标准 | 不通过处理 |
|--------|------|-----------|
| 音频时长 | 与素材总时长相近（±20%） | 调整语速或素材时长 |
| 音频数量 | 与 items 数量匹配 | 补充或裁剪 |

### AI视频 卡点

| 检查项 | 标准 | 不通过处理 |
|--------|------|-----------|
| 视频数量 | 与 items 数量匹配 | 补充生成失败项 |

### 成片输出 卡点

| 检查项 | 标准 |
|--------|------|
| 字幕准确 | 与原始文案一一对应 |

**卡点不通过自动修复后再进入下一阶段。**

---

## 共享资源

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

- `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 成片组装 |