novel-storyboard

novel-storyboard

给 AI 短剧出分镜——管线里第一个直接面对视频模型的层。前提刻在骨子里：镜头是生成出来的，多切一镜的成本几乎为零，所以这里不心疼镜头数量，上限只有一个：视频模型单段生成的时长（默认 15 秒）。

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

交付	解决什么
节拍认领	每个节拍被恰好一个镜头认领、顺序不乱——剧本改了重跑 validate，失效的镜头当场点名
单镜头 ≤ 15 秒	AI 视频单段生成上限，长对话在这里被强制拆镜（params.maxShotSeconds 按模型改）
台词装得下	认领节拍的台词秒数 ≤ 镜头秒数——逐镜检查，不是拍脑袋
分镜图提示词 + 镜头正文	分镜图提示词（frame，中文，直呼角色名）给图像模型配合设定图出图；镜头正文（shot，中文，通用身份）写这几秒发生什么。景别是枚举，中文景别词必须写进分镜图提示词
H3 视频提示词（每段一条）	MiniMax H3 的 I2VA 结构：固定对齐指令 + integrated_multimodal_description + overall_soundscape + non_diegetic_music。认领节拍的台词逐字进 <d>[Chinese] …</d> 块——对白、声景、配乐一段提示词全带上
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 工作底稿

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 的形象要点）

流程：先按剧情单元分段（每段 9–15 秒、不跨场），段内切 2–5 秒的分镜（对话正反打、关键动作插入特写、进场三件套——切镜语法都在 storyboard-pass.md），每切写一条分镜图提示词（中文，直呼角色名）、一段镜头正文 shot（中文，通用身份）和六个构图字段；每段写 blocking、soundscape，有配乐再写 music。全部分镜图与下游生成图必须保持顶层 aspectRatio 指定的同一画幅。

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

每段写一条 h3Prompt，照 {baseDir}/references/h3-prompt.md 写（官方方法论的内化版，不依赖任何外部 skill）。官方口径默认英文（promptLang 可切中文），每个镜头独立一行。要点：首行对齐指令和 [Shot k] 切点时刻由分镜秒数推导，一个字符都不许漂（validate 逐字对账）；认领台词逐字进 <d>[Chinese] …</d>；每切的运镜词写进自己那一行；声景与配乐分进后两个字段——声景也是动作指令，画面改了声景一起改。

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

切完把 seedScenes 删掉。

Step 3 — 校验 ⛔ 不能跳

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

18 道质量门全是代码：节拍全覆盖（分镜级，恰好一次、按顺序、连续）、段 0 < 总秒 ≤ 15、每切 2–5 秒、台词装得进分镜、每集总时长在剧本目标 ±15% 内、同框 ≤ 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 — 输出与汇报

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 （怎么拍：镜头、首帧、批次）

分镜是消费端：seed 吃 script.json，分镜图出图（在下游）吃 art 和 characters 的设定图当参考，H3 提示词直接下单给视频模型，配音对齐单接 script 台词本的 TTS 产物。五份 JSON 各自的报告都带导出按钮，改完都能喂回各自的 render/validate。

边界

• 报告界面内置中英（--lang，默认中文）；提示词语言由 promptLang 单独控制（默认英文）
• 秒数是下给视频模型的生成时长不是估算——段上限按你的模型改 params.maxSegmentSeconds，切的节奏区间改 min/maxCutSeconds
• 口型/唇形同步暂不管——那是生成管线的事
• 分镜图不追求一次到位——它是给视频模型的构图锚，构图对、资产对就够，微调交给重生成

门失败会累积

validate 与 checkup 每次都把门的结果追加到当前目录的 .gates.jsonl；跑 stats 汇总：

node {baseDir}/scripts/novel-storyboard.mjs stats

回答三件事：哪道门最常响（那条规则模型最常无视，该改的是措辞）、哪道门从没响过（可能是死门，也可能规则已被内化）、失败详情长什么样（反复出现却没有门的那类问题，只能靠人看）。

不想记加 --no-log；写不进去静默跳过，不影响校验。

自测

node {baseDir}/scripts/selftest.mjs

336 项断言，不调模型、不花额度。18 道质量门每一道都有击穿用例。改完脚本先跑这个。

自带样例

{baseDir}/examples/渡口-storyboard.json：《渡口》第 1 集完整分镜——10 段 34 切认领剧本全部 35 拍，平均 3.5 秒一切，共 119 秒 / 目标 120 秒，2 个生成批次，每段带完整的 H3 视频提示词（多图对齐 + 切点时刻全部对账通过）。当质量基准，也是自测夹具。