# 漫剧分集规则（产品主规范）

> **地位**：PRINTFILM 漫剧「分集 → 分镜 → Seedance 生成」的**单一真相源**。  
> 后续改 `fragment_plan` / `build_fragments` / 前端编辑器 / 规则弹窗，均以本文为准。  
>  
> 细则附录：[SEEDANCE_2_5.md](./SEEDANCE_2_5.md)（模型参数）· [SHOT_SPLITTING.md](./SHOT_SPLITTING.md)（拆镜操作细节）  
> 资料来源：火山方舟 / Seed 官方、社区 Prompt Skill（MapleShaw / dexhunter）、本仓库现实现。  
> 版本：v1.0 · 2026-08-13

---

## 0. 一句话原则

**一集 = 开幕交代 + 若干可独立重跑的分镜；一分镜 = 一次 Seedance 任务（≤30s）；镜内用画面/对白/旁白分段，空镜绝不口播。**

---

## 1. 层级模型

```
项目 Project
  └─ 分集 Episode（本集场记正文 + 顶栏生成参数）
        └─ 分镜 Fragment（一次 Seedance 调用）
              └─ 段 Beat（@duration + 画面|对白|旁白）
```

| 层级 | 产品对象 | 时长 | 一次动作 |
|------|----------|------|----------|
| 分集 | `DramaEpisode` | 多镜串联，常见 1–3 分钟量级成片 | AI 重新分镜 / 全部生成 |
| 分镜 | `DramaFragment` | **优先 8–20s，硬上限 30s** | 单镜「生成」 |
| 段 | 脚本内 `@duration` | **3–12s** | 镜内节奏，非独立任务 |

常量（代码必须对齐）：

| 常量 | 值 | 位置 |
|------|-----|------|
| 单段 min/max | 3 / 12 | `seedance_segments` / `segmentDuration.ts` |
| 单镜软/硬上限 | 20 / 30 | `build_fragments` |
| Seedance duration | 4–30 | `fragment_content_duration` / Ark |
| 参考音频目标/上限 | 15s / ~30s | `voice_reference_audio` |

---

## 2. 分集结构规则

### 2.1 开幕镜（强制，`fragments[0]`）

| 要求 | 说明 |
|------|------|
| `is_opening: true` | 仅首条 |
| 时长 | 建议 8–15s |
| 必须交代 | 「第 N 集」原文 + 本集标题；1–3 句背景/前情；开场气氛画面 |
| 角色 | `character_names` 通常空或极少；**禁止**写人物介绍文案 |
| 片头 | 集号只在开幕强调一次；后续镜禁止重复整集片头 |

系统后处理写入：`【片头·集号叠字】`、`【背景介绍·画面叠字】` 等（模型不要输出这些 cue）。

### 2.2 正戏镜（`fragments[1…]`）

- 按**场面 / 情绪段落**拆，一场戏通常 1–4 镜  
- 覆盖场记全部有效冲突与转折，禁止无故删戏  
- 整集避免碎成「一句一对白一镜」  

### 2.3 何时必须切新镜

满足任一即切：

1. 场景切换（地点 / 日夜 / 内外）  
2. 主要角色组合明显变化  
3. 情绪段落切换（铺垫→冲突→反转→收束）  
4. 叙事职责不同（开幕 ≠ 对白戏 ≠ 纯空镜）  
5. 累计将超过软上限 ~20s（硬上限 30s）  

### 2.4 分集顶栏参数（作用于本集各镜）

| UI | 提交字段 | 规则 |
|----|----------|------|
| 视频风格 | 提示词风格块 | 全片强制画风 |
| 模型 | `model` | 默认 Seedance 2.5 |
| 画幅 | `ratio` | 竖屏短剧常用 `9:16` |
| 清晰度 | `resolution` | 草稿 `480p`，成片可 `720p` |

同集生成应保持画幅/风格一致；单镜可改脚本，不改顶栏默认。

---

## 3. 分镜脚本规则（Fragment content）

### 3.1 脚本组装顺序（系统写入）

```
【字幕 cue】
【BGM cue】
【片头/背景叠字】（仅开幕）
【人物介绍·画面叠字·角色身旁】（仅本剧首次出场，贴角色身旁）
@duration:N
【画面|对白|旁白】正文…
（可多段 @duration）
```

