@oh-story/dsh 0.1.8 → 0.1.10

package/lib/drama/skills/short-drama-video-prompts/references/minimax-h3.md

@@ -29,10 +29,24 @@ overall_soundscape: ...
 non_diegetic_music: ...
 ```
 
-- 画面段按 `[Shot 1]`、`[Shot 2]` 写动作和镜头；单镜也保留 `[Shot 1]`。
-- 声音段闭合所有对白、环境声与音效。无配乐时写 `non_diegetic_music: N/A`，不要留空让模型补乐。
+- `integrated_multimodal_description` 按 `[Shot 1]`、`[Shot 2]` 写画面、动作、说话人、逐字对白和同步声音；
+  单镜也保留 `[Shot 1]`。第一镜不加切镜时间戳，后续切镜用 `[Shot 2] At 00:03.500, ...`，时间递增且落在本次生成时长内。
+  小样本观察到切点接近要求，但仍有偏差；交付要求精确时应检查实际切点并在剪辑中调整。
+- `overall_soundscape` 汇总环境声、物理音效和非语言人声，不重复对白；对白事件留在上面的主时间线。
+  无非画内配乐时写 `non_diegetic_music: N/A`，不要留空让模型补乐——这一条有实测支撑，见
+  [无对白镜](#无对白镜)。
 - 首帧模式从输入帧的可见姿态开始；首尾帧模式只能到达上游已接受终点，不发明过渡后的新状态。
 
+## 无对白镜
+
+在 `overall_soundscape` 写清全镜的环境声、音效或静默。
+**`craft_default`**：优先描述需要的声轨；必要时可以补「无对白」，不因用了否定句判错。
+人物嘴部状态按实际表演写，不能把无对白一律改成全程闭嘴。
+
+无非画内配乐时保留 `non_diegetic_music: N/A`。小样本中省略这一层出现过额外配乐，
+显式写空可作为 H3 的默认写法，不保证所有生成都遵守。
+时间线总结只列本镜实际存在的声音层，不照抄包含对白的模板。
+
 ## 选哪一种模式
 
 模式由本镜「输入参考图」里各槽位的 `用途` 决定，不由“想不想用多模态”决定：
@@ -105,7 +119,11 @@ REF-STUDY-PLATE（顺序：3；用途：地理）    -> <Picture 3>
 
 ### 每张图带什么、不带什么
 
-`用途` 决定这一张在正文里被要求保留什么，具体到哪几项由该槽位自己写下的 `控制` 范围决定：
+`用途` 决定这一张在正文里被要求保留什么，具体到哪几项由该槽位自己写下的 `控制` 范围决定。
+
+需要保留构图时，在 `控制` 中点名构图、站位或机位高度。
+`不得控制` 记录不应照搬的内容，生成后仍需检查实际参考影响，不能把文字声明当成模型保证。
+
 `起始帧` 只锚定开场构图与姿态，`身份` 锚定这个人跨镜不变的长相与体态（角色板同时固定本集造型时，
 `控制` 里会写明），
 `地理` 只锚定空间关系，`造型状态` 只锚定服装与损污。把这条差异写进 `retention_analysis`，
@@ -113,6 +131,7 @@ REF-STUDY-PLATE（顺序：3；用途：地理）    -> <Picture 3>
 
 角色始终使用同一个说话人 ID；中文对白只出现在 `<d>[Chinese] ...</d>` 内。禁字幕写进可见文字约束，
 与获准的画内文字分开。
+Full-reference 的逐字对白与同步声音放在 `detailed_description` 的对应事件里，`overall_soundscape` 仍只汇总底声与音效。
 不要为了“多模态”把所有资产图都带上；每镜只绑定它真正可见且需要保持的起始帧、人物、地点或关键道具图。
 
 ### 一个完整例子
@@ -135,7 +154,7 @@ non_diegetic_music: N/A
 ```
 
 三张图各自只负责一件事：`<Picture 1>` 给构图，`<Picture 2>` 给身份，`<Picture 3>` 给地理。
-把这条差异写进 `retention_analysis`，角色板就不会顺带决定构图，场景板也不会顺带决定长相。
+把这条差异写进 `retention_analysis`，生成后检查身份、构图与地理是否分别保留。
 
 ## 素材数量上限
 
@@ -164,7 +183,57 @@ full-reference：
 
 ## 时长
 
