novel-storyboard

Files (23)

• README.en.md
• README.md
• SKILL.md
• report.webp · assets/
• 渡口-storyboard.json · examples/
• fight-enhancement.md · references/
• frame.md · references/
• h3-prompt.md · references/
• report-style.md · references/
• schema.md · references/
• seedance-prompt.md · references/
• shot-writing.md · references/
• storyboard-pass.md · references/
• hands-tell.md · references/test-fixtures/shot-recipes/
• insert-beat.md · references/test-fixtures/shot-recipes/
• ots-shot-reverse.md · references/test-fixtures/shot-recipes/
• README.md · references/test-fixtures/upstream/
• 渡口-art.json · references/test-fixtures/upstream/
• 渡口-cast.json · references/test-fixtures/upstream/
• 渡口-outline.json · references/test-fixtures/upstream/
• 渡口-script.json · references/test-fixtures/upstream/
• novel-storyboard.mjs · scripts/
• selftest.mjs · scripts/

SKILL.md (first lines)

## novel-storyboard

打戏增强是可选模式，由 Python Agent 的 `--fight-enhancement off|auto|enhanced` 控制；默认 `auto`。详细规则见 `{baseDir}/references/fight-enhancement.md`。`off` 完全沿用普通分镜；`auto` 只强化剧情重要的打戏；`enhanced` 强化所有真实打戏。不要为非打戏场景添加战斗，增强动作仍须通过原有分镜质量门。

给 AI 短剧出**分镜**——管线里第一个直接面对视频模型的层。**前提刻在骨子里：镜头是生成出来的，多切一镜的成本几乎为零**，所以这里不心疼镜头数量。段长与切长以当前 `storyboard.json.params` 为准，不得把其他文档的默认值覆盖当前配置。

**核心机制：镜头认领节拍。** 每个镜头声明它覆盖剧本某场的哪几个连续节拍（`sceneIndex` + `beats: [起, 止]`），镜头不许跨场次——换景必换镜。这让分镜和剧本的关系变成可机械对账的：

| 交付 | 解决什么 |
| --- | --- |
| 节拍认领 | 每个节拍被恰好一个镜头认领、顺序不乱——剧本改了重跑 validate，失效的镜头当场点名 |
| 段长与切长由 params 控制 | `maxSegmentSeconds` 限制一次生成总时长，`minCutSeconds` / `maxCutSeconds` 限制段内每个分镜；超限必须拆分或合并镜头 |
| 台词装得下 | 认领节拍的台词秒数 ≤ 镜头秒数——逐镜检查，不是拍脑袋 |
| 分镜图提示词 + 镜头正文 | 分镜图提示词（`frame`，中文，直呼角色名）给图像模型配合设定图出图；镜头正文（`shot`，中文，通用身份）写这几秒发生什么。景别是枚举，中文景别词必须写进分镜图提示词 |
| **Ref2V 视频提示词（每段一条）** | 直接遵循所选模型的 Ref2V Skill：H3 Ref2VA 或 Wan 3.0 Ref2V；不经过 I2V/T2V 中间格式 |
| **Seedance 视频提示词（每段一条，程序拼）** | 跟 H3 并列。由脚本按官方结构拼：参考图声明、段级走位、逐镜量化字段、台词 `{}`、音效 `<>`、配乐 `（）`、编号约束。模型只写每切的 `shot`，不写秒数、编号和图片引用 |
| 构图量化字段 | 每段 `blocking`（谁在左谁在右、间距），每镜焦距／机位／构图／视线落点／焦点／稳定性——不出分镜图时，它们就是构图的全部来源 |
| 生成批次单 | 同场景 + 同光照的镜头归一批，共用同一张环境参考图——AI 版的顺场表，脚本自动汇总 |
| 配音对齐单 | 每句台词对到镜号——TTS 音频贴到哪一段视频，脚本自动汇总 |

`{baseDir}` = 本文件所在目录。脚本 `{baseDir}/scripts/novel-storyboard.mjs`，零依赖，`node` 直接跑。

**边界（不做的事）**：不写戏不改台词（`novel-script` 的活）、不出场景/角色/道具设定图（`novel-art` / `novel-characters` 的活）、不做视频生成与剪辑合成。口型/唇形同步暂不管——那是生成管线的事。

---

### Step 0 — 定输入与范围

**script.json 是硬前提**——分镜离开剧本没有意义，validate/render 都必须给 `--script`。其余上游按有则用：

