@oh-story/dsh 0.1.7 → 0.1.9

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

@@ -29,10 +29,47 @@ 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, ...`，时间递增且落在本次生成时长内。
+  实测这个时间戳很准：要求第 4.0 秒切，三次实际落在 3.96/4.04/4.12 秒。需要成员边界与已接受时长
+  对得上的多镜容器，用这种写法。
+- `overall_soundscape` 汇总环境声、物理音效和非语言人声，不重复对白；对白事件留在上面的主时间线。
+  无非画内配乐时写 `non_diegetic_music: N/A`，不要留空让模型补乐——这一条有实测支撑，见
+  [无对白镜](#无对白镜)。
 - 首帧模式从输入帧的可见姿态开始；首尾帧模式只能到达上游已接受终点，不发明过渡后的新状态。
 
+## 无对白镜
+
+H3 画音同轨。实测下来两个通道的表现并不一样：**配乐通道不写就会被模型填上**，语音通道在本套件
+的样本里没有出现过这种情况。下面两节按这个差别分开写，别把配乐那条的力度套到语音上。
+三段结构和六段结构同此处理。
+
+**`craft_default`**：无对白镜的声音段正面写，不用 `no dialogue`、`无对白`、`不说话` 这类排除句
+关闭语音通道。这条是写法约定，不是已验证的因果：本套件用 H3 实测过含 `No dialogue` 排除句的正文
+（文生 5 次、多槽参考 3 次，共 8 次），没有一次生成出台词，所以**不能说**排除句会招来对白。
+选正面写法的理由是它同时交代了这一镜该有什么声音，排除句只说了不要什么。
+
+正面写法有两处，缺一处都不算写满：
+
+- `overall_soundscape` 写这条声轨**由什么组成、覆盖多长**，只列已声明的 ambience 与音效。例如
+  `overall_soundscape: A faint wind outside the window is the only sound present, continuous from the first frame to the last.`
+- 主时间线（`integrated_multimodal_description` 或 `detailed_description`）把「不说话」写成**可见状态**，
+  绑到本镜真正在场的人身上。它是表演描述，说的是画面里看得见的事。例如
+  `Both keep their lips closed and their mouths still for the full shot.`
+
+### 配乐通道必须显式关掉
+
+这一条有实测支撑，且比上面一条重要得多：正文写了 `non_diegetic_music: N/A` 的 14 次生成没有一次
+自带配乐；完全不提配乐的 3 次里有 2 次返回了自造的背景音乐（持续谐波音床，随镜头变化换和弦）。
+**所以 `non_diegetic_music` 这一行不能省。** 语音通道目前没有观察到同样的现象，配乐通道有。
+
+### 时间线完整声明
+
+主时间线闭合时只声明**本镜实际有的**声音层：无对白镜写
+`The audio timeline is complete after the listed ambience and effects.`，
+把 `timed dialogue` 加进这句是有对白时才成立的写法。无对白镜枚举 `timed dialogue` 是一句与本镜事实
+不符的话；实测未观察到它单独导致生成台词，但正文不该写与本镜不符的内容。
+
 ## 选哪一种模式
 
 模式由本镜「输入参考图」里各槽位的 `用途` 决定，不由“想不想用多模态”决定：
@@ -105,7 +142,14 @@ REF-STUDY-PLATE（顺序：3；用途：地理）    -> <Picture 3>
 
 ### 每张图带什么、不带什么
 
-`用途` 决定这一张在正文里被要求保留什么，具体到哪几项由该槽位自己写下的 `控制` 范围决定：
+`用途` 决定这一张在正文里被要求保留什么，具体到哪几项由该槽位自己写下的 `控制` 范围决定。
+
+**实测口径**：模型响应的是 `控制` 这半句的肯定表述——正文明确写「保留起始构图、站位、机位高度」时，
+构图会被准确带过来；只写 `fully_preserved` 或只写「不得控制构图」时，构图都不会被带过来。
+所以**需要保住构图的槽位（典型是 `用途：起始帧`）必须在 `控制` 里点名构图**，漏写就拿不到这个锚点，
+在别处补多少 `不得控制` 都无效。`不得控制` 照常写，但它是给 owner 与 reviewer 看的责任边界，
+不是对模型的开关。
+
 `起始帧` 只锚定开场构图与姿态，`身份` 锚定这个人跨镜不变的长相与体态（角色板同时固定本集造型时，
 `控制` 里会写明），
 `地理` 只锚定空间关系，`造型状态` 只锚定服装与损污。把这条差异写进 `retention_analysis`，
@@ -113,6 +157,7 @@ REF-STUDY-PLATE（顺序：3；用途：地理）    -> <Picture 3>
 
 角色始终使用同一个说话人 ID；中文对白只出现在 `<d>[Chinese] ...</d>` 内。禁字幕写进可见文字约束，
 与获准的画内文字分开。
+Full-reference 的逐字对白与同步声音放在 `detailed_description` 的对应事件里，`overall_soundscape` 仍只汇总底声与音效。
 不要为了“多模态”把所有资产图都带上；每镜只绑定它真正可见且需要保持的起始帧、人物、地点或关键道具图。
 
 ### 一个完整例子
@@ -164,7 +209,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 字/秒**，容量约 `4.1 × 镜长`；超出后先赶语速（最快约 2.5 倍），
+再超过约 9 字/秒就**静默截断**，接口不报错。别把"没报错"当成台词说完了。
+口语语言、声线与语速描述放在 `<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

