@oh-story/dsh 0.1.11 → 0.1.13

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

@@ -478,6 +478,53 @@ def check_screen_text_and_effects() -> None:
         require(any("[画面文字]" in item for item in findings), f"编造的画面文字没抓到: {findings}")
 
 
+def check_still_cuts() -> None:
+    """The static route: keyframes with a camera move and voice lines, every shot accounted for."""
+
+    with tempfile.TemporaryDirectory() as scratch:
+        root = Path(scratch)
+        episode = build(root, CUT_LIST)
+        (episode / "分镜.md").write_text(
+            "## SHOT-EP001-010 · 甲\n\n## SHOT-EP001-011 · 乙\n", encoding="utf-8"
+        )
+        for name in ("010.png", "line.wav"):
+            (episode / "media" / name).write_bytes(b"")
+        still = (
+            "- 画幅与帧率：1080×1920 · 24fps\n\n"
+            "## CUT-EP001-001 · 定格\n\n"
+            "- 来源：SHOT-EP001-010 · media/010.png\n"
+            "- 入点：0.00\n- 出点：2.00\n- 时长：2.00\n"
+            "- 取舍：入点=起；出点=止\n- 声音：配音\n"
+            "- 运镜：推近 8%\n- 配音：0.30 media/line.wav\n"
+        )
+        (episode / "剪辑单.md").write_text(still, encoding="utf-8")
+        delivery, cuts, unused = parse_cut_list(episode / "剪辑单.md")
+        require(cuts[0].still and cuts[0].move[:2] == ("推近", 8), f"静帧与运镜没有解析出来: {cuts[0]}")
+        require(len(cuts[0].voices) == 1, "配音没有解析出来")
+        findings = check_cuts(episode, cuts, root, probe=False, unused=unused, delivery=delivery)
+        require(
+            any("SHOT-EP001-011" in item for item in findings),
+            f"用了 SHOT 静帧之后，没用也没写进未采用的镜头必须报: {findings}",
+        )
+
+        # A line can start inside its file and before its picture (a J-cut).
+        (episode / "剪辑单.md").write_text(
+            still.replace("- 配音：0.30 media/line.wav", "- 配音：-0.40 media/line.wav（增益：-2；起点：0.10）"),
+            encoding="utf-8",
+        )
+        _, cuts, _ = parse_cut_list(episode / "剪辑单.md")
+        voice = cuts[0].voices[0]
+        require((voice.start, voice.gain_db, voice.offset) == (-0.4, -2.0, 0.1), f"起点与增益没有解析出来: {voice}")
+
+        (episode / "剪辑单.md").write_text(still + "- 运镜：旋转 8%\n", encoding="utf-8")
+        try:
+            parse_cut_list(episode / "剪辑单.md")
+        except EditError:
+            pass
+        else:
+            raise AssertionError("运镜写了两遍应当被拒绝")
+
+
 def main() -> int:
     with tempfile.TemporaryDirectory() as scratch:
         root = Path(scratch)
@@ -547,6 +594,7 @@ def main() -> int:
     check_ass_escaping()
     check_multi_subtitle()
     check_screen_text_and_effects()
+    check_still_cuts()
     check_stale_window()
     check_missing_shots_are_reported()
     check_grain_is_a_delivery_wide_decision()

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

@@ -25,6 +25,9 @@ license: MIT
 （MiniMax 为 `first_frame`/`last_frame`/`reference_image`/`reference_video`/`reference_audio`，
 Seedance 为三个 `reference_*`）；带参考图却没有绑定的 job 会直接失败，不替它猜一个 role。
 本地图片由内置 adapter 按 base64 data URI 直接送出，不需要自建上传服务。