- `--outline` / `--cast`：提示词禁人名检查 + 报告里 C01 显示成人名
- `--art`：报告里 S01 显示成场景名 + 批次单嵌场景设定图
- `--shots <卡片目录>`：**可选**挂载 shot-recipes 的镜头配方卡库（指向 `shot-recipes/references/cards`，只接受目录不接受导出的 JSON），开第 18 道 `shot-recipe` 门。没装 shot-recipes 就别给——本 skill 自包含，不依赖它

**一次切几集**：跟剧本的批次走（剧本写到哪就分到哪），默认一批 ≤ 3 集。

**先定画幅**：storyboard.json 顶层 `aspectRatio` 是分镜与下游出图共同遵守的正式合同，只接受 `16:9` 或 `9:16`。没有特别要求时使用 `16:9`；竖屏短剧明确写 `9:16`。

### Step 1 — seed 工作底稿

```bash
node {baseDir}/scripts/novel-storyboard.mjs seed <script.json> --eps 1-3 --aspect 16:9 > <workdir>/storyboard.json
```

确定性展开：每场的节拍清单（编号、动作/台词、每拍秒数、说话人）进 `seedScenes`，这就是切镜时的工作底稿；同时把 `--aspect` 写进顶层 `aspectRatio`，省略时默认 `16:9`。**每拍几秒是算出来的，不要让模型重新估。** shots 留空，切镜才是模型的活。

### Step 2 — 逐集先切镜、再分段

每集一份任务，能并发就并发。每份任务拿到：

- `{baseDir}/references/storyboard-pass.md` 和 `{baseDir}/references/schema.md`（读它们，照着做）
- 该集的 seedScenes 底稿 + 场景卡（art.json 的锚点与光照提示词）+ 角色卡（cast.json 的形象要点）

流程：**先逐场切完全部镜头，再由程序分段**。模型按 sceneIndex 一场一份 scenePlan 输出完整有序 cuts，不输出 segments 或视频提示词；程序按每场每 3 镜头一段分组，末组允许 1–2 镜头，绝不跨场。每段总时长必须 ≤ `params.maxSegmentSeconds`；超限必须在镜头规划阶段解决，禁止事后拆段、删镜头或删节拍。每切写分镜图提示词（中文，直呼角色名）、镜头正文 `shot`（中文，通用身份）和六个构图字段；每段写 `blocking`、`soundscape`，有配乐再写 `music`。全部分镜图与下游生成图必须保持顶层 `aspectRatio` 指定的同一画幅。

**每段的镜头正文照 `{baseDir}/references/shot-writing.md` 写**（协议无关：一切一个运镜、动作要做得完、台词逐字、声音分层、不写画风）。发给哪个视频服务，就再套哪份协议语法：MiniMax H3 uses `skills/h3-prompt-writing/SKILL.md`，Seedance 见 the Seedance protocol instructions。

程序完成每场三镜头分组、资产绑定和连续性编号后，**为每段独立生成一条最终 Ref2V 提示词**，保存在兼容字段 `h3Prompt`，并复制到下游字段 `videoPrompt`。按 `videoModel` 使用对应外部 Skill：H3 或 Wan Ref2V。提示词只覆盖本段 cuts，参考图标签、对白格式和结构遵循选定 Skill。

**Seedance 提示词不用写**：`render` 报告的提示词面板和 `export --protocol seedance` 都会从上面这些字段现拼。视觉风格由调用方提交时附加，全局约束用 `--constraints <文件>` 给。

切完把 `seedScenes` 删掉。

### Step 3 — 校验 ⛔ 不能跳

```bash
node {baseDir}/scripts/novel-storyboard.mjs validate <storyboard.json> \
  --script <script.json> --outline <outline.json> --cast <cast.json> \
  [--shots </path/to/cards>]
```

18 道质量门全是代码：节拍全覆盖（分镜级，恰好一次、按顺序、连续）、段 0 < 总秒 ≤ `params.maxSegmentSeconds`、**每切 `params.minCutSeconds`–`params.maxCutSeconds` 秒**、台词装得进分镜、每集总时长在剧本目标 ±100% 内（可由 `params.tolerance` 覆盖）、同框 ≤ 3 人（超了必须带拆解说明）、段号 E01-01 格式连号、中文景别词在分镜图提示词里、运镜用 H3 词表且在自己的 [Shot k] 段落里、**H3 对齐指令由分镜结构推导逐字对账 + 切点时刻逐个对**、**认领台词逐字进 `<d>` 块**、**提示词语言与 promptLang 一致**（双向查：中文写成英文、英文混进中文都拦）、分镜图提示词中文非空、**视频提示词不含角色名**（H3 正文不分语言、Seedance 镜头正文都查；分镜图提示词直呼其名放行）、**构图量化字段齐全**、**Seedance 镜头正文合规**（中文非空，不写时间、镜头编号、图片引用和协议符号）、场次/人物/道具对账剧本、**镜头配方对账**（可选门，见下）。