@@ -172,7 +172,13 @@ reviewer 结合完整故事义务决定，不能让未承担内容随更短提
 1. 按发生顺序列出本镜全部对白、VO、OS、必要非语言发声和 SFX；
 2. 每条台词同时标说话人、声源性质、口语语言和逐字文本，发声从原文首字开始、到末字结束；
 3. 所列事件之外只保留已声明的 ambience 或静默；相邻两句之间若有停顿，也明确回到这一底声；
-4. 声明时间线完整并结束声音段落，不再列出或否定集合外的语言、语气或声源。
+4. 声明时间线完整并结束声音段落，不再列出或否定集合外的语言、语气或声源；这条声明只列本镜
+   实际有的层，不枚举本镜没有的层。
+
+本镜一句发声都没有时，第 1、2 步的列表为空，第 3、4 步照做，而且是这一镜声音写法的全部：正面写出
+底声或静默的构成与覆盖区间，把「不说话」写成在场人物的可见状态（嘴唇闭合），完整性声明里不出现
+dialogue。不用 `no dialogue`、`无对白` 关闭语音通道：正面句同时说清了这一镜该有什么声音，排除句
+只说了不要什么。非画内配乐层另外显式写空——这一层不写，实测会被模型补上一段自造配乐。
 
 确有叹气、吸气、笑声或重叠说话时，把它作为有来源的事件列入。声音不同轨时仍只写后期职责。
 

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

@@ -148,6 +148,41 @@
 
 评估：句长与语言、人物语速、情绪造成的停顿/吞吐、是否需要听见对方/环境 cue、口型要求、动作是否能与说话叠加、结尾是否有 reaction landing。固定每秒字数只能作为 production profile 的可覆盖估算，不能成为通用规则。
 