漫剧字幕 cue：`【字幕：底部居中·简体中文·逐句轮换·与口播同步】`  
（同一时刻只显示一行/一句，随口播逐句轮换；勿用「全程旁白烧录」类科普 cue，避免整镜被念。）

### 3.2 三类正文（铁律）

| 类型 | 用户/LLM 写法 | 系统前缀 | 配音 | 字幕 |
|------|---------------|----------|------|------|
| 画面 / 空镜 | `空镜：…` `远景：…` 或纯环境动作描写 | `【画面·无配音仅环境音】` | 否 | 否 |
| 对白 | `角色名：台词` | `【对白·慢速清晰·同步字幕】` | 是 | 是 |
| 旁白 | `旁白（VO）：…` | `【旁白·慢速清晰·同步字幕】` | 是 | 是 |

**禁止**：

- 把 `空镜：黄河浪…` 写成对白/旁白（会口播并烧字幕）  
- 在画面段要求「对口型 / 贴词同步」  
- 无口播意图却使用「同步字幕」对白前缀  

提交 Seedance 前须纠正误标行（已实现 `rewrite_misclassified_visual_voice_lines`）。

### 3.3 镜内节奏模板（推荐）

**建立空镜 →（动作）→ 对白/旁白 →（反应空镜）**

```
【字幕：底部居中·简体中文·逐句轮换·与口播同步】
【BGM：史诗弦乐铺底，音量低于人声】
@duration:4
【画面·无配音仅环境音】空镜：浑浊黄河拍击老石，远坡百姓扶老携幼……
@duration:6
【对白·慢速清晰·同步字幕】禹：水患未平，岂能退！
@duration:4
【画面·无配音仅环境音】特写：禹攥紧简册，目光望向下游。
```

单镜内镜头变化建议：**约 3–7 段**；15s 内过密易闪。

### 3.4 时长估算

| 类型 | 经验 |
|------|------|
| 空镜 / 画面 | 2–6s |
| 旁白 | ~3 字/秒，再钳 3–12s |
| 对白 | 略短于旁白，留呼吸停顿 |

口播：**慢速清晰，禁止赶词**（写入 Seedance 强制约束）。

### 3.5 `@asset` 与 `@duration`

| Token | 含义 | 提交时 |
|-------|------|--------|
| `@asset:ID` | 引用角色/场景/道具 | →「名称（参考图 N）」；正文里已经写了同名则不再叠写 |
| `@duration:N` | 本段秒数 | → `00:00-00:04` 时间区间；合计 → API `duration` |

LLM 分镜**禁止**直接输出 `@asset` / `@duration` / `【字幕】【BGM】【人物介绍】`（系统后处理注入）。

---

## 4. 资产与参考规则

### 4.1 本镜引用范围

- 只引用**本镜真正用到的**角色图 / 场景图  
- 稳定优先：主体参考图约 **1–8**，勿一镜塞满 30 张  
- `character_names`：仅正文点到的出镜角色；群演可省略  

### 4.2 音色（暂关）

当前**不绑定、不提交** `reference_audio`。口播由 Seedance `generate_audio` 按对白/旁白自行发挥。角色图仍作 `reference_image`。

| 规则 | 说明 |
|------|------|
| 要对白的角色 | 不强制试听；写清对白即可 |
| 角色 VO | `角色（vo）：台词` 走对白/内心独白，不是第三人称旁白；纯 `角色（vo，情绪）。` 是舞台指示，禁止口播 |
| 旁白 | 第三人称旁白行由模型配音，不挂项目级旁白音频 |

<!-- 恢复绑定后改回：要对白的角色必须绑定试听；未开口角色只挂形象图 -->

### 4.3 人物介绍叠字

- 仅**本剧第一次出现**的重要角色  
- 格式：`【人物介绍·画面叠字·角色身旁】姓名｜短简介`  
- 位置：贴在对应角色**身旁**（肩侧小字），随首次入画短暂出现；禁止居中大标题、禁止与底部口播字幕抢位  
- 非口播；不要让模型念介绍全文  

### 4.4 Seedance 2.5 素材上限（生成侧）

| 类型 | 上限 | 备注 |
|------|------|------|
| 参考图 | ≤30 | 产品侧按本镜精简 |
| 参考视频 | ≤10，合计 ≤~30s | 当前主路径少用 |
| 参考音频 | ≤10，合计 ≤~30s | 角色+旁白 |