-MiniMax-H3 的整数时长是 4–15 秒，`MiniMax-H3-Max` 是 5–15 秒（不支持 4 秒）。短动作在至少 4 秒的镜头内完成并 hold 已接受终点；超过 15 秒的
-镜头在分镜阶段按闭合状态拆开。本阶段不偷改镜头秒数。
+**`structural_invariant`（执行端契约）**：MiniMax-H3 的 `duration` 必填，为 4–15 的任一整数秒，
+并非只有 5/10/15 三档。网页界面或 job 的时长设置要与分镜时长和正文终点一致；写在提示词里的秒数
+不能替代生成设置。短动作在合法镜长内完成并保持已接受终点；超过 15 秒的镜头回分镜按闭合状态拆开。
+本阶段不偷改镜头秒数。
+
+`MiniMax-H3-Max` 是另一型号：5–15 秒、480P/768P，仅支持文生和首/尾帧，不支持 full-reference。
+不能把本页 H3 的参考音频路径或 4 秒下限套到 Max。
+
+### 对白容量与自然语速
+
+**`craft_default`**：按 [对白预算](performance-action-timing.md#对白预算) 先核对完整发声需要多久，
+再给主时间线安排开口、停顿与落点。分镜镜长够长但开口太晚，一样会赶词。
+H3 中文小样本可参考约 4.1 个可发声字/秒；用实际可发声区间估算，生成后核对台词完整性。
+样本出现过赶词与静默截断，不能据此确定通用截断阈值。
+口语语言、声线与语速描述放在 `<d>` 外；`<d>` 内只放语言标签和逐字台词，不放秒数或表演指令。
+稳定说话人用 `(S1)`、`(S2)`；full-reference 中说话人物同时写 `<Subject N> (Sx)`。
+
+无参考音频时，以自然语言交代说话方式、开口 cue、句间停顿和说完后的动作；文本估时区间只留在镜头说明中，
+不把每个词硬塞进小数秒槽。实际有音频对齐依据或已接受的精确时点时，才据此细化声音时序。
+H3 官方接口未提供独立 `speech_rate` 参数，也没有公布「中文每秒固定几字」的可靠公式；
+提示词中的语速与时机是生成指导，不能当作秒级执行保证。仅追加“自然语速”无法补上缺失的发声时间。
+
+同一次生成内，已接受的对白跨切镜时可以用 `<scenetrans>` 并声明声音连续；它不会增加总时长，也不能
+保证两个独立 job 的音频无缝衔接。`<cutoff>` 表示视频结束时有意截断发声，只用于剧本已要求的截断，
+不用于处理装不下的完整台词。
+
+### 有配音或参考音频时
+
+**`craft_default`**：已有同句同表演音频时，先测实际发声与停顿，再确定镜长。没有现成音频仍可按文本估计
+写提示词，不为完成本阶段自动调用 TTS 或生成服务。
+
+- 只参照音色、情绪或说话方式：使用 `reference`；它会重新表演本镜台词，不能拿参考音频的文件长度
+  当作新台词时长，也不携带参考音频里无关的原话。
+- 已接受完整声音轨原样复用：`fully_copy` 表示整条最终音轨；只用对白层或片段并另加环境声时使用
+  `partially_copy`，写清源片段与目标时间的对应。复用用到的发声区间要完整容纳，不为适配镜长压缩语速。
+- 参考音频走 full-reference，配合至少一张参考图或一段参考视频；每段音频 2–15 秒，最多三段、合计
+  不超过 15 秒。图片改用 `reference_image`，不能与 `first_frame`/`last_frame` 混用。
+
+`fully_copy` 等是官方提示词的复用意图，不是逐样本一致的验收证明。生成后核听逐字内容、语速、停顿、
+尾音完整性与口型；项目需要精确锁定已有音轨时，以后期保留该音轨并核对画面同步作为最终依据。
+
+### Context-IR 的作用
+
+H3-Context-IR 把多模态输入增强成结构化提示词，本身不生成视频，且仍要求调用方先给出 4–15 秒的
+`duration`。它不能代替对白预算。若执行端使用该服务，检查增强后的逐字台词、声音时间线与原时长一致，
+不因使用官方增强就跳过容量检查。
+
+官方依据（2026-09-07 核对）：
 
-依据：MiniMax-H3 官方 base/ref prompt writing guides 与 MiniMax v2 video generation API。
+- [Base 提示词指南](https://github.com/MiniMax-AI/MiniMax-H3/blob/main/skills/h3-prompt-writing/references/base-en.txt)：对白位置、说话人、语速描述、切镜时间戳与跨镜发声。
+- [Full-reference 指南](https://github.com/MiniMax-AI/MiniMax-H3/blob/main/skills/h3-prompt-writing/references/ref-en.txt)：六段结构、音频引用与复用语义。
+- [视频生成 API](https://platform.minimax.io/docs/api-reference/video-generation-v2-create)：必填时长、型号差异和输入模式互斥。
+- [官方 CLI 的 H3 指南](https://github.com/MiniMax-AI/cli/blob/main/skill/h3-video/references/h3-video.md)：音频配合视觉参考，声音对齐与生成后检查。
+- [Context-IR API](https://platform.minimax.io/docs/api-reference/video-generation-v2-h3-context-ir)：提示词增强和独立的时长输入。

package/lib/drama/skills/short-drama-video-prompts/references/motion-recipe.md

@@ -130,7 +130,7 @@ reviewer 结合完整故事义务决定，不能让未承担内容随更短提
 
 先把起点中的持续关系翻译成动作自由度：用正向状态写清贯穿本镜的支撑、固定、接触或空间关系，
 再只安排允许的身体/物件通道。关系变化必须来自已接受动作并落到已接受终点；否则按 `VID-01`
-保持只读。可复制正文只写持续状态和允许动作，不用 `no/not/without + 动作` 复述边界。
+保持只读。可复制正文写清持续状态和允许动作，避免重复约束；必要的排除条件可以保留。
 成稿后在正文内直接改掉残留的这类否定结构，不另建检查步骤或报告。
 
 **`craft_default`**：一条运动提示词优先只有一个主导的戏剧变化，必要反应、环境与摄影
@@ -172,7 +172,10 @@ reviewer 结合完整故事义务决定，不能让未承担内容随更短提
 1. 按发生顺序列出本镜全部对白、VO、OS、必要非语言发声和 SFX；
 2. 每条台词同时标说话人、声源性质、口语语言和逐字文本，发声从原文首字开始、到末字结束；
 3. 所列事件之外只保留已声明的 ambience 或静默；相邻两句之间若有停顿，也明确回到这一底声；
-4. 声明时间线完整并结束声音段落，不再列出或否定集合外的语言、语气或声源。
+4. 用实际存在的声音层总结时间线，避免模板与本镜内容矛盾。
+
+无对白镜写清底声或静默及覆盖区间。必要的「无对白」声明可以保留，
+人物嘴部状态由本镜表演决定。非画内配乐的空形式按目标方言填写。
 
 确有叹气、吸气、笑声或重叠说话时，把它作为有来源的事件列入。声音不同轨时仍只写后期职责。
 

package/lib/drama/skills/short-drama-video-prompts/references/performance-action-timing.md

@@ -148,6 +148,27 @@
 
 评估：句长与语言、人物语速、情绪造成的停顿/吞吐、是否需要听见对方/环境 cue、口型要求、动作是否能与说话叠加、结尾是否有 reaction landing。固定每秒字数只能作为 production profile 的可覆盖估算，不能成为通用规则。
 
+**`craft_default`**：先读取分镜「声音」的预算依据。有同句同表演录音时用实测发声区间；没有时按完整原文、
+语言和表演方式给出「文本估计」区间，以较慢一端检查容量，不假称朗读或 TTS 实测。对白可用窗口要扣除
+开口前等待、不能同时进行的动作、轮流说话的其他发声与末尾反应；句内停顿已经计入时不再重复扣除。
+并行动作可以共享时间，顺序事件必须累加。把依据简写在当前镜头说明里，不放进可复制正文当成模型指令。
+
+例如 accepted duration 为 7 秒，开场与收尾各占 0.5 秒，实际只剩 6 秒发声；若完整台词估计需要
+8–10 秒（含句内停顿），即使写成「0–7 秒」也不成立。请求分镜按至少 11 秒重新安排，或按语义拆镜，
+待上游修订后同步本镜时长、正文时序和生成设置。不要用更快语速、截断标记或静默删词让算术看起来成立。
+
+### H3 中文的估算参考
+
+**`craft_default`**：一次同镜头、20 次生成的中文对照中，自然语速约 4.1 个可发声字/秒。
+短镜装入更多台词时先出现赶词，较长输入还出现未报错的截断；延长镜头改善了该组表现。
+样本不能确定通用截断阈值，其他声音、表演和模型需要另行校准。
+
+无录音时可用约 4.1 字/秒辅助估算实际可发声区间，并另计开口等待、停顿和顺序动作。
+这不是按整个镜长计算的保证容量；有音频时以实际发声区间为准，生成后回听是否完整。
+
+这里的字数不含标点。`duration_estimate.py` 的 `dialogue_characters` 包含标点，
+不能直接按这一语速换算发声时长。
+
 对白太长时选项：
 
 1. 简化非必要动作，让对白成为主事件；

package/lib/drama/skills/short-drama-video-prompts/references/production-prompt-grammar.md

@@ -244,11 +244,8 @@
 **`VID-22 · reviewed_invariant`**：交给执行端的那段文本里，只能出现要被拍出来的画面内容。
 任何描述“我们内部怎么做这件事”的流程词都不得进入。本条同样管关键帧的交付文本。
 
-执行端把整段交付文本当作**画面描述**读取，它没有办法区分“这句是给人看的工艺备注”和
-“这句是要画的东西”，于是把文件名渲染成画面上的字符、把版本号读成画面里有两个版本的
-同一个人、把否定罗列里的名词当成应当出现的物件。这类缺陷和动作超载不是同一种问题：
-超载只是难以完成，工艺词进入交付文本会直接让画面长出没有人要过的东西，而且是最难在
-文字审查中被发现的一类——它读起来“信息很全”。
+可复制正文只保留生成所需的画面、动作、声音和限制条件。
+内部流程备注留在正文外，避免与生成内容混淆；不假定出现某个词就一定被模型画出来。
 
 不得进入交付文本：
 
@@ -256,18 +253,10 @@
 2. 内部锁定标记、规则 ID、`hash`、字段路径与状态词（`accepted`、`stale`、`provisional`）；
 3. 走位草图、示意图、分镜板格号的指代（“按草图第二格”“沿用上次走位”）；
 4. 任务备注、重投说明、失败记录与待办（“这次重生成”“上次手部崩坏”“重点修手”）；
-5. 成段的否定罗列：把一长串“不要 X”堆在正文首尾。唯一允许的否定是项目确实没有可读
-   文字义务时的无文字要求（见第五节第 1 条）。
-6. **把本文件的规则本身抄进去**。实测最常见的一种：
-   `以竖屏当代写实动画化 SHOT-EP001-01，时长 2.5 秒。戏剧目的：冷开场。表演者：CHAR-JIANGCHEN。
-   只做常见的整体动作，不做精确拦截、不可见内部状态、否定式动作或三步以上双手编排。`
-   ——镜头 ID、角色记录 ID、内部工艺词（“戏剧目的”“表演者”）与 `VID-21` 的禁令原文一次踩齐。
-   它读起来“很规范”，但整段没有一个可以画出来的名词：谁、在哪、什么光、手里有什么，一个都没有。
-   判据只有一句：**把这段文本交给一个没读过规格的人，他能不能画出一张确定的画**。
-
-这些内容留在 Markdown 卡片、规格字段和审查记录里；交付文本只承接它们的**结果**：否定
-意图改写成正向状态，参考图约束改写成可见事实，重投经验改写成本次要保持的状态，而不是
-失败史。
+5. 与本镜无关或重复的否定罗列。必要的排除条件可以保留，文字限制须服从本镜的文字政策。
+6. 把规则说明原样抄入正文，却没有描述主体、环境和具体动作。
+
+将参考范围与修订要求落实为本镜需要的状态和动作；失败记录、规则 ID 和维护说明留在正文外。
 
 ### 合成反例与改写
 

package/lib/drama/skills/short-drama-video-prompts/references/seedance-2.0.md

@@ -19,7 +19,10 @@
 
 - 用中文写“主体 + 动作细节 + 场景 + 光色 + 运镜 + 视觉形态 + 约束”。具体可见事实优先，质量词只保留必要项。
 - 单镜直接按动作先后写。一次生成含多个镜头时才用 `镜头1：`、`镜头2：`；每个内部镜头都写
-  “谁、在哪、做什么、镜头怎么动”，不强塞逐秒时间码。
+  “谁、在哪、做什么、镜头怎么动”。官方说明 2.0 响应镜头序号、不响应时间戳；秒数可作为内部预算，
+  正文用动作顺序与相对停顿表达，不把逐秒时间码当作执行保证。
+  三次小样本的切点没有按两镜均分。需要精确成员边界时，评估独立生成再剪或其他方言，
+  并核对实际输出；容器时长算术正确不代表切点准确。
 - 每个可辨对白事件都必须写成 `{角色用中文说：“逐字台词”}`，不能只留下普通引号或把说话要求散落
   在括号外；对白全文只用一种口语语言，专名除外，不在台词前增加外语暖场。
 - 每个音效事件写 `<声音>`，音乐写 `（音乐）`。字幕只有创作者明确开启时才用 `【字幕】`；默认禁字幕时正文
@@ -34,8 +37,14 @@
 
 ## 时长与边界
 
-Seedance 2.0 原生整数时长是 4–15 秒。镜头进入本阶段前就应落在区间内。短于 4 秒的叙事动作放进
+Seedance 2.0 手动指定的整数时长是 4–15 秒。镜头进入本阶段前就应落在区间内。短于 4 秒的叙事动作放进
 至少 4 秒的镜头，并让终点成为可见 hold；长于 15 秒的动作在分镜阶段按状态闭合点拆开，不能在这里
 截断或跨镜省略交接。
 
-依据：Seedance 2.0 官方提示词指南与火山引擎视频生成 API。
+对白、VO、OS 都按 [performance-action-timing.md](performance-action-timing.md) 的发声窗口复核；
+同轨音画生成不代表正常语速必然容得下原文。API 另支持 `duration: -1`，由模型在 4–15 秒内自动选择。
+固定镜长交付仍传已接受的正整数；采用自动时长时说明它是自适应生成，返回后按实际视频重新核对剪辑时长、
+逐字完整性和语速。自动选择不会突破 15 秒上限，也不能替代超长对白的拆镜。
+
+依据（2026-09-07 核对）：[视频生成 API](https://docs.volcengine.com/docs/82379/1520757)、
+[Seedance 2.5 指南中的 2.0/2.5 时间控制差异](https://docs.volcengine.com/docs/82379/2607689)。

package/lib/drama/skills/short-drama-video-prompts/references/seedance-2.5.md

@@ -14,15 +14,45 @@
 ```
 
 2.5 沿用中文自然指令和 `@图片N`、`@视频N`、`@音频N` 绑定，但不能直接套 2.0：它支持 30 秒长叙事、
-基于时间戳的精确控制，以及明确的参考、编辑、延长三类全模态任务。
+整数秒时间戳控制，以及明确的参考、编辑、延长三类全模态任务。
 
 ## 生成与参考
 
 - 短单镜按“主体 + 动作 + 场景 + 光色 + 运镜 + 风格 + 约束”写。
-- 多镜或长叙事按 `镜头 1 [0:00–0:03]：` 顺序写；每段时间不重叠、不留无意空档，最后一个终点
-  等于总时长。时间戳服务于 2.5 的长叙事控制，不能反过来改写上游镜头状态链。
+- 单镜内部的动作时机先写清先后与触发；散文秒数不保证精确落点。
+- 多镜或长叙事按 `镜头 1 [0:00–0:03]：` 写时间段，不重叠、不留无意空档，最后终点等于总时长。
+  时间戳仍有生成偏差，不能作为音节同步或精确剪辑点的保证。
+
 - 每次使用素材时重复绑定 `人物 @图片1`、`@视频1 的表演节奏` 等具体职责。普通参考任务说明保留和
   借用什么，不让一个素材顺手控制身份、动作、构图等所有维度。
+- 多镜容器使用一份参考清单，各镜的 `@图片N` 重新映射到这份清单，不能照抄独立生成时的编号。
+- 多镜容器不自动保证跨镜一致性。一组对照没有改善，但容器的起始帧锚点也更少，不能归因于
+  一次生成本身。按当前参考输入检查结果，不把该次观察变成禁用规则。
+- 多镜容器包含切口；一镜到底是连续画面。按叙事目的选择，并保留生成后剪辑的余地。
+
+### 两端都锚：`用途：起始帧` 与 `用途：结束帧`
+
+接口提供 `first_frame` 与 `last_frame` 两个位置，各自只收一张。
+终点状态重要时可增加尾帧约束，仍需检查生成后的中间动作与节奏。
+
+按分镜已接受的终点制作尾帧并绑定 `用途：结束帧`；套件内生产入口见
+`$short-drama-storyboard` 的「首尾成对」。未提供尾帧时，在正文中说明终点。
+
+两个帧位仍然各占一个图片序号，所以 `@图片N` 的编号按素材出现顺序连续往下数，不跳过它们。
+
+首尾帧与其他参考能否混用，按目标接口核对并验证。H3 的互斥规则不能直接套到 2.5，
+2.5 的素材角色共用一个 `content` 数组也不能证明任意组合都被接受。
+
+### 音色参考
+
+目标接口支持 `reference_audio` 时，可用已接受的角色参考音频辅助约束声音。
+参考可以来自预置音色合成或已授权录音，选型由视觉设定记录，生成后回听确认。
+
+当前 creator-first 的 `输入参考图` 只接受图片，封闭用途表也没有「音色」。
+不要在该字段塞入音频或写 `用途：音色`；这会被校验器拒绝。
+内置 adapter 可处理音频 role，但从五文档准备带音频的 job 尚无完整绑定路径。
+需要该能力时使用已支持音频绑定的外部执行流程，并记录角色、音频来源和实际 role；
+不能仅凭正文提到音频就声称已经绑定。
 
 ## 编辑与延长不是普通参考
 
@@ -37,6 +67,19 @@
 若提示词写的是编辑而 job 标成参考，或反过来，2.5 仍会根据语义复判并报任务类型不匹配；因此任务
 类型是创作选择，不由 adapter 从若干关键词猜。
 
+**它写在哪里**：creator-first 的 `MOTION-...` 条目里加一行 `- 任务类型：reference | edit | extend`，
+写在 `生成方式` 之后。这两个字段回答的不是同一个问题，谁也不能代替谁：
+
+| 字段 | 回答什么 | 取值 | 谁决定 |
+|---|---|---|---|
+| `生成方式` | 这一镜送不送图 | `文生视频` / `图生视频` | 由「输入参考图」是否为空机械推出，`creator_markdown_check.py` 会核对 |
+| `任务类型` | 这一次是参考、编辑还是延长 | `reference` / `edit` / `extend` | 创作决定，本套件不推断 |
+
+`edit` 与 `extend` 使用视频素材，不一定有图片；不能把“送素材”一律写成“图生视频”。
+现有五文档的图片字段不足以表达纯视频输入，准备 job 时需核对实际绑定。`edit` 与 `extend`
+在 API 上还各自要求 `ratio: adaptive`（`edit` 另要求 `duration: -1`），送错会被 2.5 判为任务
+类型不匹配。目标模型不是 2.5 时不写这一行——其余方言没有这个概念。
+
 ## 对白、声音与文字
 
 - 每个可辨对白事件都必须整体写进 `{角色用中文说：“逐字台词”}`，不能只用普通引号；同一句带花括号
@@ -60,7 +103,20 @@
 
 ## 时长
 
-Seedance 2.5 原生整数时长是 4–30 秒。项目采用一镜一生成时每镜均落在此区间；采用 30 秒多镜容器时，
+Seedance 2.5 手动指定的整数时长是 4–30 秒。项目采用一镜一生成时每镜均落在此区间；采用 30 秒多镜容器时，
 先按交付形态确认容器，不把若干独立镜头擅自合并。短动作到达终点后 hold，超长动作按状态闭合点拆分。
 
-依据：火山引擎《Doubao Seedance 2.5 教程》《Doubao Seedance 2.5 提示词指南》和视频生成 API。
+对白、VO、OS 同样按 [performance-action-timing.md](performance-action-timing.md) 先预算再排时。
+30 秒扩大了可用容量，不代表固定短镜中的长对白会自动恢复自然语速。
+
+- 普通生成/参考任务支持 `duration: -1`，由模型在 4–30 秒内选择，2.5 默认也采用该值。固定时长交付
+  仍显式传已接受的正整数；采用自动时长时，不把规划镜长写成已经保证的输出长度。
+- `edit` 的 `duration: -1` 表示基本保持待编辑视频的时长。换成更长对白时仍须检查原片发声窗口，
+  不能靠 `-1` 自动延长；放不下就回上游调整任务或台词，不静默切换为延长。
+- `extend` 的时长针对新增片段，预算其中新增对白与过渡，不把原片长度当成新增发声容量。
+
+实际回测需听台词完整性、语速、尾音，并测量媒体真实时长。API 返回的 `duration` 是按帧数折算后向下
+取整的近似秒数；编辑结果也可能与源片略有时长差异，不能只看响应整数就判定逐秒满足要求。
+
+依据（2026-09-07 核对）：[视频生成 API](https://docs.volcengine.com/docs/82379/1520757)、
+[Seedance 2.5 提示词指南](https://docs.volcengine.com/docs/82379/2607689)。

package/lib/drama/skills/short-drama-video-prompts/references/stage-contract.md

@@ -17,7 +17,7 @@
 
 | ID | Class | Knowledge |
 |---|---|---|
-| VID-01 | structural_invariant | Motion reads but cannot rewrite shot start/end/duration/dialogue and next-shot state. |
+| VID-01 | structural_invariant | Motion reads but cannot rewrite shot start/end/duration/dialogue and next-shot state. The duration a MOTION declares is compared against its SHOT: they must be the same number, because 时长 is what reaches the execution end and what VID-04/VID-13 arithmetic is built on. A downstream copy left behind by an upstream revision is a defect even though every string still parses. |
 | VID-02 | craft_default | Write start anchor, ordered subject motion, camera behavior, timing, and end report; add performance change and environment/audio only when this shot actually carries them. |
 | VID-03 | structural_invariant | Choose image-to-video only when the matching storyboard's reference set is complete, declares readable REF inputs, and is copied unchanged. No REF is not by itself consent to text-to-video: first discover and bind matching real project images; preserve any verified partial bindings, but if required images remain missing, report them and stop before the final motion document. Choose text-to-video only after the creator explicitly selects it, and carry a non-empty static visual anchor in the copyable text. Only image-to-video may omit appearance/composition already carried by its real reference frame. |
 | VID-04 | structural_invariant | Explicit segment timing sums exactly to its shot's accepted duration—neither exceeding it nor leaving an unallocated remainder. |
@@ -38,8 +38,8 @@
 | VID-19 | reviewed_invariant | When the creator profile declares required literal tokens for a delivery route, that route's delivery text preserves them byte-for-byte and outside the verbatim-dialogue fence. Paraphrase, translation, reordering, or omission is treated as a defect because a literal-matching surface has no reason to reject the rewritten text—the failure is silent rather than reported. The suite asserts no specific surface's behaviour, and whether a given result took the route is returned adherence, provable only by a bound production observation. Tokens declare a route and never substitute for the start state, action, or endpoint. Absent a declared token list the suite invents none; until the profile exposes a machine-readable list at a pinned field path, the reviewer cites the profile against the delivery text rather than claiming mechanical enforcement. |
 | VID-20 | reviewed_invariant | Packing routes change delivery granularity only, leaving shot boundaries, shot purpose, and per-shot reviewability intact. A single long-form generation carrying several accepted shots *is* a multi-shot container and is billed under VID-13 and VID-15; it introduces no separate accounting and no exemption from the contiguity, binding-chain, and scene-boundary constraints. A continuation route instead starts from a previously generated result, which is observation evidence and not an accepted artifact: the accepted shot start boundary stays the sole authority, and any claim about the observed state binds a production observation record or remains `unverified`. |
 | VID-21 | craft_default | When the project's accepted production profile has generated imagery carry the frame, actions are written as high-frequency, whole-body or single-limb movements common in everyday footage; precise interception, invisible internal states, negative actions, and three-or-more-step two-handed choreography are rewritten into equivalent common-action combinations, with the dramatic information carried by combination and timing. The rule is inactive for live action or an undeclared profile, and a rewrite may never change accepted shot boundaries, terminal states, or screenplay fact. |
-| VID-22 | reviewed_invariant | Copyable text carries only what will be filmed. IDs, workflow status, hashes, file paths and craft notes stay outside the prompt; negative action intent is rewritten as a visible positive state. Unless explicitly authored, the copyable prompt directly prohibits non-diegetic subtitles, captions and dialogue-text overlays at every moment rather than naming an abstract empty layer; this never erases an exact-readable in-scene text obligation, which stays a closed allow-list of exact glyph, language, carrier and placement. A prompt that only recites constraints renders as nothing. |
-| VID-23 | reviewed_invariant | When the target model is declared to generate audio in the same pass, the copyable body treats all allowed dialogue, VO, OS, non-verbal vocalization, SFX, ambience and silence as a closed event set. Each spoken event keeps its source, speaker, spoken language and verbatim text boundary; gaps return to declared ambience or silence instead of leaving an undefined vocal channel for the execution end to fill. |
+| VID-22 | reviewed_invariant | Copyable text describes the intended image and action. IDs, workflow status, hashes and file paths stay outside it. Prefer observable states where they clarify execution; necessary negative constraints are allowed. Unless explicitly authored, prohibit non-diegetic subtitles, captions and dialogue overlays while preserving approved in-scene text and its exact content, carrier and placement. |
+| VID-23 | reviewed_invariant | For models generating audio with video, specify the intended dialogue, VO, OS, vocalizations, effects, ambience and silence. Keep source, speaker, language and verbatim dialogue boundaries. Summaries must match the actual sound layers; follow model-specific music syntax without assuming missing layers will always be generated. |
 | VID-24 | structural_invariant | An image-to-video shot carries the storyboard's `REF-...` and `PLAN-...` slots unchanged, each with its 用途, so the motion document itself answers which start frame and which identity, geography, and prop pictures this shot sends — and, for `PLAN-...`, in which order the creator attaches them. The reference mode — first frame, first and last frame, or multi-slot reference — is read from that 用途 combination and translated by the matched model dialect; where a model makes frame and reference conditioning mutually exclusive, the start frame joins the reference group rather than splitting the request. |
 | VID-25 | structural_invariant | Quoted Chinese in a copyable body is delivered, not authored. Every run of four or more Han characters inside a `<d>` tag or quotation marks resolves, ignoring punctuation and spacing, to text that already exists in `剧本.md`, `视觉设定.md` or `分镜.md`. A line the shot wishes the character had said belongs upstream in the screenplay, not in the prompt. Runs of three characters or fewer are in-frame labels and interjections far more often than lines, so they stay with review rather than the mechanical check. |
 

package/lib/drama/skills/short-drama-write/SKILL.md

@@ -67,8 +67,10 @@ license: MIT
 
 用户问时长时才把索引写入系统临时目录。先用 Python 查询跨平台临时目录，把第一条命令打印的完整
 路径原样替换进后两条命令的引号内。以下每条都是一行完整命令，不依赖 shell 变量或续行符；Windows
-没有 `python3` 命令时使用 `py -3`。`--speaker` 的示例值必须替换为本集实际说话者；只有存在项目
-配置时才添加 `--project short-drama.json`：
+没有 `python3` 命令时使用 `py -3`。`--speaker` 的示例值必须替换为本集实际说话者。
+`--project short-drama.json` **只加在第三条命令上**（`duration_estimate.py` 才接受它，
+`screenplay_index.py` 没有这个参数，加上去会直接报 `unrecognized arguments`），且只在项目
+配置确实存在时加：
 
 ```text
 python3 -c "from pathlib import Path; import tempfile, uuid; print(Path(tempfile.gettempdir()) / ('short-drama-' + uuid.uuid4().hex + '.jsonl'))"
@@ -76,6 +78,13 @@ python3 "{技能目录}/scripts/screenplay_index.py" "剧集/EP001/剧本.md" --
 python3 "{技能目录}/scripts/duration_estimate.py" "剧集/EP001/剧本.md" --index "粘贴第一条命令输出的完整路径"
 ```
 
+**改稿后重跑**：第二条命令写过一次的输出路径不能直接再写一次，会以 `already holds an index` 失败。
+要保留原有块 ID 就加 `--previous-index <同一路径>`，要从头重编号就加 `--no-previous`；
+或者干脆回到第一条命令另取一个临时路径。
+
+估时前区分计数口径：`dialogue_characters` 包含标点，视频提示词中的参考语速按可发声字数计算。
+按语速换算时排除标点，并按实际读法处理数字和缩写；不把两个计数混用。
+
 估算是参考，不是门禁；没有语速或动作段速率时只报告可数事实，不猜秒数。但任务已给目标时长时，
 写作者仍须用真实朗读和动作通读判断能否容纳，并直接压缩重复节拍；“不能精确估秒”不是忽略目标的理由。
 

package/lib/drama/skills/short-drama-write/references/screenplay-format.md

@@ -74,6 +74,12 @@
 - **`craft_default`**：使用现在时与可执行动词；焦点行动、信息或空间关系变化时另起段落。
 - **`reviewed_invariant · SCR-03`**：关键心理/认知变化要有行为、证据、空间后果或有意声音作为载体。
 - **`taste_option`**：完整动作链、氛围或推理可以保留较长段落，不按统一长度切分。
+- **`craft_default · SCR-18`**：动作段落**不要以「短语＋全角冒号」开头**。
+  `第二格：一只手把杯子推过去。` 与 `屏幕上正在放的东西：一段没有声音的录像。` 这样的写法
+  和 3.2 的对白语法（`角色名：台词`）在字面上完全一样，索引器只能报
+  `ambiguous_dialogue_or_action` 交回本阶段判断，而它每次都要人来读一遍才能消掉。
+  改法是把冒号换成破折号、逗号或一个动词：`第二格换成一只手把杯子推过去。`
+  `屏幕上正在放的是一段没有声音的录像。` 句中的冒号不受影响，只有**行首**这一处会撞。
 
 不要在动作段落里写镜号、景别、镜头运动、焦段、生成参数或素材位。
 

package/lib/drama/skills/short-drama-write/references/stage-contract.md

@@ -29,6 +29,7 @@
 | SCR-15 | craft_default | A local payoff leaves a legible result or aftereffect without replacing the episode's meaning with a slogan. A cost framed as central pressure has a material exit-state effect rather than automatically resetting once the action succeeds. The result may be plot change, relationship response, irony, stillness, tonal afterimage, or an intentionally open state; a new external event is not mandatory. |
 | SCR-16 | reviewed_invariant | When a literal precise deadline is foregrounded and audience-auditable, its action chain fits the stated time and established resources, or the screenplay makes compression, failure, or a changed objective legible. Qualitative urgency is not upgraded into invented minutes, timestamps, notifications, or records. Montage, ellipsis, subjective time, and declared stylization follow their own established convention rather than an automatic real-time test. |
 | SCR-17 | reviewed_invariant | When the brief defines a limited number of attempts, turns, breaths, beats, or other units, each unit is counted by its visible end-state. A label, count, request, authorization, preparation step, or cleanup after the boundary does not substitute for the required completion; intentional partial completion or failure remains valid when it is the legible result of that unit. |
+| SCR-18 | craft_default | An action paragraph does not open with a noun phrase followed by a full-width colon. `第二格：一只手把杯子推过去。` is byte-for-byte the dialogue form `角色名：台词`, so the indexer can only return `ambiguous_dialogue_or_action` and hand it back for a human read; every such line costs one round trip for nothing. A dash, a comma, or a verb removes the collision. Colons inside a sentence are unaffected — only the start of the line collides. |
 
 规则分级由高到低：`structural_invariant`（结构缺陷，阻断）、
 `reviewed_invariant`（需证据判断）、`craft_default`（常用做法，可覆盖）、