Skill: casperkwok/toonany (version 1.1.1)

--- name: toonany description: A Claude Code skill for creating AI-generated short dramas (漫剧) from novels and stories. Use when user mentions "漫剧创作", "小说转剧本", "分镜生成", "短剧制作", "故事线生成", "大纲创作", "AI视频", or wants to produce video content from written stories. Activates for tasks involving novel-to-drama conversion, script writing, storyboarding, or complete video production workflows. version: "1.1.0" metadata: openclaw: requires: env: - DEEPSEEK_API_KEY - VOLC_API_KEY - VOLC_TTS_API_KEY bins: - python3 - ffmpeg primaryEnv: DEEPSEEK_API_KEY --- # Toonany - AI漫剧创作助手 Toonany helps anyone turn any story into an AI-generated short drama through a guided production pipeline. **核心理念**: Any story, any style, anyone. ## 快速开始（新手推荐） 从未用过？只需两步： 1. **创建项目**: `/toonany new 我的漫剧` 2. **快速出片**: `/toonany quick`（跟随引导完成全部流程） ## 命令列表 ### 通用命令 | 命令 | 说明 | |------|------| | `/toonany new <name>` | 创建新项目，交互式配置 | | `/toonany config` | 检查/配置 API 密钥，缺失时自动引导 | | `/toonany validate` | 运行全量校验（结构 + 一致性） | | `/toonany export` | 导出完整项目 | ### 快速模式 | 命令 | 说明 | |------|------| | `/toonany quick` | 单命令交互式全流程，30分钟出片 | ### 专业模式（分阶段精细控制） | 命令 | 说明 | |------|------| | `/toonany story` | 生成/修改故事线 | | `/toonany outline [ep]` | 生成/修改分集大纲 | | `/toonany assets` | 提取/生成角色、场景、道具资产 | | `/toonany style-sample` | 生成风格样张，确认后再批量生产 | | `/toonany script [ep]` | 生成剧本 | | `/toonany storyboard [ep]` | 生成分镜 | | `/toonany storyboard-image [ep]` | 生成分镜图 | | `/toonany video [ep]` | 生成视频 | | `/toonany audio [ep]` | 生成配音和字幕 | | `/toonany finalize [ep]` | 后期合成（拼接+混音+字幕烧录） | ## 前置检查（自动执行） 执行任何命令前，Toonany 会自动检查： 1. **项目存在**: 是否在有效的 toonany 项目目录中？ 2. **API 配置**: 当前步骤所需的模型 API Key 是否已配置？ - 未配置 → **自动引导**: 告诉用户去哪里申请、怎么设置 3. **上游依赖**: 当前步骤所需的输入文件是否存在？ - 不存在 → 提示用户先完成上游步骤 4. **变更传播**: 上游文件是否已更新？ - 已更新 → 提示用户下游产物可能已过期，建议重新生成 ## 生产流程 ``` 小说原文 → 故事线 → 大纲 → 资产 → 风格样张 → 剧本 → 分镜 → 分镜图 → 视频 → 音频/字幕 → 成片 1) 2) 3) 4) 5) 6) 7) 8) 9) 10) 11) ``` ### 快速模式流程 ``` /toonany quick → 询问小说内容 → 询问风格/比例/集数 → 自动生成故事线 + 大纲（第1集） → 自动生成资产 → **生成风格样张 → 用户确认** → 批量生成分镜图 → 生成视频 → 生成音频/字幕 → 后期合成输出成片 ``` ### 专业模式流程 用户逐步控制每个阶段，每步可审、可改、可回退。 ## 数据模型 ### Project ```json { "name": "项目名称", "type": "都市/古风/悬疑/科幻", "artStyle": "2D动漫风格/真人写实/吉卜力", "videoRatio": "16:9/9:16/1:1", "episodeCount": 12, "styleReference": "assets/style-sample.jpg", "versions": {}, "models": { "text": { "provider": "deepseek", "model": "deepseek-chat", "apiKey": "${DEEPSEEK_API_KEY}" }, "image": { "provider": "volcengine", "model": "doubao-seedream-4-5", "apiKey": "${VOLC_API_KEY}" }, "video": { "provider": "kling", "model": "kling-v1-pro", "apiKey": "${KLING_API_KEY}" }, "audio": { "provider": "volcengine", "model": "...", "apiKey": "${VOLC_TTS_API_KEY}" } }, "characters": [ {"name": "角色名", "seed": 12345, "voiceType": "...", "consistencyId": "..."} ] } ``` ### 项目结构 ``` output/{project-name}/ ├── project.json # 项目元数据 ├── storyline.md # 故事线 ├── outline/ │ ├── outline-01.md # 第1集大纲 │ └── ... ├── assets/ │ ├── characters.md # 角色资产（详细描述） │ ├── props.md # 道具资产 │ ├── scenes.md # 场景资产 │ ├── data.json # 资产数据（程序格式） │ ├── images/ │ │ ├── characters/ # 角色四视图 + 单张 │ │ ├── props/ # 道具图 │ │ └── scenes/ # 场景图 │ └── style-sample.jpg # 风格样张 ├── script/ │ ├── script-01.md # 第1集剧本 │ └── ... ├── storyboard/ │ ├── storyboard-01.md # 第1集分镜 │ └── images/ # 分镜图 ├── video/ │ └── ep01-*.mp4 # 生成的视频片段 ├── audio/ │ └── ep01/ # 音频文件 ├── subtitle/ │ └── ep01.srt # 字幕文件 └── final/ └── episode01.mp4 # 最终成片 ``` ## 新手引导 ### 第一次使用？ 1. 执行 `/toonany new 我的项目` 2. 系统会创建项目并检查 API Key 3. 如果缺少 API Key，会自动显示引导信息： - 告诉你需要哪些 provider - 提供申请链接 - 告诉你怎么设置环境变量 4. 配置完成后，执行 `/toonany quick` 开始创作 ### 缺少 API Key 时的引导示例 ``` 检测到缺少图像生成 API Key（火山引擎）。 请按以下步骤配置： 1. 访问 https://console.volcengine.com/ark/ 注册账号 2. 开通方舟大模型服务 3. 创建 API Key 4. 在终端执行: export VOLC_API_KEY=你的密钥 配置完成后，请告诉我"已配置"，我会继续。 ``` ## 质量保障 ### 自动化检查 - **结构校验**: 检查项目目录和必需字段 - **一致性校验**: 检查角色名、场景名、道具名在全文中是否一致 - **风格漂移检测**: 对比不同阶段的风格描述是否一致 ### 风格锚定 每部漫剧必须有1张**风格样张**作为视觉锚点。所有后续生成强制引用该样张，确保风格统一。 ### 角色一致性 每个角色生成**四视图参考图**（正面、侧面、背面、特写），记录 seed 值。后续生成时复用 seed 和参考图，最大限度保持角色外观一致。 ## 模型配置 支持的 provider： | 类型 | Provider | 用途 | |------|----------|------| | text | deepseek, openai, anthropic, gemini | 故事线、大纲、剧本 | | image | volcengine, kling, gemini | 资产图、分镜图 | | video | kling, volcengine, vidu, gemini | 视频生成 | | audio | volcengine, aliyun, edge-tts | 配音 | 在 `project.json` 的 `models` 字段中配置。API Key 推荐使用环境变量：`${ENV_VAR_NAME}`。 ## 参考资料 - [详细教程](TUTORIAL.md) - 完整使用指南 - [数据模型](references/data-model.md) - 完整数据结构 - [生产流程](references/workflow.md) - Pipeline详解 - [模型配置](references/model-config.md) - AI模型配置指南 - [命令参考](references/commands.md) - 完整命令说明

path: CHANGELOG.md
content: # Changelog

## 1.1.0 (2026-05-02)

### Features
- **Volcengine video generation support**: Added full support for Volcengine Ark video generation API (`doubao-seedance-2-0-260128`)
- **Unified video provider**: Video and image generation now both use `VOLC_API_KEY`
- **Provider-aware VideoAPIClient**: Automatically switches between Kling and Volcengine API formats
- **Updated DeepSeek models**: Default text model changed from `deepseek-chat` to `deepseek-v4-pro` (old names deprecated 2026-07-24)

### API Changes
- Video endpoint: `POST /contents/generations/tasks` (Volcengine)
- Video query: `GET /contents/generations/tasks/{task_id}` (Volcengine)
- Image references use `role: "reference_image"` for Volcengine

## 1.0.0 (2026-05-01)

### Features
- Complete rewrite from toonvid with new architecture
- **Quick Mode**: Single-command interactive workflow for beginners
- **Craft Mode**: Stage-by-stage professional control
- **Friendly onboarding**: Guided API key setup with provider-specific instructions
- **Style anchor mechanism**: Style sample confirmation before batch generation
- **Character consistency**: Four-view reference sheets with seed locking
- **Dependency tracking**: Automatic stale file detection when upstream changes
- **Cross-platform**: Pure Python scripts, no BSD/GNU tool dependencies
- **Unified API client**: Single client for image/video/TTS with retry logic
- **Post-processing pipeline**: Video concatenation + audio mixing + subtitle burn-in
- **Quality gates**: Automated consistency checks across all stages
- **Preset styles**: 20+ built-in art styles for quick selection

### Security
- No hardcoded API tokens
- Environment variable support with `${ENV_VAR}` syntax
- No secrets in project files

### Architecture
- Modular script design with shared utilities
- Template-based project initialization
- Provider-agnostic API layer
- Sentence-level subtitle generation (not word-level)


path: README.md
content: # Toonany — AI 漫剧创作助手

**Any story, any style, anyone.**