详见 [SEEDANCE_2_5.md](./SEEDANCE_2_5.md)。

---

## 5. 运镜与提示词写法（分集内可用）

社区与官方共识，写入镜内画面描写时遵守：

1. **公式**：主体 + 动作/姿态 + 场景环境 +（景别/运镜）+ **结束态** +（光影可选）  
2. **每段运动轴 ≤ 2**（推+摇可以；推+摇+升同时易失控）  
3. **近景大旋转易崩脸** → 环绕留给中景以上  
4. **参考必须写清用途**：形象 / 场景 / 运镜 / 音色（本仓库用「参考图 N / 参考音频 N」约束块）  
5. **信息完整、忌干瘪**：禁止「禹站在河边」式一句摘要；须写清空间关系、道具用法与本段结束可见状态。同时避免堆砌无关形容词噪声  
6. **勿写编辑/延长措辞**于普通生成（避免任务被重分类）  

景别标签可直接用于画面行：`空镜：` `远景：` `近景：` `特写：` `全景：` 等。

AI 重新分镜（`fragment_plan`）须按上述公式输出画面行；单镜建议 **3–7 行**（建立→动作→口播→反应），对白镜至少保留 1 条画面行。

### 5.1 编辑器词库（`@` → 小工具 → 景别/运镜）

代码源：`frontend/src/lib/dramaCameraLexicon.ts`

| 组 | 可插入前缀 |
|----|------------|
| 景别 | `空镜：` `远景：` `全景：` `中景：` `近景：` `特写：` `大特写：` `建立镜头：` `气氛镜头：` |
| 运镜 | `推镜：` `拉镜：` `摇镜：` `移镜：` `跟拍：` `俯拍：` `仰拍：` `航拍：` |

插入后继续补写主体与动作；这些行一律按**画面**处理，禁止再包一层对白/旁白 cue。

## 6. Seedance 提交契约（每镜）

| 字段 | 来源 |
|------|------|
| `model` | 顶栏模型 |
| `content[]` | text 提示词 + reference_image（暂不提交 reference_audio） |
| `duration` | `@duration` 合计（4–30） |
| `ratio` / `resolution` | 顶栏 |
| `generate_audio` | `true`（短剧口播） |
| `watermark` | `false` |
| `return_last_frame` | `true`（落盘 `params.lastFrameUrl`；顶栏可开关跨镜衔接） |

提示词块顺序：

1. 画面风格强制约束  
2. 音频/字幕/BGM 强制约束（区分画面-only vs 对白/旁白）  
3. 角色形象 / 场景 / 道具 → 参考图序号  
4. 正文（已替换 asset / duration）  

（角色/旁白音色 → 参考音频序号：暂关）  

---

## 7. AI 重新分镜（`fragment_plan`）契约

### 7.1 模型只输出

```json
{
  "fragments": [
    {
      "duration_sec": 12,
      "scene_name": "地点",
      "character_names": ["角色"],
      "is_opening": true,
      "lines": ["空镜：…", "禹：…", "旁白（VO）：…"]
    }
  ]
}
```

### 7.2 模型禁止输出

`### 场`、出场人物行、一切 `【字幕】【BGM】【人物介绍】【片头】`、`@asset`、`@duration`。

### 7.2.1 画面描写密度（与 §5 对齐）

- 每条画面行：主体 + 动作 + 场景 + 景别/运镜 + 结束态  
- 单镜约 3–7 行；对白镜至少 1 条画面行  
- 禁止干瘪一句摘要；禁止把动作塞进对白冒号后当台词  

### 7.3 系统后处理

1. 行分类打前缀（空镜 → 画面）  
2. 注入 cue / `@duration` / 开幕叠字 / 首次介绍  
3. 超软上限拆 Fragment  

---

## 8. 生成与预览行为

| 规则 | 说明 |
|------|------|
| 单镜生成 | 仅锁当前镜按钮；其它镜可编辑、可预览 |
| 全部生成 | 有进行中任务时禁止重复全部入队 |
| 并行 | video 队列最多约 10 路 |
| 预览 | 轮询刷新 fragments **不得打断**正在播放的视频 |
| AI 重新分镜 | 与视频生成互斥 |

---

## 9. 分集质量门禁（发布前 / 生成前）

### 9.1 结构

