@oh-story/dsh 0.1.8 → 0.1.9

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

@@ -29,6 +29,13 @@ profile above explicitly permits their values, then sent as the API's top-level
 `generate_audio` is a boolean. The broad compiler envelope remains configurable rather than proving
 that every Seedance release supports every value.
 
+The compiler also forwards `duration: -1` without applying the positive-integer range. For ordinary
+Seedance 2.0/2.5 generation this asks the model to choose within its native range; for 2.5 `edit` it
+preserves the source video's duration instead. The adapter does not estimate spoken dialogue or
+lengthen a short job. Fixed-duration delivery needs an explicit accepted duration; auto-duration
+output needs its actual media length and speech checked before timing is accepted. The API response's
+integer `duration` rounds down the frame-based duration, so it is not a precise media measurement.
+
 `compile_seedance_payload` accepts explicit `reference_image`, `reference_video`, and
 `reference_audio` roles with matching HTTPS, `asset://` or base64 data URI values. It emits the matching multimodal
 content type and uses `@图片N`、`@视频N`、`@音频N` in its appended reference contract. The bundled

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

@@ -27,8 +27,22 @@ PNG = base64.b64decode(
 def main() -> int:
     parser = argparse.ArgumentParser()
     parser.add_argument("--fail", action="store_true")
+    # A real video provider bills at submission and can be interrupted at any
+    # point afterwards. `--submit-then-fail` reproduces exactly that: record the
+    # handle the way a live adapter does, then die before returning anything.
+    parser.add_argument("--submit-then-fail", action="store_true")
     args = parser.parse_args()
     job = json.load(sys.stdin.buffer)
+    collecting = job.get("collect_provider_job_id")
+    if args.submit_then_fail and not collecting:
+        destination = job.get("handle_path")
+        if isinstance(destination, str) and destination:
+            path = Path(destination)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(
+                json.dumps({"provider_job_id": "fixture-task-1"}), encoding="utf-8"
+            )
+        return 7
     if args.fail:
         return 7
     directory_raw = job.get("output_root")
@@ -52,7 +66,10 @@ def main() -> int:
                 handle.setframerate(8000)
                 handle.writeframes(struct.pack("<h", 0) * 80)
         outputs.append({"target": target, "source": str(path)})
-    json.dump({"outputs": outputs, "provider_job_id": "fixture-local"}, sys.stdout)
+    response = {"outputs": outputs, "provider_job_id": "fixture-local"}
+    if isinstance(collecting, str) and collecting:
+        response["provider_job_id"] = collecting
+    json.dump(response, sys.stdout)
     return 0
 
 

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

@@ -1547,6 +1547,37 @@ def _active_run(root: Path, job_id: str) -> dict[str, Any] | None:
     return running[-1] if running else None
 
 
+def _read_provider_handle(root: Path, job_id: str, run_id: str) -> str | None:
+    """The provider job id an adapter recorded before it started polling.
+
+    A video task is billed the moment it is submitted, not when it is collected.
+    If the adapter is then interrupted — killed, disconnected, the machine
+    sleeps — the run record would otherwise say `running` with no way back to a
+    task that is alive and already paid for, and the only move left is to submit
+    (and pay) again. The adapter writes the id here as soon as it has one, into
+    project metadata rather than the attempt's temporary directory, so it
+    outlives the process that created it.
+    """
+
+    try:
+        document = _metadata_read_json(
+            root, ("handles", _job_key(job_id)), f"{run_id}.json",
+            maximum=MAX_RUN_RECORD_BYTES,
+        )
+    except (FileNotFoundError, ValueError, json.JSONDecodeError):
+        return None
+    if not isinstance(document, Mapping):
+        return None
+    value = document.get("provider_job_id")
+    if isinstance(value, str) and 0 < len(value) <= 200:
+        return value
+    return None
+
+
+def _handle_metadata_path(root: Path, job_id: str, run_id: str) -> Path:
+    return root / PRODUCTION_ROOT / "handles" / _job_key(job_id) / f"{run_id}.json"
+
+
 def _write_run(root: Path, job_id: str, run: Mapping[str, Any]) -> None:
     _metadata_atomic_json(
         root,
@@ -1620,6 +1651,9 @@ def run_job(root: Path, *, job_id: str, adapter_config: Path) -> dict[str, Any]:
                 "run_id": run_id,
                 "project_root": str(snapshot_root),
                 "output_root": str(output_root),
+                # Where to record the provider job id the instant it exists, so
+                # an interrupted attempt can be collected instead of re-billed.
+                "handle_path": str(_handle_metadata_path(root, job_id, run_id)),
             }
         )
         try:
@@ -1640,11 +1674,20 @@ def run_job(root: Path, *, job_id: str, adapter_config: Path) -> dict[str, Any]:
                             "sha256": digest,
                         }
                     )
+                if _run_status(root, job_id, run_id) == "succeeded":
+                    # `collect` reached the same provider task first and its
+                    # outputs are already in the project. Leave that record
+                    # alone rather than replacing a collected attempt.
+                    raise RuntimeError(
+                        "这次尝试已经被 collect 取回并标为成功；本次运行不覆盖它"
+                    )
                 run["status"] = "succeeded"
                 run["finished_at"] = utc_now()
                 run["outputs"] = written
-                provider_job_id = response.get("provider_job_id")
-                if isinstance(provider_job_id, str) and len(provider_job_id) <= 200:
+                provider_job_id = response.get("provider_job_id") or _read_provider_handle(
+                    root, job_id, run_id
+                )
+                if isinstance(provider_job_id, str) and 0 < len(provider_job_id) <= 200:
                     run["provider_job_id"] = provider_job_id
                 _write_run(root, job_id, run)
         except Exception as exc:
@@ -1653,6 +1696,12 @@ def run_job(root: Path, *, job_id: str, adapter_config: Path) -> dict[str, Any]:
                 run["finished_at"] = utc_now()
                 if isinstance(exc, AdapterError) and exc.public_error is not None:
                     run["error"] = exc.public_error
+                # A timeout or a killed adapter does not cancel the provider's
+                # task. Carry the handle onto the failed record so `audit` can
+                # say "collect this" instead of the creator paying twice.
+                orphan = _read_provider_handle(root, job_id, run_id)
+                if orphan is not None:
+                    run["provider_job_id"] = orphan
                 _write_run(root, job_id, run)
             raise
     return {
@@ -1663,6 +1712,101 @@ def run_job(root: Path, *, job_id: str, adapter_config: Path) -> dict[str, Any]:
     }
 
 
+def _run_status(root: Path, job_id: str, run_id: str) -> str | None:
+    """The status one attempt currently has on disk, re-read rather than cached."""
+
+    for run in _read_run_history(root, job_id):
+        if str(run.get("run_id")) == run_id:
+            status = run.get("status")
+            return status if isinstance(status, str) else None
+    return None
+
+
+def collect_job(root: Path, *, job_id: str, adapter_config: Path) -> dict[str, Any]:
+    """Collect an already-submitted task's result without submitting a new one.
+
+    This is deliberately outside the confirmation gate. The gate exists to stop
+    an unintended charge; collecting costs nothing, because the charge already
+    happened when the task was submitted. Requiring a fresh confirmation here
+    would mean the cheapest way out of an interrupted attempt is to pay again,
+    which is exactly the outcome the gate is meant to prevent.
+    """
+
+    root = find_project(root)
+    with tempfile.TemporaryDirectory(prefix="short-drama-collect-") as directory:
+        output_root = Path(directory) / "outputs"
+        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)
+            target_run = None
+            for run in reversed(_read_run_history(root, job_id)):
+                if run.get("status") == "succeeded":
+                    continue
+                handle = run.get("provider_job_id") or _read_provider_handle(
+                    root, job_id, str(run["run_id"])
+                )
+                if handle:
+                    target_run = (run, handle)
+                    break
+            if target_run is None:
+                raise RuntimeError(
+                    "no unfinished attempt of this job carries a provider job id; "
+                    "there is nothing to collect"
+                )
+            run, provider_job_id = target_run
+
+        payload = {key: job[key] for key in ALLOWED_JOB_KEYS if key in job}
+        payload.update(
+            {
+                "run_id": str(run["run_id"]),
+                "output_root": str(output_root),
+                "collect_provider_job_id": provider_job_id,
+            }
+        )
+        response = _run_adapter(command, timeout, payload, root)
+        adapter_outputs = _validate_adapter_outputs(job, response, output_root)
+        written: list[dict[str, Any]] = []
+        with _project_lock(root):
+            # A live `run_job` on the same provider task is indistinguishable
+            # from a dead one — both sit at `running`. Re-read before writing,
+            # or two writers race onto the same bytes and one record is lost.
+            if _run_status(root, job_id, str(run["run_id"])) == "succeeded":
+                raise RuntimeError(
+                    "这次尝试在取回期间已经自己完成了，产物已经落进项目；"
+                    "没有覆盖它——先看 status，确认无误就不需要再做别的"
+                )
+            for target_name, source in adapter_outputs:
+                target = _project_file(root, target_name, create_parent=True)
+                digest, size = _copy_output(
+                    source, target, overwrite=bool(job["overwrite"])
+                )
+                written.append(
+                    {
+                        "path": target_name,
+                        "media_type": MEDIA_TYPES[PurePosixPath(target_name).suffix.casefold()],
+                        "bytes": size,
+                        "sha256": digest,
+                    }
+                )
+            collected = dict(run)
+            collected["status"] = "succeeded"
+            collected["finished_at"] = utc_now()
+            collected["outputs"] = written
+            collected["provider_job_id"] = provider_job_id
+            collected["collected"] = True
+            collected.pop("error", None)
+            _write_run(root, job_id, collected)
+    return {
+        "job_id": job_id,
+        "run_id": str(run["run_id"]),
+        "state": "succeeded",
+        "collected": True,
+        "provider_job_id": provider_job_id,
+        "outputs": written,
+    }
+
+
 def job_status(root: Path, *, job_id: str) -> dict[str, Any]:
     root = find_project(root)
     job = _read_job(root, job_id)
