book-video-generator

原始内容

---
name: book-video-generator
slug: book-video-generator
version: 2.8.0
displayName: 三分钟精读一本书视频生成器
description: 三分钟精读一本书视频生成器。输入书名+作者，一键生成3分钟读书解说视频（书评文案→AI插图→TTS配音→字幕→最终合成MP4）。触发词：三分钟精读书、生成读书视频、精读一本书、book video、做读书视频、书评视频。跨平台兼容 WorkBuddy / OpenClaw / Codex CLI / TRAE Work。
---

# 三分钟精读一本书 视频生成器

## 概述

将任意书籍自动生成一个 3 分钟解说视频：从书评文案撰写、分镜生成、AI 插图、TTS 配音到字幕合成，全流程自动化。

源于扣子工作流 "Pipadushu_video_1"，本 Skill 遵循 [Agent Skills 开放标准](https://agentskills.io)，跨平台兼容 WorkBuddy、OpenClaw、Codex CLI、TRAE Work。

使用本地开源工具替代扣子插件：剪映小助手 → ffmpeg，扣子图像生成 → 多模型图像生成（默认 ImageGen + 备选火山即梦/Gemini/Agnes），扣子 TTS → 火山引擎 TTS（默认，1.2x 语速）/ edge-tts（备选）。v2.8.0 新增火山即梦/Gemini/Agnes 三种图像生成备选方案，用户可通过环境变量 IMAGE_API 切换。v2.7.0 新增背景音乐、转场音效、字幕入场/出场动画，移除画面缩放。

## 平台工具映射

本 Skill 的工作流涉及 3 个平台相关工具，各平台替代方案如下。执行时根据当前运行平台选择对应工具。

### 联网搜索（阶段 1 用于搜索书籍信息）

| 平台 | 工具 | 说明 |
|------|------|------|
| WorkBuddy | `WebSearch` | 内置工具，直接调用 |
| OpenClaw | 内置 web search | 自动可用 |
| Codex CLI | `shell: curl` 或 MCP 搜索插件 | 通过 shell 命令或安装搜索 MCP |
| TRAE Work | 内置联网搜索 | 自动可用 |

### 图像生成（阶段 4a 用于生成分镜插图）

提供了 **1 个默认 + 3 个备选** 图像生成方案，用户可通过环境变量 `IMAGE_API` 切换：

| 方案 | 工具 | 模型 | 环境变量 | 说明 |
|------|------|------|----------|------|
| 🏠 **默认** | `ImageGen` | 腾讯混元（WorkBuddy 内置） | 无需配置 | 在 WorkBuddy 中直接调用 DeferExecuteTool |
| 🏔️ 备选 | `volcengine` | 火山引擎即梦 Seedream 5.0 lite（字节跳动） | `ARK_API_KEY`（推荐）或 `VOLCENGINE_AK` + `VOLCENGINE_SK` | 原扣子工作流用的字节生图，中文扁平风最优，支持去水印。使用前需在[火山方舟控制台](https://console.volcengine.com/ark/region:ark+cn-beijing/openManagement)开通模型。已开通: 5.0 Pro / 5.0 lite / 4.5 / 4.0，默认 5.0 lite（`doubao-seedream-5-0-260128`） |
| 🤖 备选 | `gemini` | Google Gemini 3 Pro Image | `GEMINI_API_KEY` | 细节丰富，语义理解强 |
| ✨ 备选 | `agnes` | Agnes AI（完全免费） | `AGNES_API_KEY` | 免费注册获取，OpenAI 兼容接口 |

**切换方式**：

- **WorkBuddy**：默认使用 `ImageGen`。如需切换，设置 `IMAGE_API=volcengine|gemini|agnes` 后，脚本自动调用 `scripts/generate_image.py` 而非 ImageGen
- **CLI 平台**（Codex CLI / OpenClaw）：直接运行 `scripts/generate_image.py --api <方案>`
  ```bash
  # 单张生成
  python3 scripts/generate_image.py --prompt "<desc_promopt>" --output "scene_000.png" --api volcengine

  # 批量生成（从 storyboard.json）
  python3 scripts/generate_image.py --batch storyboard.json --output-dir images/ --api gemini
  ```

> 无论使用哪个平台，图像生成的 prompt 统一使用分镜中的 `desc_promopt` 字段。

### LLM 调用（阶段 1-3 用于生成文案和分镜）

所有平台均内置 LLM 对话能力，直接将 `references/prompts.md` 中的 System Prompt 发送给当前平台的 LLM 即可。

## 输入

| 参数 | 说明 | 必填 |
|------|------|------|
| `book_name` | 书籍名称 | 是 |
| `author_name` | 作者名称 | 是 |
| `ip_name` | 账号名称（用于封面图底部水印） | 否，默认不显示 |

## 环境准备

执行前确保以下 Python 依赖已安装：

```bash
pip install edge-tts imageio-ffmpeg pillow
```

> 脚本会在首次运行时自动安装缺失的依赖，但建议预先安装以避免中断。

ffmpeg 由 `imageio-ffmpeg` 包自动提供二进制，无需单独安装系统级 ffmpeg。

### TTS 引擎配置（可选）

| 引擎 | 凭证 | 时间戳 | 说明 |
|------|------|--------|------|
| 火山引擎 TTS（默认） | `VOLC_TTS_API_KEY` | 基于音频时长估算 | 豆包语音合成 2.0，中文自然度最高，1.2x 语速（匹配扣子工作流），可商用，需在[火山引擎控制台](https://console.volcengine.com/speech/new)获取 API Key |
| edge-tts（备选） | 无需配置 | WordBoundary 原生精确 | 微软免费 TTS，pip 安装即用，无凭证时自动回退 |

设置火山引擎凭证：
```bash
export VOLC_TTS_API_KEY="your-api-key"
```

> 未设置火山引擎凭证时，脚本自动使用 edge-tts，功能完整不受影响。
> 火山引擎 TTS 2.0 不原生支持词级时间戳，脚本基于返回的音频时长按字符均匀估算时间戳（标点符号占比较短时间），字幕同步精度略低于 edge-tts 但完全可用。

## 完整工作流（5 个阶段）

### 阶段 1：生成书评文案

**目标**：根据书名+作者，用 LLM 生成约 1000 字的 3 分钟视频文案。

**操作**：
1. 用当前平台的**联网搜索工具**搜索书籍真实信息（简介、解读、出版年份）
2. 使用 system prompt（见 `references/prompts.md` 第 1 节），要求 LLM 输出 JSON：

```json
{
  "book_name": "...",
  "author_name": "...",
  "year": "yyyy-MM",
  "content": "1000+字书评文案（含开篇引言+核心内容+观点提炼）",
  "category": "图书分类"
}
```

**要点**：
- 文案需满足约 3 分钟口播时长（约 700-1000 字）
- 开篇引言必须极具吸引力
- 信息来源需通过搜索获取，确保内容准确

### 阶段 2：生成分镜脚本

**目标**：将书评文案拆分为 8-50 个分镜，每个分镜包含字幕文案、画面描述、AI 图像提示词。

**操作**：
使用 system prompt（见 `references/prompts.md` 第 2 节），输入阶段 1 的 content，输出：
```json
{
  "list": [
    {
      "story_name": "分镜名称",
      "desc": "画面描述",
      "cap": "字幕文案（一句话）",
      "desc_promopt": "图像生成提示词"
    }
  ],
  "keywords": ["重点词1", "重点词2"]
}
```

然后在 list 开头插入引言分镜（模仿原工作流 node 150774 的逻辑）：
```python
list.insert(0, {
    "story_name": "引言",
    "desc": "每日精读一本书",
    "cap": f"3分钟精读一本书，今天我们读《{book_name}》",
    "desc_promopt": "每日精读一本书"
})
```

**风格约束**：扁平插画风，人物卡通风简洁线条，背景扁平化符号，柔和明亮低饱和度色调。

### 阶段 3：生成标题进度条

**目标**：根据文案内容划分为 4 个板块，每板块 6 字以内标题，用于视频顶部进度条显示。

**操作**：
使用 system prompt（见 `references/prompts.md` 第 3 节），输出 4 个标题（title1-title4）。

**使用方式**：4 个标题通过 `segments.json` 的 `chapter_titles` 字段传入 `compose_video.py`，在视频顶部渲染为进度条（当前板块橙色高亮 + 底部进度线）。同时需要 `segment_chapters` 字段指定每个分镜所属的板块索引（0-3），未指定时自动均匀分配。

### 阶段 4：生成素材（并行）

本阶段生成视频所需的全部素材：

#### 4a. AI 插图生成

对每个分镜的 `desc_promopt`，调用图像生成工具生成插图。**默认使用 WorkBuddy 内置的 `ImageGen`（腾讯混元模型），可通过环境变量 `IMAGE_API` 切换到备选方案。**

**统一风格参数**（原工作流图像生成节点配置）：
- 尺寸：1024x768
- 风格：扁平风（flat illustration）
- 主角上衣 #FF7F72，裤子 #243139
- 30% 透明玻璃效果背景
- 负向提示词：无

**方案选择与调用方式**：

| 方案 | `IMAGE_API` 值 | 调用方式 | 需要配置 |
|------|----------------|----------|---------|
| 🏠 腾讯混元（默认） | 不设置或 `imagegen` | WorkBuddy 内置 `ImageGen` 工具 | 无 |
| 🏔️ 火山即梦 | `volcengine` | `python3 scripts/generate_image.py --api volcengine` | `ARK_API_KEY`（推荐）或 `VOLCENGINE_AK` + `VOLCENGINE_SK`。默认用 Seedream 5.0 lite（`doubao-seedream-5-0-260128`），可通过 `VOLCENGINE_MODEL` 切换。5.0 lite 最小 2K 分辨率，代码自动升级 |
| 🤖 Google Gemini | `gemini` | `python3 scripts/generate_image.py --api gemini` | `GEMINI_API_KEY` |
| ✨ Agnes AI | `agnes` | `python3 scripts/generate_image.py --api agnes` | `AGNES_API_KEY` |

**执行逻辑**：
1. 如果运行在 **WorkBuddy** 且未设置 `IMAGE_API`：直接调用 `ImageGen` 工具（DeferExecuteTool），参数 `prompt` = desc_promopt，`size` = "1024x768"
2. 如果设置了 `IMAGE_API=volcengine|gemini|agnes`：调用 `scripts/generate_image.py` 脚本，自动安装依赖并通过 API 生成
3. 如果运行在 **CLI 平台**（Codex CLI 等）：默认调用 `scripts/generate_image.py --api gemini`

> 生成的图片统一命名为 `scene_000.png` ~ `scene_NNN.png`，存放到 `output/{book_name}/images/` 目录。

#### 4b. TTS 语音合成

对每个分镜的 `cap`（字幕文案），使用 TTS 引擎生成 MP3 音频，同时生成词级时间戳（保存为同名 `.words.json` 文件，用于阶段 5 的逐句字幕精确同步）。

**双引擎架构**：
- **火山引擎 TTS**（默认）：V1 API + X-Api-Key 认证，豆包语音合成 2.0 音色，中文自然度最高，可商用，需设置环境变量 `VOLC_TTS_API_KEY`
- **edge-tts**（备选）：免费无需配置，原生 WordBoundary 词级时间戳，未设置火山引擎凭证时自动回退

**默认音色**：
- 火山引擎：`zh_female_zhixingnv_uranus_bigtts`（知性女声 2.0，适合读书解说）
- edge-tts：`zh-CN-XiaoxiaoNeural`（晓晓，女声）

查看所有可用音色：`python3 scripts/generate_audio.py --list-voices`

运行（所有平台通用，自动选择引擎）：
```bash
python3 scripts/generate_audio.py --text "<字幕>" --output "audio_001.mp3"
```

指定引擎或音色：
```bash
# 强制使用火山引擎
python3 scripts/generate_audio.py --text "<字幕>" --output "audio_001.mp3" --engine volcano --voice zh_female_zhixingnv_uranus_bigtts

# 强制使用 edge-tts
python3 scripts/generate_audio.py --text "<字幕>" --output "audio_001.mp3" --engine edge --voice zh-CN-XiaoxiaoNeural
```

批量模式：
```bash
python3 scripts/generate_audio.py --batch captions.json --output-dir audio/ --voice "zh_female_zhixingnv_uranus_bigtts"
```

#### 4c. 开场封面图

为视频第一帧生成专属封面图（1920x1080），包含书名、作者、品牌文字。

**操作**：运行 `python3 scripts/generate_cover.py`

```bash
# 用第一张分镜图做模糊背景（推荐，与视频风格一致）
python3 scripts/generate_cover.py \
  --book-name "原子习惯" \
  --author "James Clear" \
  --output output/原子习惯/images/cover.png \
  --bg output/原子习惯/images/scene_000.png

# 无背景图，使用深蓝渐变
python3 scripts/generate_cover.py \
  --book-name "原子习惯" \
  --author "James Clear" \
  --output output/原子习惯/images/cover.png
```

**封面布局**：
- 顶部：「3 分钟精读一本书」品牌文字 + 橙色分隔线（#FF7F72，与分镜主角上衣同色）
- 中部：书名大字（自动换行居中，80pt）
- 中下：作者名（42pt）
- 底部：账号名称水印（**可选**，通过 `--ip-name` 指定，不传则不显示）

**字体**：自动检测系统中文字体（Windows: 微软雅黑 / macOS: PingFang SC / Linux: Noto Sans CJK），无需手动修改。

> 封面图在阶段 5 合成时，通过 segments.json 中的 `cover` 字段指定，会在第一分镜前 `cover_duration` 秒（默认5秒）显示封面图，之后切换回原始分镜图（旁白全程不中断）。
>
> ```json
> {
>   "output": "output/书名_三分钟精读书.mp4",
>   "cover": "output/书名/images/cover.png",
>   "chapter_titles": ["开篇引言", "核心方法", "实践技巧", "总结"],
>   "segment_chapters": [0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3],
>   "keywords": ["原子习惯", "微小改变", "复利效应"],
>   "bgm": "assets/bgm_reading.mp3",
>   "bgm_volume": 0.15,
>   "transition_sound": "assets/transition_page_flip.mp3",
>   "transition_interval": 3,
>   "transition_volume": 0.3,
>   "segments": [
>     {"image": "images/scene_000.png", "audio": "audio/audio_000.mp3", "caption": "字幕文本"},
>     ...
>   ]
> }
> ```
> - `cover`：可选，封面图路径，在第一分镜前 `cover_duration` 秒显示，之后切回原始分镜图
> - `cover_duration`：可选，封面显示时长（秒），默认 5.0，仅作用于第一分镜前半段
> - `chapter_titles`：可选，板块标题列表，用于顶部进度条显示
> - `segment_chapters`：可选，每个分镜所属板块索引（0-based），未提供时自动均匀分配
> - `keywords`：可选，关键词列表，字幕中匹配到的关键词显示为橙色高亮
> - `bgm`：可选，背景音乐路径，未提供时自动查找 `assets/bgm_reading.mp3`，传空字符串禁用
> - `bgm_volume`：可选，BGM 音量 (0.0-1.0)，默认 0.15
> - `transition_sound`：可选，转场音效路径，未提供时自动查找 `assets/transition_page_flip.mp3`，传空字符串禁用
> - `transition_interval`：可选，每 N 个分镜添加一次转场音效，默认 3
> - `transition_volume`：可选，转场音效音量 (0.0-1.0)，默认 0.3

### 阶段 5：视频合成

**目标**：将所有素材合成为最终 MP4 视频。

**操作**：运行 `python3 scripts/compose_video.py`，该脚本执行：
1. 计算每个分镜时长（基于 TTS 音频时长 + gap 间隔）
2. 图片缩放/裁剪为 1920x1080（16:9）
3. 为每个分镜添加 **0.3s 淡入淡出转场**（dip-to-black）
4. 使用 ffmpeg 将图片+音频合成为视频片段
5. **进度条 overlay**：顶部显示板块标题（当前板块橙色高亮+实心圆点，其余灰色+空心圆点），底部进度线显示总体播放进度
6. 生成**逐句单行 ASS 字幕**（基于 TTS 词级时间戳精确同步语音，按标点+字数拆分为单行短句，白色加粗文字+黑色描边，**关键词橙色高亮**，**入场淡入+上滑/出场淡出动画**）
7. 拼接所有片段为完整视频
8. **混音**：将背景音乐（BGM）以低音量全程混合 + 每 3 个分镜在边界处叠加转场翻页音效

**字幕参数**（对应原工作流 add_captions_1 节点）：
- 字体颜色：白色 (#FFFFFF)
- 关键词高亮：橙色 (#FF7F72)，通过 ASS 内联颜色标签 `{\c&H727FFF&}` 实现
- 边框颜色：黑色 (#000000)
- 字号：64pt（加粗）
- 位置：底部居中（MarginV=30）
- 字体：**自动检测**系统可用中文字体（Windows: 微软雅黑 / macOS: PingFang SC / Linux: Noto Sans CJK SC），无需手动修改
- 字幕格式：**ASS**（Advanced SubStation Alpha），支持行内颜色标签+动画标签
- **逐句单行显示**：利用 TTS 词级时间戳（火山引擎基于音频时长估算 / edge-tts WordBoundary 原生精确），将长字幕按标点拆分为单行短句，每句时间与语音同步
- **入场动画**：淡入 200ms + 从下方 20px 上滑（ASS `\fad` + `\move` 标签）
- **出场动画**：淡出 150ms（ASS `\fad` 标签）

**进度条参数**：
- 位置：画面顶部（80px 高度）
- 背景：半透明深色（alpha=130）
- 当前板块：橙色 (#FF7F72) 文字 + 实心圆点
- 非当前板块：灰色 (#AAAAAA) 文字 + 空心圆点
- 底部进度线：橙色填充 + 深灰底色，显示总体播放进度
- 字体：自动检测系统中文字体，44pt

**动态效果参数**：
- 转场淡入淡出时长：0.3s（短于 0.6s 的分镜自动减半）

**音频混音参数**：
- 背景音乐：`assets/bgm_reading.mp3`（3分56秒读书背景音乐，自动循环），音量 0.15
- 转场音效：`assets/transition_page_flip.mp3`（0.71s 翻页声效），每 3 个分镜在结尾前 0.5s 触发，音量 0.3
- 混音方式：ffmpeg `amix` 滤镜，BGM 循环播放 + 转场音效按时间点 `adelay` 叠加

> **📌 音频素材为可选**：由于 SkillHub 不支持上传 .mp3 文件，音频素材未随技能打包。如果 `assets/` 目录下没有这些文件，视频仍可正常生成（仅不含 BGM 和转场音效）。如需添加，请参考 `assets/README.md` 中的获取方式。

### 输出

最终输出：`output/{book_name}_三分钟精读书.mp4`

## 跨平台安装

### WorkBuddy

技能已安装在 `~/.workbuddy/skills/book-video-generator/`，直接使用。

### OpenClaw

```bash
# 复制到 OpenClaw 技能目录
cp -r ~/.workbuddy/skills/book-video-generator ~/.openclaw/skills/

# 或通过 ClawHub 安装（如果已发布）
openclaw skills install book-video-generator
```

如需在 frontmatter 中声明图像生成 tool，参考 OpenClaw 文档的 `tools` 字段定义。

### Codex CLI

```bash
# 1. 开启 Skills 功能（如未开启）
echo '[features]\nsskills = true' >> ~/.codex/config.toml

# 2. 复制技能目录
cp -r ~/.workbuddy/skills/book-video-generator ~/.codex/skills/

# 3. 重启 Codex CLI
# 4. 输入 /skills 确认技能已加载
```

Codex CLI 无内置图像生成，需在 `scripts/` 目录中添加 `generate_image.py` 脚本，调用外部 API（如 OpenAI DALL-E、Stability AI）。脚本需接受 `--prompt` 和 `--output` 参数。

### TRAE Work

```
1. 打开 TRAE Work → 规则和技能 → 技能 → 创建 → 导入文件
2. 上传 SKILL.md 文件
3. 确保 scripts/ 和 references/ 目录也复制到技能目录
```

TRAE Work 通过 MCP 接入图像生成服务。在 TRAE 的 MCP 配置中添加火山引擎或通义万相的图像生成 MCP，然后在执行阶段 4a 时通过 MCP 调用。

## 原工作流参考

原始扣子工作流文件位于 `references/workflow-original.yaml`，包含 30+ 节点的完整链路：
```
开始 → LLM(DeepSeek V3.2)生成书评 → 上标题总结 → 分镜画面描述
→ 代码拼接引言 → 批量图像生成+抠图 → TTS语音合成
→ 创建剪映草稿 → 批量添加图片/字幕/音频 → 保存草稿 → 结束
```

原始流程依赖**剪映小助手插件**（视频合成核心）、扣子内置**图像生成+抠图**和**TTS**插件。
本 Skill 使用 ffmpeg、edge-tts、平台图像生成工具替代。

## 快速使用示例

用户说："帮我生成《原子习惯》James Clear 的 3 分钟精读视频"

执行流程：
1. 搜索"原子习惯 James Clear 简介 书评"
2. 用阶段 1 prompt 生成书评文案
3. 用阶段 2 prompt 生成分镜脚本
4. 用阶段 3 prompt 生成标题进度条
5. 对每个分镜：图像生成工具生成插图 + TTS 生成配音（火山引擎默认 / edge-tts 备选）
6. compose_video.py 合成最终视频
7. 输出 `output/原子习惯_三分钟精读书.mp4`

## 资源文件

- `references/prompts.md` — 所有 LLM 提示词原文（平台无关，可直接复用）
- `references/workflow-original.yaml` — 原始扣子工作流（完整 YAML 备份）
- `scripts/compose_video.py` — 视频合成脚本（纯 Python + ffmpeg，跨平台，含淡入淡出转场 + 字体自动检测 + 封面图支持 + 逐句单行 ASS 字幕精确语音同步 + 关键词高亮 + 入场/出场动画 + 顶部进度条 + BGM 背景音乐混音 + 转场音效）
- `scripts/generate_audio.py` — TTS 语音生成脚本（纯 Python，双引擎：火山引擎 TTS V1 API + X-Api-Key 默认 1.2x 语速 / edge-tts 备选 +20% 语速，含词级时间戳输出，自动检测凭证切换引擎）
- `scripts/generate_cover.py` — 封面图生成脚本（纯 Python + Pillow，自动换行 + 模糊背景 + 字体自动检测）

name: book-video-generator slug: book-video-generator version: 2.8.0 displayName: 三分钟精读一本书视频生成器 description: 三分钟精读一本书视频生成器。输入书名+作者，一键生成3分钟读书解说视频（书评文案→AI插图→TTS配音→字幕→最终合成MP4）。触发词：三分钟精读书、生成读书视频、精读一本书、book video、做读书视频、书评视频。跨平台兼容 WorkBuddy / OpenClaw / Codex CLI / TRAE Work。

三分钟精读一本书视频生成器

概述

将任意书籍自动生成一个 3 分钟解说视频：从书评文案撰写、分镜生成、AI 插图、TTS 配音到字幕合成，全流程自动化。

源于扣子工作流 "Pipadushu_video_1"，本 Skill 遵循 Agent Skills 开放标准，跨平台兼容 WorkBuddy、OpenClaw、Codex CLI、TRAE Work。

使用本地开源工具替代扣子插件：剪映小助手 → ffmpeg，扣子图像生成 → 多模型图像生成（默认 ImageGen + 备选火山即梦/Gemini/Agnes），扣子 TTS → 火山引擎 TTS（默认，1.2x 语速）/ edge-tts（备选）。v2.8.0 新增火山即梦/Gemini/Agnes 三种图像生成备选方案，用户可通过环境变量 IMAGE_API 切换。v2.7.0 新增背景音乐、转场音效、字幕入场/出场动画，移除画面缩放。

平台工具映射

本 Skill 的工作流涉及 3 个平台相关工具，各平台替代方案如下。执行时根据当前运行平台选择对应工具。

联网搜索（阶段 1 用于搜索书籍信息）

平台	工具	说明
WorkBuddy	`WebSearch`	内置工具，直接调用
OpenClaw	内置 web search	自动可用
Codex CLI	`shell: curl` 或 MCP 搜索插件	通过 shell 命令或安装搜索 MCP
TRAE Work	内置联网搜索	自动可用

图像生成（阶段 4a 用于生成分镜插图）

提供了 1 个默认 + 3 个备选 图像生成方案，用户可通过环境变量 IMAGE_API 切换：

方案	工具	模型	环境变量	说明
🏠 默认	`ImageGen`	腾讯混元（WorkBuddy 内置）	无需配置	在 WorkBuddy 中直接调用 DeferExecuteTool
🏔️ 备选	`volcengine`	火山引擎即梦 Seedream 5.0 lite（字节跳动）	`ARK_API_KEY`（推荐）或 `VOLCENGINE_AK` + `VOLCENGINE_SK`	原扣子工作流用的字节生图，中文扁平风最优，支持去水印。使用前需在火山方舟控制台开通模型。已开通: 5.0 Pro / 5.0 lite / 4.5 / 4.0，默认 5.0 lite（`doubao-seedream-5-0-260128`）
🤖 备选	`gemini`	Google Gemini 3 Pro Image	`GEMINI_API_KEY`	细节丰富，语义理解强
✨ 备选	`agnes`	Agnes AI（完全免费）	`AGNES_API_KEY`	免费注册获取，OpenAI 兼容接口

切换方式：

WorkBuddy：默认使用 ImageGen。如需切换，设置 IMAGE_API=volcengine|gemini|agnes 后，脚本自动调用 scripts/generate_image.py 而非 ImageGen

CLI 平台（Codex CLI / OpenClaw）：直接运行 scripts/generate_image.py --api <方案>

# 单张生成
python3 scripts/generate_image.py --prompt "<desc_promopt>" --output "scene_000.png" --api volcengine

# 批量生成（从 storyboard.json）
python3 scripts/generate_image.py --batch storyboard.json --output-dir images/ --api gemini

无论使用哪个平台，图像生成的 prompt 统一使用分镜中的 desc_promopt 字段。

LLM 调用（阶段 1-3 用于生成文案和分镜）

所有平台均内置 LLM 对话能力，直接将 references/prompts.md 中的 System Prompt 发送给当前平台的 LLM 即可。

输入

参数	说明	必填
`book_name`	书籍名称	是
`author_name`	作者名称	是
`ip_name`	账号名称（用于封面图底部水印）	否，默认不显示

环境准备

执行前确保以下 Python 依赖已安装：

pip install edge-tts imageio-ffmpeg pillow

脚本会在首次运行时自动安装缺失的依赖，但建议预先安装以避免中断。

ffmpeg 由 imageio-ffmpeg 包自动提供二进制，无需单独安装系统级 ffmpeg。

TTS 引擎配置（可选）

引擎	凭证	时间戳	说明
火山引擎 TTS（默认）	`VOLC_TTS_API_KEY`	基于音频时长估算	豆包语音合成 2.0，中文自然度最高，1.2x 语速（匹配扣子工作流），可商用，需在火山引擎控制台获取 API Key
edge-tts（备选）	无需配置	WordBoundary 原生精确	微软免费 TTS，pip 安装即用，无凭证时自动回退

设置火山引擎凭证：

export VOLC_TTS_API_KEY="your-api-key"

未设置火山引擎凭证时，脚本自动使用 edge-tts，功能完整不受影响。火山引擎 TTS 2.0 不原生支持词级时间戳，脚本基于返回的音频时长按字符均匀估算时间戳（标点符号占比较短时间），字幕同步精度略低于 edge-tts 但完全可用。

完整工作流（5 个阶段）

阶段 1：生成书评文案

目标：根据书名+作者，用 LLM 生成约 1000 字的 3 分钟视频文案。

操作：

用当前平台的联网搜索工具搜索书籍真实信息（简介、解读、出版年份）
使用 system prompt（见 references/prompts.md 第 1 节），要求 LLM 输出 JSON：

{
  "book_name": "...",
  "author_name": "...",
  "year": "yyyy-MM",
  "content": "1000+字书评文案（含开篇引言+核心内容+观点提炼）",
  "category": "图书分类"
}

要点：

文案需满足约 3 分钟口播时长（约 700-1000 字）
开篇引言必须极具吸引力
信息来源需通过搜索获取，确保内容准确

阶段 2：生成分镜脚本

目标：将书评文案拆分为 8-50 个分镜，每个分镜包含字幕文案、画面描述、AI 图像提示词。

操作：使用 system prompt（见 references/prompts.md 第 2 节），输入阶段 1 的 content，输出：

{
  "list": [
    {
      "story_name": "分镜名称",
      "desc": "画面描述",
      "cap": "字幕文案（一句话）",
      "desc_promopt": "图像生成提示词"
    }
  ],
  "keywords": ["重点词1", "重点词2"]
}

然后在 list 开头插入引言分镜（模仿原工作流 node 150774 的逻辑）：

list.insert(0, {
    "story_name": "引言",
    "desc": "每日精读一本书",
    "cap": f"3分钟精读一本书，今天我们读《{book_name}》",
    "desc_promopt": "每日精读一本书"
})

风格约束：扁平插画风，人物卡通风简洁线条，背景扁平化符号，柔和明亮低饱和度色调。

阶段 3：生成标题进度条

目标：根据文案内容划分为 4 个板块，每板块 6 字以内标题，用于视频顶部进度条显示。

操作：使用 system prompt（见 references/prompts.md 第 3 节），输出 4 个标题（title1-title4）。

使用方式：4 个标题通过 segments.json 的 chapter_titles 字段传入 compose_video.py，在视频顶部渲染为进度条（当前板块橙色高亮 + 底部进度线）。同时需要 segment_chapters 字段指定每个分镜所属的板块索引（0-3），未指定时自动均匀分配。

阶段 4：生成素材（并行）

本阶段生成视频所需的全部素材：

4a. AI 插图生成

对每个分镜的 desc_promopt，调用图像生成工具生成插图。默认使用 WorkBuddy 内置的 ImageGen（腾讯混元模型），可通过环境变量 IMAGE_API 切换到备选方案。

统一风格参数（原工作流图像生成节点配置）：

尺寸：1024x768
风格：扁平风（flat illustration）
主角上衣 #FF7F72，裤子 #243139
30% 透明玻璃效果背景
负向提示词：无

方案选择与调用方式：

方案	`IMAGE_API` 值	调用方式	需要配置
🏠 腾讯混元（默认）	不设置或 `imagegen`	WorkBuddy 内置 `ImageGen` 工具	无
🏔️ 火山即梦	`volcengine`	`python3 scripts/generate_image.py --api volcengine`	`ARK_API_KEY`（推荐）或 `VOLCENGINE_AK` + `VOLCENGINE_SK`。默认用 Seedream 5.0 lite（`doubao-seedream-5-0-260128`），可通过 `VOLCENGINE_MODEL` 切换。5.0 lite 最小 2K 分辨率，代码自动升级
🤖 Google Gemini	`gemini`	`python3 scripts/generate_image.py --api gemini`	`GEMINI_API_KEY`
✨ Agnes AI	`agnes`	`python3 scripts/generate_image.py --api agnes`	`AGNES_API_KEY`

执行逻辑：

如果运行在 WorkBuddy 且未设置 IMAGE_API：直接调用 ImageGen 工具（DeferExecuteTool），参数 prompt = desc_promopt，size = "1024x768"
如果设置了 IMAGE_API=volcengine|gemini|agnes：调用 scripts/generate_image.py 脚本，自动安装依赖并通过 API 生成
如果运行在 CLI 平台（Codex CLI 等）：默认调用 scripts/generate_image.py --api gemini

生成的图片统一命名为 scene_000.png ~ scene_NNN.png，存放到 output/{book_name}/images/ 目录。

4b. TTS 语音合成

对每个分镜的 cap（字幕文案），使用 TTS 引擎生成 MP3 音频，同时生成词级时间戳（保存为同名 .words.json 文件，用于阶段 5 的逐句字幕精确同步）。

双引擎架构：

火山引擎 TTS（默认）：V1 API + X-Api-Key 认证，豆包语音合成 2.0 音色，中文自然度最高，可商用，需设置环境变量 VOLC_TTS_API_KEY
edge-tts（备选）：免费无需配置，原生 WordBoundary 词级时间戳，未设置火山引擎凭证时自动回退

默认音色：

火山引擎：zh_female_zhixingnv_uranus_bigtts（知性女声 2.0，适合读书解说）
edge-tts：zh-CN-XiaoxiaoNeural（晓晓，女声）

查看所有可用音色：python3 scripts/generate_audio.py --list-voices

运行（所有平台通用，自动选择引擎）：

python3 scripts/generate_audio.py --text "<字幕>" --output "audio_001.mp3"

指定引擎或音色：

# 强制使用火山引擎
python3 scripts/generate_audio.py --text "<字幕>" --output "audio_001.mp3" --engine volcano --voice zh_female_zhixingnv_uranus_bigtts

# 强制使用 edge-tts
python3 scripts/generate_audio.py --text "<字幕>" --output "audio_001.mp3" --engine edge --voice zh-CN-XiaoxiaoNeural

批量模式：

python3 scripts/generate_audio.py --batch captions.json --output-dir audio/ --voice "zh_female_zhixingnv_uranus_bigtts"

4c. 开场封面图

为视频第一帧生成专属封面图（1920x1080），包含书名、作者、品牌文字。

操作：运行 python3 scripts/generate_cover.py

# 用第一张分镜图做模糊背景（推荐，与视频风格一致）
python3 scripts/generate_cover.py \
  --book-name "原子习惯" \
  --author "James Clear" \
  --output output/原子习惯/images/cover.png \
  --bg output/原子习惯/images/scene_000.png

# 无背景图，使用深蓝渐变
python3 scripts/generate_cover.py \
  --book-name "原子习惯" \
  --author "James Clear" \
  --output output/原子习惯/images/cover.png

封面布局：

顶部：「3 分钟精读一本书」品牌文字 + 橙色分隔线（#FF7F72，与分镜主角上衣同色）
中部：书名大字（自动换行居中，80pt）
中下：作者名（42pt）
底部：账号名称水印（可选，通过 --ip-name 指定，不传则不显示）

字体：自动检测系统中文字体（Windows: 微软雅黑 / macOS: PingFang SC / Linux: Noto Sans CJK），无需手动修改。

封面图在阶段 5 合成时，通过 segments.json 中的 cover 字段指定，会在第一分镜前 cover_duration 秒（默认5秒）显示封面图，之后切换回原始分镜图（旁白全程不中断）。
{
  "output": "output/书名_三分钟精读书.mp4",
  "cover": "output/书名/images/cover.png",
  "chapter_titles": ["开篇引言", "核心方法", "实践技巧", "总结"],
  "segment_chapters": [0, 0, 0, 0, 1, 1, 1, 1, 1, 2, 2, 2, 2, 3, 3, 3],
  "keywords": ["原子习惯", "微小改变", "复利效应"],
  "bgm": "assets/bgm_reading.mp3",
  "bgm_volume": 0.15,
  "transition_sound": "assets/transition_page_flip.mp3",
  "transition_interval": 3,
  "transition_volume": 0.3,
  "segments": [
    {"image": "images/scene_000.png", "audio": "audio/audio_000.mp3", "caption": "字幕文本"},
    ...
  ]
}
cover：可选，封面图路径，在第一分镜前 cover_duration 秒显示，之后切回原始分镜图

cover_duration：可选，封面显示时长（秒），默认 5.0，仅作用于第一分镜前半段

chapter_titles：可选，板块标题列表，用于顶部进度条显示

segment_chapters：可选，每个分镜所属板块索引（0-based），未提供时自动均匀分配

keywords：可选，关键词列表，字幕中匹配到的关键词显示为橙色高亮

bgm：可选，背景音乐路径，未提供时自动查找 assets/bgm_reading.mp3，传空字符串禁用

bgm_volume：可选，BGM 音量 (0.0-1.0)，默认 0.15

transition_sound：可选，转场音效路径，未提供时自动查找 assets/transition_page_flip.mp3，传空字符串禁用

transition_interval：可选，每 N 个分镜添加一次转场音效，默认 3

transition_volume：可选，转场音效音量 (0.0-1.0)，默认 0.3

阶段 5：视频合成

目标：将所有素材合成为最终 MP4 视频。

操作：运行 python3 scripts/compose_video.py，该脚本执行：

计算每个分镜时长（基于 TTS 音频时长 + gap 间隔）
图片缩放/裁剪为 1920x1080（16:9）
为每个分镜添加 0.3s 淡入淡出转场（dip-to-black）
使用 ffmpeg 将图片+音频合成为视频片段
进度条 overlay：顶部显示板块标题（当前板块橙色高亮+实心圆点，其余灰色+空心圆点），底部进度线显示总体播放进度
生成逐句单行 ASS 字幕（基于 TTS 词级时间戳精确同步语音，按标点+字数拆分为单行短句，白色加粗文字+黑色描边，关键词橙色高亮，入场淡入+上滑/出场淡出动画）
拼接所有片段为完整视频
混音：将背景音乐（BGM）以低音量全程混合 + 每 3 个分镜在边界处叠加转场翻页音效

字幕参数（对应原工作流 add_captions_1 节点）：

字体颜色：白色 (#FFFFFF)
关键词高亮：橙色 (#FF7F72)，通过 ASS 内联颜色标签 {\c&H727FFF&} 实现
边框颜色：黑色 (#000000)
字号：64pt（加粗）
位置：底部居中（MarginV=30）
字体：自动检测系统可用中文字体（Windows: 微软雅黑 / macOS: PingFang SC / Linux: Noto Sans CJK SC），无需手动修改
字幕格式：ASS（Advanced SubStation Alpha），支持行内颜色标签+动画标签
逐句单行显示：利用 TTS 词级时间戳（火山引擎基于音频时长估算 / edge-tts WordBoundary 原生精确），将长字幕按标点拆分为单行短句，每句时间与语音同步
入场动画：淡入 200ms + 从下方 20px 上滑（ASS \fad + \move 标签）
出场动画：淡出 150ms（ASS \fad 标签）

进度条参数：

位置：画面顶部（80px 高度）
背景：半透明深色（alpha=130）
当前板块：橙色 (#FF7F72) 文字 + 实心圆点
非当前板块：灰色 (#AAAAAA) 文字 + 空心圆点
底部进度线：橙色填充 + 深灰底色，显示总体播放进度
字体：自动检测系统中文字体，44pt

动态效果参数：

转场淡入淡出时长：0.3s（短于 0.6s 的分镜自动减半）

音频混音参数：

背景音乐：assets/bgm_reading.mp3（3分56秒读书背景音乐，自动循环），音量 0.15
转场音效：assets/transition_page_flip.mp3（0.71s 翻页声效），每 3 个分镜在结尾前 0.5s 触发，音量 0.3
混音方式：ffmpeg amix 滤镜，BGM 循环播放 + 转场音效按时间点 adelay 叠加

📌 音频素材为可选：由于 SkillHub 不支持上传 .mp3 文件，音频素材未随技能打包。如果 assets/ 目录下没有这些文件，视频仍可正常生成（仅不含 BGM 和转场音效）。如需添加，请参考 assets/README.md 中的获取方式。

输出

最终输出：output/{book_name}_三分钟精读书.mp4

跨平台安装

WorkBuddy

技能已安装在 ~/.workbuddy/skills/book-video-generator/，直接使用。

OpenClaw

# 复制到 OpenClaw 技能目录
cp -r ~/.workbuddy/skills/book-video-generator ~/.openclaw/skills/

# 或通过 ClawHub 安装（如果已发布）
openclaw skills install book-video-generator

如需在 frontmatter 中声明图像生成 tool，参考 OpenClaw 文档的 tools 字段定义。

Codex CLI

# 1. 开启 Skills 功能（如未开启）
echo '[features]\nsskills = true' >> ~/.codex/config.toml

# 2. 复制技能目录
cp -r ~/.workbuddy/skills/book-video-generator ~/.codex/skills/

# 3. 重启 Codex CLI
# 4. 输入 /skills 确认技能已加载

Codex CLI 无内置图像生成，需在 scripts/ 目录中添加 generate_image.py 脚本，调用外部 API（如 OpenAI DALL-E、Stability AI）。脚本需接受 --prompt 和 --output 参数。

TRAE Work

1. 打开 TRAE Work → 规则和技能 → 技能 → 创建 → 导入文件
2. 上传 SKILL.md 文件
3. 确保 scripts/ 和 references/ 目录也复制到技能目录

TRAE Work 通过 MCP 接入图像生成服务。在 TRAE 的 MCP 配置中添加火山引擎或通义万相的图像生成 MCP，然后在执行阶段 4a 时通过 MCP 调用。

原工作流参考

原始扣子工作流文件位于 references/workflow-original.yaml，包含 30+ 节点的完整链路：

开始 → LLM(DeepSeek V3.2)生成书评 → 上标题总结 → 分镜画面描述
→ 代码拼接引言 → 批量图像生成+抠图 → TTS语音合成
→ 创建剪映草稿 → 批量添加图片/字幕/音频 → 保存草稿 → 结束

原始流程依赖剪映小助手插件（视频合成核心）、扣子内置图像生成+抠图和TTS插件。本 Skill 使用 ffmpeg、edge-tts、平台图像生成工具替代。

快速使用示例

用户说："帮我生成《原子习惯》James Clear 的 3 分钟精读视频"

执行流程：

搜索"原子习惯 James Clear 简介书评"
用阶段 1 prompt 生成书评文案
用阶段 2 prompt 生成分镜脚本
用阶段 3 prompt 生成标题进度条
对每个分镜：图像生成工具生成插图 + TTS 生成配音（火山引擎默认 / edge-tts 备选）
compose_video.py 合成最终视频
输出 output/原子习惯_三分钟精读书.mp4

资源文件

references/prompts.md — 所有 LLM 提示词原文（平台无关，可直接复用）
references/workflow-original.yaml — 原始扣子工作流（完整 YAML 备份）
scripts/compose_video.py — 视频合成脚本（纯 Python + ffmpeg，跨平台，含淡入淡出转场 + 字体自动检测 + 封面图支持 + 逐句单行 ASS 字幕精确语音同步 + 关键词高亮 + 入场/出场动画 + 顶部进度条 + BGM 背景音乐混音 + 转场音效）
scripts/generate_audio.py — TTS 语音生成脚本（纯 Python，双引擎：火山引擎 TTS V1 API + X-Api-Key 默认 1.2x 语速 / edge-tts 备选 +20% 语速，含词级时间戳输出，自动检测凭证切换引擎）
scripts/generate_cover.py — 封面图生成脚本（纯 Python + Pillow，自动换行 + 模糊背景 + 字体自动检测）