+**`craft_default`**：先读取分镜「声音」的预算依据。有同句同表演录音时用实测发声区间；没有时按完整原文、
+语言和表演方式给出「文本估计」区间，以较慢一端检查容量，不假称朗读或 TTS 实测。对白可用窗口要扣除
+开口前等待、不能同时进行的动作、轮流说话的其他发声与末尾反应；句内停顿已经计入时不再重复扣除。
+并行动作可以共享时间，顺序事件必须累加。把依据简写在当前镜头说明里，不放进可复制正文当成模型指令。
+
+例如 accepted duration 为 7 秒，开场与收尾各占 0.5 秒，实际只剩 6 秒发声；若完整台词估计需要
+8–10 秒（含句内停顿），即使写成「0–7 秒」也不成立。请求分镜按至少 11 秒重新安排，或按语义拆镜，
+待上游修订后同步本镜时长、正文时序和生成设置。不要用更快语速、截断标记或静默删词让算术看起来成立。
+
+### 超出容量时会发生什么（H3 中文实测）
+
+**`craft_default`**：本套件在 MiniMax H3 上测过同一镜从 7 字到 108 字、镜长 5–13 秒的表现，
+分三段，可作为该模型的可覆盖估算（别的模型、别的语言要各自实测）：
+
+| 送入字数 ÷ 镜长 | 表现 |
+|---|---|
+| ≤ 约 4.1 字/秒 | 自然语速，完整 |
+| 约 4.1–9 字/秒 | **完整但明显赶**，最快到自然语速的 2.5 倍 |
+| > 约 9 字/秒 | **静默截断**：超出的部分根本不发声 |
+
+两件事决定了为什么必须先做预算，而不是"生成出来再听"：
+
+- **接口不会报错**。截断时任务照样返回成功、画面正常，只是台词后半段没有了
+  （实测送 78 字只说了 46 字，送 108 字同样只说了 46 字）。文字审查看不出来，
+  秒段加总也仍然"正确"——**算术通过从来不是台词说得完的证据**。
+- **延长镜头确实管用**，这一条也实测过：37 字从 5 秒改到 10 秒，语速由 7.0 回到 4.3 字/秒；
+  50 字从 5 秒改到 13 秒，由 9.6 回到 4.2 字/秒，都恢复自然且完整。所以下面第 3 项不是敷衍的建议。
+
+估算按 **容量 ≈ 4.1 × 镜长（秒）字**：5 秒镜约 20 字，10 秒镜约 40 字。
+样本为同一镜 20 次生成（7/15/20/29/37/50/78/108 字，镜长 5/10/13 秒）。
+
+**这里的「字」是可发声字，不含标点。** 写作阶段 `duration_estimate.py` 报的
+`dialogue_characters` 是另一个口径（标点计入），拿它乘 4.1 会高估约两成；按秒核对容量时
+以可发声字数为准。
+
 对白太长时选项：
 
 1. 简化非必要动作，让对白成为主事件；

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

@@ -246,7 +246,9 @@
 
 执行端把整段交付文本当作**画面描述**读取，它没有办法区分“这句是给人看的工艺备注”和
 “这句是要画的东西”，于是把文件名渲染成画面上的字符、把版本号读成画面里有两个版本的
-同一个人、把否定罗列里的名词当成应当出现的物件。这类缺陷和动作超载不是同一种问题：
+同一个人。「把否定罗列里的名词当成应当出现的物件」这一条常被当作定论，但本套件的定向实测
+没有复现：向 H3 送入含 `There is no red balloon anywhere in the room.` 的正文 3 次，没有一次
+画出气球。下面的禁入清单按“交付文本只含交付内容”成立，不依赖这个未复现的机制。这类缺陷和动作超载不是同一种问题：
 超载只是难以完成，工艺词进入交付文本会直接让画面长出没有人要过的东西，而且是最难在
 文字审查中被发现的一类——它读起来“信息很全”。
 

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

@@ -19,7 +19,11 @@
 
 - 用中文写“主体 + 动作细节 + 场景 + 光色 + 运镜 + 视觉形态 + 约束”。具体可见事实优先，质量词只保留必要项。
 - 单镜直接按动作先后写。一次生成含多个镜头时才用 `镜头1：`、`镜头2：`；每个内部镜头都写