+`MOTION-*` 的「参考音频」行同样逐条进 `reference_bindings`，排在图片之后、role 固定为 `reference_audio`、`character` 照抄该行的 `角色`；
+adapter profile 没有声明接受 `reference_audio` 时 `run` 在提交前失败，见
+[adapter-contract.md](references/adapter-contract.md#adapter-config)。
 条目的「输入参考图」写成 `PLAN-...` 时，那些图片在创作者自己的工具里，项目内没有文件可送：
 `prepare` 直接失败并说明先把真实文件放进项目、改写成 `REF-...`，不拿计划当输入，也不静默丢掉参考。
 `references` 可以省略并由绑定顺序生成，也可以作为相同顺序的显式镜像。输出放在
@@ -98,7 +101,9 @@ python3 <本技能目录>/scripts/production_tool.py audit <project>
   输入统一译为 `reference_video + reference_image`，不能混成 `reference_video + first_frame`；不以
   计划尾帧或文字描述代替真实文件。
 - **tts**：从 `剧本.md` 读取原句与表演要求，声音参考由用户或现有媒体明确提供。不得在生产 job
-  中改词，也不为 TTS 新建第六份创作文档。
+  中改词，也不为 TTS 新建第六份创作文档。表演要求来自这句台词的括注和上下文：执行端接受自然语言语气时，
+  写成一句语气说明放在台词前（「憋屈地压低声音，咬着牙应一声：是。」），同一角色每句挂同一段参考音色；
+  只接受枚举情绪时映射到最近的一档，再用强度、音调细调。只给音色、不给语气时，短剧台词会念成播音腔。
 - **music**：读取 `视频提示词.md` 中创作者已确认的时间线音乐章节；主题曲使用已确认歌词，纯配乐
   不携带歌词。供应商不能精确承诺时长时，生成源音轨后仍由 `$short-drama-edit` 按文档里的混音意图完成落点、
   循环、淡入淡出和对白 ducking。

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

@@ -58,6 +58,12 @@
   `reference_video`, `reference_audio` for MiniMax, and the three `reference_*`
   values for Seedance. A video job carrying references without bindings fails
   closed there rather than having a role guessed for it.
+  A `MOTION-*` entry's `参考音频` line binds after the pictures: its slots follow
+  the `输入参考图` bindings in audio `顺序`, continuing the job's `order`, each with
+  role `reference_audio` and `character` copied exactly from its `角色` field. Only those
+  slots may use that role. Leaving a declared voice or its character out, or swapping
+  characters, fails `prepare`. Adapters must preserve this character binding; bundled
+  compilers derive the voice label from `character`, not the free-form asset `label`.
 - `references`: zero to sixteen current project files actually sent to production.
   It may be omitted when `reference_bindings` is present, in which case the paths
   are derived in binding order. If both are present, they must match exactly.
@@ -99,6 +105,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.
 
+A profile may add `"reference_roles": [...]`, the roles its configured model accepts. When present,
+`run` refuses any binding whose role is not listed. A `reference_audio` binding always needs it:
+a model without an audio input can drop the voice without an error. Either way `run` stops before
+the confirmation is spent or the adapter starts. List `reference_audio` only for a model you know
+accepts reference audio.
+
 ## Capability sources
 
 Use the provider's current API reference for roles, limits and supported combinations.

package/lib/drama/skills/short-drama-produce/scripts/production_tool.py

@@ -149,6 +149,17 @@ REFERENCE_LINE_RE = re.compile(
     re.IGNORECASE,
 )
 
+# A MOTION's `- 参考音频：` line: the speaking character's accepted voice. It
+# compiles to role `reference_audio` after the picture bindings, so the audio
+# 顺序 stays the provider's own audio numbering (`@音频N`, `<Audio N>`).
+AUDIO_REFERENCE_ROLE = "reference_audio"
+AUDIO_REFERENCE_LINE_RE = re.compile(
+    r"(REF-[A-Z0-9][A-Z0-9-]{0,79})（顺序：([1-9]\d*)）· "
+    r"([^；\n]+?\.(?:wav|mp3|m4a|aac|flac))《([^》\n]+)》"
+    r"（用途：[^；）\n]+；角色：([^；）\n]+)；控制：([^；）\n]+)；不得控制：([^）\n]+)）",
+    re.IGNORECASE,
+)
+
 
 class ConfirmationRequiredError(RuntimeError):
     """The exact current job has not been explicitly confirmed."""
@@ -705,7 +716,7 @@ def _normalize_reference_bindings(value: object) -> list[dict[str, Any]]:
     normalized: list[dict[str, Any]] = []
     for index, binding in enumerate(value, 1):
         label = f"reference_bindings[{index}]"
-        if not isinstance(binding, Mapping) or set(binding) != {
+        if not isinstance(binding, Mapping) or set(binding) - {"character"} != {
             "slot_id",
             "order",
             "path",
@@ -732,6 +743,12 @@ def _normalize_reference_bindings(value: object) -> list[dict[str, Any]]:
             raise ValueError(f"{label} label must contain Chinese text")
         if not isinstance(role, str) or not role.strip() or len(role) > 80:
             raise ValueError(f"{label} role is invalid")
+        character = binding.get("character")
+        if "character" in binding and (
+            role != AUDIO_REFERENCE_ROLE or not isinstance(character, str)
+            or not character.strip() or len(character) > 200
+        ):
+            raise ValueError(f"{label} character is invalid")
         may_control = _scope_list(
             binding.get("may_control"), label=f"{label}.may_control"
         )
@@ -749,6 +766,7 @@ def _normalize_reference_bindings(value: object) -> list[dict[str, Any]]:
                 "path": _relative_path(binding.get("path")),
                 "label": raw_label.strip(),
                 "role": role.strip(),
+                **({"character": character.strip()} if isinstance(character, str) else {}),
                 "may_control": may_control,
                 "must_not_control": must_not_control,
             }
@@ -817,12 +835,25 @@ def _contains_plan_token(value: str) -> bool:
     return "plan-" in value.casefold()
 
 
+def _field_values(section: str, field_name: str) -> list[str]:
+    """Every value of one `- 字段：值` field, read the way the creator checker reads it.
+
+    `- **参考音频**：…` is the same field to a human and to
+    creator_markdown_check.py; reading it any other way here would let the
+    checker validate a binding that production then silently omits.
+    """
+    values = []
+    for key, value in re.findall(r"^- ([^：\n]+)：(.+)$", section, re.MULTILINE):
+        key = re.sub(r"^(?:\*\*|__|\*|_)(.+?)(?:\*\*|__|\*|_)$", r"\1", key.strip())
+        if key == field_name:
+            values.append(value)
+    return values
+
+
 def _markdown_reference_bindings(
     section: str, *, field_name: str, creator_supplied_ok: bool = False
 ) -> list[dict[str, Any]]:
-    lines = re.findall(
-        rf"^- {re.escape(field_name)}：(.+)$", section, re.MULTILINE
-    )
+    lines = _field_values(section, field_name)
     if not lines:
         raise ValueError(f"source entry has no {field_name} declaration")
     if len(lines) != 1:
@@ -879,6 +910,45 @@ def _markdown_reference_bindings(
     ]
 
 
+def _markdown_audio_bindings(section: str) -> list[dict[str, Any]]:
+    """The MOTION's 参考音频 slots in audio order; empty when there is none."""
+    lines = _field_values(section, "参考音频")
+    if not lines:
+        return []
+    if len(lines) != 1:
+        raise ValueError("source entry has duplicate 参考音频 declarations")
+    value = lines[0].strip()
+    if not _contains_ref_token(value) and re.fullmatch(r"无(?:（[^）\n]+）)?。?", value):
+        return []
+    matches = list(AUDIO_REFERENCE_LINE_RE.finditer(value))
+    cursor = 0
+    for index, match in enumerate(matches):
+        if value[cursor : match.start()] != ("" if index == 0 else "；"):
+            matches = []
+            break
+        cursor = match.end()
+    if not matches or value[cursor:] not in {"", "。"}:
+        raise ValueError("source entry 参考音频 declaration is invalid")
+    bindings = sorted(
+        (
+            {
+                "slot_id": match.group(1),
+                "order": int(match.group(2)),
+                "path": _relative_path(match.group(3)),
+                "label": match.group(4).strip(),
+                "character": match.group(5).strip(),
+                "may_control": _scope_items(match.group(6)),
+                "must_not_control": _scope_items(match.group(7)),
+            }
+            for match in matches
+        ),
+        key=lambda binding: binding["order"],
+    )
+    if [binding["order"] for binding in bindings] != list(range(1, len(bindings) + 1)):
+        raise ValueError("source entry 参考音频 order must be contiguous from 1")
+    return bindings
+
+
 def _verify_markdown_source(
     root: Path,
     *,
@@ -902,6 +972,25 @@ def _verify_markdown_source(
         # reference field records creative intent, not this job's inputs.
         creator_supplied_ok=source_path.name == "分镜.md",
     )
+    # Voices follow the pictures, so neither numbering moves the other. A
+    # declared voice missing from the job fails here instead of being dropped
+    # on the way to the provider.
+    audio = (
+        _markdown_audio_bindings(section)
+        if source_path.name == "视频提示词.md"
+        else []
+    )
+    declared = declared + [
+        {**binding, "order": len(declared) + binding["order"]} for binding in audio
+    ]
+    audio_slots = {binding["slot_id"] for binding in audio}
+    for binding in bindings:
+        if (binding["slot_id"] in audio_slots) != (
+            binding["role"] == AUDIO_REFERENCE_ROLE
+        ):
+            raise ValueError(
+                "a 参考音频 slot binds role reference_audio, and only it does"
+            )
     comparable = [
         {key: binding[key] for key in (
             "slot_id",
@@ -913,6 +1002,9 @@ def _verify_markdown_source(
         )}
         for binding in bindings
     ]
+    for binding, comparison in zip(bindings, comparable):
+        if "character" in binding:
+            comparison["character"] = binding["character"]
     if declared != comparable:
         raise ValueError("job reference bindings do not match the selected source entry")
 
@@ -1236,14 +1328,18 @@ def _inputs_current(root: Path, job: Mapping[str, Any]) -> bool:
         return False
 
 
-def _load_adapter(config_path: Path, profile: str, root: Path) -> tuple[list[str], int]:
+def _load_adapter(config_path: Path, profile: str, root: Path) -> tuple[list[str], int, frozenset[str] | None]:
     resolved = config_path.expanduser().resolve()
     if resolved.is_relative_to(root):
         raise ValueError("adapter config must live outside the project")
     document = json.loads(resolved.read_text(encoding="utf-8"))
     adapters = document.get("adapters") if isinstance(document, Mapping) else None
     selected = adapters.get(profile) if isinstance(adapters, Mapping) else None
-    if not isinstance(selected, Mapping) or set(selected) - {"command", "timeout_seconds"}:
+    if not isinstance(selected, Mapping) or set(selected) - {
+        "command",
+        "timeout_seconds",
+        "reference_roles",
+    }:
         raise ValueError(f"adapter profile is missing or invalid: {profile}")
     command = _string_list(selected.get("command"), label="adapter command", limit=32)
     if not command or any(not part for part in command):
@@ -1251,7 +1347,39 @@ def _load_adapter(config_path: Path, profile: str, root: Path) -> tuple[list[str
     timeout = selected.get("timeout_seconds", 300)
     if not isinstance(timeout, int) or isinstance(timeout, bool) or not 1 <= timeout <= MAX_TIMEOUT_SECONDS:
         raise ValueError(f"adapter timeout must be 1-{MAX_TIMEOUT_SECONDS} seconds")
-    return command, timeout
+    roles = selected.get("reference_roles")
+    declared = (
+        frozenset(_string_list(roles, label="adapter reference_roles"))
+        if roles is not None
+        else None
+    )
+    return command, timeout, declared
+
+
+def _require_adapter_roles(
+    job: Mapping[str, Any], declared: frozenset[str] | None
+) -> None:
+    """Refuse, before anything is submitted, a role the target model cannot take.
+
+    A profile may list the `reference_roles` its configured model accepts. A
+    voice reference always needs that declaration: a model without the input
+    can drop it without an error, and the drift is only heard in the take.
+    """
+    unsupported = sorted(
+        {
+            str(binding["role"])
+            for binding in job.get("reference_bindings", [])
+            if (declared is not None and binding["role"] not in declared)
+            or (declared is None and binding["role"] == AUDIO_REFERENCE_ROLE)
+        }
+    )
+    if unsupported:
+        raise ValueError(
+            f"adapter profile {job['adapter']} does not declare reference_roles "
+            + ", ".join(unsupported)
+            + "; nothing was submitted. Declare them only if this profile's model "
+            "accepts them, or remove the binding (参考音频) from the source entry"
+        )
 
 
 def _generic_adapter_error(
@@ -1599,7 +1727,8 @@ def run_job(root: Path, *, job_id: str, adapter_config: Path) -> dict[str, Any]:
             if _active_run(root, job_id) is not None:
                 raise RuntimeError("this job is already running")
             job = _read_job(root, job_id)
-            command, timeout = _load_adapter(adapter_config, str(job["adapter"]), root)
+            command, timeout, roles = _load_adapter(adapter_config, str(job["adapter"]), root)
+            _require_adapter_roles(job, roles)
             try:
                 receipt = _metadata_read_json(
                     root,
@@ -1738,7 +1867,7 @@ def collect_job(root: Path, *, job_id: str, adapter_config: Path) -> dict[str, A
         output_root.mkdir(parents=True)
         with _project_lock(root):
             job = _read_job(root, job_id)
-            command, timeout = _load_adapter(adapter_config, str(job["adapter"]), root)
+            command, timeout, _ = _load_adapter(adapter_config, str(job["adapter"]), root)
             target_run = None
             for run in reversed(_read_run_history(root, job_id)):
                 if run.get("status") == "succeeded":

package/lib/drama/skills/short-drama-produce/scripts/provider_adapters.py

@@ -256,6 +256,12 @@ def _prompt_with_reference_contract(
             or not all(isinstance(item, str) and item.strip() for item in must_not_control)
         ):
             raise ValueError("reference binding semantics are invalid")
+        character = binding.get("character")
+        if character is not None:
+            if role != "reference_audio" or not isinstance(character, str) or not character.strip():
+                raise ValueError("reference audio character is invalid")
+            # The source's explicit speaker wins over the free-form asset label.
+            label = f"{character.strip()}音色参考"
         values = {
             "order": index,
             "reference": reference_tokens[index - 1] if reference_tokens else str(index),

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

@@ -102,6 +102,8 @@ license: MIT
 - 复杂群戏先锁空间锚点和屏幕方向，再决定景别变化。
 - 起终边界除了逐人姿态，还要写清本镜依赖的身体—物件—空间关系。关系在镜内不变时两端都保留；确需改变时，过程与终点必须有剧本依据。
 - 冻结关键帧只写该瞬间能看见的内容；文字、手指、反射和遮挡要可生成。
+- 近景类关键帧挂着地点板生成时，图片常被拉宽成中远景；正文写具体取景（画面切在哪、脸在画面哪里、机位距离），出图仍偏宽就这一镜不挂地点板，把背景写进正文。
+- 一集的关键帧要像同一部片：每条正文用同一句画风（写实就写写实，不混用「漫剧」「插画」这类会把一部分图拉向插画脸的词），每个场景写同一句光与色温；生成时先出该场景一张中远景作定调图并接受，其余镜头把它作为最后一张参考、只取色调、光线与质感，不取构图。
 - 《视觉设定.md》的连续性锁在生效镜头上原样写进冻结关键帧正文；锁面不因“参考图会交代”而省略。
 - 检查发现遗漏就直接修正文档，不生成覆盖表来证明自己检查过。镜头块里的「视觉依据」是本镜的依据字段，不是这里说的覆盖表。
 

package/lib/drama/skills/short-drama-storyboard/references/production-shot-grammar.md

@@ -54,7 +54,7 @@
 |---|---|
 | 一拍 = 一句台词 + 一个动作 | 若同一镜头目的和边界可承担，可保留一镜；不是等式 |
 | 一拍含多次行动转向或听者后果 | 按议程变化、听者反应与可执行语速拆镜；不使用固定句数/字数配额 |
-| 一拍是爆发动作 | 若单镜过载，可按起势/接触/结果等力学阶段拆，切点绑定精确状态 |
+| 一拍是爆发动作 | 若单镜过载，可按起势/接触/结果等力学阶段拆，切点绑定精确状态；H3 的掌掴/推搡小样本中，掌掴一镜写全更可读，推搡拆成「到接触为止」与「从接触后状态起」才推退人物。H3 可据此先试；其他动作（拉住、带离）或模型须另测，不据此强制拆镜 |
 | 一拍是纯反应/沉默 | 只有承担反应或选择后果时独立成镜；停留由后果与节奏决定 |
 
 **建立镜头要自己挣到位置**。新地点确实可能需要让观众定位人物、入口或冲突区域，但
@@ -261,6 +261,8 @@
 - **单镜成立条件**：路径、接触、道具归属和退路都可读，且已接受时长足以完成。
 - **拆镜条件**：遮挡使钥匙易手不可读，或退到门边需要新的空间边界；切点绑定钥匙
   在谁手中、双方位置和朝向，而不是套“起势—发力—结果”固定链。
+- **拆开后的代价**：两镜各自生成时背景、服装细节和脸型可能漂，前一镜也可能越过接触点才结束。
+  两镜用同一组身份与地点参考，后一镜从已接受的接触后关键帧起，生成后核对切点两侧。
 
 ### 保持不动也可能是有效表演
 

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

@@ -55,6 +55,13 @@ license: MIT
 跟随本镜已解析的视频提示词语言并原样进入正文；正文每个非空行都以 `>` 组成 Markdown 引用块。
 重写内容不能改名、另造替代字段或改成普通段落。
 
+本镜说话的人物要保持音色、且目标模型接受参考音频时，在「输入参考图」下一行加
+`- 参考音频：REF-<slot>（顺序：<n>）· <音频路径>《<中文名称>》（用途：音色；角色：<人物名>；控制：<范围>；不得控制：<范围>）`，
+多条用 `；` 连接（VID-27）。路径照抄该人物在《视觉设定.md》登记的 `- 声音参考：`，角色必须在本镜正文里说出
+《剧本.md》记在其名下的台词，本镜来源场次里别人也说过同一句时，在引文前的分句里点名说话人；
+`不得控制` 至少写 `台词、语气、情绪`（逐项用顿号或逗号分隔，不用「与」连接）。音频的 `顺序` 与图片分开从 1 数，就是正文里的
+`@音频N`、`<Audio N>` 或 `音频N`。音频不进「输入参考图」，分镜也不写这一行。
+
 ## 工作流
 
 1. 先检查每镜「输入参考图」。用户未手工点名图片时，根据本镜冻结关键帧和可见人物、地点、关键道具的一致性需求，在用户输入、

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

@@ -111,6 +111,20 @@
 晚半拍才让路、故意制造噪声掩饰，或看见别人停顿后才理解变化。所有差异都要来自角色立场、
 已接受信息和空间关系。
 
+### H3 反应镜：先点名，再给两处可见泄露（`craft_default`）
+
+目标为 H3、且一镜的职责就是接收一个消息（震惊、被打脸、得意、压怒）时，按这个顺序写：触发 → 一个情绪词点名
+「他立刻震惊」→ 两处当前景别读得到的泄露（目光停住、拇指悬住；笑容停住、手臂收紧）→ 落点并定住。
+反应在触发后一秒半内落下，剩下的时间给落点。
+
+H3 实测四个反应节拍，这种写法盲评清晰度 3.9/5、自然度 4.0/5，四拍全部排第一或并列第一；只写情绪词会演过头
+（强度 4.3、自然度 2.8），把可见反应逐段写满又太弱（强度 1.9），「不动声色的得意」这类反应尤其会被读错。
+情绪词在 H3 这套写法里是给表演定调的锚，不是可删的形容词；链条仍要写，但只写两步。
+
+Seedance 2.5 样片档的同轮对照以逐段可见反应链最好，保留上文完整的触发、处理、可见反应与落点，
+不套用 H3 的两处泄露与 1.5 秒默认；具体见 `seedance-2.5.md`。其他模型沿用可见表演原则并实测，
+这轮证据不支持把 H3 配方外推成通用约束。
+
 只在注意真正交接时，简写“谁/什么拥有注意 → 哪个可见或可听触发 → 注意转给谁/什么”；没有交接
 就不补这一段。交接两端可以是角色、道具、证据、声源或已建立的空间区域；使用它们在
 `视觉设定.md` / `分镜.md` 中的可见 ID，不要为了套人物格式把道具或空间伪装成角色。

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

@@ -30,6 +30,12 @@
   一次生成本身。按当前参考输入检查结果，不把该次观察变成禁用规则。
 - 多镜容器包含切口；一镜到底是连续画面。按叙事目的选择，并保留生成后剪辑的余地。
 
+### 反应镜：保留可见反应链（`craft_default`）
+
+样片档同轮对照里，逐段可见反应链的盲评最好，只写情绪词最差。按触发 → 人物处理 → 当前景别读得到的
+可见反应 → 落点展开，不套用 H3 的「情绪点名＋两处泄露＋1.5 秒内落下」默认。
+仍按角色立场与镜头目的选动作；这是小样本起点，生成后核对可读性与自然度，不保证正式档同样表现。
+
 ### 两端都锚：`用途：起始帧` 与 `用途：结束帧`
 
 接口提供 `first_frame` 与 `last_frame` 两个位置，各自只收一张。
@@ -38,6 +44,9 @@
 按分镜已接受的终点制作尾帧并绑定 `用途：结束帧`；套件内生产入口见
 `$short-drama-storyboard` 的「首尾成对」。未提供尾帧时，在正文中说明终点。
 
+开场构图要锁住时用 `first_frame`，不要只在参考模式里写「@图片1 是开场画面」：样片档实测以上一段真实尾帧
+这样挂成参考，3 次开场与它的相似度只有 0.09–0.46。
+
 两个帧位仍然各占一个图片序号，所以 `@图片N` 的编号按素材出现顺序连续往下数，不跳过它们。
 
 首尾帧与其他参考能否混用，按目标接口核对并验证。H3 的互斥规则不能直接套到 2.5，
@@ -45,14 +54,14 @@
 
 ### 音色参考
 
-目标接口支持 `reference_audio` 时，可用已接受的角色参考音频辅助约束声音。
+目标接口支持 `reference_audio` 时，可用已接受的角色参考音频辅助约束声音：在本镜写一行
+`参考音频`（写法见本技能 SKILL 的字段说明），正文照 `顺序` 写「江晨说话时音色参考 @音频1」。
 参考可以来自预置音色合成或已授权录音，选型由视觉设定记录，生成后回听确认。
+样片档实测：绑一段该角色另一句话的合成做参考，青年角色 6 镜里 5 镜的声音明显靠近参考，中年角色 3 镜没有变化；
+把本句台词的合成挂上去，模型仍重新发声，不会原样播放。所以绑定只是提高命中，逐镜回听不能省。
+
+`输入参考图` 仍只接受图片；音频须单独写在 `参考音频` 字段，不能仅凭正文提到音频就声称已经绑定。
 
-当前 creator-first 的 `输入参考图` 只接受图片，封闭用途表也没有「音色」。
-不要在该字段塞入音频或写 `用途：音色`；这会被校验器拒绝。
-内置 adapter 可处理音频 role，但从五文档准备带音频的 job 尚无完整绑定路径。
-需要该能力时使用已支持音频绑定的外部执行流程，并记录角色、音频来源和实际 role；
-不能仅凭正文提到音频就声称已经绑定。
 
 ## 编辑与延长不是普通参考
 
@@ -63,6 +72,8 @@
   参数必须是 `ratio: adaptive`、`duration: -1`。
 - `extend`：写“在 @视频1 的基础上续写 N 秒”，再从输入视频的实际终点描述唯一动作和新终点；
   API 使用 `ratio: adaptive`。连续创作可另绑实际尾帧为 `@图片1`，只控制新段开场可见状态。
+  实测延长的输出把原段完整带出，接缝处没有跳变，新段人声与原段接近；动作要无缝接下去时优先用延长，
+  而不是另起一段再挂尾帧。
 
 若提示词写的是编辑而 job 标成参考，或反过来，2.5 仍会根据语义复判并报任务类型不匹配；因此任务
 类型是创作选择，不由 adapter 从若干关键词猜。
@@ -90,6 +101,8 @@
   声音时间线末尾直接写“对白直接从指定中文首字开始；不生成外语前导、语气词、额外人声或重复对白”，
   只写一次。没有这些上游边界时不自行追加固定负面后缀。
 - 默认禁字幕时明确写“全程无字幕、无对白文字叠加”，且正文不出现 `【】`；画内获准文字仍独立说明。
+- 手机收到通知这类画面，2.5 常把通知画成浮在画面上的气泡或计数器（实测正式档 2/2），数字还会乱码。
+  写明「通知只在手机屏幕里亮起，画面上不出现浮层」，生成后检查；要显示的数字交给剪辑叠加。
 
 ## 连续容器
 

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

@@ -43,6 +43,7 @@
 | 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. |
 | VID-26 | craft_default | Absent a director's choice, performance intensity follows form and genre. At motion-comic and wish-fulfilment peaks, key poses and expressions go outward—an expression change readable at a glance, whole-arm gestures, emotion carried by the upper body and the whole face—still written as common whole-body actions, never with the plot resting on a micro-expression. AI live action keeps a subtler realism but still gives each peak one readable performance beat. An inferred inner state is not deleted but translated into a visible expression or movement. |
+| VID-27 | structural_invariant | A voice reference is bound on its own `参考音频` line of a `MOTION-...` entry, never inside `输入参考图` and never on a `SHOT-...`. Each slot names a `人物` entry of `视觉设定.md` who speaks in this copyable body a line the screenplay gives that character, points at a readable project audio file equal to the path that character's `声音参考` records, has 用途 `音色`, and numbers audio 顺序 from 1 separately from pictures. Whether the bound voice actually carried into the take is heard after generation, not asserted here. |
 
 ### `CON`
 

package/lib/drama/skills/short-drama-video-prompts/references/target-model-profile.md

@@ -18,6 +18,11 @@
 模型可以由本技能的版本化方言文件提供推荐值。每一条取值都由创作者按自己接入的执行端声明一次，
 本集共用。生产端具体接哪个供应商、用什么字段，属于 `$short-drama-produce` 的 adapter 档案，不进入创作文档。
 
+还没选定 `target_video_model` 时，一组小样本对照（同一起始帧与镜头说明，每类每模型 2 次，盲评排序）可作先试哪个的参考：
+没有一个模型在所有镜头类型上领先。H3 在建立镜推近、多人同框只一人说话时最好；Seedance 2.5 在反应镜、
+走位跟摇、手部插入与夜景情绪近景时最好；Wan 3.0 多数类型居中或靠后；单人对白近景三者持平。
+本集最多的是哪类镜头，就先拿那一类试。
+
 **`craft_default`**： 能力轴是**声明**出来的，不是推断出来的。没有声明就按“未声明时怎么写”写；
 不要因为某个执行端“据说支持”某种写法就改写已接受的镜头边界、时长或起止状态。
 

package/lib/drama/skills/short-drama-video-prompts/references/wan-3.0.md

@@ -66,7 +66,10 @@ Wan 3.0 用中文自然指令，素材写成 `图1`、`视频1`、`音频1`。
   4.6 个可发声字/秒：21 字配 5 秒、41 字配 10 秒都以常速说完。41 字塞进 5 秒仍说完，但赶到
   8.2–8.7 字/秒；66 字塞进 5 秒时只说出前 21–24 字，其余静默丢掉，接口不报错。所以超出容量时
   看不到失败提示，生成后逐字核对台词是否说完。
-- 说话人的声音要跟参考音频走时，写「图1 中的女子说话时，音色参考音频1」；这是官方写法，本套件未实测。
+- 说话人的声音要跟参考音频走时，写「图1 中的女子说话时，音色参考音频1」。实测挂一段该角色另一句话的合成做参考，
+  两个角色 9 镜的声音都明显靠向参考，口型与不挂参考时接近；这是跨镜保持角色音色的默认做法。
+- 把这句台词本身的合成挂成音频1、写「口型与音频1 逐字同步」时，生成的人声几乎就是这段音频，音色最稳；
+  代价是口型略差（句中停住、提前张嘴更常见）。音色必须一致时用它，生成后逐镜看口型。
 - 双人镜里不说话的人按 [对白、口型与声音](camera-audio-continuity.md#精确引用) 的顺序处理；Wan 3.0 的
   小样本太小，写不写「他不说话、嘴唇闭合」没有看出差别。