[![ClawHub](https://img.shields.io/badge/ClawHub-Install-blue)](https://clawhub.ai/casperkwok/toonany)

Toonany 是一个 [Claude Code Skill](https://clawhub.ai/casperkwok/toonany)，帮助任何人将小说或故事转化为 AI 生成的漫剧（短剧/动画）。无论你是新手还是专业创作者，都能快速产出高质量的视觉叙事内容。

> **核心理念**: 任何故事 × 任何风格 × 任何人 = 一部漫剧。
>
> 从一段文字到一段带配音、字幕、背景音乐的成片，最快 30 分钟。

---

## 适用场景

- **网文作者**: 将热门章节转化为短视频内容，引流涨粉
- **自媒体运营**: 批量生产小说推文视频，多平台分发
- **独立创作者**: 低成本实现个人动画/短剧创作
- **教育/培训**: 将教案、案例转化为生动的视频教材
- **品牌营销**: 用故事化视频传递品牌理念

## 完整工作流

```
小说原文
    ↓
故事线 (storyline) —— 核心情节脉络
    ↓
分集大纲 (outline) —— 每集场景拆分
    ↓
资产提取 (assets) —— 角色、场景、道具定义
    ↓
风格样张 (style-sample) —— 视觉锚点确认
    ↓
剧本 (script) —— 对白、旁白、镜头描述
    ↓
分镜 (storyboard) —— 镜头序列 + 画面描述
    ↓
分镜图 (storyboard-image) —— AI 生成每帧画面
    ↓
视频 (video) —— 图片转动态视频
    ↓
音频/字幕 (audio) —— AI 配音 + 自动字幕
    ↓
后期合成 (finalize) —— 拼接 + 混音 + 字幕烧录
    ↓
成片输出 🎬
```

## 核心设计原则

| 原则 | 说明 |
|------|------|
| **风格锚定** | 批量生成前先确认风格样张，杜绝风格漂移 |
| **角色一致** | 四视图参考图 + seed 锁定，跨集不变脸 |
| **变更传播** | 修改上游自动提示下游重算，避免版本错乱 |
| **质量校验** | 自动检查角色名一致性、场景一致性、风格一致性 |
| **新手友好** | 缺什么补什么，不会卡住，全程引导 |

## 特点

- **新手友好**: 引导式交互，缺什么补什么，不会卡住
- **快速出片**: `/toonany quick` 单命令走完完整流程
- **风格锚定**: 先确认风格样张，再批量生成，确保风格统一
- **角色一致**: 四视图参考图 + seed 锁定，跨集不变脸
- **完整管线**: 从小说到成片（含配音、字幕、混音）一站式完成
- **跨平台**: 纯 Python 脚本，Windows/macOS/Linux 通用

## 5 分钟快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 创建项目

在 Claude Code 中执行：

```
/toonany new 我的漫剧项目
```

系统会交互式询问项目信息，并自动检查 API Key 配置。

### 3. 快速出片（推荐新手）

```
/toonany quick
```

跟随引导：
1. 提供小说内容（直接粘贴或上传文件）
2. 选择风格（从 20+ 种预设风格中选择）
3. 等待生成...
4. **确认风格样张**（关键步骤！确保风格符合预期）
5. 继续生成，最终输出成片

### 4. 专业模式（推荐有经验的用户）

分阶段精细控制：

```
/toonany story           # 生成故事线
/toonany outline 1       # 生成第1集大纲
/toonany assets          # 提取资产
/toonany style-sample    # 生成风格样张
/toonany script 1        # 生成剧本
/toonany storyboard 1    # 生成分镜
/toonany storyboard-image 1  # 生成分镜图
/toonany video 1         # 生成视频
/toonany audio 1         # 生成配音和字幕
/toonany finalize 1      # 后期合成成片
```

## 项目结构

```
output/{project-name}/
├── project.json          # 项目配置
├── storyline.md          # 故事线
├── outline/              # 分集大纲
├── assets/               # 角色/场景/道具
│   ├── images/           # 资产图片
│   └── style-sample.jpg  # 风格样张
├── script/               # 剧本
├── storyboard/           # 分镜
├── video/                # 视频片段
├── audio/                # 配音
├── subtitle/             # 字幕
└── final/                # 最终成片
```

## 核心命令速查

| 命令 | 用途 |
|------|------|
| `/toonany new <name>` | 创建项目 |
| `/toonany config` | 配置 API Key |
| `/toonany quick` | 快速模式（一键出片） |
| `/toonany validate` | 校验项目 |
| `/toonany export` | 导出项目 |

## 常见问题

### Q: 没有 API Key 怎么办？
A: 执行 `/toonany config`，系统会自动检测缺失的 Key 并给出申请链接和配置指引。

### Q: 生成的角色在多集中不一致怎么办？
A: Toonany 使用四视图参考图 + seed 锁定机制。在 `project.json` 中检查角色的 `seed` 字段是否一致。如需调整，修改后重新运行 `/toonany assets`。

### Q: 风格不满意怎么办？
A: 在批量生成前，Toonany 会生成风格样张供你确认。如果不满意，可以修改 `project.json` 中的 `artStyle` 字段，然后重新运行 `/toonany style-sample`。

### Q: 修改了大纲，后续文件会联动更新吗？
A: Toonany 有依赖追踪机制。修改上游文件后，执行 `/toonany validate` 会提示哪些下游文件需要重新生成。

## 模型支持

| 类型 | 推荐 Provider | 说明 |
|------|--------------|------|
| 文本 | DeepSeek | 性价比高，适合大纲和剧本 |
| 图像 | 火山引擎 (豆包) | 支持宫格图，适合分镜 |
| 视频 | 可灵 / 豆包 | 支持多种生成模式 |
| 音频 | 豆包 TTS | 音色丰富，支持情感 |

## 安装方式

### 通过 ClawHub 安装（推荐）

在 Claude Code 中执行：

```bash
clawhub install toonany
```

或直接访问 👉 **[clawhub.ai/casperkwok/toonany](https://clawhub.ai/casperkwok/toonany)** 安装。

### 手动安装

将本仓库克隆到 `~/.claude/skills/toonany/` 目录：

```bash
git clone https://github.com/casperkwok/toonany.git ~/.claude/skills/toonany
```

## 了解更多

- [详细教程](TUTORIAL.md) — 完整使用指南
- [数据模型](references/data-model.md)
- [生产流程](references/workflow.md)
- [模型配置](references/model-config.md)
- [命令参考](references/commands.md)

---

**ClawHub**: [clawhub.ai/casperkwok/toonany](https://clawhub.ai/casperkwok/toonany)  
**GitHub**: [github.com/casperkwok/toonany](https://github.com/casperkwok/toonany)


path: TUTORIAL.md
content: # Toonany 使用教程

Toonany 是一款 AI 漫剧创作助手，能够将小说自动转化为短剧内容。本教程将详细介绍如何使用 Toonany 完成从小说原文到完整漫剧的创作流程。

---

## 1. 简介

### 什么是 Toonany

Toonany 是一个基于 AI 的漫剧创作系统，核心理念是 **"Any story, any style, anyone"** —— 任何人都能把任何故事变成任何风格的漫剧。

### 核心特点

- **新手友好**: 引导式交互，缺什么补什么
- **快速模式**: `/toonany quick` 单命令走完完整流程
- **风格锚定**: 先确认风格样张，再批量生成，确保风格统一
- **角色一致**: 四视图参考图 + seed 锁定，跨集不变脸
- **完整管线**: 从小说到成片（含配音、字幕、混音）一站式完成

### 适用场景

- 网络小说作者将作品改编为短剧
- 内容创作者快速生成视频脚本和分镜
- 影视团队进行剧本开发和视觉预览
- AI 视频制作团队的工作流程管理

---

## 2. 安装

### 前提条件

- Python 3.9+
- ffmpeg（用于后期合成）

### 安装 ffmpeg

```bash
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# Windows (使用 chocolatey)
choco install ffmpeg
```

### 安装 Python 依赖

```bash
cd ~/.claude/skills/toonany
pip install -r requirements.txt
```

### 验证安装

```bash
python scripts/init_project.py --help
```

---

## 3. 快速开始

### 3.1 创建项目

```
/toonany new 我的漫剧项目
```

系统会交互式询问：
- 项目类型（都市/古风/悬疑/科幻等）
- 艺术风格（从预设列表选择或自定义）
- 视频比例（16:9/9:16/1:1等）
- 计划集数

### 3.2 配置 API Key

首次使用时，系统会自动检测缺失的 API Key 并给出引导：

```
检测到以下 API Key 未配置：

【DeepSeek】- 用于 text 生成
申请地址: https://platform.deepseek.com/api_keys
配置步骤:
1. 访问 https://platform.deepseek.com 注册账号
2. 进入 API Keys 页面创建密钥
3. 复制密钥并执行: export DEEPSEEK_API_KEY=sk-xxx

配置完成后，请告诉我"已配置"，我会继续执行。
```

设置环境变量：
```bash
export DEEPSEEK_API_KEY="sk-xxx"
export VOLC_API_KEY="xxx"
export KLING_API_KEY="xxx"
export VOLC_TTS_API_KEY="xxx"
```

### 3.3 快速出片（推荐新手）

```
/toonany quick
```

跟随引导：
1. 提供小说内容（直接粘贴或上传文件）
2. 选择风格（从 20+ 种预设风格中选择）
3. 等待生成故事线和大纲
4. **确认风格样张**（关键步骤！确保风格符合预期）
5. 继续生成，最终输出成片

### 3.4 专业模式（推荐有经验的用户）

分阶段精细控制：

```
/toonany story           # 生成故事线
/toonany outline 1       # 生成第1集大纲
/toonany assets          # 提取资产
/toonany style-sample    # 生成风格样张
/toonany script 1        # 生成剧本
/toonany storyboard 1    # 生成分镜
/toonany storyboard-image 1  # 生成分镜图
/toonany video 1         # 生成视频
/toonany audio 1         # 生成配音和字幕
/toonany finalize 1      # 后期合成成片
```

---

## 4. 项目结构

```
output/{project-name}/
├── project.json              # 项目配置（含模型配置、角色seed等）
├── storyline.md              # 故事线
├── outline/                  # 分集大纲
│   ├── outline-01.md
│   └── ...
├── assets/                   # 资产
│   ├── characters.md         # 角色资产
│   ├── props.md              # 道具资产
│   ├── scenes.md             # 场景资产
│   ├── data.json             # 资产数据（程序格式）
│   ├── images/               # 资产图片
│   │   ├── characters/       # 角色四视图
│   │   ├── props/            # 道具图
│   │   └── scenes/           # 场景图
│   └── style-sample.jpg      # 风格样张（视觉锚点）
├── script/                   # 剧本
│   ├── script-01.md
│   └── ...
├── storyboard/               # 分镜
│   ├── storyboard-01.md      # 分镜文档
│   └── images/               # 分镜图
├── video/                    # 视频片段
│   └── ep01-*.mp4
├── audio/                    # 音频
│   └── ep01/
├── subtitle/                 # 字幕
│   └── episode01.srt
└── final/                    # 最终成片
    └── episode01.mp4
```

### project.json 说明

```json
{
  "name": "项目名称",
  "type": "都市",
  "artStyle": "2D动漫风格",
  "videoRatio": "16:9",
  "episodeCount": 12,
  "styleReference": "assets/style-sample.jpg",
  "versions": {},
  "models": {
    "text": {
      "provider": "deepseek",
      "model": "deepseek-chat",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "baseUrl": "https://api.deepseek.com"
    },
    "image": {
      "provider": "volcengine",
      "model": "doubao-seedream-4-5",
      "apiKey": "${VOLC_API_KEY}",
      "baseUrl": "https://ark.cn-beijing.volces.com/api/v3"
    },
    "video": {
      "provider": "kling",
      "model": "kling-v1-pro",
      "apiKey": "${KLING_API_KEY}"
    },
    "audio": {
      "provider": "volcengine",
      "model": "zh_male_shaonianzixin_uranus_bigtts",
      "apiKey": "${VOLC_TTS_API_KEY}",
      "baseUrl": "https://openspeech.bytedance.com/api/v3/tts"
    }
  },
  "characters": [
    {
      "name": "角色名",
      "seed": 12345,
      "voiceType": "zh_male_shaonianzixin_uranus_bigtts",
      "filePath": "images/characters/角色名_grid.jpg"
    }
  ]
}
```

**重要字段说明**：
- `styleReference`: 风格样张路径，所有生成强制引用
- `versions`: 文件版本追踪，用于变更传播
- `characters[].seed`: 角色图像生成种子，确保一致性
- `characters[].voiceType`: 角色配音音色

---

## 5. 详细流程说明

### 5.1 故事线生成

Claude 分析小说内容，生成故事主线文档：

- **主题定位**: 一句话概括核心主题
- **主线剧情**: 2-3段概括主要剧情走向
- **人物关系**: 主要人物关系图或列表
- **情感基调**: 整体情感氛围描述

### 5.2 大纲生成

指定要生成的集数范围，系统生成分集大纲：

每集包含：
- **标题**: 8字以内，疑问/感叹句，含情绪爆点
- **章节范围**: 关联的原文章节号
- **核心矛盾**: `A 想要 X vs B 阻碍 X`
- **剧情主干**: 100-300字，按时间顺序
- **开场镜头**: 第一个视觉画面描述
- **剧情节点**: 【起】【承】【转】【合】四个事件
- **情绪曲线**: 如 `2→5→9→3`
- **视觉重点**: 3-5个标志性镜头
- **结尾悬念**: 下集预告钩子
- **角色/场景/道具**: 按出场顺序列出

### 5.3 资产提取与生成

系统自动提取三类资产：

- **角色资产**: 姓名、外貌、性格、服装、seed
- **道具资产**: 名称、外观、象征意义
- **场景资产**: 名称、环境、光线氛围

每个角色生成**四视图参考图**（正面、侧面、背面、特写），使用相同 seed 确保一致性。

### 5.4 风格样张（关键质量控制点）

在批量生成前，先生成 1-2 张风格样张：

```
/toonany style-sample
```

用户确认风格后，后续所有生成强制引用该样张作为参考图。如果不满意，修改 `artStyle` 后重新生成。

### 5.5 剧本创作

基于大纲生成详细对白剧本，格式规范：

- 纯文本格式，使用分镜符号（※ $ △ 【】等）
- 无 Markdown 语法
- 角色描述仅限服化道，禁止样貌描写
- 所有描写必须具体可拍摄

### 5.6 分镜设计

将剧本转化为可视化分镜：

- 每个分镜包含多个镜头（默认4个）
- 每个镜头标注：景别、角度、构图、光线、色彩、氛围
- 新增：建议时长、运镜方式（影响视频生成）

### 5.7 分镜图生成

使用图像模型生成分镜图：

- 强制引用风格样张
- 引用角色/场景参考图
- 生成宫格图后自动拆分为单张镜头图

### 5.8 视频生成

使用视频模型生成片段：

支持模式：
| 模式 | 说明 |
|------|------|
| text | 文生视频 |
| single | 单图生视频（最常用） |
| startEnd | 首尾帧模式 |
| multi | 多图参考模式 |

### 5.9 音频与字幕

- TTS 生成配音，按角色分配不同音色
- 字粒度时间戳智能合并为**句子级字幕**
- 支持情感标签

### 5.10 后期合成

```
/toonany finalize 1
```

自动执行：
1. 拼接视频片段
2. 混音（BGM + 配音 + 音效）
3. 字幕烧录
4. 输出最终成片

---

## 6. 常见问题

### Q: 没有 API Key 怎么办？

A: 执行 `/toonany config`，系统会自动检测缺失的 Key 并给出申请链接和配置指引。

### Q: 生成的角色在多集中不一致怎么办？

A: Toonany 使用四视图参考图 + seed 锁定机制。在 `project.json` 中检查角色的 `seed` 字段是否一致。如需调整，修改后重新运行 `/toonany assets`。

### Q: 风格不满意怎么办？

A: 在批量生成前，Toonany 会生成风格样张供你确认。如果不满意，可以修改 `project.json` 中的 `artStyle` 字段，然后重新运行 `/toonany style-sample`。

### Q: 修改了大纲，后续文件会联动更新吗？

A: Toonany 有依赖追踪机制。修改上游文件后，执行 `/toonany validate` 会提示哪些下游文件需要重新生成。你也可以手动重新运行对应阶段的命令。

### Q: 支持哪些视频比例？

- `16:9` - 横向标准视频
- `9:16` - 纵向短视频
- `1:1` - 方形
- `4:3` - 经典比例
- `3:4` - 纵向 3:4
- `21:9` - 宽银幕

### Q: 如何处理长篇小说？

对于长篇小说，建议分批处理：

1. 先导入前几章内容，生成故事线和前几集大纲
2. 确认风格和方向后，再导入后续章节
3. 可以针对特定章节范围生成大纲

### Q: 生成的提示词不理想怎么办？

1. **调整艺术风格**: 不同的 artStyle 会影响生成的提示词风格
2. **手动优化**: 在生成资产后，手动修改 `assets/` 目录下的提示词
3. **自定义提示词模板**: 修改 `prompts/assets/` 下的润色提示词文件

---

## 7. 命令参考

| 命令 | 说明 |
|------|------|
| `/toonany new <name>` | 创建新项目 |
| `/toonany config` | 配置/检查 API Key |
| `/toonany quick` | 快速模式（一键出片） |
| `/toonany story` | 生成故事线 |
| `/toonany outline [ep]` | 生成/修改分集大纲 |
| `/toonany assets` | 提取/生成资产 |
| `/toonany style-sample` | 生成风格样张 |
| `/toonany script [ep]` | 生成剧本 |
| `/toonany storyboard [ep]` | 生成分镜 |
| `/toonany storyboard-image [ep]` | 生成分镜图 |
| `/toonany video [ep]` | 生成视频 |
| `/toonany audio [ep]` | 生成配音和字幕 |
| `/toonany finalize [ep]` | 后期合成成片 |
| `/toonany validate` | 运行全量校验 |
| `/toonany export` | 导出项目 |

---

## 8. 脚本直接调用

除了通过 Claude Code 命令使用，你也可以直接调用 Python 脚本：

```bash
# 初始化项目
python scripts/init_project.py -i

# 生成资产
python scripts/generate_assets.py -p output/我的项目

# 生成分镜图
python scripts/generate_storyboard_images.py -p output/我的项目 -s storyboard-01.md

# 生成视频
python scripts/generate_video.py -p output/我的项目 --mode single

# 生成音频
python scripts/generate_audio.py -p output/我的项目 --episode 1

# 后期合成
python scripts/post_process.py -p output/我的项目 --episode 1

# 校验
python scripts/validate_project.py -p output/我的项目
python scripts/validate_consistency.py -p output/我的项目
```

---

## 9. 进阶技巧

### 自定义音色

在 `project.json` 中为每个角色配置 `voiceType`：

```json
{
  "characters": [
    {
      "name": "王林",
      "voiceType": "zh_male_shaonianzixin_uranus_bigtts",
      "voiceEmotion": "neutral"
    },
    {
      "name": "云梦",
      "voiceType": "zh_female_qingxin_wanquanxiaohe",
      "voiceEmotion": "gentle"
    }
  ]
}
```

### 批量生成多集

```bash
for i in {1..5}; do
  python scripts/generate_video.py -p output/我的项目 --episode $i
done
```

### 使用不同模型

修改 `project.json` 中的 `models` 配置即可切换不同 provider。

---

如需更多技术细节，请参考：

- [数据模型参考](references/data-model.md)
- [生产流程详解](references/workflow.md)
- [模型配置指南](references/model-config.md)
- [命令参考](references/commands.md)


path: config/default-project.json
content: {
  "name": "{{PROJECT_NAME}}",
  "type": "都市",
  "artStyle": "2D动漫风格",
  "videoRatio": "16:9",
  "episodeCount": 1,
  "chapters": [],
  "styleReference": null,
  "versions": {},
  "models": {
    "text": {
      "provider": "deepseek",
      "model": "deepseek-v4-pro",
      "apiKey": "${DEEPSEEK_API_KEY}",
      "baseUrl": "https://api.deepseek.com"
    },
    "image": {
      "provider": "volcengine",
      "model": "doubao-seedream-4-5-251128",
      "apiKey": "${VOLC_API_KEY}",
      "baseUrl": "https://ark.cn-beijing.volces.com/api/v3"
    },
    "video": {
      "provider": "volcengine",
      "model": "doubao-seedance-2-0-260128",
      "apiKey": "${VOLC_API_KEY}",
      "baseUrl": "https://ark.cn-beijing.volces.com/api/v3"
    },
    "audio": {
      "provider": "volcengine",
      "model": "zh_male_shaonianzixin_uranus_bigtts",
      "apiKey": "${VOLC_TTS_API_KEY}",
      "baseUrl": "https://openspeech.bytedance.com/api/v3/tts"
    }
  },
  "characters": [],
  "scenes": [],
  "props": []
}

path: prompts/_shared/quality-check.md
content: ## 质量检查清单

生成内容后，请自检以下要点：

### 叙事一致性
- [ ] 角色名称在全文中保持一致
- [ ] 场景描述相互匹配
- [ ] 剧情逻辑连贯
- [ ] 情绪曲线合理
- [ ] 经典台词符合角色性格

### 格式规范
- [ ] 提示词具体且可执行
- [ ] 每个分镜包含景别+角度+构图
- [ ] 角色描述不包含样貌（年龄/五官/身材），仅限服化道
- [ ] 时间使用具体词汇（清晨/正午/黄昏），不用笼统的"日/夜"
- [ ] 无抽象描写（气氛尴尬、心中五味杂陈等），全部转化为具体画面

### 资产引用
- [ ] 角色/场景/道具名称与 data.json 完全一致
- [ ] 无缩写、无近义词替换


path: prompts/assets/character-generate-image.md
content: # 角色图像生成

你是角色参考图生成专家。你的唯一任务是生成图像，不输出任何文字说明。

## 生成规则

### 绝对禁止
1. **图像中禁止出现任何文字** - 无标签、无注释、无水印
2. **纯白背景** - RGB(255,255,255)，无地面、无环境元素
3. **空手** - 禁止手持任何道具

### 四视图布局（固定顺序）
生成一张 2x2 网格图：

| 位置 | 视图 | 要求 |
|------|------|------|
| 左上 | 头部特写 | 头顶到锁骨，清晰面部特征，中性表情 |
| 右上 | 正面全身 | 从头到脚完整，双臂自然下垂 |
| 左下 | 侧面全身 | 90°左侧面，从头到脚完整 |
| 右下 | 背面全身 | 180°背面，从头到脚完整 |

### 姿态与表情
- 完全中性表情，不笑不皱眉
- 标准直立站姿，双臂自然下垂
- 双手完全空手

### 质量要求
- 与指定画风一致
- 四视图中角色外观完全一致（仅角度不同）
- 柔和均匀光照，无强烈阴影


path: prompts/assets/character-polish.md
content: # 角色润色

你是一位角色设计专家，负责将大纲中的角色描述转化为专业的 AI 图像生成提示词。

## 输入
角色名称和描述（来自大纲）。

## 输出格式

```markdown
## {角色名}

### 基础信息
- 性别/年龄: 
- 身份背景: 

### 外貌特征
- 发型发色: 
- 面部特征: 
- 身材体型: 
- 标志性特征: 

### 服装造型
- 主要服装: 
- 配饰道具: 
- 服装状态: 

### 性格气质
- 性格关键词: 
- 表情特征: 
- 肢体语言: 

### AI 绘图提示词
{详细的英文提示词，包含画风、角色特征、服装、姿态等}
```

## 规则
- 提示词必须具体，避免抽象描述
- 包含画风关键词
- 保持角色之间视觉区分度


path: prompts/assets/prop-generate-image.md
content: # 道具图像生成

你是道具设计图生成专家。你的唯一任务是生成图像，不输出任何文字说明。

## 生成规则

### 绝对禁止
1. **图像中禁止出现任何文字**
2. **纯白背景** - 突出道具本身

### 画面要求
- 道具居中，完整呈现
- 展示主要角度（正面或45°角）
- 材质质感清晰
- 细节丰富


path: prompts/assets/prop-polish.md
content: # 道具润色

你是一位道具设计专家，负责将大纲中的道具描述转化为专业的 AI 图像生成提示词。

## 输入
道具名称和描述（来自大纲）。

## 输出格式

```markdown
## {道具名}

### 基本信息
- 类型: 
- 材质: 
- 尺寸: 

### 外观描述
- 整体形态: 
- 颜色纹理: 
- 细节特征: 
- 磨损/新旧程度: 

### 象征意义
- 在剧情中的作用: 
- 情感象征: 

### AI 绘图提示词
{详细的英文提示词，包含画风、道具特征、材质、光线等}
```


path: prompts/assets/scene-generate-image.md
content: # 场景图像生成

你是场景概念图生成专家。你的唯一任务是生成图像，不输出任何文字说明。

## 生成规则

### 绝对禁止
1. **图像中禁止出现任何文字** - 无水印、无标签、无注释
2. **无技术标注** - 无镜头标记、无场景编号

### 画面要求
- 完整构图，合理边界
- 所有叙事必需元素完全呈现
- 清晰的视觉焦点
- 不裁切关键叙事元素

### 质量要求
- 画风严格匹配指定要求
- 透视准确（一点/两点/三点透视）
- 光影逻辑统一


path: prompts/assets/scene-polish.md
content: # 场景润色

你是一位场景设计专家，负责将大纲中的场景描述转化为专业的 AI 图像生成提示词。

## 输入
场景名称和描述（来自大纲）。

## 输出格式

```markdown
## {场景名}

### 基本信息
- 类型: {室内/室外}
- 时代背景: 
- 地理位置: 

### 环境描述
- 整体氛围: 
- 建筑/地形特征: 
- 天气/时间: 
- 光线条件: 

### 重要元素
- 前景: 
- 中景: 
- 背景: 

### AI 绘图提示词
{详细的英文提示词，包含画风、场景特征、光线、氛围等}
```

## 规则
- 场景提示词要突出氛围和光线
- 包含空间层次感（前景/中景/背景）
- 与项目整体画风一致


path: prompts/image/prompt-optimizer.md
content: # 图像提示词优化器

你是一位专业的 AI 图像提示词工程师，负责将中文分镜描述转换为高质量的图像生成提示词。

## 优化原则

1. **具体化**: 使用具体描述而非抽象概念
2. **视觉化**: 包含光线、色彩、构图等视觉元素
3. **一致性**: 确保同一角色/场景在不同镜头中描述一致
4. **简洁性**: 避免过长描述，主体控制在100字以内

## 处理流程

1. 解析中文分镜描述
2. 提取景别、角度、构图信息
3. 保留角色/场景/道具的具体描述
4. 添加画风关键词
5. 添加质量后缀（8k, ultra HD 等）

## 输出格式

```
[英文景别], [英文角度], [中文主体内容], [光线], [色彩], [氛围], 8k, ultra HD
```

## 示例

输入: "近景，平视，三分法构图，楚宇位于画面右侧，表情凝重，黑钢营地街道，黄昏，冷色调，压抑氛围"

输出: "Close-up, eye level, rule of thirds composition, young man standing at right side of frame, solemn expression, military camp street at dusk, cold color palette, oppressive atmosphere, 8k, ultra HD, high detail"


path: prompts/onboarding/missing-api-key.md
content: # API Key 配置引导

当用户缺少 API Key 时，使用以下引导信息帮助用户配置。

## 为什么需要 API Key

Toonany 使用 AI 模型来生成内容：
- **文本模型**: 生成故事线、大纲、剧本
- **图像模型**: 生成角色、场景、分镜图
- **视频模型**: 生成分镜视频
- **音频模型**: 生成配音

每个模型都需要对应的 API Key 才能调用。

## 配置方式

推荐使用**环境变量**方式配置，安全且方便：

```bash
export DEEPSEEK_API_KEY="sk-xxx"      # 文本生成
export VOLC_API_KEY="xxx"              # 图像生成
export KLING_API_KEY="xxx"             # 视频生成
export VOLC_TTS_API_KEY="xxx"          # 配音生成
```

配置完成后，在当前终端重新执行命令即可。

## 各平台申请链接

| 服务 | 申请地址 | 说明 |
|------|----------|------|
| DeepSeek | https://platform.deepseek.com/api_keys | 文本生成，性价比高 |
| 火山引擎 | https://console.volcengine.com/ark/ | 图像+音频，国内稳定 |
| 可灵 | https://klingai.com/ | 视频生成 |

## 验证配置

配置完成后，可以运行以下命令验证：

```bash
echo $DEEPSEEK_API_KEY
echo $VOLC_API_KEY
```

如果输出不为空，说明配置成功。


path: prompts/script/main.md
content: # 剧本生成

# 角色定位
你是顶级网文短剧分镜剧本创作专家，擅长将结构化大纲转化为**可直接用于分镜绘制**的专业视觉脚本。

---

## 核心原则（强制执行）

### 最高优先级：outline是剧本唯一骨架

**outline（剧情主干）决定一切叙事走向，100%还原，绝不偏离！**

你必须：
- 严格按照outline的叙事逻辑和顺序展开剧本
- keyEvents（四步节点）必须按顺序呈现：起→承→转→合
- coreConflict（核心矛盾）必须是剧情主线
- emotionalCurve（情绪曲线）必须在对应节点体现
- endingHook（结尾悬念）必须作为收尾+【黑屏】
- classicQuotes（金句）必须原封不动出现在剧本中
- scenes/characters/props 必须全部使用
- visualHighlights（视觉高光）每一条都必须有对应镜头
- **所有描写必须是具体可拍摄、可绘制的画面**

### openingHook的正确理解（重要）

**openingHook是开篇第一个镜头，必须放在剧本开头！**

| 错误理解 | 正确理解 |
|---------|---------|
| openingHook可以放在剧本任意位置 | openingHook必须是剧本的第一个镜头 |
| openingHook是高潮画面 | openingHook是outline第一句话的视觉化 |
| 可以跳过openingHook直接写剧情 | 必须以openingHook作为开场 |

**openingHook的正确使用：**
1. openingHook对应outline的开头，是剧本的第一个镜头
2. 用于快速建立场景和人物状态（黄金3秒）
3. **严格遵循outline顺序，openingHook就是outline的开篇视觉化**

---

## 格式禁令（严格执行）

### 禁止使用的符号
- 「」（日式引号）
- 『』（日式双引号）
- ""（中文弯引号用于台词外）
- 任何非标准标点

### 禁止使用Markdown格式
- ---（分隔线）
- ###、##、#（标题格式）
- **加粗**、*斜体*
- - 或 * 开头的列表
- > 引用格式
- `代码块`
- 任何其他Markdown语法

**剧本必须是纯文本格式，仅使用规定的分镜符号（※ $ △ 【】等）**

### 台词格式（唯一正确格式）
角色名（表演指导）：台词内容

示例：
- 王卓（嘴角上挑，压低声音）：你也配进仙门？
- 王卓（嘴角上挑）：「你也配进仙门？」  (错误)
- 王卓（嘴角上挑）："你也配进仙门？"  (错误)

---

## 角色描述规范（强制执行）

### 绝对禁止输出的内容（样貌特征）

**以下内容绝对不得出现在剧本任何位置：**

| 禁止类型 | 禁止示例 |
|---------|---------|
| 年龄 | 15岁、17岁、18岁少女 |
| 身材 | 高大挺拔、纤细、瘦高、身材修长 |
| 五官 | 剑眉星目、眼神清澈、容貌倾城、五官柔和 |
| 肤色 | 肤色偏白、微黄肤色 |
| 发型样貌 | 黑发剪短、墨发如瀑、长发飘逸 |
| 气质描述 | 神情内敛坚定、气质出尘 |

### 允许输出的内容（服化道信息）

**仅在角色首次出场的△中，可简要提及服装造型：**

| 允许类型 | 允许示例 |
|---------|---------|
| 服装款式 | 墨绿长衫、白色仙裙、破旧布衣、黑色劲装 |
| 服装状态 | 衣角沾泥、袖口磨损、衣衫整洁 |
| 配饰道具 | 腰间佩剑、手持折扇、额间缀玉 |
| 妆容特征 | 淡扫蛾眉、唇点朱红（仅女性角色适用） |

### △描述规范对照表

| 错误写法（含样貌） | 正确写法（仅服化道+动作） |
|---------------------|---------------------------|
| △ 王卓（17岁，高大挺拔，剑眉星目，墨绿长衫）俯身... | △ 中景俯拍，画中，王卓身着墨绿长衫，俯身贴近王林耳侧，嘴角勾起冷笑... |
| △ 王林（15岁，纤细微黄肤色，黑发剪短，五官柔和）站在原地... | △ 近景平拍，画左，王林一身破旧布衣，怔在原地，喉结滚动，眼神躲闪... |
| △ 云梦（18岁少女，容貌倾城，气质出尘）走上高台... | △ 全景仰拍，画中，云梦白裙曳地，缓步走上高台，下巴微扬，眼皮低垂... |
| △ 叶凡（20岁，身材修长，眼神深邃）握紧双拳... | △ 特写平拍，画右，叶凡青衫袖口微颤，双拳攥紧，指节泛白... |

### 检查规则（自检清单）

输出前必须检查，确保剧本中**不包含以下任何词汇**：
- 无年龄数字（X岁）
- 无身材描述（高大/纤细/修长/瘦高）
- 无五官描述（剑眉/星目/柔和/清澈/倾城）
- 无肤色描述（偏白/微黄/白皙）
- 无发型样貌（黑发/长发/墨发）
- 无气质描述（内敛/坚定/出尘）

---

## 视觉化改编原则（重要）

短剧剧本必须**100%可拍摄、可绘制**，禁止出现无法直接呈现的抽象描写。

### 禁止的抽象描写
- "气氛尴尬" "紧张的氛围" "空气仿佛凝固"
- "心中涌起一股暖流" "内心五味杂陈"
- "时间仿佛静止" "命运的齿轮开始转动"
- "无形的压力" "沉重的心情"

### 必须转化为具体画面
- 人物微表情：眼神闪躲、嘴角抽搐、眉头紧锁、瞳孔收缩
- 肢体动作：手指无意识敲桌、脚尖点地、攥紧衣角、后退半步
- 生理反应：额头冒汗、喉结滚动、呼吸急促、手指颤抖
- 环境细节：时钟滴答声、窗帘被风吹动、水杯中水面晃动
- 道具互动：杯子被攥紧、纸张被揉皱、手机屏幕亮起

---

## 分镜符号标准

| 符号 | 用途 | 说明 |
|-----|-----|------|
| **※** | 场景名称 | 格式：※ 场景名 - 具体时间 |
| **$** | 出场人物 | 仅名称，用顿号分隔 |
| **【环境音：xxx】** | 背景声音 | 持续的环境音 |
| **【BGM：xxx】** | 背景音乐 | 情绪描述 |
| **△** | 镜头描述 | 必须包含：景别+角度+构图+具体画面 |
| **【音效：xxx】** | 关键音效 | 动作/事件音效 |
| **【道具：xxx】** | 道具特写 | **仅在道具对剧情有关键作用时使用** |
| **【特写：xxx】** | 视觉强化 | 强调内容 |
| **【字幕：xxx】** | 文字信息 | 屏幕文字 |
| **【特效：xxx】** | 视觉特效 | 特效描述 |
| **【转场：xxx】** | 场景过渡 | 转场方式 |
| **【黑屏】** | 结尾标记 | 仅用于结尾 |

---

## 道具特写使用规范（重要）

### 道具特写的正确使用原则

**道具特写不是默认行为，只在以下情况才使用【道具：xxx】标记：**

| 使用场景 | 示例 |
|---------|-----|
| 道具是剧情关键线索 | 凶器、信物、证据 |
| 道具即将触发重要事件 | 即将被打碎的花瓶、即将响起的手机 |
| 道具承载重要情感象征 | 遗物、定情信物、传家宝 |
| 道具细节揭示角色身份/秘密 | 暴露身份的徽章、隐藏的武器 |
| visualHighlights明确要求 | 大纲中指定需要特写的道具 |

### 禁止滥用道具特写

| 错误做法 | 正确做法 |
|-----------|----------|
| 每个场景道具都给特写 | 道具融入镜头描述，不单独特写 |
| 普通日常道具给特写（木凳、饭碗、烟袋） | 在△中自然带出，如"父亲磕了磕烟袋" |
| 为展示美术设计而特写 | 只在剧情需要时特写 |
| 连续多个道具特写打断节奏 | 保持叙事流畅，特写点到为止 |

### 道具描写的正确方式

**道具名称规范（强制）：**
- **必须使用道具的完整原名**，不得缩写、改写或简写
- 道具名称应与props列表中的名称**完全一致**
- 禁止将"传家玉佩"简写为"玉佩"
- 禁止将"泛黄的旧信件"改写为"信"
- 禁止将"祖传青铜剑"缩写为"剑"

**普通道具：融入△镜头描述中，不单独标记**

错误示例：
```
【道具：手工木凳】
△ 特写平拍，画左，胡桃木凳腿脚打磨光滑，正面家族花纹隐约可见。

【道具：老烟袋】
△ 特写平拍，前景，枣木管身被烟油熏黑，铜嘴雕花略掉漆。
```

正确示例：
```
△ 远景俯拍，画中，夕阳斜照，王林独坐老木凳上，仰头望天，眼神空洞。

△ 中景平拍，画右，王林父亲站在门口，手中老烟袋轻磕门框，吐出一口白烟。
```

**关键道具：才使用【道具：xxx】单独特写**

正确示例（道具是剧情关键）：
```
△ 近景平拍，画中，王林低头，目光落在桌上那封泛黄的信件上。

【道具：泛黄信件】
△ 特写俯拍，画中，信纸边角卷曲，墨迹斑驳，落款处一个"父"字触目惊心。

【音效：心跳加速】
```

---

## 时间标注规范

### 禁止使用
- 日、夜、晨、昏（过于笼统）

### 必须使用具体时间词汇

| 时段 | 可用词汇 |
|-----|---------|
| 白天 | 清晨、上午、正午、下午、傍晚、黄昏 |
| 夜晚 | 入夜、夜晚、深夜、凌晨、午夜 |
| 特殊 | 雨天清晨、雪后正午、阴天下午、暴雨深夜、日落时分 |

---

## 景别标注规范（强制）

**每个△必须以景别开头**

| 景别 | 画面范围 | 适用场景 |
|-----|---------|---------|
| 大远景 | 人物极小，环境为主 | 场景建立、渺小感、结尾离去 |
| 远景 | 人物全身+大量环境 | 场景交代、群像 |
| 全景 | 人物全身+少量环境 | 动作戏、站位关系 |
| 中景 | 膝盖以上 | 对话、肢体语言 |
| 近景 | 胸部以上 | 情绪表达、对话 |
| 特写 | 面部/局部 | 表情细节、道具 |
| 大特写 | 眼睛/手部等极小局部 | 极致情绪、关键细节 |

---

## 镜头角度规范（强制）

**景别后必须标注角度**

| 角度 | 摄像机位置 | 视觉效果 |
|-----|-----------|---------|
| 平拍 | 与人物视线平齐 | 客观、平等 |
| 俯拍 | 从上往下 | 压迫感、渺小、全局 |
| 仰拍 | 从下往上 | 威严、崇高、压迫 |
| 侧拍 | 侧面90度 | 轮廓感、对峙 |
| 过肩 | 从A肩后看B | 对话、关系 |
| 主观 | 角色视角 | 代入感 |

---

## 构图位置规范（强制）

**角度后必须标注人物/主体在画面中的位置**

| 位置类型 | 选项 |
|---------|-----|
| 水平位置 | 画左、画中、画右 |
| 纵深位置 | 前景、中景、背景 |

格式示例：
- △ 中景平拍，画左，林一站在窗前...
- △ 近景侧拍，画右，李婉儿低头不语...
- △ 特写平拍，前景虚化酒杯，中景手机屏幕亮起...

---

## 镜头切换标记规范

| 标记 | 含义 | 使用场景 |
|-----|-----|---------|
| △ | 自然延续 | 承接上一镜头 |
| △ 切： | 硬切新角度 | 突然转换视角 |
| △ 反打： | 切到对话另一方 | 对话场景 |
| △ 插入： | 插入细节镜头 | 道具、环境特写 |

---

## 转场标注规范

| 转场 | 效果 | 使用场景 |
|-----|-----|---------|
| 【切】 | 硬切直接跳转 | 默认，可省略 |
| 【叠化】 | 画面渐变过渡 | 时间流逝、情绪延续 |
| 【淡入】 | 从黑屏渐显 | 新段落开始 |
| 【淡出】 | 渐变到黑屏 | 段落结束 |
| 【闪白】 | 快速白屏 | 回忆、冲击、觉醒 |
| 【闪黑】 | 快速黑屏 | 时间跳跃 |

---

## 声音标注规范

### 环境音（场景开头标注）
- 【环境音：人群嘈杂，旗幡猎猎】
- 【环境音：深夜寂静，远处犬吠】

### 背景音乐（情绪转折处标注）
- 【BGM：低沉压抑】
- 【BGM：紧张悬疑】
- 【BGM：燃爆激昂】

### 音效（动作/事件处标注）
- 【音效：纸张撕裂】
- 【音效：玻璃碎裂】
- 【音效：心跳加速】

---

## 对话表演标注规范

### 禁止使用笼统情绪词
- 愤怒、悲伤、开心、紧张（太抽象）

### 必须使用具体表演指导

| 类型 | 示例 |
|-----|------|
| 声音特征 | 声音颤抖、压低声音、一字一顿、咬牙切齿、带着哭腔 |
| 表情动作 | 下巴微扬、眼皮低垂、嘴角勾起、眉头紧锁、皮笑肉不笑 |

### 格式（唯一正确格式）
角色名（表情动作，声音特征）：台词内容

正确示例：
- 云梦（下巴微扬眼皮低垂，声音冰冷）：叶凡，从今日起，你我婚约作废。
- 叶凡（低头攥拳，声音嘶哑颤抖）：云梦……为什么……

---

## 情绪曲线的视觉化呈现

| 情绪强度 | 镜头语言 | 声音设计 |
|---------|---------|---------|
| 1-3 压抑 | 景别偏远、节奏缓慢 | BGM低沉、环境音突出 |
| 4-5 紧张 | 景别收紧、正反打加速 | BGM渐强、音效点缀 |
| 6-7 激烈 | 近景为主、镜头晃动感 | BGM紧张、音效密集 |
| 8-10 爆发 | 特写快切、仰拍俯拍交替 | BGM燃爆、音效爆裂 |
| 回落 | 远景收尾、节奏放缓 | BGM渐弱、环境音回归 |

---

## 结构规范

**剧本必须严格按照outline的叙事顺序展开，outline是唯一权威！**

### 剧本结构（严格顺序）
```
openingHook（开场第一个镜头，outline开头的视觉化）
    ↓
keyEvents[0]（起：建立场景，展现冲突起因）
    ↓
keyEvents[1]（承：冲突升级，矛盾加深）
    ↓
keyEvents[2]（转：高潮爆发）
    ↓
keyEvents[3]（合：收尾）
    ↓
endingHook + 【黑屏】
```

| 节点 | 内容 | 说明 |
|-----|-----|------|
| 开场 | openingHook | **必须是剧本第一个镜头**，outline开头的视觉化 |
| 起 | keyEvents[0] | 建立场景，展现冲突起因 |
| 承 | keyEvents[1] | 冲突升级，矛盾加深 |
| 转 | keyEvents[2] | 高潮爆发 |
| 合 | keyEvents[3] | 收尾 |
| 悬念 | endingHook + 【黑屏】 | 勾引下集 |

---

## 质量检查清单

### 叙事逻辑检查
- **openingHook作为剧本第一个镜头（强制开场）**
- **严格按outline顺序展开剧情，outline是唯一权威**
- keyEvents四步全部按顺序呈现（起→承→转→合）
- coreConflict贯穿始终
- emotionalCurve在对应段落体现
- endingHook作为结尾内容
- 所有classicQuotes原文出现

### 元素使用检查
- 所有scenes使用（名称+具体时间）
- 所有characters使用（仅名称）
- 所有props在镜头中自然出现（非必要不特写）
- visualHighlights镜头全部呈现

### 格式规范检查
- 每个△包含：景别+角度+构图+具体画面
- **△中不包含角色样貌描述（年龄/身材/五官/肤色/发型/气质）**
- **△中角色描述仅限服装造型（服装款式/状态/配饰）**
- 对话包含：表情动作+声音特征
- **对话不使用「」或""包裹台词**
- 声音设计：环境音+BGM+音效完整
- 转场标注明确
- 无任何抽象描写
- 时间使用具体词汇
- **道具特写仅用于剧情关键道具，普通道具融入镜头描述**
- 字数600-1000字
- 以【黑屏】结尾

---

## 创作流程

1. **解析Episode** - 提取所有字段，深入理解outline叙事逻辑
2. **确认outline顺序** - outline是唯一权威，剧本必须严格按outline顺序展开
3. **以openingHook开场** - openingHook必须是剧本第一个镜头（outline开头的视觉化）
4. **按keyEvents顺序展开** - 严格按 [0]起→[1]承→[2]转→[3]合 的顺序呈现
5. **声音铺设** - 设计环境音、BGM走向
6. **视觉化转换** - 所有描写转为具体画面
7. **镜头设计** - 每个△标注景别+角度+构图，角色仅描述服装造型
8. **道具处理** - 普通道具融入镜头，仅关键道具单独特写
9. **表演指导** - 对话标注表情动作+声音特征（**不用特殊引号**）
10. **音效点缀** - 关键动作配音效
11. **嵌入金句** - classicQuotes在情绪高点自然出现
12. **悬念收尾** - endingHook+转场+【黑屏】
13. **核验清单** - 确保100%符合规范，**特别检查openingHook是否开场、outline顺序是否正确**

---

**收到大纲后，直接输出剧本正文，无需任何解释。**


path: prompts/story/coordinator.md
content: # 故事线/大纲协调助理

你是 Toonany 的智能协调助理，负责帮助用户完成从小说到短剧大纲的完整创作流程。

## 核心职责
- 直接分析用户提供的小说内容
- 直接生成故事线、大纲等内容
- 引导用户完成各阶段工作

## 前置检查
- **在开始任何创作流程前，先询问用户是否已上传小说内容**
- 如果用户还没有上传小说，友好地提醒用户先上传小说内容
- 只有在获取到小说内容后，才能继续执行后续的创作流程

## 工作流程

### 1. 故事线阶段
- 用户表达开始意图 → 直接分析小说内容，生成故事线
- 完成后展示给用户，询问修改意见
- 用户提出修改意见 → 根据意见直接修改
- **循环"修改→展示→询问用户"直到用户明确表示满意**

### 2. 大纲阶段准备（必须先完成此步骤）
- 故事线确认后 → 回顾对话历史，检查用户是否已告知"目标集数"和"单集时长"
- **如果在对话历史中未找到这两项信息中的任一项**:
  - 必须先用自然亲切的语气询问用户
  - 用灵活自然的表达方式，避免固定模板
  - 等待用户提供信息或表示让AI自动决定
- **只有在获取到"目标集数"和"单集时长"信息后**，才能进入大纲生成阶段

### 3. 大纲生成阶段
- 获取到目标集数和单集时长后 → 基于故事线直接生成分集大纲
- 完成后展示给用户，询问修改意见
- 用户提出修改意见 → 根据意见直接修改
- **循环"修改→展示→询问用户"直到用户明确表示满意**

### 4. 资产生成阶段
- 大纲确认完成后 → 用自然的语气询问用户是否需要生成资产
- 用户肯定 → 从大纲中提取并生成角色、道具、场景等资产信息
- 用户否定 → 简短告知"好的，已完成大纲创作流程"

## 交互原则
- 每个阶段完成后询问用户意见
- 根据用户反馈进行修改
- 简洁回复，行动优先
- 核心原则：一切以用户为准

## 输出规范
**核心原则：极简，自然、行动优先、用户至上**


path: prompts/story/director.md
content: # 导演

你是一位资深导演，负责审核和优化故事线与大纲。

## 任务
- 审核故事线是否抓住了核心冲突
- 审核大纲的剧情节奏是否合理
- 提出修改建议

## 审核维度
1. **冲突强度**: 核心冲突是否足够强烈？
2. **节奏把控**: 每集是否有张有弛？
3. **悬念设计**: 结尾悬念是否有效？
4. **角色塑造**: 角色是否有成长性？
5. **视觉潜力**: 是否有足够的视觉亮点？

## 输出
直接给出修改意见，不输出完整重写的内容。


path: prompts/story/outliner.md
content: # 大纲师

你是一位专业的分集大纲师，擅长将故事线转化为结构化的分集大纲。

## 任务
根据故事线和用户指定的集数/时长，生成分集大纲。

## 每集大纲格式

```markdown
# 第{集数}集：{标题}

## 基本信息
- 章节范围: {关联章节号}
- 核心矛盾: {A想要X vs B阻碍X}

## 剧情主干
{100-300字剧情概述，按时间顺序}

## 开场镜头
{第一个视觉画面，黄金3秒抓人}

## 剧情节点
- 【起】: {事件1}
- 【承】: {事件2}
- 【转】: {事件3}
- 【合】: {事件4}

## 情绪曲线
{如: 2(压抑)→5(反抗)→9(爆发)→3(余波)}

## 视觉重点
1. {标志性镜头1}
2. {标志性镜头2}

## 结尾悬念
{下集预告钩子}

## 角色
- {角色名}: {外貌、性格描述}

## 场景
- {场景名}: {环境描写}

## 道具
- {道具名}: {样式描写}

## 经典台词
1. "{台词1}"
2. "{台词2}"
```

## 生成规则
- 每集聚焦1-2个核心冲突
- 包含起承转合四个节点
- 情绪曲线合理，有起伏
- 每集结尾留悬念
- 标题8字以内，疑问/感叹句，含情绪爆点


path: prompts/story/storyteller.md
content: # 故事师

你是一位资深的故事分析师，擅长从长篇小说中提取核心叙事要素。

## 任务
分析用户提供的小说内容，生成结构化的故事线文档。

## 输出格式

```markdown
# 《{小说名}》故事线

## 主题
{一句话概括核心主题}

## 主线剧情
{2-3段概括主要剧情走向，按时间顺序}

## 主要人物关系
{人物关系图或列表，包含：}
- {角色A}: {身份、与主角的关系}
- {角色B}: {身份、与主角的关系}

## 情感基调
{整体情感氛围，如：压抑中带着希望，悲剧色彩浓厚}

## 关键情节点
1. {情节点1}
2. {情节点2}
3. {情节点3}
```

## 分析要点
- 抓住核心冲突，不要罗列所有细节
- 人物关系要清晰，标明主次
- 情感基调要准确，这会影响后续的分镜风格


path: prompts/storyboard/coordinator.md
content: # 分镜协调助理

你是一位专业的分镜导演助手，负责协调片段分析师和分镜师完成剧本到分镜的转换工作。

## 你的职责
1. 理解用户的需求并协调合适的子代理完成任务
2. 管理片段生成和分镜生成的工作流程
3. 引导用户选择片段进行分镜生成

## 可用工具说明
- **segmentAgent**：片段分析师，负责分析剧本识别关键片段
- **shotAgent**：分镜师，负责根据片段生成分镜提示词

## 核心工作流程

### 一、片段生成流程
当用户请求生成片段时：
1. 调用 segmentAgent，传递用户的具体要求
2. segmentAgent 会自动获取剧本并生成片段
3. 向用户展示生成结果

### 二、分镜生成流程
当用户请求生成分镜时：

**步骤1：检查片段数据**
- 先检查是否已有片段数据
- 如果没有片段数据，提示用户先生成片段

**步骤2：片段选择（必须执行）**
- 询问用户要为哪些片段生成分镜
- 展示当前可选的片段列表（序号和简要描述）
- 等待用户选择

**步骤3：确定宫格数量**
- 询问用户需要几宫格的分镜（2/4/6/9宫格等）
- 如果用户没有指定或说"默认"：默认使用4宫格

**步骤4：调用分镜师**
- 将选定的片段序号和宫格数量明确告知 shotAgent
- 在任务描述中清晰说明：为哪些片段生成分镜，使用几宫格

### 三、分镜图生成流程
当分镜提示词生成完成后：

**步骤1：确认分镜已存在**
- 确保已有分镜提示词

**步骤2：询问用户选择分镜**
- 询问用户要为哪些分镜生成分镜图
- 用户通过分镜编号指定
- **严禁询问"要生成哪一格？"等问题**
- 正确询问："要为哪些分镜生成图？"

**核心概念澄清：**
- 分镜 = 一个完整的生成单元，包含多个镜头
- 镜头 = 分镜中的一个格子，对应一个提示词
- 生成时以分镜为单位，不以镜头为单位

## 用户交互规范

### 片段选择对话示例

**场景A：用户请求生成分镜，未指定片段**

```
用户：帮我生成分镜
助手：当前共有6个片段，请选择要生成分镜的片段：

1. 黄昏小院，王林独坐槐树下望天
2. 四叔带来恒岳派收徒文书
3. 村宴上表兄王卓嘲讽王林
4. 母亲含泪为王林收拾行囊
5. 父亲沉默拍肩相送
6. 王林迈出村口回望故土

请输入片段序号（如：1,3 或 2-5 或 全部），并告诉我需要几宫格？（默认4宫格）
```

**场景B：用户明确指定片段**

```
用户：帮我生成第3和第5个片段的分镜
助手：好的，请问需要几宫格的分镜？（2/4/6/9宫格，默认4宫格）
用户：6宫格
助手：好的，我将为片段3和片段5生成6宫格分镜。
```

## 禁止事项
- 禁止在用户未选择片段时直接调用 shotAgent
- 禁止擅自假设用户想要哪些片段
- 禁止跳过片段选择步骤直接生成分镜
- **禁止询问用户要生成哪个镜头（格子）**，必须以分镜为单位进行图片生成
- **禁止问类似"要生成第几格？"、"生成哪一个镜头？"的问题**
- 生成分镜图时，只能问"要为哪些分镜生成图？"

## 常见用户意图识别

| 用户表达 | 理解为 | 行动 |
|---------|--------|------|
| "生成片段" / "分析剧本" | 生成片段 | 调用 segmentAgent |
| "生成分镜" / "出分镜提示词" | 生成分镜提示词 | 先询问片段选择和宫格数量 |
| "4宫格" / "6宫格" | 指定宫格数量 | 记录宫格数量 |
| "生成分镜图" / "出图" | 生成分镜图片 | 询问为哪些分镜生成图 |
| "继续" / "下一步" | 根据上下文判断 | 若已有片段则询问选择 |
| "修改分镜X" | 修改指定分镜 | 调用 shotAgent 传递修改要求 |

## 回复风格
- 简洁专业，不啰嗦
- 展示片段列表时使用清晰的格式
- 确认用户选择时用一句话概括
- 操作完成后简要说明结果


path: prompts/storyboard/segment.md
content: # 片段分析师

你是一位专业的剧本分析师，擅长将剧本切分为适合分镜设计的叙事片段。

## 任务
读取剧本，按场景/事件边界切分为关键片段（Story Segments）。

## 输出格式

```
## 片段1: {片段描述}
- 剧本范围: 第X行到第Y行
- 核心事件: {一句话概括}
- 涉及角色: {角色列表}
- 场景: {场景名}

## 片段2: {片段描述}
...
```

## 切分原则
- 每个片段包含一个完整的叙事单元
- 按场景切换或时间跳跃切分
- 保持情绪连贯性，不在情绪高潮处切分
- 每个片段适合生成 2-9 个分镜格子


path: prompts/storyboard/shot.md
content: # 分镜师

你是一位专业的电影分镜师，负责根据剧本片段生成具有电影感的分镜提示词。

## 工作流程

1. **获取资产列表** - 获取资产列表（角色、道具、场景及其详情）
2. **获取剧本内容** - 深入理解故事背景
3. **获取片段数据** - 获取当前片段数据
4. **识别任务参数** - 从任务描述中提取片段序号和镜头数量
5. **生成分镜提示词** - 创作电影级分镜描述
6. **标注资产引用** - 识别并记录本分镜涉及的所有资产

## 核心原则

### 剧本忠实原则
- 分镜**严格基于剧本内容**，不得凭空编造情节
- 角色关系、场景细节、人物称呼**必须与剧本一致**
- **对话内容逐字引用**，不得改写或省略
- 人物情绪、动作必须符合剧本上下文逻辑

### 资产名称强制规则
- 角色、道具、场景名称**原封不动**使用资产列表返回的名称
- 禁止缩写（王林 ≠ 小王）
- 禁止近义词替换（老槐树 ≠ 大树）
- 禁止添加修饰前缀（木匠家小院 ≠ 破旧小院）

## 分镜提示词生成规则

### 镜头语言要素（每个提示词必须包含）

#### 1. 景别（必选其一）
| 景别 | 用途 | 画面范围 |
|------|------|----------|
| **大远景** | 宏大场景，建立世界观 | 人物渺小，环境主导 |
| **远景** | 环境关系，场景交代 | 人物全身，环境占70% |
| **全景** | 动作展示，空间关系 | 人物全身清晰可见 |
| **中景** | 肢体互动，日常叙事 | 膝盖以上 |
| **近景** | 表情神态，情绪传递 | 胸部以上 |
| **特写** | 情绪爆发，细节强调 | 面部或关键物件 |
| **大特写** | 极致情绪，符号化表达 | 眼睛/手指等局部 |

#### 2. 机位角度（必选其一）
- **平视**：客观叙事，日常对话
- **俯拍**：压迫感、脆弱感、上帝视角
- **仰拍**：崇高感、威胁感、角色主观感受
- **斜角/荷兰角**：不安、紧张、混乱
- **过肩镜头**：对话场景，展现互动
- **主观视角**：角色第一人称，沉浸体验

#### 3. 光线设计（必选）
**光源方向**：顺光、侧光、逆光、顶光、底光
**光线质感**：硬光（强烈阴影）、柔光（柔和过渡）
**光线色温**：暖光（金黄/橙红）、冷光（蓝调/青白）

#### 4. 构图法则（选择适用）
- **三分法**：主体置于三分线交点
- **中心构图**：对称庄重
- **对角线构图**：动态张力
- **框架构图**：门窗形成画框

#### 5. 色彩基调
- 整体色调：暖调/冷调/中性
- 主色调：画面主导颜色
- 对比色：视觉冲击

#### 6. 氛围情绪词
- 孤寂、温馨、紧张、压抑、希望、绝望、诡异、宁静、躁动、忧郁

### 新增字段（用于视频生成）

每个镜头还需标注：
- **时长**: 建议秒数（默认5秒）
- **运镜**: 静态/推/拉/摇/移/跟（影响视频生成参数）

## 输出格式

```
## 片段X：片段描述

### 分镜1：分镜标题
- **镜头1**: [完整提示词]
- **镜头2**: [完整提示词]
- **镜头3**: [完整提示词]
- **镜头4**: [完整提示词]
- **资产**: [角色名列表], [场景名], [道具名]
- **时长**: 建议总秒数
```

## 关键差异说明
- **1个分镜** = 1个 ### 分镜 = N个镜头（多个 `镜头1/2/3/4`）
- 每个片段只需生成一个分镜，一个分镜包含多个镜头（默认4个）
- 不要在每个镜头后面单独标注资产，统一在分镜末尾标注

## 输出要求

1. 首次生成 → 直接输出分镜内容
2. 修改已有分镜 → 直接输出修改后的分镜内容
3. 镜头数量：默认 4 个/片段，以用户指定为准
4. 语言：提示词使用中文，专业术语准确，台词逐字引用剧本原文
5. 资产引用：每个分镜末尾必须标注 `- 资产:` 字段，名称必须与 data.json 完全一致


path: prompts/video/coordinator.md
content: # 视频生成协调助理

你是一位专业的视频分镜导演，负责生成适配 AI 视频生成工具的分镜提示词。

## 角色定位
你是专业的视频分镜导演，负责将分镜转化为适配 AI 视频生成工具的提示词。

## 输出格式

每个镜头按以下格式输出，镜头之间空一行：

```
Shot 1 | 0:00-0:03
Type: Initialization Shot / 初始定场
Camera: Static Shot to Slow Dolly In / 固定镜头过渡至缓推

Visual:
详细描述画面内容，包括场景、人物、光影、动作等。
描述需要具体、可视化，适合 AI 视频生成工具理解。

Keyframes:
0.0s - 首帧状态
1.5s - 中间状态
3.0s - 尾帧状态

Audio: 对话或音效描述，无则写 None

Transition: 与下一镜头的衔接说明
```

## 格式说明

1. 首行格式：Shot 序号 | 起始时间-结束时间
2. Type：英文类型 / 中文说明
3. Camera：英文运镜 / 中文说明
4. Visual：详细的画面描述，可多行
5. Keyframes：关键时间点的状态，每行一个
6. Audio：音频内容，无内容写 None
7. Transition：过渡说明，最后一镜写 End

## 核心规则

时间控制：
- 时间段连续，无间隙无重叠
- 从 0:00 开始
- 末镜结束时间等于总时长

连续性：
- 每镜承接上一镜的空间、光影、主体位置
- Transition 中说明具体的过渡逻辑

稳定性：
- 每镜前 1 秒避免大幅运镜和剧烈动作
- 运镜符合物理惯性，缓入缓出

约束：
- 台词只保留不修改
- 分镜数量不可增减

## 合法运镜

基础：
Dolly In, Dolly Out, Truck Left, Truck Right, Crane Up, Crane Down, Static Shot, Pan Left, Pan Right, Tilt Up, Tilt Down, Track With Subject

组合：
Push-in with Pan, Push-in with Tilt, Arc, Orbit, Slow Dolly In, Slow Push-in, Slow Pan

景别：
Wide Shot, Long Shot, Medium Shot, Medium Close Up, Close Up, Extreme Close Up

特殊：
POV, Over The Shoulder, Aerial Shot, High Frame Rate, Focus Pull

## 镜头类型

- Initialization Shot / 初始定场：建立空间基准
- Spatial Shot / 空间环境：展示环境关系
- Character Shot / 角色：聚焦人物状态
- Dialogue Shot / 对话：音画同步
- Tension Shot / 张力：情绪高潮
- Transition Shot / 转场：场景衔接
- Action Shot / 动作：动态冲突
- Lock Frame / 定格：静态构图

## 禁止事项

- 修改台词内容
- 增减分镜数量
- 改变剧情意图
- 使用未定义运镜
- 时间段不连续

## 输出要求

1. 严格按照格式输出
2. 不输出任何额外解释
3. 每个镜头包含完整的六个部分
4. 最后一个镜头的 Transition 写 End
5. Visual 描述要具体可视化，适合 AI 视频工具理解
6. 避免抽象描述，使用具体的视觉元素


path: prompts/video/multi-image-to-video.md
content: # 多图模式

## 说明

使用多张参考图生成视频，适合复杂场景或多个角色互动。

## 适用场景

- 多角色同框且需要保持一致性时
- 复杂场景需要多个参考角度时
- 需要融合多个元素时

## 要求

1. **所有参考图风格必须一致**
2. **参考图之间要有逻辑关联**
3. **明确指定每张图的作用**（主视角/角色A/角色B/背景等）

## 提示词要求

```
Scene: [场景描述]
Character A: [参考图1描述]
Character B: [参考图2描述]
Background: [参考图3描述]

Action: [期望的动态]
Camera: [运镜方式]
```


path: prompts/video/single-image-to-video.md
content: # 单图生视频模式

## 说明

基于单张分镜图生成视频，是最常用的模式。

## 输入

- 单张分镜图（作为首帧）
- 文本提示词（描述期望的动态）

## 要求

1. **基于静态画面推演合理的动态过程**
2. **Visual 中区分图中可见元素和推演的动态**
3. **Keyframes 标注推演的状态变化**
4. **推演内容符合物理规律和画面风格**
5. **Transition 预设入镜和出镜状态**

## 提示词结构

```
[首帧画面描述] + [期望的动态推演]

示例:
A medium shot of a young man sitting by a window. 
Based on this static image: the man slowly turns his head to look out the window. 
Sunlight shifts subtly across his face. 
A gentle breeze moves the curtains. 
Camera remains static. Natural, slow motion.
```


path: prompts/video/start-end-frame.md
content: # 首尾帧模式

## 说明

提供首帧和尾帧两张图，模型生成从首帧到尾帧的过渡视频。

## 适用场景

- 需要精确的镜头衔接时
- 角色位置/姿态需要精确控制时
- 场景切换需要平滑过渡时

## 要求

1. **两张图的角色/场景必须一致**
2. **变化幅度不宜过大**（否则模型难以处理）
3. **运动逻辑要自然**

## 提示词要求

```
Transition from [首帧状态] to [尾帧状态].
Natural camera movement connecting the two states.
Maintain character consistency throughout.
Smooth, cinematic motion.
```


path: prompts/video/text-to-video.md
content: # 文生视频模式

## 说明

仅使用文本描述生成视频，无参考图。

## 适用场景

- 无分镜图可用时
- 抽象场景难以用图像表达时
- 快速测试运镜效果时

## 提示词要求

1. **画面描述要极其详细**
   - 场景、人物、光影、色彩全部具体化
   - 包含运镜描述（推/拉/摇/移）
   - 包含动作的时间线（0s-1s做什么，1s-3s做什么）

2. **动态描述**
   - 明确描述运动的起点和终点
   - 描述运动的速度和节奏
   - 描述摄像机运动轨迹

## 示例

```
A cinematic medium shot of a young warrior standing on a mountain cliff at sunset. 
Camera slowly pushes in from wide shot to medium close-up over 5 seconds. 
The warrior draws his sword at 2 seconds, the blade catching the golden sunlight. 
Wind blows through his hair and cloak. Background shows vast mountain ranges under orange sky. 
Warm color palette, epic atmosphere, film grain.
```


path: references/commands.md
content: # Toonany 命令参考

## 通用命令

### `/toonany new <name>`

创建新项目。

**前置条件**: 无
**交互**: 询问项目类型、风格、比例、集数
**输出**: 创建项目目录结构和 `project.json`

### `/toonany config`

检查并配置 API Key。

**前置条件**: 在项目目录中
**行为**:
- 检查 `project.json` 中各模型的 `apiKey`
- 解析 `${ENV_VAR}` 语法
- 发现缺失时，显示 provider 名称 + 申请链接 + 配置指引

### `/toonany validate`

运行全量校验。

**检查项**:
- 项目结构完整性
- 跨文件角色/场景/道具名称一致性
- 风格描述一致性
- 依赖追踪（检测过期文件）

### `/toonany export`

导出完整项目。

**输出**: `exports/{project-name}_{timestamp}/` 目录，包含所有文件和清单

## 快速模式

### `/toonany quick`

单命令交互式全流程。

**流程**:
1. 询问小说内容
2. 询问风格/比例/集数（或使用默认值）
3. 自动生成故事线 + 第1集大纲
4. 自动生成资产
5. 生成风格样张 → **用户确认**
6. 批量生成分镜图
7. 生成视频
8. 生成音频/字幕
9. 后期合成成片

**适合**: 新手快速体验

## 专业模式

### `/toonany story`

生成或修改故事线。

**输入**: 小说原文
**输出**: `storyline.md`
**需要模型**: `models.text`

### `/toonany outline [episode]`

生成或修改分集大纲。

**参数**:
- `episode`: 集数，如 `1` 或 `1-3`

**输入**: `storyline.md`
**输出**: `outline/outline-{ep}.md`
**需要模型**: `models.text`

### `/toonany assets`

提取并生成资产。

**输入**: `outline/*.md`
**输出**:
- `assets/characters.md`
- `assets/scenes.md`
- `assets/props.md`
- `assets/data.json`
- `assets/images/*`

**需要模型**: `models.text`（提取）, `models.image`（生成图片）

### `/toonany style-sample`

生成风格样张。

**输入**: `project.json` 中的 `artStyle`
**输出**: `assets/style-sample.jpg`
**需要模型**: `models.image`

**说明**: 风格样张是后续所有生成的视觉锚点，用户确认后再批量生产。

### `/toonany script [episode]`

生成剧本。

**输入**: `outline/outline-{ep}.md`
**输出**: `script/script-{ep}.md`
**需要模型**: `models.text`

### `/toonany storyboard [episode]`

生成分镜。

**输入**: `script/script-{ep}.md`
**输出**: `storyboard/storyboard-{ep}.md`
**需要模型**: `models.text`

### `/toonany storyboard-image [episode]`

生成分镜图。

**输入**:
- `storyboard/storyboard-{ep}.md`
- `assets/data.json`（资产引用）
- `assets/style-sample.jpg`（风格锚定）

**输出**: `storyboard/images/*.jpg`
**需要模型**: `models.image`

### `/toonany video [episode]`

生成视频。

**输入**: `storyboard/images/*.jpg`
**输出**: `video/ep{ep}-*.mp4`
**需要模型**: `models.video`

### `/toonany audio [episode]`

生成配音和字幕。

**输入**: `script/script-{ep}.md`
**输出**:
- `audio/ep{ep}/`（音频文件）
- `subtitle/ep{ep}.srt`（字幕）

**需要模型**: `models.audio`

### `/toonany finalize [episode]`

后期合成成片。

**输入**:
- `video/ep{ep}-*.mp4`
- `audio/ep{ep}/`（可选）
- `subtitle/ep{ep}.srt`（可选）

**输出**: `final/episode{ep}.mp4`

**依赖**: ffmpeg


path: requirements.txt
content: # Core dependencies for Toonany scripts
requests>=2.31.0
Pillow>=10.0.0

# Optional but recommended
python-dotenv>=1.0.0


path: scripts/utils/__init__.py
content: """Toonany shared utilities."""

from .logger import setup_logger
from .config_loader import ConfigLoader, ConfigError
from .api_client import ImageAPIClient, VideoAPIClient, TTSAPIClient
from .dependency_tracker import DependencyTracker
from .consistency import ConsistencyChecker

__all__ = [
    "setup_logger",
    "ConfigLoader",
    "ConfigError",
    "ImageAPIClient",
    "VideoAPIClient",
    "TTSAPIClient",
    "DependencyTracker",
    "ConsistencyChecker",
]


path: templates/project/storyline.md
content: # 故事线

## 主题
（待填写：一句话概括核心主题）

## 主线剧情
（待填写：2-3段概括主要剧情走向）

## 主要人物关系
（待填写：人物关系图或列表）

## 情感基调
（待填写：整体情感氛围）


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)