-  “谁、在哪、做什么、镜头怎么动”，不强塞逐秒时间码。
+  “谁、在哪、做什么、镜头怎么动”。官方说明 2.0 响应镜头序号、不响应时间戳；秒数可作为内部预算，
+  正文用动作顺序与相对停顿表达，不把逐秒时间码当作执行保证。
+  **实测后果**：8 秒装两镜、按序号写，三次切点落在 5.21/5.38/5.54 秒，稳定偏后而不是均分。
+  也就是说 2.0 能给你两个镜头，但给不了你切在第几秒。**成员边界必须等于已接受时长时
+  （`VID-13`），不要把容器交给 2.0**——改用会响应时间戳的方言，或一镜一生成。
 - 每个可辨对白事件都必须写成 `{角色用中文说：“逐字台词”}`，不能只留下普通引号或把说话要求散落
   在括号外；对白全文只用一种口语语言，专名除外，不在台词前增加外语暖场。
 - 每个音效事件写 `<声音>`，音乐写 `（音乐）`。字幕只有创作者明确开启时才用 `【字幕】`；默认禁字幕时正文
@@ -34,8 +38,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,13 +14,19 @@
 ```
 
 2.5 沿用中文自然指令和 `@图片N`、`@视频N`、`@音频N` 绑定，但不能直接套 2.0：它支持 30 秒长叙事、
-基于时间戳的精确控制，以及明确的参考、编辑、延长三类全模态任务。
+整数秒时间戳控制，以及明确的参考、编辑、延长三类全模态任务。
 
 ## 生成与参考
 
 - 短单镜按“主体 + 动作 + 场景 + 光色 + 运镜 + 风格 + 约束”写。
+- **单镜正文里用散文写的秒数不构成时间控制。** 「约第一秒八把眼镜戴回、约第三秒半开口」
+  这样的写法只对人有效：实测一条 9 秒单镜，动作顺序与终点都照做了，中途那个动作却被推到接近结尾，
+  说话时它还没发生。需要模型按秒排布时用下面的时间戳语法；散文秒数留给分镜与剪辑读，
+  它记录的是意图，不是给模型的指令。
 - 多镜或长叙事按 `镜头 1 [0:00–0:03]：` 顺序写；每段时间不重叠、不留无意空档，最后一个终点
-  等于总时长。时间戳服务于 2.5 的长叙事控制，不能反过来改写上游镜头状态链。
+  等于总时长。官方时间戳以整数秒为单位；时间段塞入过多内容仍可能造成过度剪切或剧情遗漏。
+  实测切点精度约 ±0.4 秒（要求第 4 秒切，三次落在 3.71/4.29/4.46 秒），比 H3 松、比 2.0 可控。
+  时间戳服务于 2.5 的长叙事控制，不能反过来改写上游镜头状态链，也不是音节级同步保证。
 - 每次使用素材时重复绑定 `人物 @图片1`、`@视频1 的表演节奏` 等具体职责。普通参考任务说明保留和
   借用什么，不让一个素材顺手控制身份、动作、构图等所有维度。
 
@@ -37,6 +43,18 @@
 若提示词写的是编辑而 job 标成参考，或反过来，2.5 仍会根据语义复判并报任务类型不匹配；因此任务
 类型是创作选择，不由 adapter 从若干关键词猜。
 
+**它写在哪里**：creator-first 的 `MOTION-...` 条目里加一行 `- 任务类型：reference | edit | extend`，
+写在 `生成方式` 之后。这两个字段回答的不是同一个问题，谁也不能代替谁：
+
+| 字段 | 回答什么 | 取值 | 谁决定 |
+|---|---|---|---|
+| `生成方式` | 这一镜送不送图 | `文生视频` / `图生视频` | 由「输入参考图」是否为空机械推出，`creator_markdown_check.py` 会核对 |
+| `任务类型` | 这一次是参考、编辑还是延长 | `reference` / `edit` / `extend` | 创作决定，本套件不推断 |
+
+三种任务类型都是图生视频（都送素材），所以只看 `生成方式` 分不出它们；而 `edit` 与 `extend`
+在 API 上还各自要求 `ratio: adaptive`（`edit` 另要求 `duration: -1`），送错会被 2.5 判为任务
+类型不匹配。目标模型不是 2.5 时不写这一行——其余方言没有这个概念。
+
 ## 对白、声音与文字
 
 - 每个可辨对白事件都必须整体写进 `{角色用中文说：“逐字台词”}`，不能只用普通引号；同一句带花括号
@@ -60,7 +78,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. |

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,15 @@ python3 "{技能目录}/scripts/screenplay_index.py" "剧集/EP001/剧本.md" --
 python3 "{技能目录}/scripts/duration_estimate.py" "剧集/EP001/剧本.md" --index "粘贴第一条命令输出的完整路径"
 ```
 