- [ ] 存在开幕镜且含集号+背景+气氛  
- [ ] 正戏覆盖关键冲突，无无故删戏  
- [ ] 无「一句一镜」碎片化  

### 9.2 脚本

- [ ] 每镜合计 ≤30s，单段 3–12s  
- [ ] 空镜/景别均为画面前缀  
- [ ] 对白/旁白前缀仅用于真实口播  
- [ ] BGM 声明音量低于人声  

### 9.3 资产

- [ ] 出镜角色有图  
- [ ] 本镜引用未明显超量  

### 9.4 提交

- [ ] 顶栏画幅/模型/风格已确认  
- [ ] 普通生成未含「编辑/延长」歧义措辞  

---

## 10. 后续完善清单（按本文推进）

改代码时对照本节勾选；完成一项在 PR / 发布记录里引用本文章节号。

| 优先级 | 项 | 对应章节 | 状态 |
|--------|-----|----------|------|
| P0 | 空镜/景别永不进对白前缀；提交前纠正 | §3.2 | 已做 |
| P0 | 开幕镜强制字段与系统叠字 | §2.1 | 已有，持续校验 |
| P1 | `fragment_plan_prompt` 与本文 §3/§5/§7 全文对齐（含画面密度/结束态） | §5、§7 | 已对齐（2026-08-13 加密度硬约束） |
| P1 | 前端脚本校验：空镜行禁止对白 cue、时长合计告警 | §3、§9 | 已做（`dramaEpisodeScriptValidate` + 编辑区提示 + 生成阻断） |
| P1 | SeedanceRulesModal 文案与本文同步 | §3–§6 | 已同步（漫剧字幕 cue / 空镜铁律） |
| P2 | 运镜词库（景别/推拉摇移）写入编辑器 @ 菜单或帮助 | §5 | 已做（`dramaCameraLexicon` + @ 小工具） |
| P2 | 生成前资产门禁（缺图/缺音色阻断或明确警告） | §4、§9.3 | 已做（警告级，确认框可继续） |
| P2 | 尾帧衔接 / 延长路径产品化（可选） | §6 `return_last_frame` | 已做：落盘尾帧；有参考媒体时以 `reference_image` 衔接（禁混 `first_frame`）；延长路径未做 |
| P3 | 剪辑节奏公式用于整集导出 | 社区 Skill | 已做（导入时写入时长；`dramaEditRhythm` 可供导出规划） |

---

## 11. 相关代码索引

| 模块 | 路径 |
|------|------|
| AI 分镜提示 | `backend/app/services/drama/fragment_plan_prompt.py` |
| AI 分镜规范化 | `backend/app/services/drama/fragment_plan.py` |
| 场记切镜 / 行分类 | `backend/app/services/drama/build_fragments.py` |
| 生产约束 / 空镜纠正 | `backend/app/services/seedance_segments.py` |
| 组装请求体 | `backend/app/services/drama/build_seedance_generate_body.py` |
| 生成任务 | `backend/app/services/drama/generation.py` / `jobs.py` |
| 前端时长 | `frontend/src/lib/segmentDuration.ts` |
| 前端脚本/资产门禁 | `frontend/src/lib/dramaEpisodeScriptValidate.ts` |
| 运镜/景别词库 | `frontend/src/lib/dramaCameraLexicon.ts` |
| 分镜板宫格导入 | `frontend/src/lib/dramaStoryboardGrid.ts` / `StoryboardGridImportModal` |
| 剪辑节奏公式 | `frontend/src/lib/dramaEditRhythm.ts` |
| 分集编辑页 | `frontend/src/pages/drama/EpisodeEditPage.tsx` |
| 规则弹窗 | `frontend/src/components/drama/SeedanceRulesModal.tsx` |

---

## 12. 文档关系

| 文档 | 职责 |
|------|------|
| **本文 EPISODE_RULES.md** | 分集产品规则主规范（改需求先改这里） |
| [SEEDANCE_2_5.md](./SEEDANCE_2_5.md) | 模型/API 参数百科 |
| [SHOT_SPLITTING.md](./SHOT_SPLITTING.md) | 拆镜操作手册与示例 |
| [STANDARDS.md](./STANDARDS.md) | 工程规范 |

上游 Seedance 官方变更时：先更新 `SEEDANCE_2_5.md`，再修订本文 §4.4 / §6，最后改代码常量。