结构检查还会校验可选的 `aspectRatio`：只接受 `16:9` 或 `9:16`。它属于 storyboard.json 合同检查，不另算质量门。

**有违规逐条修，改完重跑，直到通过。**

**第 18 道 `shot-recipe`（可选挂载）**：给了 `--shots` 才查，不给就明说跳过。cut 上可以写一个可选的 `recipe`（配方卡 id，**cut 级不是 segment 级**，**多格配方靠连续同 id 的分镜表达**，不是数组），门查三条——id 在卡库里、卡片的每条 `must_phrases` 出现在该切的 `frame` 里（两边小写化后 `includes`）、卡片 `cuts` 下限 ≥ 2 时连续同 id 的分镜数不得低于该下限。卡片的**建议景别与运镜不设门**，只在报告的「配方」列和 `checkup` 末尾提示偏离：配方是语汇不是法条，可选挂载的东西一旦变严就没人挂。

### Step 4 — 输出与汇报

```bash
cd <输出目录>
node {baseDir}/scripts/novel-storyboard.mjs render <剧名>-storyboard.json --md \
  --script <script.json> --outline <outline.json> --art <art.json> > <剧名>-storyboard.md
node {baseDir}/scripts/novel-storyboard.mjs render <剧名>-storyboard.json --html \
  --script <script.json> --outline <outline.json> --art <art.json> > storyboard-report.html
```

报告界面语言用 `--lang zh|en` 指定（优先级 `--lang` > JSON 顶层 `lang` 字段 > 默认中文）——只切界面标签，与 `promptLang`（H3 提示词语言）互相独立。主分镜图与子分镜条按顶层 `aspectRatio` 排版；旧数据的 `_meta.orientation` 与 frame 末尾画幅标签只作兼容。`render` 用 `--frames <目录>` 找分镜图（`<目录>/<段号>/f<切序>.png`，默认当前目录）、用 `--images <目录>` 找批次单的场景设定图（`<目录>/<场景 slug>-sheet.png`，默认 `./images`），两个都可以指到任意路径——**本 skill 不产生这些文件**，下游出完图重跑一次 render 就能嵌进报告。`export --frames <目录>` 会把找得到的分镜图拷进投产包，不用手动往包里放。报告含：KPI 带、分镜节奏带（粗分隔 = 段边界、片宽 = 分镜时长占比、颜色深浅 = 景别远近、点击跳段卡）、分集分镜表（主分镜图 + 子分镜条 + 逐切分镜行 + 分镜图/H3 提示词复制按钮）、生成批次单、配音对齐单、质量门、导出 JSON。Markdown 版每段附完整 H3 提示词，直接复制可用。

汇报一句话说清：几集几镜、总时长 vs 目标、几个生成批次、报告路径；没过的门明说。

**不要说「已出图」**——这一步不存在了，交付的是提示词和挂图清单。

最终落地：

```
<输出目录>/
├── <剧名>-storyboard.json
├── <剧名>-storyboard.md
├── storyboard-report.html         ← 双击就能开
├── manifest.json                  ← export 生成
└── E01-01/                        ← 一段一个文件夹 = 一次 H3 生成的全部材料
    ├── f1.png                     ← 主分镜图（下游出完放这儿）
    ├── f2.png …                   ← 子分镜图
    └── prompt.md                  ← H3 提示词（export 生成）
```

---

## 五个 skill 的接力（管线到此闭环）

```
novel-outline    → outline.json    （什么：结构与分集）
novel-characters → cast.json       （谁：角色设定图）
novel-art        → art.json        （哪里：场景/道具设定图）
novel-script     → script.json     （戏：场次、节拍、台词）
novel-storyboard → storyboard.json （怎么拍：镜头、首帧、批次）

From andnls100/shuohao-python-agen, Apache-2.0.

More from andnls100/shuohao-python-agen