@@ -1816,6 +1960,28 @@ def audit_project(root: Path) -> dict[str, Any]:
         attempts_failed += sum(run["status"] == "failed" for run in completed)
         attempts_running += len(running)
         attempts_superseded += len(history) - len(current)
+        for run in current:
+            if run.get("status") == "succeeded":
+                continue
+            handle = run.get("provider_job_id") or _read_provider_handle(
+                root, job_id, str(run["run_id"])
+            )
+            if not handle:
+                continue
+            problems.append(
+                {
+                    "code": "orphaned_provider_job",
+                    "job_id": job_id,
+                    "run_id": run["run_id"],
+                    "provider_job_id": handle,
+                    "action": "collect_before_retry",
+                    # A live attempt and a dead one both sit at `running`, so
+                    # this finding cannot tell them apart. Collecting is still
+                    # the right first move — it is the only one that costs
+                    # nothing — and it refuses safely if the attempt finished.
+                    "note": "status 为 running 时它可能仍在正常轮询；collect 会先确认再写",
+                }
+            )
         if running:
             running_jobs += 1
             for run in running:
@@ -1986,6 +2152,13 @@ def build_parser() -> argparse.ArgumentParser:
     run.add_argument("project")
     run.add_argument("--job-id", required=True)
     run.add_argument("--adapter-config", required=True)
+    collect = commands.add_parser(
+        "collect",
+        help="Fetch the result of an already-submitted provider task without paying again.",
+    )
+    collect.add_argument("project")
+    collect.add_argument("--job-id", required=True)
+    collect.add_argument("--adapter-config", required=True)
     status = commands.add_parser("status", help="Show one media job state.")
     status.add_argument("project")
     status.add_argument("--job-id", required=True)
@@ -2011,6 +2184,12 @@ def main(argv: list[str] | None = None) -> int:
                 job_id=args.job_id,
                 adapter_config=Path(args.adapter_config),
             )
+        elif args.command == "collect":
+            result = collect_job(
+                Path(args.project),
+                job_id=args.job_id,
+                adapter_config=Path(args.adapter_config),
+            )
         elif args.command == "status":
             result = job_status(Path(args.project), job_id=args.job_id)
         else:

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