+**改稿后重跑**：第二条命令写过一次的输出路径不能直接再写一次，会以 `already holds an index` 失败。
+要保留原有块 ID 就加 `--previous-index <同一路径>`，要从头重编号就加 `--no-previous`；
+或者干脆回到第一条命令另取一个临时路径。
+
+**字数单位不要混用**：`duration_estimate.py` 报的 `dialogue_characters` **把标点计入**
+（`关窗，水进来了！` 记 8 而不是 6，这是它的既定口径，有测试固定）。而视频提示词阶段
+「对白预算」给出的那个「约 4.1 字/秒」是按**可发声字**（不含标点）实测的。两个数直接相乘
+会高估两成左右——要按秒核对容量时，用可发声字数自己数一遍，别拿 `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`（常用做法，可覆盖）、

package/lib/index.js

@@ -140,7 +140,8 @@ var DSH_DRAMA_BRIDGE = [
   "This Skill is a native contribution to the current DeepSeek Harness session.",
   "DSH owns the workspace, model, preset, permissions, Session Log, tools, approvals, cancellation, resume, and Agent UI.",
   "The \u77ED\u5267 tab is the creator workspace. Never start dashboard_server.py, another web server, Dashboard, Agent runtime, session transport, or model configuration.",
-  "Drama Skills v0.6 uses a creator-first contract: each episode keeps only the requested documents, up to five creator-facing sources at \u5267\u96C6/<EP>/\u5267\u672C.md, \u89C6\u89C9\u8BBE\u5B9A.md, \u5206\u955C.md, \u56FE\u7247\u63D0\u793A\u8BCD.md, and \u89C6\u9891\u63D0\u793A\u8BCD.md. Never precreate empty documents, backfill nominal stages, or start work the creator did not request. Persisted reviews use creator-readable Markdown under \u5BA1\u67E5/; an oral review writes nothing.",
+  "Drama Skills uses a creator-first contract: each episode keeps only the requested documents, up to five creator-facing sources at \u5267\u96C6/<EP>/\u5267\u672C.md, \u89C6\u89C9\u8BBE\u5B9A.md, \u5206\u955C.md, \u56FE\u7247\u63D0\u793A\u8BCD.md, and \u89C6\u9891\u63D0\u793A\u8BCD.md. Never precreate empty documents, backfill nominal stages, or start work the creator did not request. Persisted reviews use creator-readable Markdown under \u5BA1\u67E5/; an oral review writes nothing.",
+  "\u5267\u96C6/<EP>/\u526A\u8F91\u5355.md is the v0.7 assembly record, not a sixth creative truth. It is written after footage exists and records only which frames of that footage reach the cut; changing a line, a shot's job, or a declared duration means returning to the document that owns it.",
   "For a v0.6 project, never create a parallel JSON/JSONL lifecycle truth, indexes, fingerprints, coverage tables, or QA records merely because legacy maintenance scripts and templates remain bundled.",
   "Never upgrade a v0.5 structured project in place or mix both contracts in one project root. Keep legacy production/audit artifacts read-only and pinned to v0.5; migrate only into a new creator-first root with manual per-episode creator confirmation.",
   "Use only tools visible in the current DSH preset and preserve the upstream project ownership, freshness, review, and explicit production-confirmation contracts.",
@@ -150,7 +151,8 @@ var DSH_DRAMA_BRIDGE = [
 ].join("\n");
 var DSH_DRAMA_OVERRIDES = {
   "short-drama": "A dashboard request means focus or use the native \u77ED\u5267 tab in this DSH Session. Do not run the bundled standalone Dashboard script. New projects follow only the v0.6 creator-first contract and create only documents required by the current request.",
-  "short-drama-produce": (skillRoot) => `Use an upstream adapter only after the creator explicitly confirms the exact current job. Its source must be the current creator-first Markdown and its output belongs under \u5267\u96C6/<EP>/\u5236\u4F5C\u6210\u679C/. DSH permissions and approval UI remain authoritative. When oh_story_production is visible, register the previewed job with track_job after the confirmation is valid and before run \u2014 never at prepare time \u2014 passing the same job ID, target, modality and count the creator just approved. DeepSeek generates no media: every image, video, or music result comes from a provider adapter. The bundled adapters are ${dramaAdapterSummary()}; they are registered for this DSH host in ${dramaAdapterConfigPath(skillRoot).path} \u2014 pass that file as --adapter-config unless the creator names another config (${DRAMA_ADAPTER_CONFIG_ENV}). Credentials are read only from the DSH host process environment. Before preparing a paid job, name the adapter that will run it; if its variables are missing, tell the creator exactly which ones to export before starting DSH instead of failing inside run. Never read, print, or write credential values.`,
+  "short-drama-produce": (skillRoot) => `Use an upstream adapter only after the creator explicitly confirms the exact current job. Its source must be the current creator-first Markdown and its output belongs under \u5267\u96C6/<EP>/\u5236\u4F5C\u6210\u679C/. DSH permissions and approval UI remain authoritative. When oh_story_production is visible, register the previewed job with track_job after the confirmation is valid and before run \u2014 never at prepare time \u2014 passing the same job ID, target, modality and count the creator just approved. DeepSeek generates no media: every image, video, or music result comes from a provider adapter. The bundled adapters are ${dramaAdapterSummary()}; they are registered for this DSH host in ${dramaAdapterConfigPath(skillRoot).path} \u2014 pass that file as --adapter-config unless the creator names another config (${DRAMA_ADAPTER_CONFIG_ENV}). Credentials are read only from the DSH host process environment. Before preparing a paid job, name the adapter that will run it; if its variables are missing, tell the creator exactly which ones to export before starting DSH instead of failing inside run. Never read, print, or write credential values. A submitted video job is already billed, so an interrupted run is recovered, not resubmitted: when audit reports orphaned_provider_job, recover it with collect, passing --job-id \u2014 the drama job the finding names, not its provider_job_id, which collect reads from the run handle itself. collect spends nothing and does not need the confirmation gate \u2014 the gate exists to stop unintended spending \u2014 but re-running the same job does, and would charge the creator twice.`,
+  "short-drama-edit": "Assembly runs inside this DSH Session. Write \u5267\u96C6/<EP>/\u526A\u8F91\u5355.md first, then run edit_tool.py check and render through the current DSH execution world; the rendered cut belongs under \u5267\u96C6/<EP>/\u5236\u4F5C\u6210\u679C/\u6210\u7247/ and the \u77ED\u5267 tab shows it there. ffmpeg and ffprobe come from the DSH host \u2014 when one is missing, say so instead of approximating or reporting an untested measurement as a pass. Keep the zero-dependency ffmpeg subtitle route by default; the Remotion route installs Node dependencies and renders every frame through a headless browser, so take it only after the creator approves that install, and never treat it as a second Agent runtime, dashboard, or session transport. This stage never generates footage and never edits \u5267\u672C.md, \u5206\u955C.md, or \u89C6\u9891\u63D0\u793A\u8BCD.md \u2014 route those back to their owning Skill.",
   "short-drama-assets": "Keep one stable `- ID\uFF1AVISUAL-*` line on every \u4EBA\u7269/\u9020\u578B/\u5730\u70B9/\u9053\u5177/\u72B6\u6001 entry in \u89C6\u89C9\u8BBE\u5B9A.md, and never change an existing ID when editing its heading or text. The \u751F\u4EA7 view identifies canvas nodes by that ID; entries without one still render, but the workbench reports their node identity as unstable."
 };
 var DSH_GAME_BRIDGE = [