AI video auto generator

SKILL.md

---
name: ai-video-auto-generator
version: 2.3.0
description: "AI 短视频全自动流水线：从想法到成片，一键出视频。脚本生成→自动修复→资产生成→视频→音频→字幕，全自动无人值守。| AI video auto pipeline: from idea to final video, one command. Script generation → auto repair → assets → video → audio → subtitles, fully automated."
category: video-generation
platforms:
  - WorkBuddy
  - QClaw
  - ima
  - Claude Code
  - Cursor
tags:
  - video
  - ai-video
  - pipeline
  - automation
  - short-video
  - tts
  - subtitle
  - script-generation
---

> 📖 **README**: `README.md` | **CHANGELOG**: `CHANGELOG.md`

# ai-video-auto-generator

将书面需求转换为结构化视频脚本，用于AI视频生成流水线。

**目录**
- <a href="#agent-mode">🤖 Agent 使用模式（核心工作流）</a>
- <a href="#quick-start">⚡ Quick Start（4 路径出片）</a>
- <a href="#architecture">🏗️ 流水线架构</a>
- <a href="#verification">🔍 验证体系</a>
- <a href="#self-healing">🩹 自愈机制</a>
- <a href="#cli">🛠️ 流水线 CLI</a>
- **参考文档**
  - [端到端案例](references/e2e-walkthrough.md)
  - [脚本生成检查清单](references/script-json-checklist.md)
  - [Provider 配置](references/provider-config.md)
  - [景别设计](references/shot-scales.md)
  - [剪辑与包装](references/editing-specs.md)
  - [节奏与叙事结构](references/pacing-narrative.md)
  - [Prompt 工程规则](references/prompt-rules.md)
  - [视频生成模式](references/video-modes.md)
  - [环境搭建](references/setup-guide.md)
  - [流水线排错](references/troubleshooting.md)
  - [Segment 合并设计](references/segment-design.md) — 仅小云雀 Provider

---

<h2 id="quick-start">⚡ Quick Start（4 路径出片）</h2>

**🔥 尝鲜（30 秒出预览，无需 API Key）：**
```bash
python ~/.workbuddy/skills/ai-video-auto-generator/scripts/pipeline.py \
  --project ~/.workbuddy/skills/ai-video-auto-generator/sample --mode demo
```

**💬 一句话生成视频（推荐，通过 AI Agent）：**
```bash
# 1. 在 WorkBuddy 中加载 ai-video-auto-generator skill
# 2. 直接告诉 AI Agent 你的需求，例如：
#    "帮我做一个古代将军在现代城市醒来的短视频，紧张氛围，约30秒"
# 3. Agent 会自动：分析需求 → 生成 script.json → 跑流水线 → 出片
```

> 📌 **脚本生成已由 AI Agent 接管。** 之前的 `--mode generate` / `--prompt` 命令已废弃，保留入口但不再执行脚本生成。所有脚本生成直接在对话中完成。

**📄 从文档生成视频（通过 AI Agent）：**
```bash
# 直接把文件/URL/飞书链接发给 AI Agent
# Agent 会自动读取内容 → 生成 script.json → 跑流水线
```

**📦 从模板创建（手动编辑）：**
```bash
python3 ~/.workbuddy/skills/ai-video-auto-generator/scripts/create_project.py \
  --project "$HOME/WorkBuddy/我的视频" --template short_drama
cd "$HOME/WorkBuddy/我的视频" && python scripts/pipeline.py --mode auto
```

> 详细说明见 `README.md`。

---

<h2 id="agent-mode">🤖 Agent 使用模式（核心工作流）</h2>

> **你提供需求，AI Agent（当前对话）帮你搞定一切。** 不需要手动调命令，直接说就好。

### 如何与 Agent 配合

| 你的输入 | Agent 自动执行 |
|---------|---------------|
| `"帮我做一个军事短剧，紧张氛围"` | ① 解析需求 → 生成 `script.json` → 写回项目目录<br>② 创建角色卡、场景卡、镜头列表<br>③ 运行 `--mode auto` 启动流水线 |
| `"从这篇文章生成视频"` + 贴 URL | ① WebFetch 读取文章内容<br>② 分析角色/场景/情绪 → 生成 `script.json`<br>③ 运行 `--mode auto` |
| `"从这份文档生成视频"` + 上传文件 | ① Read 读取文档内容<br>② 提取关键信息 → 生成 `script.json`<br>③ 运行 `--mode auto` |
| `"帮我优化这个脚本"` + 贴 JSON | ① 读取当前 `script.json`<br>② 运行 `fix_script_narrative` 12 维修复<br>③ 输出修复报告 |
| `"修一下 shot_05 的运镜问题"` | ① 定位问题<br>② 修改 `script.json`<br>③ 通知验证结果 |

### Agent 脚本生成规则（重要）

当 Agent 为你生成 `script.json` 时，遵循以下标准：

```
📋 角色卡要求:
  - 每个角色必须有 name / title / appearance（clothing/physique/face/features）
  - appearance 要细化到发型、脸型、瞳色、肤色、体态、着装
  - 每个角色至少 front + face 两个视图，主角加 side + back
  - asset_background 固定为 "white"

📋 场景卡要求:
  - 每个场景有 name / description / views（广角/中景/特写）
  - description 描述环境氛围（光线/色调/空间感/情绪）

📋 镜头要求（最重要）:
  - 每个镜头有 id / description / duration / voice_over
  - description 包含: 景别 + 运镜 + 人物动作 + 环境 + 情绪
  - duration 3-8 秒，总时长控制在 60-120 秒
  - 前 3 个镜头要有钩子（冲突/悬念/意外）
  - 高潮镜头放在总时长的 70-85% 处
  - 收尾镜头要有结局感

📋 叙事结构:
  - 开头抓人 → 展开 → 冲突升级 → 高潮 → 收尾
  - 运镜要变化（不要连续 3+ 镜头同运镜）
  - 情绪要有起伏（不要从欢快跳到悲伤）
  - 对话和动作镜头比例合理（各不超过 70%）

📋 流水线触发:
  - script.json 写完后，自动执行 `pipeline.py --mode auto`
  - 如果项目已有 task_tracker 且部分完成，auto 会自动从断点继续
```