@@ -1134,8 +1134,45 @@ def _download(
     return path
 
 
+def _record_handle(job: Mapping[str, Any], provider_job_id: str) -> None:
+    """Write the provider task id where the caller can find it after a crash.
+
+    A video task is billed at submission. Everything after that — polling,
+    downloading — can be interrupted, and without this the caller is left with a
+    live, already-paid task it has no id for. Written before the first poll, and
+    deliberately best-effort: failing to record the handle must not fail a task
+    that was submitted successfully.
+    """
+
+    destination = job.get("handle_path")
+    if not isinstance(destination, str) or not destination:
+        return
+    try:
+        path = Path(destination)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+        temporary.write_text(
+            json.dumps({"provider_job_id": provider_job_id}, ensure_ascii=True),
+            encoding="utf-8",
+        )
+        temporary.replace(path)
+    except OSError:
+        return
+
+
+def _collect_target(job: Mapping[str, Any]) -> str | None:
+    value = job.get("collect_provider_job_id")
+    if isinstance(value, str) and value:
+        return value
+    return None
+
+
 def _run_seedance(job: Mapping[str, Any]) -> tuple[Path, str]:
     token = _credential("ARK_API_KEY")
+    base = _base_url("SEEDANCE_BASE_URL", SEEDANCE_BASE_URL)
+    collecting = _collect_target(job)
+    if collecting is not None:
+        return _poll_seedance(job, base=base, token=token, task_id=collecting)
     model = os.environ.get("SEEDANCE_MODEL", "")
     references = _reference_paths(job)
     reference_roles = (
@@ -1155,7 +1192,6 @@ def _run_seedance(job: Mapping[str, Any]) -> tuple[Path, str]:
         allowed_ratios=allowed_ratios,
         duration_range=duration_range,
     )
-    base = _base_url("SEEDANCE_BASE_URL", SEEDANCE_BASE_URL)
     created, _ = _request_json(
         f"{base}/contents/generations/tasks",
         provider="seedance",
@@ -1167,6 +1203,14 @@ def _run_seedance(job: Mapping[str, Any]) -> tuple[Path, str]:
         raise AdapterFailure(
             "Seedance did not return a task id", code="missing_task_id"
         )
+    # Billed from here on. Record the id before the first poll.
+    _record_handle(job, task_id)
+    return _poll_seedance(job, base=base, token=token, task_id=task_id)
+
+
+def _poll_seedance(
+    job: Mapping[str, Any], *, base: str, token: str, task_id: str
+) -> tuple[Path, str]:
     try:
         interval = float(os.environ.get("SEEDANCE_POLL_INTERVAL", "5"))
         deadline = time.monotonic() + float(os.environ.get("SEEDANCE_TIMEOUT_SECONDS", "1800"))
@@ -1330,6 +1374,10 @@ def _run_minimax(job: Mapping[str, Any]) -> tuple[Path, str | None]:
 
 def _run_minimax_video(job: Mapping[str, Any]) -> tuple[Path, str]:
     token = _credential("MINIMAX_API_KEY")
+    base = _base_url("MINIMAX_VIDEO_BASE_URL", MINIMAX_VIDEO_BASE_URL)
+    collecting = _collect_target(job)
+    if collecting is not None:
+        return _poll_minimax_video(job, base=base, token=token, task_id=collecting)
     model = os.environ.get("MINIMAX_VIDEO_MODEL", "")
     references = _reference_paths(job)
     reference_roles = (
@@ -1350,7 +1398,6 @@ def _run_minimax_video(job: Mapping[str, Any]) -> tuple[Path, str]:
         allowed_resolutions=resolutions,
         duration_range=duration_range,
     )
-    base = _base_url("MINIMAX_VIDEO_BASE_URL", MINIMAX_VIDEO_BASE_URL)
     created, _ = _request_json(
         f"{base}/video_generation",
         provider="minimax-h3",
@@ -1363,6 +1410,14 @@ def _run_minimax_video(job: Mapping[str, Any]) -> tuple[Path, str]:
             "MiniMax did not return a task id",
             code=_provider_code(created) or "missing_task_id",
         )
+    # Billed from here on. Record the id before the first poll.
+    _record_handle(job, task_id)
+    return _poll_minimax_video(job, base=base, token=token, task_id=task_id)
+
+
+def _poll_minimax_video(
+    job: Mapping[str, Any], *, base: str, token: str, task_id: str
+) -> tuple[Path, str]:
     try:
         interval = float(os.environ.get("MINIMAX_VIDEO_POLL_INTERVAL", "5"))
         deadline = time.monotonic() + float(

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

@@ -71,6 +71,9 @@ license: MIT
 - 剧本对白、动作、声音、画面文字是否都有画面/声音承载；
 - 人物、地点、道具状态和镜头起止是否连续；
 - 提示词是否从准确起点到准确终点；
+- 目标模型画音同轨时，可复制正文的声音段是否写成正面闭合事件集：无对白镜不靠 `No dialogue`、
+  `无对白` 关闭语音通道，完整性声明也不枚举本镜没有的层（`VID-22`、`VID-23`，见
+  [视觉运动审查表](references/rubric-visual-motion.md)）；
 - 私有输入、凭据、绝对路径或内部流程文字是否泄漏。
 
 缺少必要输入时只停止依赖它的判断，其他问题可以继续汇总。

package/lib/drama/skills/short-drama-review/references/production-quality-gates.md

@@ -71,6 +71,26 @@
 - 角色名/资产引用进入台词内文；
 - 音效、环境底噪与对白方向没有来源或相互遮蔽。
 
+目标模型画音同轨时（`VID-23`），这一节多四条只在同轨条件下成立的核对。四条里只有配乐那条
+有实测后果，其余三条是「正文要如实、完整地交代本镜声音」，按这个理由报，不要替它们编一套
+生成机制：
+
+- **配乐层在正文里整个缺席**（实测有后果）：写了空形式（H3 为 `non_diegetic_music: N/A`）的
+  14 次生成没有一次自带配乐，完全不提配乐的 3 次里 2 次返回了自造配乐。这一条按 major 起报。
+  **空形式本身就是合规写法**：`non_diegetic_music: N/A` 是「本镜没有非画内配乐」的正面陈述，
+  不是待填占位符。只有整行不存在时才报，永远不要要求 owner 删掉已经写好的空形式；
+- 用排除句代替声轨描述：正文出现 `No dialogue`、`无对白` 而没有正面写出这条声轨由什么组成、
+  覆盖多长——问题在于正文没交代本镜该有什么声音，不在于"否定会招来它"；
+- 完整性声明枚举了本镜没有的层：无对白镜写出
+  `The audio timeline is complete after the listed ambience, effects and timed dialogue.`
+  是一句与本镜事实不符的话；
+- 无对白镜从没说清声轨**是什么**：既没有覆盖全时长的底声构成，也没给在场人物一个可见的
+  不说话状态（嘴唇闭合）。
+
+中间两条同时出现时按一个 finding 报，证据引这两句话本身：它们互相矛盾，本身就是声音契约
+没写清。修订要求写成正面声轨，不能是"再加一句不要对白"。本套件实测未观察到这组写法导致
+模型补出台词，报 finding 时不要这样断言。
+
 ### 5. 负面补丁淹没动作
 
 为防止模型缺陷叠加大量禁令，真正的起点、动作、表演与终点被挤成几句。

package/lib/drama/skills/short-drama-review/references/rubric-visual-motion.md

@@ -86,6 +86,42 @@
 - Does each media reference state its exact purpose, what may be copied, and what
   must not be copied, rather than treating all visible pixels as authority?
 
+For a copyable body, ask these separately — they are the two rules a rewrite regresses on
+most often, because a body that reads "complete" can still carry both defects. Findings here
+are about whether the body states this shot's sound and text truthfully and completely; only
+the music-layer item below has a measured generation consequence behind it:
+
+- Does the body carry only what will be filmed (`VID-22`)? Negative action intent must
+  already be rewritten as a visible positive state. The one permitted negation is the
+  no-subtitle/caption/dialogue-overlay declaration; a second exclusion clause is a defect,
+  not extra safety. (The often-repeated reason — that a noun inside a negation gets
+  rendered — did not reproduce in this suite's probes, so cite the body's own clarity,
+  not that mechanism, when you raise this.)
+- When the target model generates audio in the same pass (`VID-23`), is the sound written
+  as a closed positive event set — what the track consists of, and across what span —
+  rather than a list of what must not be heard? Check three failures by name:
+  - an exclusion clause (`No dialogue`, `无对白`, `no music`) standing in for a positive
+    soundscape, so the body never says what this shot sounds like;
+  - a completeness declaration that enumerates a layer this shot does not have. "The audio
+    timeline is complete after the listed ambience, effects and timed dialogue" on a shot
+    with no lines states something untrue of this shot. Read the declaration against the
+    shot's actual layers, not against a template;
+  - a shot that leaves the non-diegetic music layer unstated. This is the one sound defect
+    with measured consequences: bodies that omitted the layer came back with an invented
+    score. **The dialect's empty form satisfies this** — for H3 that is the literal line
+    `non_diegetic_music: N/A`, which is a correct statement of "no non-diegetic music",
+    not a placeholder. Raise this only when the layer is missing from the body altogether;
+    never ask an owner to delete a present empty form;
+  - a shot with no lines whose body never says what the track *is* for the full duration,
+    and never gives the on-screen performers a visible non-speaking state.
+  Report a contradictory pair — an exclusion clause plus a declaration that enumerates the
+  excluded layer — as one finding against the body's sound contract, and quote both
+  sentences. Raise it as an internally inconsistent sound contract, which it is; do not
+  assert that it makes the model invent lines, which this suite has probed and not seen.
+
+These two apply to a body the review itself is about to ask an owner to rewrite. A revision
+request that removes a defect by adding `no ...` has moved the defect, not fixed it.
+
 For a pickup or alternate, ask these separately:
 
 - Does the pickup/alternate name its master by visible `MOTION-...` heading?

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

@@ -49,6 +49,8 @@ license: MIT
    先用已接受集长换成明确时间边界再分镜；例如 60 秒作品的“后半段首次出现”不得早于 30 秒。
 3. 每镜写清唯一职责、来源、时长、景别/机位、起点、唯一主要动作、终点和声音；用
    `起点 → 唯一动作 → 终点` 直接说明人物、双手与持物怎样完成本镜状态转换。三条依据留到第 6 步。
+   有对白、VO 或 OS 时，先按原文和人物说话方式估算完整发声时间，再安排不能重叠的动作、停顿与
+   末尾反应；把估时依据简写在本镜「声音」里。具体做法见 [对白估时](references/shot-craft.md#对白估时)。
 4. 锁定人物朝向、位置、视线、持物、出入口、屏幕方向和必要状态；上游已有会限制动作空间的持续关系时，把关系投影进本镜起点与终点。
 5. 冻结关键帧只投影镜头起点；删除终点才出现的文字、动作、姿态或道具状态。
 6. 关键帧成稿后，先从成稿正文读出这一格里需要保持身份、造型或地理的人物、地点和道具，
@@ -69,6 +71,11 @@ license: MIT
 
 - 每镜有唯一职责、明确来源、可见起止状态和合理时长。「来源」以《剧本.md》里真实存在的场景 ID 开头，
   ID 之后可以跟必要短引文，跨场次的镜头用 `、` 连写多条；`creator_markdown_check.py` 会核对每个 ID 都解析得到。
+- **引文是认领，不是背景。** 「来源」里引了哪一句，就等于说这一镜负责拍它。引一个本镜画面里
+  根本没有的人做的动作——把「另一个人低头去翻自己的稿子」写进一个只拍某一个人的特写——
+  那个动作就从所有人的清单上消失了：没有别的镜头认领它，也没有任何一步报它缺失，
+  于是它根本不会被拍出来，而这个缺口只有等人看完成片、问「他的反应呢」才浮出来。
+  确实看不见就在「视觉依据」末尾写 `；画外：<类别>「<名称>」`，机械核对认这个写法。
 - 剧本里的每个场景都要有镜头承载。确实决定不拍某一场时，在《分镜.md》正文开头写一行
   `- 未拍场次：<场景 ID>（理由：……）`，多项用 `；` 连接。SHT-01 一直允许带理由的省略，
   但省略和漏拍在成稿文档里长得一模一样，所以理由要写下来，而不是留在对话里。

package/lib/drama/skills/short-drama-storyboard/assets/keyframe-prompts.md

@@ -4,6 +4,10 @@
 每次导出都记下配方版本；文本被手改时，先预览恢复、
 采用或合并的结果。
 
+**这份模板属于结构化管线**（`keyframes.jsonl` 一路）。creator-first 项目的《分镜.md》骨架
+以 `SKILL.md` 为准：`## SHOT-... · 中文名`，关键帧正文标题是 `### 冻结关键帧提示词`。
+不要把这里的加粗字段名、`KEY-...` 或 `### 可复制通用提示词` 搬进 creator-first 文档。
+
 ```markdown
 # EP<编号> · 冻结关键帧提示词
 

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

@@ -65,6 +65,27 @@
 镜头可以负责建立空间、让观众站到某个人物一边、展示证据、暂缓信息、转移权力、
 表现反应，或让后果无法回避。“中景展示人物说话”不算足够的镜头目的。
 
+### 承受者也要有一镜
+
+一次打击、否定、揭穿或翻盘，画面上有两个人：**说出它的人，和挨了它的人**。
+只拍前者，观众收到的是一句评价；拍了后者，观众才收到一次事件。
+
+这不是「多给一个反应镜头会更好」的锦上添花。剧情上被推翻的那个人如果全程只有后脑、
+只在群像里占几十个像素，观众其实不知道该看谁输——那句最狠的台词就只是一个人在说话，
+爽点不成立。**分镜阶段就要决定谁承受这一下、哪一镜给他**，不要留给剪辑去补，
+因为剪辑只能在已经生成的素材里选，选不出一个没拍过的反应。
+
+具体到写法：
+
+- 台词落点是针对某个在场的人时，检查分镜里有没有一镜的画面主体是**那个人**；
+- 没有就补一镜，通常很短（一到两秒足够：停手、抬眼、想开口又闭嘴）；
+- 承受者不在场时，那一下的后果要落到别的可见东西上（屏幕、门、被推开的文件），
+  否则这次打击在画面上没有发生过；
+- 群像镜头**不算**承受者反应：一张在四个人里的脸承担不了「他输了」这件事。
+
+**这条只在剧情确实存在承受者时生效。** 不为每句台词配反应镜头，也不把它变成正反打配额——
+安静的场次、独角戏、纯信息交代不适用。
+
 ### 观众可见性 (`SHT-12`)
 
 构图同时决定观众此刻能知道什么。每个事实单独写一条观众可见性判断：绑定准确场景 ID，说明
@@ -156,6 +177,24 @@
 在变化处切镜：新信息、新目光、新决定、新空间关系、新威胁、新证据或节奏变化。
 不要只为换角度而重复同一个动作。给反应留下足够时间，让观众读懂后果。
 
+### 对白估时
+
+**`craft_default`**：先排完整声音事件，再确定镜长。不要先选一个短镜长，再要求人物加快语速把台词塞进去。
+
+- 有同一句、同语言、同表演方式的录音或配音时，使用实际发声区间；文件首尾静默与句内停顿分开核对，
+  不把整个文件长度当作纯说话时间。没有音频时按原文、人物语速、情绪和换气估一个区间，明确标为
+  「文本估计」，不要声称已实测。项目已校准的语速可以辅助估算；数字、缩写按实际读法考虑，不能只数可见字符。
+- 顺序说话的多句或多人对白累加，句间停顿与听者反应按实际顺序加入。边说边抬眼等确能并行的动作
+  与对白共用时间；必须等话说完才发生的动作另占时间。不要重复计算已包含在录音或估计里的停顿。
+- 在本镜「声音」中简写依据，例如「对白按克制语气文本估计 8–10 秒（含句内停顿）；开口前 0.5 秒，
+  说完后的反应 1 秒；抬眼与对白并行」。此例按估计上沿需要 11.5 秒；若目标是 H3，向上取到 12 秒，
+  余下 0.5 秒安排在已有终点停留。数字只是此例的预算，不是统一余量或官方语速。
+- 取容得下时间线的合法时长；超过模型上限时按语义和可见状态闭合点拆镜，并检查整集总时长。
+  已接受镜长或集长固定且放不下时，说明冲突并提出延长、拆镜或剧本修订；不擅自删词或把正常对白改成快读。
+
+文本估计是规划依据，实际生成后还需听完整性、语速和尾音。没有录音、配音或生成结果时，不把估计写成
+秒级准确的声音控制承诺；纯动作镜无需补对白预算。
+
 ## 视觉方向选择 (`SHT-07`)
 
 焦段语言、节奏、固定机位、手持或形式化调度属于 `taste_option`，读取创作者已接受的

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

@@ -37,6 +37,8 @@
 | SHT-23 | structural_invariant | An omitted reference choice is not consent to text-to-video. After reference discovery, each shot either binds all verified real images as `REF-...`, declares creator-supplied pictures as `PLAN-...` slots that locate an existing `IMG-...` board or `SHOT-...` keyframe, preserves partial bindings while naming the still-missing start/identity/geography/prop images, or records the creator's explicit text-to-video choice. A prompt entry, plausible filename, or text description never counts as a real image, and a `PLAN-...` slot never claims one: it states that the picture is supplied outside the project at generation time, which is why it cannot be sent to production. |
 | SHT-24 | reviewed_invariant | A visual basis describes this frame, not the episode's cast list. Each declared 控制 scope stays within what this frame can carry, and a binding is not carried forward merely because the subject remains in the scene. |
 | SHT-25 | structural_invariant | Every real reference image a shot binds declares one 用途 from the closed set 身份/造型状态/地理/构图/尺度/效果/起始帧/结束帧/风格, so the shot can say which start frame and which identity/geography/prop pictures a downstream job sends. At most one 起始帧 and one 结束帧 per shot, and 结束帧 requires 起始帧. |
+| SHT-26 | structural_invariant | A shot's 来源 is its claim on the screenplay: whatever it quotes, this shot is the one that films it. Every 视觉设定 entry the quote calls by name is therefore either in this shot's 视觉依据 or declared 画外 there. Quoting an action performed by someone the frame never shows takes that action off every list — no other shot claims it and nothing reports it missing, so it simply never gets filmed, and the gap only surfaces when a person watches the finished film. The check matches entry names rather than 画面代称, because a 来源 quote comes from 剧本.md; an entry that opted out with `画面代称：无` stays out of this check too. |
+| SHT-27 | reviewed_invariant | When a beat lands on a present character — a reversal, a rebuttal, an exposure, a decision that overrules someone — some shot takes that person as its subject. Filming only the speaker delivers a remark; filming the one it lands on delivers an event, and an audience that cannot see who lost does not experience the turn. A group shot does not count: one face among four cannot carry it. Editing cannot supply this later, because editing chooses among shots that exist. Inactive where no one is on the receiving end — quiet scenes, solo work, and plain exposition are not owed a reaction shot, and this is not a shot-reverse-shot quota. |
 
 ### `CON`
 

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

@@ -74,6 +74,8 @@ license: MIT
    多槽参考与首/尾帧在同一请求内互斥的模型，起始帧也随整组走多槽参考，不拆成两套输入。
 5. 核对本镜时长落在目标模型档案的原生区间内；不在区间内就回到分镜修订，不能写完提示词后留给
    adapter 报错，也不能在正文里暗自改变时长。
+   有对白、VO 或 OS 时，同时核对分镜「声音」中的估时依据与实际可用发声窗口；缺少依据就按
+   [对白预算](references/performance-action-timing.md#对白预算) 补做判断。秒段加总正确不代表台词说得完。
 6. 写不能动的边框：图生视频以参考帧和视觉设定锁定；文生视频把必要静态事实写入「静态视觉锚点」和可复制正文。
 7. 原样读取分镜的「起点 → 唯一动作 → 终点」，确认人物、双手和持物的状态转换都发生在镜内。
 8. 写“静态锚点 → 起点 → 唯一动作（触发、接触、落点）→ 次级反应 → 运镜 → 声音 → 终点”，
@@ -85,7 +87,10 @@ license: MIT
    且逐字对白在单镜可复制正文中只出现一次。视觉动作段只按时间和说话人引用该声音事件，不再抄一遍
    台词。事件外回到已声明的环境声或静默。Brief、剧本或声音方向已经明确禁止外语前导、语气词、
    额外人声或重复时，把这些**已确认的发声边界**在完整时间线末尾合并写一次；不靠“只包含”让执行端
-   猜，也不自行扩充新的禁用类别。完整时间线声明是声音段落终点，其后不再追加第二组声音排除句。
+   猜，也不自行扩充新的禁用类别。完整时间线声明是声音段落终点，其后不再追加第二组声音排除句，
+   且只列本镜实际有的声音层。本镜没有对白时，这条声明里不出现 dialogue，正文也不写 `no dialogue`、
+   `无对白` 这类排除句，改为正面写出底声的构成与覆盖区间，并把「不说话」写成在场人物的可见状态：
+   正面句同时交代了这一镜该有什么声音。配乐层则必须显式关掉，那一条有实测支撑。
 13. 成稿时逐句把 `no/not/without + 动作或状态变化` 改写为当前持续状态或允许动作；直接改正文，不调用工具或生成检查产物。再检查不跨下一镜、不要求互斥动作、不让人物或道具瞬移变形。
 14. 用户要整集就完成整集，镜头组只是内部批次。
 15. 同一连续时空中相邻正式生成段、且目标档案支持续接时，默认选择“从上一段生成结果续接”；
@@ -108,6 +113,7 @@ license: MIT
 - 声音只写该镜需要的对白、画外音、环境或转场职责，不擅自补歌词。
 - 非画内字幕、caption 和对白文字叠加默认不生成；正文直接声明全镜任何时刻都不生成这些内容，不用抽象工作流术语代替执行指令。只有剧本或创作者明确要求才开启。画内精确文字是独立允许集合，不因关闭字幕而消失，也不让未批准文字混入。
 - 同轨对白/VO/OS 同时写逐字文本、口语语言和发声边界；完整时间线闭合后，不再枚举不存在的语言、语气或声源，也不追加 `no/not/without + 声音类别`。
+- 同轨模型下的无对白镜同样要写满声音段：正面写出底声的构成与覆盖区间，把「不说话」写成在场人物的可见状态，完整性声明只列本镜实际有的层，不枚举 dialogue。非画内配乐层显式写空（H3 为 `non_diegetic_music: N/A`）——不写配乐层实测会被模型补上，语音层未观察到同样现象。
 - 正文里被引号或 `<d>` 包起来的中文必须逐字来自《剧本.md》，画内标牌文字可来自《视觉设定.md》；
   分镜自己写下的画内文字与声音同样算数。`creator_markdown_check.py` 会核对四字以上的引文（VID-25）。
   台词不在剧本里就回到写作技能改剧本，不在提示词里改。