@oh-story/dsh 0.1.9 → 0.1.11

package/lib/drama/skills/short-drama-edit/scripts/selftest.py

@@ -15,7 +15,9 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 from edit_tool import (  # noqa: E402
+    _unaccounted_shots,
     DEFAULT_REMOTION_CONCURRENCY,
+    DisplayCue,
     REMOTION_SOURCE,
     REMOTION_SOURCE_FILES,
     EditError,
@@ -101,7 +103,7 @@ def check_subtitle_geometry() -> None:
     """
 
     width, height = 768, 1344
-    ass = _build_ass([(1.0, 2.0, "这条路我自己走")], width, height)
+    ass = _build_ass([DisplayCue(1.0, 2.0, "这条路我自己走")], width, height)
     require(f"PlayResX: {width}" in ass, "PlayResX 必须等于画面宽")
     require(f"PlayResY: {height}" in ass, "PlayResY 必须等于画面高")
     style = next(line for line in ass.splitlines() if line.startswith("Style:"))
@@ -112,7 +114,12 @@ def check_subtitle_geometry() -> None:
         f"字号 {font_size} 不在画面高度的 2%–6% 之间",
     )
     margin_v = float(fields[21])
-    require(margin_v < height * 0.2, f"底边距 {margin_v} 会把字幕推离安全区")
+    # The baseline sits about a quarter up, above the platform's own bottom UI;
+    # much higher and the line lands on faces.
+    require(
+        height * 0.15 < margin_v < height * 0.3,
+        f"底边距 {margin_v} 不在画面高度的 15%–30% 之间",
+    )
     margin_h = float(fields[19])
     require(margin_h > 0, "左右边距为 0 时长句会顶到画面边缘")
     require("这条路我自己走" in ass, "台词原文必须原样进 ASS")
@@ -147,18 +154,17 @@ def check_subtitle_timing() -> None:
 
 
 def check_shot_match() -> None:
-    """A declared correction is applied; an undeclared one never is.
+    """A stated correction becomes its own filter chain, within the tool's ranges.
 
-    Generated shots drift a stop apart, so the join reads as a mistake. The
-    correction has to be visible in the document — a tool that measured clips
-    and adjusted them on its own would be changing pictures nobody could review.
+    Generated shots drift a stop apart, so the join reads as a mistake. What a
+    cut states in 「画面」 replaces the automatic within-scene match for that cut.
     """
 
     with tempfile.TemporaryDirectory() as scratch:
         root = Path(scratch)
         episode = build(root, CUT_LIST)
         _, cuts, _ = parse_cut_list(episode / "剪辑单.md")
-        require(_shot_match_filter(cuts[0]) == "", "没写画面的段不得被改动")
+        require(_shot_match_filter(cuts[0]) == "", "没写画面的段没有自己的校正")
 
         listed = CUT_LIST.replace(
             "- 声音：保留原声\n- 字幕：无",
@@ -340,7 +346,7 @@ def check_ass_escaping() -> None:
     escaped = _ass_text(line)
     require("\\{" in escaped and "\\}" in escaped, f"花括号没有转义: {escaped}")
     require("姓名" in escaped, "转义把字弄丢了")
-    ass = _build_ass([(1.0, 2.0, line)], 1080, 1920)
+    ass = _build_ass([DisplayCue(1.0, 2.0, line)], 1080, 1920)
     dialogue = [row for row in ass.splitlines() if row.startswith("Dialogue")][0]
     require(dialogue.endswith(escaped), f"Dialogue 行没有用转义后的正文: {dialogue}")
     require(
@@ -361,7 +367,7 @@ def check_remotion_sources_all_shipped() -> None:
         path.relative_to(REMOTION_SOURCE).as_posix()
         for path in REMOTION_SOURCE.rglob("*")
         if path.is_file()
-        and path.suffix in {".ts", ".tsx", ".json"}
+        and path.suffix in {".ts", ".tsx", ".mjs", ".json"}
         and "node_modules" not in path.parts
     }
     listed = set(REMOTION_SOURCE_FILES)
@@ -377,6 +383,101 @@ def check_remotion_concurrency_is_capped() -> None:
     require("--concurrency=" in source, "render 必须显式传 --concurrency，不能用 Remotion 的默认值")
 
 
+def check_grain_is_a_delivery_wide_decision() -> None:
+    """Grain is declared once for the film, and refused when it is not grain.
+
+    Per cut it would become one more thing that differs between segments, which
+    is the defect it exists to cover.
+    """
+
+    with tempfile.TemporaryDirectory() as scratch:
+        root = Path(scratch)
+        episode = build(root, CUT_LIST)
+        path = episode / "剪辑单.md"
+        baseline = path.read_text(encoding="utf-8")
+
+        delivery, _, _ = parse_cut_list(path)
+        require(delivery.grain is None, "没声明颗粒时应当是 None")
+
+        anchor = "- 交付响度："
+        require(anchor in baseline, "夹具里应当有交付响度那一行")
+        path.write_text(baseline.replace(anchor, "- 颗粒：6\n" + anchor, 1), encoding="utf-8")
+        delivery, _, _ = parse_cut_list(path)
+        require(delivery.grain == 6.0, f"颗粒没有解析出来: {delivery.grain}")
+
+        path.write_text(baseline.replace(anchor, "- 颗粒：无\n" + anchor, 1), encoding="utf-8")
+        delivery, _, _ = parse_cut_list(path)
+        require(delivery.grain is None, "「无」应当解析成不加颗粒")
+
+        path.write_text(baseline.replace(anchor, "- 颗粒：80\n" + anchor, 1), encoding="utf-8")
+        try:
+            parse_cut_list(path)
+        except EditError as error:
+            require("超出" in str(error), f"越界报错没说清: {error}")
+        else:
+            raise AssertionError("颗粒 80 应当被拒绝")
+
+
+def check_missing_shots_are_reported() -> None:
+    """A shot absent from the film must be absent on purpose.
+
+    Absence is invisible in a finished film — nobody watching can tell that an
+    episode's opening seven shots were never made. The only place it can be
+    caught is here, against the document that lists them.
+    """
+
+    known = {f"MOTION-EP006-{i:03d}" for i in range(1, 5)}
+
+    class Stub:
+        def __init__(self, motion): self.motion = motion
+
+    used = [Stub("MOTION-EP006-003"), Stub("MOTION-EP006-004")]
+    findings = _unaccounted_shots(known, used, [])
+    require(findings, "少了两镜却没有任何 finding")
+    require("001" in findings[0] and "002" in findings[0], f"没点名缺的镜头: {findings}")
+
+    excused = _unaccounted_shots(
+        known, used, ["MOTION-EP006-001（理由：质量不可用）", "MOTION-EP006-002（理由：文件缺失）"]
+    )
+    require(not excused, f"写进未采用的镜头不该再报: {excused}")
+
+    require(not _unaccounted_shots(known, [Stub(m) for m in known], []), "全采用时不该报")
+
+
+def check_screen_text_and_effects() -> None:
+    """Screen text is traced to [画面文字] lines; effects are held to their cut."""
+
+    with tempfile.TemporaryDirectory() as scratch:
+        root = Path(scratch)
+        episode = build(root, CUT_LIST)
+        (episode / "剧本.md").write_text(
+            SCREENPLAY + "\n[画面文字] 剩余 4 天 23:59:58\n", encoding="utf-8"
+        )
+        (episode / "media" / "chime.wav").write_bytes(b"")
+        anchor = "- 字幕：这条路我自己走"
+        require(anchor in CUT_LIST, "夹具里应当有一条台词字幕")
+        lines = (
+            "- 画面文字 1：0.00-1.00 任务面板 剩余（倒计时：431998）\n"
+            "- 画面文字 2：1.00-2.00 角标 剩余（倒计时：接续）\n"
+            "- 音效：0.00-0.50 media/chime.wav（增益：-10）"
+        )
+        (episode / "剪辑单.md").write_text(
+            CUT_LIST.replace(anchor, anchor + "\n" + lines), encoding="utf-8"
+        )
+        _, cuts, _ = parse_cut_list(episode / "剪辑单.md")
+        require(len(cuts[1].screen_texts) == 2, "两条画面文字应全部解析")
+        require(len(cuts[1].sound_effects) == 1, "音效应当解析")
+        require(not check_cuts(episode, cuts, root, probe=False), "合法的画面文字与音效不该报错")
+
+        (episode / "剪辑单.md").write_text(
+            CUT_LIST.replace(anchor, anchor + "\n- 画面文字：0.00-1.00 卡片 剩余 5 天"),
+            encoding="utf-8",
+        )
+        _, cuts, _ = parse_cut_list(episode / "剪辑单.md")
+        findings = check_cuts(episode, cuts, root, probe=False)
+        require(any("[画面文字]" in item for item in findings), f"编造的画面文字没抓到: {findings}")
+
+
 def main() -> int:
     with tempfile.TemporaryDirectory() as scratch:
         root = Path(scratch)
@@ -445,7 +546,10 @@ def main() -> int:
     check_shot_match()
     check_ass_escaping()
     check_multi_subtitle()
+    check_screen_text_and_effects()
     check_stale_window()
+    check_missing_shots_are_reported()
+    check_grain_is_a_delivery_wide_decision()
     check_remotion_sources_all_shipped()
     check_remotion_concurrency_is_capped()
     print("short-drama-edit self-tests passed")

package/lib/drama/skills/short-drama-image-prompts/SKILL.md

@@ -20,6 +20,8 @@ license: MIT
 
 有当前视觉设定即可直接开始；剧本只在提示词需要确认剧情状态时读取。Look Development 是可选分支。
 先确认用途：身份板、造型/状态变体、地点板、道具板、组合 production sheet 或比较风格帧。
+分镜需要生产尾帧时，可把已接受的「收尾关键帧提示词」落实为独立 `IMG-...` 状态图条目：
+说明来源 SHOT 与终点，沿用视觉事实和参考范围，不重新设计动作。实际生成以该 IMG 条目为来源。
 
 创作者可读说明跟随项目语言；可复制正文跟随 `short-drama.json#/format/prompt_language`。没有
 `short-drama.json` 时正文默认

package/lib/drama/skills/short-drama-image-prompts/references/common-recipe.md

@@ -203,6 +203,17 @@
 - **`taste_option`**：写实度、媒介、颗粒、色调和镜头感由视觉风格或创作者决定。
 - 禁止用固定词表或形容词比例阻断交付；描述是否空泛，由审查者指出具体缺了什么。
 
+### 光学与表面描述
+
+**`craft_default`**：对需要明确透视或写实质感的画面，写明机位、取景距离和可见表面特征。
+焦段可辅助表达，但不能据此承诺模型会精确模拟光学。
+
+根据画面尺度选择毛孔、布料折痕或金属使用痕迹；「干净」不必等同于没有任何纹理和折痕。
+不要给每张图添加相同的相机参数、瑕疵清单或排除词。
+
+**`taste_option`**：表面是否平滑、是否修饰，以及写实程度由已接受的视觉风格决定。
+结果用对照图检查；像素纹理指标只作辅助，不能代替人物与材质的视觉判断。
+
 ## 5. 输出、常见问题与检查
 
 ### 输出

package/lib/drama/skills/short-drama-novel-analyze/SKILL.md

@@ -170,7 +170,7 @@ python3 {技能目录}/scripts/novel_index.py coverage \
 
 - `story-units.md`：把情节点归成有始有终的单元，每个单元记录进入状态、冲突、代价与出去状态；
 - `rhythm-and-emotion.md`：关键信息如何逐章推进、情绪触动点的铺垫→释放→余波、
-  跨章伏笔与兑现。
+  跨章伏笔与兑现，以及按观众收益排名的爽点表。
 
 聚合完成后跑同一文件里的三条阈值自检（归属置信、覆盖率、重叠率）与散落情节兜底。
 阈值不是评分，是**边界模糊的信号**：重叠率过高说明两个单元其实是一个。
@@ -192,8 +192,8 @@ python3 {技能目录}/scripts/novel_index.py coverage \
 
 - `adaptation-value.md`：哪些单元在竖屏短剧里能直接成立、哪些要换载体、哪些是纯文字快感
   （内心戏、叙述性诡计、长铺垫）在画面上无法兑现；制作负担落在哪里。
-- `episode-candidates.jsonl`：按**局部戏剧结果与精确交接**切出的候选集，不按章号或字数
-  平均切。每条带来源 span、承担的功能、以及未决项。
+- `episode-candidates.jsonl`：按**爽点分布、局部戏剧结果与精确交接**切出的候选集，不按章号
+  或字数平均切。每条带来源 span、承担的功能、承接的爽点以及未决项。
 
 同时**回填快评**：S1 的哪几条判断被全量结果推翻了，写进 `adaptation-value.md` 的开头。
 一个抽样结论被证伪，比它被悄悄忘掉有用得多——下一本书的快评会因此更准。

package/lib/drama/skills/short-drama-novel-analyze/assets/episode-candidate.example.jsonl

@@ -1,3 +1,3 @@
 {"record_type":"sources","schema_version":"1.0.0","sources":{"index":{"owner":"short-drama-novel-analyze","artifact":"项目开发/source-analysis/_index.json"},"original-source":{"owner":"creator","artifact":"输入/original-source.txt"}}}
-{"example_only":true,"destination":"项目开发/source-analysis/episode-candidates.jsonl","schema_version":"1.0.0-draft","record_type":"episode_candidate","candidate_id":"NVA-EPC-EXAMPLE-001","status":"candidate","source_ref":{"src":"original-source"},"index_ref":{"src":"index"},"story_units":["UNIT-EXAMPLE-03"],"chapter_range":{"sequence_start":14,"sequence_end":19},"screen_judgement":"needs_carrier","trope_tags":["信息差","反转打脸"],"entering_knowledge":"观众已知两人共用一份旧证据，但不知道其中一人已经改过它","promise_paid":"改动被第三方当场指出，怀疑从猜测变成具体指控","exit_pressure":"被指控者必须在下一次公开场合前决定认或不认","inherited_facts":["改动过的证据仍在对方手里","两人的合作关系尚未破裂"],"preserved_functions":["关系压力","信息不对称"],"carrier_change":{"original_carrier":"长段内心权衡","new_carrier":"第三方当众比对两份文件的可见动作","lost_or_changed":["读者原本先于角色知道改动，改编后观众与角色同时知道"]},"production_load":{"distinct_locations":2,"characters_in_frame":3,"readable_text_required":true,"notes":"证据文件的可读文字需与美术确认"},"unresolved":["第三方的立场在原文中前后不一致，待创作者裁定"],"creator_acceptance":{"status":"pending","decision_ref":null}}
-{"example_only":true,"destination":"项目开发/source-analysis/episode-candidates.jsonl","schema_version":"1.0.0-draft","record_type":"episode_candidate","candidate_id":"NVA-EPC-EXAMPLE-002","status":"candidate","source_ref":{"src":"original-source"},"index_ref":{"src":"index"},"story_units":["UNIT-EXAMPLE-04"],"chapter_range":{"sequence_start":20,"sequence_end":22},"screen_judgement":"screen_ready","trope_tags":["打脸"],"entering_knowledge":"观众已知指控成立，不知道被指控者手里还有一份未公开的记录","promise_paid":"记录被主动交出，代价是失去唯一的退路","exit_pressure":"退路没了，对手却仍未出手","inherited_facts":["记录已进入公开视野"],"preserved_functions":["代价","权力转移"],"carrier_change":null,"production_load":{"distinct_locations":1,"characters_in_frame":2,"readable_text_required":false,"notes":null},"unresolved":[],"creator_acceptance":{"status":"pending","decision_ref":null}}
+{"example_only":true,"destination":"项目开发/source-analysis/episode-candidates.jsonl","schema_version":"1.0.0-draft","record_type":"episode_candidate","candidate_id":"NVA-EPC-EXAMPLE-001","status":"candidate","source_ref":{"src":"original-source"},"index_ref":{"src":"index"},"story_units":["UNIT-EXAMPLE-03"],"chapter_range":{"sequence_start":14,"sequence_end":19},"screen_judgement":"needs_carrier","trope_tags":["信息差","反转打脸"],"payoffs":["PAY-EXAMPLE-07"],"entering_knowledge":"观众已知两人共用一份旧证据，但不知道其中一人已经改过它","promise_paid":"改动被第三方当场指出，怀疑从猜测变成具体指控","exit_pressure":"被指控者必须在下一次公开场合前决定认或不认","inherited_facts":["改动过的证据仍在对方手里","两人的合作关系尚未破裂"],"preserved_functions":["关系压力","信息不对称"],"carrier_change":{"original_carrier":"长段内心权衡","new_carrier":"第三方当众比对两份文件的可见动作","lost_or_changed":["读者原本先于角色知道改动，改编后观众与角色同时知道"]},"production_load":{"distinct_locations":2,"characters_in_frame":3,"readable_text_required":true,"notes":"证据文件的可读文字需与美术确认"},"unresolved":["第三方的立场在原文中前后不一致，待创作者裁定"],"creator_acceptance":{"status":"pending","decision_ref":null}}
+{"example_only":true,"destination":"项目开发/source-analysis/episode-candidates.jsonl","schema_version":"1.0.0-draft","record_type":"episode_candidate","candidate_id":"NVA-EPC-EXAMPLE-002","status":"candidate","source_ref":{"src":"original-source"},"index_ref":{"src":"index"},"story_units":["UNIT-EXAMPLE-04"],"chapter_range":{"sequence_start":20,"sequence_end":22},"screen_judgement":"screen_ready","trope_tags":["打脸"],"payoffs":["PAY-EXAMPLE-02"],"entering_knowledge":"观众已知指控成立，不知道被指控者手里还有一份未公开的记录","promise_paid":"记录被主动交出，代价是失去唯一的退路","exit_pressure":"退路没了，对手却仍未出手","inherited_facts":["记录已进入公开视野"],"preserved_functions":["代价","权力转移"],"carrier_change":null,"production_load":{"distinct_locations":1,"characters_in_frame":2,"readable_text_required":false,"notes":null},"unresolved":[],"creator_acceptance":{"status":"pending","decision_ref":null}}

package/lib/drama/skills/short-drama-novel-analyze/references/adaptation-triage.md

@@ -83,14 +83,18 @@ python3 {技能目录}/scripts/novel_index.py sample \
 
 回答一个问题：**如果这本书改成短剧，第 1 集从哪里开始**？
 
-找**第一个可见的、有代价的、当场发生的转折**——主角第一次做出会付出代价的选择，
-且这个选择能被拍出来而不是被想出来。它通常不在第一章。写清三条：
+找**观众在此处收益最强、且能同时交代主角身份、眼前危机与目标的一处**：打脸、奇观、
+反转、身份揭露、奖励兑现或危机爆发，能被拍出来而不是被想出来。兑现它的可以是旁观者——
+群体改口、对手当众吃瘪，收益照样落在观众身上。它通常不在第一章，也常常不是时间上最早的那个
+爽点：后文的高潮可以提前做冷开。写清四条：
 
-- 落在第几章（用索引的 `sequence`）；
+- 落在第几章（用索引的 `sequence`），收益类型是什么；
+- 抽样里若另有更晚、更强的高光，一并写出，它是冷开候选；
 - 它之前的内容里，哪些是观众必须知道的，可以怎样在开场后补进去；
 - 哪些是原著读者需要、短剧观众不需要的。
 
-抽样里没有这样的转折时，写「抽样内未见可用的开篇替换点」，并列进第 5 段的风险。
+抽样里没有这样的一处时，写「抽样内未见可用的开篇替换点」，并列进第 5 段的风险。
+全量拆解后，S3 的爽点表会给出完整排名，S5 回填时拿它对照这里的判断。
 
 ## 结论限于抽样范围
 

package/lib/drama/skills/short-drama-novel-analyze/references/adaptation-value.md

@@ -76,7 +76,13 @@
 
 ## 分集候选
 
-按**局部戏剧结果与精确交接**切，不按章号、字数或平均分配。一个候选集必须能回答：
+按**爽点分布、局部戏剧结果与精确交接**切，不按章号、字数或平均分配。先读
+[爽点表](aggregation-and-entities.md#爽点表)：候选集的边界跟着爽点走，没有爽点的长间隔
+并进相邻候选或标为可删，而不是单独成集；排名靠前、落在后文的高光写进交接摘要，
+由 `$short-drama-develop` 决定是否提前或做冷开。章与集不是 1:1——一章撑不起一集时合并，
+一章里有两个大爽点时可以拆。
+
+一个候选集必须能回答：
 
 1. 进入时观众已经知道什么；
 2. 本集内兑现了哪一部分承诺（不能一条都不兑现）；
@@ -87,7 +93,8 @@
 
 每条候选写进 `episode-candidates.jsonl`，字段见
 [分集候选样例](../assets/episode-candidate.example.jsonl)。每条都带：来源单元与章号区间、
-承担的功能、判定类别、桥段标签、未决项、以及 `creator_acceptance: pending`。
+承担的功能、判定类别、桥段标签、承接的爽点（`payoffs`，没有就写空并说明这一集靠什么留人）、
+未决项、以及 `creator_acceptance: pending`。
 
 **集数不由本技能决定**。 候选可以多于、也可以少于创作者设定的集数；差多少要明说，
 由创作者与 `$short-drama-develop` 决定合并还是拆分。
@@ -120,5 +127,5 @@
 - 没有把本技能的判定写成结论——它们是候选，等创作者接受。
 
 交接摘要给创作者读，说清：拆了多少章、跳过哪些、多少单元分别落进三类、
-切出多少候选集、最大的三处改编风险、快评里被推翻的判断。风险要具体到单元，
+切出多少候选集、排名前列的爽点落在哪几个候选、最大的三处改编风险、快评里被推翻的判断。风险要具体到单元，
 不写「改编难度较大」。

package/lib/drama/skills/short-drama-novel-analyze/references/aggregation-and-entities.md

@@ -99,16 +99,40 @@
 
 ## 节奏与情绪
 
-`rhythm-and-emotion.md` 写三件事，全部要能回指到章或情节点：
+`rhythm-and-emotion.md` 写四件事，全部要能回指到章或情节点：
 
 - **关键信息推进**：某条信息何时进入读者视野 → 如何被延迟、误导或验证 → 何时爆发 →
   余波与新钩子。
 - **情绪触动点索引**：每个触动点落在哪一章、由哪条情节点承担。
 - **长间隔说明**：连续 3 章以上没有触动点时，写清作者用什么维持期待。
   改编时这些长间隔就是要合并或砍掉的段落——短剧没有这个耐心。
+- **爽点表**：见下一节。
 
 回指不到章或情节点的条目删掉，不要保留无源断言。
 
+### 爽点表
+
+选段和切候选集之前，先按**观众收益**给全书情节点排名。原著的叙述顺序是给读者的，
+短剧观众为爽点付费；不先排名，候选集就会按时序一章一章往下切，全书最强的高光可能落到
+好几集之后。
+
+每行一个爽点，按收益强度从高到低排：
+
+| 列 | 写什么 |
+|---|---|
+| `PAY-<N>` | 稳定编号，供候选集引用 |
+| 位置 | 章（`sequence`）与情节点 |
+| 类型 | 打脸、奇观、反转、身份揭露、奖励兑现、危机，可多选 |
+| 谁兑现 | 主角、对手、旁观者或群体；**旁观者完成的打脸同样算**——群里改口、围观者集体道歉、老前辈当众表态，收益都落在观众身上 |
+| 收益落在谁身上 | 被打脸的是谁、他之前压迫得多具体；压迫越具体，落差越大 |
+| 首集能力 | 这一处能否同时交代主角的身份、眼前的危机与目标；能的标出来，它是开篇替换点的候选 |
+| 依赖 | 观众要先知道什么才看得懂；可以怎样在开场后补 |
+
+强度按本书内部相对排，不跨书比较，也不给分数。原著里一段喜剧反应、一张奖励清单
+也可能是爽点，照实列，不要因为它「只是反应」就漏掉。
+
+**`craft_default · NVA-13`**：切候选集之前先排爽点表，旁观者兑现的爽点同样入表；候选集引用它承接的 `PAY-<N>`。
+
 ## 人物归并
 
 跨章去重时，**一人一实体**：无法确定两个称谓是否指同一人，就分开建两条，不合并。

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

@@ -61,6 +61,7 @@
 | NVA-10 | reviewed_invariant | Episode candidates are cut on local dramatic result and precise handoff, not on chapter count or word budget. |
 | NVA-11 | craft_default | Triage a deterministic spread of chapters across the whole book and stop for the creator before committing to a full pass. |
 | NVA-12 | taste_option | Where to open, which line to keep and which ending to promise remain creator choices; analysis may argue but never blocks. |
+| NVA-13 | craft_default | Before cutting episode candidates, rank the book's plot points by audience payoff — face-slap, spectacle, reversal, identity reveal, reward delivered, crisis — counting payoffs a bystander or crowd delivers; candidates follow the payoff distribution rather than one chapter per episode and cite the payoffs they carry. The opening replacement point is the strongest payoff that can also establish the protagonist's identity, crisis and goal, and a stronger later peak is reported as a cold-open option. |
 
 规则分级由高到低：`structural_invariant`（结构缺陷，阻断）、
 `reviewed_invariant`（需证据判断）、`craft_default`（常用做法，可覆盖）、

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

@@ -16,7 +16,8 @@ license: MIT
 取出本次提示词，建立一个有边界的运行 job。creator-first job 的 `source` 必须指向拥有这条提示词的
 当前 Markdown，`source_entry` 必须点名该文档允许的二级标题：`图片提示词.md` 用 `IMG-*`，
 `视频提示词.md` 用 `MOTION-*`，`分镜.md` 用 `SHOT-*`（modality 为 `image`，正文取该镜的
-`### 冻结关键帧提示词`）。分镜这一路是本套件里唯一能把某一镜的起始画面渲染成文件的入口，但不是创作者获得起始帧的唯一办法——
+`### 冻结关键帧提示词`）。此选择器只提取首帧；尾帧需先由图片提示词阶段建立独立 `IMG-*` 状态图条目，
+再从 `图片提示词.md` 准备 image job。创作者也可以提供已有起始帧——
 在自己的工具里出图再放进项目同样成立，图片始终不进项目时走分镜的 `PLAN-...`；
 产出落在 `剧集/<EP>/制作成果/images/` 后，分镜 owner 才能把它绑成 `用途：起始帧` 的 `REF-...`。存在真实参考图时，
 还必须逐张填写 `reference_bindings` 的槽位、顺序、路径、中文名、用途以及允许/禁止控制范围；
@@ -126,6 +127,9 @@ adapter 配置必须在项目外，只包含 argv 命令和超时；凭据由 ad
   固定高保真引用并校验尺寸、格式与透明背景限制。
 - [MiniMax Music](references/providers/minimax-music.md)：使用 `music-3.0` 与 hex 结果，区分主题曲
   和纯配乐，不伪造时长请求字段。
+- [MiniMax 语音](references/providers/minimax-speech.md)：`tts` 模态；模型与 `voice_id` 都必须
+  由账号与文档显式给出，不内置音色清单。只从预置音色合成，不做声音克隆——克隆是授权问题，
+  创作者授权的参考录音按普通创作者输入走 `输入/`。
 - [MiniMax H3 视频](references/providers/minimax-h3-video.md)：模型 ID、分辨率集合与时长区间必须
   由账号显式配置；提示词进 `content` 的 text 项，参考图按显式 role 绑定，本地参考在没有可信上传时
   fail closed。该模型与画面同一次生成声音，写法影响见视频提示词技能的目标模型能力档案。

package/lib/drama/skills/short-drama-produce/references/adapter-contract.md

@@ -99,6 +99,12 @@ Keep this file outside the project:
 `command` is an argv array, never a shell string. Timeout is 1–3600 seconds. Do not put credentials in this file;
 let the adapter read its environment or operating-system credential store.
 
+## Capability sources
+
+Use the provider's current API reference for roles, limits and supported combinations.
+A relay can expose a different subset, reject inputs itself or transform requests.
+Record the tested execution path and distinguish its observations from the native API contract.
+
 ## Adapter stdin
 
 The adapter receives one UTF-8 JSON document as raw stdin bytes. Read the
@@ -121,26 +127,14 @@ on the machine locale. The document contains the confirmed job plus:
   adapter must **not submit anything**; it polls and downloads that existing
   task and returns its outputs as usual.
 
-## Why the handle exists
-
-A video task is billed the moment it is submitted, not when its result is
-collected. Everything after submission — polling for minutes, downloading — can
-be interrupted by a killed process, a dropped connection, or a sleeping laptop.
-Without a durable id the attempt record says `failed` while the provider's task
-is alive and already paid for, and the only way forward is to submit again and
-pay a second time for the same shot.
-
-So: write the handle before the first poll, and treat failing to write it as
-non-fatal — a submitted task must never be failed because its id could not be
-recorded locally. The tool copies the handle onto the attempt record on both the
-success and the failure path, `audit` reports any unfinished attempt that
-carries one as `orphaned_provider_job` with `action: collect_before_retry`, and
-`production_tool.py collect` fetches it.
-
-`collect` deliberately sits outside the confirmation gate. That gate exists to
-prevent an unintended charge; collecting spends nothing because the charge
-already happened. Requiring a fresh confirmation would make paying again the
-cheapest way out of an interruption — the exact outcome the gate is for.
+## Recovering a submitted task
+
+Record the provider task ID before polling so an interrupted task can be collected without resubmission.
+A local handle-write failure is non-fatal after submission. The tool copies the handle into the attempt
+record on success or failure; `audit` reports unfinished tasks as `orphaned_provider_job` with
+`action: collect_before_retry`.
+
+`production_tool.py collect` retrieves the existing task without new submission or confirmation.
 
 It may translate provider-neutral parameters into its chosen SDK/API. Optional
 provider adapters under `scripts/` document and implement known translations;

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

@@ -74,31 +74,13 @@ structured: base/first-frame/first-last-frame tasks use `integrated_multimodal_d
 form. Chinese dialogue remains exact inside `<d>[Chinese] ...</d>`. Full details live in the
 video-prompt skill's `references/minimax-h3.md`.
 
-Audio generation is a **capability**, not a style:
-what changes upstream is only which axes of the target-model profile a project declares — see the
-video-prompt skill's target-model profile. Two consequences are worth stating here because they
-show up as production defects rather than as API errors:
-
-- an unstated **music** channel is not a silent one. Probing this suite's own prompts against H3, a
-  body carrying `non_diegetic_music: N/A` came back without a score in 14 of 14 runs, while a body
-  that said nothing about music came back with an invented score in 2 of 3. State the music intent.
-- the **speech** channel did not behave the same way in those probes: no run invented dialogue,
-  including 8 runs whose body carried a contradictory `No dialogue` exclusion. Treat "an unstated
-  vocal channel gets filled" as unverified rather than as a known failure, and write the shot's
-  sound intent because the body should say what this shot sounds like — not on the strength of a
-  mechanism this suite has not observed.
-- readable on-screen text was **not** produced unmasked in those probes either: across 44 sampled
-  frames from 11 clips — including dialogue clips carrying no exclusion sentence, on H3 and on
-  Seedance 2.0/2.5 — no burned-in subtitle or caption appeared. The exclusion sentence this suite
-  mandates is therefore precautionary **for video** rather than evidence-driven. Keep writing it:
-  a one-line exclusion costs nothing, these probes are small enough that they only show the failure
-  was not produced here, and generator behaviour changes between versions. What should change is the
-  justification — do not defend it as a fix for an observed defect. Note the asymmetry before carrying this reasoning anywhere else:
-  the same probe run against `gpt-image-2` found the opposite — an unconstrained still came back
-  covered in invented readable text, and the exclusion sentence cleaned it up. The image stages
-  keep their text policy on evidence; only the video stage's copy of it is precautionary.
-
-Neither is written here as a fixed phrase, and this suite never injects one. The wording belongs to
-the shot and to the project's declared prompt language.
+State the intended sound layers in the prompt. For no non-diegetic music, the
+H3 dialect uses `non_diegetic_music: N/A`; small probes observed unwanted music
+when this layer was omitted. They did not establish that omitted speech or
+negative clauses cause extra dialogue.
+
+Follow the project's subtitle and in-scene-text policy. Prompt wording belongs
+to the video-prompt skill and the declared language, not to adapter-generated
+boilerplate.
 
 Protocol reference: [MiniMax video generation API](https://platform.minimax.io/docs/api-reference/video-generation-v2-create).

package/lib/drama/skills/short-drama-produce/references/providers/minimax-speech.md

@@ -0,0 +1,41 @@
+# MiniMax Speech adapter
+
+Adapter command:
+
+```json
+{"command": ["python3", "/absolute/path/provider_adapters.py", "minimax-speech"], "timeout_seconds": 600}
+```
+
+Required environment: `MINIMAX_API_KEY`. `MINIMAX_BASE_URL` optionally overrides the default
+`https://api.minimax.io/v1` and must remain HTTPS.
+
+The job uses the suite's `tts` modality and must have exactly one output. The production prompt is the
+line to be spoken, verbatim — not a description of it. Supported public parameters are `model`,
+`voice_id`, `emotion`, `speed`, `vol`, `pitch`, `sample_rate`, `bitrate`, and `format`. The requested
+format must match the target extension and be `mp3` or `wav`.
+
+`model` and `voice_id` are both required and neither has a default. The model is an account-enabled
+endpoint, exactly as for the video providers. The voice is a creative decision recorded in
+`视觉设定.md` under the character's 声音方向, and it reaches the adapter through the confirmed job.
+
+## Voice selection
+
+Read the provider's voice listing and confirm availability for the chosen model and account.
+The adapter validates the ID format, not catalogue membership. Record the selected ID in the
+character's 声音方向 and pass it through the confirmed job.
+
+This workflow selects preset voices. The adapter does not enrol or clone a voice;
+any supplied recording retains its documented authorization and usage scope.
+
+## Request shape
+
+The request is non-streaming with `output_format: hex`, `POST /t2a_v2`, and carries
+`voice_setting` (`voice_id`, and any of `emotion`, `speed`, `vol`, `pitch`) alongside `audio_setting`
+(`sample_rate`, `bitrate`, `format`). The adapter validates `base_resp.status_code`, decodes
+`data.audio` as hexadecimal bytes, and writes it to a private temporary file.
+
+`emotion` accepts the provider's seven values: `happy`, `sad`, `angry`, `fearful`, `disgusted`,
+`surprised`, `neutral`. Anything outside that set is refused rather than passed through — a rejected
+emotion is a typo caught before it is paid for.
+
+Protocol reference: [MiniMax Text to Speech](https://platform.minimax.io/docs/api-reference/speech-t2a-http).