### 快速命令

```bash
# Agent 一键出片（在对话中描述需求即可）
# 上述步骤全部由 AI Agent 自动完成

# 如果你需要手动查状态
tail -f auto.log          # 查看流水线进度
```

---

<h2 id="architecture">🏗️ 流水线架构</h2>

```
AI Agent（你） → script.json → 10 阶段全自动流水线 → final.mp4

阶段 0:   脚本优化
阶段 1:   叙事结构修复（12 维）
阶段 2:   构建资产 prompt 文件
阶段 3:   角色资产生成 + 6 维质量验证（55 分制）
阶段 4:   辅助资产生成 + 质量验证
阶段 5:   场景资产生成 + 人脸检测 + 风格检测
阶段 6:   初始化首帧图
阶段 7:   首帧图生成 + 50 分制验证
阶段 8:   提交视频任务 + 验证 prompt
阶段 9:   轮询完成 + 55 分制视频验证 + 拼接 + 音频 + 字幕

全部阶段支持断点续跑。
```

<h2 id="verification">🔍 验证体系</h2>

| 资产 | 检查项 | 评分 |
|------|--------|------|
| 角色图 | 文件+模糊+人物=1+背景+全身+风格 | 55 分 |
| 场景图 | Haar 人脸检测 + Canny 风格匹配 | pass/fail |
| 首帧图 | 文件+比例+模糊+HOG人数+色彩 | 50 分 |
| 视频 | 时长+比例+黑帧+光流运镜+情绪匹配 | 55 分 |

<h2 id="self-healing">🩹 自愈机制</h2>

```
fail → classify(5 categories) → strategy(soften/switch/backoff/regen) → capped retry(max 5)
```

<h2 id="cli">🛠️ 流水线 CLI</h2>

```bash
python scripts/pipeline.py --mode setup       # 环境检测 + 自动装依赖 + 复制 Key 模板
python scripts/pipeline.py --mode auto         # 全自动流水线（从中断继续）
python scripts/pipeline.py --mode validate     # 预检（只验证不生成）
python scripts/pipeline.py --mode demo         # 快速尝鲜（30 秒，无需 API Key）
python scripts/pipeline.py --mode poll --detached  # 仅轮询
```

---

## 参考文档

- [端到端案例](references/e2e-walkthrough.md) — 从飞书文档到成片的完整流程
- [脚本生成检查清单](references/script-json-checklist.md)
- [Provider 配置](references/provider-config.md)
- [景别设计](references/shot-scales.md)
- [剪辑与包装](references/editing-specs.md)
- [节奏与叙事结构](references/pacing-narrative.md)
- [Prompt 工程规则](references/prompt-rules.md)
- [视频生成模式](references/video-modes.md)
- [环境搭建](references/setup-guide.md)
- [流水线排错](references/troubleshooting.md)
- [Segment 合并设计](references/segment-design.md) — 仅小云雀(xiaoyunqiao) Provider 需要

---

## English Quick Start

> **AI video auto pipeline: from idea to final video, one command.**

### How it works

Load this skill in WorkBuddy, then tell the AI agent what you want:

```
"Create a short video about an ancient general waking up in a modern city"
"Generate a video from this article" + paste URL
"Turn this document into a video" + upload file
```

The agent will:
1. Read and analyze your input
2. Generate a complete `script.json` (characters, scenes, shots)
3. Run `pipeline.py --mode auto` — fully automated pipeline
4. Notify you when `final.mp4` is ready

### Pipeline stages

| Stage | Description |
|-------|-------------|
| 0 | Script optimization |
| 1 | Narrative 12-dim auto repair (hook/pacing/camera/emotion/closure) |
| 2 | Build asset prompt files |
| 3 | Character asset generation + 6-dim quality verification (55pt) |
| 4 | Troop asset generation + verification |
| 5 | Scene asset generation + face detection + style check |
| 6 | Initialize first frames |
| 7 | First frame generation + 50pt verification |
| 8 | Submit video tasks + prompt verification |
| 9 | Poll completion + 55pt video verification (camera motion/mood/black frames) + stitch + audio + subtitles |

All stages support resume from checkpoint (Ctrl+C / crash / shutdown).

### CLI reference

```bash
python scripts/pipeline.py --mode setup       # Auto-install dependencies + copy API key template
python scripts/pipeline.py --mode auto         # Full pipeline (resume from checkpoint)
python scripts/pipeline.py --mode validate     # Pre-flight check (no generation)
python scripts/pipeline.py --mode demo         # 30s preview, no API key needed
python scripts/pipeline.py --mode poll --detached  # Poll only
```

### Known limitations

- Requires API Key for AI generation (default: Agnes AI, free unlimited tier)
- Windows prioritized (macOS/Linux not fully tested)
- OpenCV ~50MB dependency (auto-installed via `--mode setup`)
- No real-time progress bar (logs written to file in detach mode)

### Reference docs

- [Provider config](references/provider-config.md)
- [Shot scales](references/shot-scales.md) (Chinese)
- [Prompt rules](references/prompt-rules.md) (Chinese)
- [Troubleshooting](references/troubleshooting.md) (Chinese)