@oh-story/dsh 0.1.8 → 0.1.10

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

@@ -41,13 +41,21 @@ MAX_ERROR_BODY_BYTES = 64 * 1024
 TERMINAL_FAILURES = {"failed", "cancelled", "canceled", "timeout", "expired"}
 SEEDANCE_RATIOS = {"adaptive", "1:1", "3:4", "4:3", "9:16", "16:9", "21:9"}
 SEEDANCE_REFERENCE_ROLES = {
+    "first_frame": "image_url",
+    "last_frame": "image_url",
     "reference_image": "image_url",
     "reference_video": "video_url",
     "reference_audio": "audio_url",
 }
+# One opening frame and one closing frame, because each names a single position
+# in the take. Note what is deliberately absent: the sibling adapter forbids
+# mixing frame conditioning with reference conditioning, and that rule belongs
+# to that provider's reference, not to this one. Do not carry it across.
+SEEDANCE_SINGULAR_ROLES = {"first_frame", "last_frame"}
 MINIMAX_VIDEO_RATIOS = {"adaptive", "1:1", "3:4", "4:3", "9:16", "16:9", "21:9"}
 MINIMAX_VIDEO_RESOLUTIONS = {"480P", "768P", "2K"}
 MINIMAX_VIDEO_PROMPT_LIMIT = 7000
+MINIMAX_SPEECH_TEXT_LIMIT = 5000
 MINIMAX_VIDEO_ROLES = {
     "first_frame": "image_url",
     "last_frame": "image_url",
@@ -369,10 +377,18 @@ def compile_seedance_payload(
     counters = {"image_url": 0, "video_url": 0, "audio_url": 0}
     labels = {"image_url": "图片", "video_url": "视频", "audio_url": "音频"}
     reference_tokens: list[str] = []
+    singular_seen: set[str] = set()
     for role in reference_roles:
         field = SEEDANCE_REFERENCE_ROLES.get(role)
         if field is None:
             raise ValueError(f"unsupported Seedance reference role: {role}")
+        if role in SEEDANCE_SINGULAR_ROLES:
+            if role in singular_seen:
+                raise ValueError(f"Seedance accepts one {role} reference")
+            singular_seen.add(role)
+        # A frame role still occupies a picture slot, so it keeps counting: the
+        # tokens are positional, and skipping one would point every later
+        # `@图片N` in the prose at the wrong picture.
         counters[field] += 1
         reference_tokens.append(f"@{labels[field]}{counters[field]}")
     if task_type in {"edit", "extend"} and "reference_video" not in reference_roles:
@@ -738,6 +754,82 @@ def compile_gpt_image_2_payload(job: Mapping[str, Any]) -> dict[str, Any]:
     }
 
 
+MINIMAX_SPEECH_EMOTIONS = {
+    "happy", "sad", "angry", "fearful", "disgusted", "surprised", "neutral",
+}
+
+
+def compile_minimax_speech_payload(job: Mapping[str, Any]) -> dict[str, Any]:
+    """Compile a tts job into the official MiniMax speech JSON body.
+
+    The voice catalogue is deliberately not enumerated here. Which preset voices
+    an account can reach depends on the model and the account, no published list
+    is authoritative for both, and a list frozen into this file would either
+    refuse a voice that works or vouch for one that does not. The document owns
+    the value and a reviewer reads it; the adapter only checks its shape.
+    """
+
+    text, parameters = _require_job(job, "tts")
+    parameters = _take(
+        parameters,
+        {"model", "voice_id", "speed", "vol", "pitch", "emotion",
+         "sample_rate", "bitrate", "format"},
+    )
+    model = parameters.pop("model", "")
+    if not isinstance(model, str) or not model.strip():
+        raise ValueError("MiniMax speech model must be explicitly configured")
+    voice_id = parameters.pop("voice_id", "")
+    if not isinstance(voice_id, str) or not voice_id.strip() or voice_id != voice_id.strip():
+        raise ValueError("MiniMax speech requires a confirmed voice_id")
+    if len(text) > MINIMAX_SPEECH_TEXT_LIMIT:
+        raise ValueError("MiniMax speech text exceeds the provider limit")
+
+    target_format = Path(job["outputs"][0]).suffix.casefold().lstrip(".")
+    requested_format = parameters.pop("format", target_format)
+    if requested_format != target_format or requested_format not in {"mp3", "wav"}:
+        raise ValueError("MiniMax output format must match a supported target extension")
+    sample_rate = parameters.pop("sample_rate", 32000)
+    bitrate = parameters.pop("bitrate", 128000)
+    if sample_rate not in {16000, 24000, 32000, 44100}:
+        raise ValueError("unsupported MiniMax sample rate")
+    if bitrate not in {32000, 64000, 128000, 256000}:
+        raise ValueError("unsupported MiniMax bitrate")
+
+    voice_setting: dict[str, Any] = {"voice_id": voice_id}
+    emotion = parameters.pop("emotion", None)
+    if emotion is not None:
+        if emotion not in MINIMAX_SPEECH_EMOTIONS:
+            raise ValueError("unsupported MiniMax speech emotion")
+        voice_setting["emotion"] = emotion
+    for name, low, high in (("speed", 0.5, 2.0), ("vol", 0.1, 10.0)):
+        value = parameters.pop(name, None)
+        if value is None:
+            continue
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise ValueError(f"MiniMax speech {name} must be a number")
+        if not low <= float(value) <= high:
+            raise ValueError(f"MiniMax speech {name} is outside the supported range")
+        voice_setting[name] = float(value)
+    pitch = parameters.pop("pitch", None)
+    if pitch is not None:
+        if isinstance(pitch, bool) or not isinstance(pitch, int) or not -12 <= pitch <= 12:
+            raise ValueError("MiniMax speech pitch is outside the supported range")
+        voice_setting["pitch"] = pitch
+
+    return {
+        "model": model.strip(),
+        "text": text,
+        "stream": False,
+        "output_format": "hex",
+        "voice_setting": voice_setting,
+        "audio_setting": {
+            "sample_rate": sample_rate,
+            "bitrate": bitrate,
+            "format": requested_format,
+        },
+    }
+
+
 def compile_minimax_music_payload(job: Mapping[str, Any]) -> dict[str, Any]:
     """Compile an audio job into the official MiniMax Music 3.0 JSON body."""
     prompt, parameters = _require_job(job, "music")
@@ -1134,8 +1226,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 +1284,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 +1295,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"))
@@ -1328,8 +1464,50 @@ def _run_minimax(job: Mapping[str, Any]) -> tuple[Path, str | None]:
     )
 
 
+def _run_minimax_speech(job: Mapping[str, Any]) -> tuple[Path, str | None]:
+    token = _credential("MINIMAX_API_KEY")
+    body = compile_minimax_speech_payload(job)
+    base = _base_url("MINIMAX_BASE_URL", MINIMAX_BASE_URL)
+    result, _ = _request_json(
+        f"{base}/t2a_v2",
+        provider="minimax-speech",
+        body=body,
+        token=token,
+    )
+    base_resp = result.get("base_resp")
+    if not isinstance(base_resp, Mapping) or base_resp.get("status_code") != 0:
+        raise AdapterFailure(
+            "MiniMax speech synthesis failed",
+            code=_provider_code(result) or "generation_failed",
+            request_id=_safe_token(result.get("trace_id")),
+        )
+    data = result.get("data")
+    audio = data.get("audio") if isinstance(data, Mapping) else None
+    if not isinstance(audio, str) or not audio:
+        raise AdapterFailure(
+            "MiniMax did not return audio data",
+            code="missing_audio",
+            request_id=_safe_token(result.get("trace_id")),
+        )
+    try:
+        content = bytes.fromhex(audio)
+    except ValueError as exc:
+        raise AdapterFailure("MiniMax returned invalid audio data") from exc
+    if not content:
+        raise AdapterFailure("MiniMax returned empty audio data")
+    trace_id = result.get("trace_id")
+    return (
+        _temporary_output(job, job["outputs"][0], content),
+        trace_id if isinstance(trace_id, str) else 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 +1528,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 +1540,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(
@@ -1429,8 +1614,15 @@ def _selftest() -> None:
         "modality": "music", "prompt": "cinematic", "references": [],
         "outputs": ["制作成果/a.mp3"], "parameters": {"lyrics": "[Verse]\nHello"},
     }
+    speech = {
+        "modality": "tts", "prompt": "你们做了多久？", "references": [],
+        "outputs": ["制作成果/a.mp3"],
+        "parameters": {"model": "configured-speech-model", "voice_id": "a-preset"},
+    }
     if compile_gpt_image_2_payload(image)["model"] != OPENAI_MODEL:
         raise RuntimeError("GPT Image 2 self-test failed")
+    if compile_minimax_speech_payload(speech)["voice_setting"]["voice_id"] != "a-preset":
+        raise RuntimeError("MiniMax speech self-test failed")
     seedance = compile_seedance_payload(
         video,
         model="configured-model",
@@ -1498,7 +1690,10 @@ def main() -> int:
     parser.add_argument(
         "provider",
         nargs="?",
-        choices=("seedance", "gpt-image-2", "minimax-music", "minimax-h3"),
+        choices=(
+            "seedance", "gpt-image-2", "minimax-music", "minimax-h3",
+            "minimax-speech",
+        ),
     )
     parser.add_argument("--selftest", action="store_true")
     args = parser.parse_args()
@@ -1516,6 +1711,7 @@ def main() -> int:
             "gpt-image-2": _run_openai,
             "minimax-music": _run_minimax,
             "minimax-h3": _run_minimax_video,
+            "minimax-speech": _run_minimax_speech,
         }
         path, provider_job_id = runners[args.provider](job)
         response: dict[str, Any] = {

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

@@ -71,6 +71,8 @@ license: MIT
 - 剧本对白、动作、声音、画面文字是否都有画面/声音承载；
 - 人物、地点、道具状态和镜头起止是否连续；
 - 提示词是否从准确起点到准确终点；
+- 目标模型画音同轨时，声音内容、时序和发声边界是否与来源一致；无对白镜是否交代底声或静默
+  （`VID-22`、`VID-23`，见 [视觉运动审查表](references/rubric-visual-motion.md)）；
 - 私有输入、凭据、绝对路径或内部流程文字是否泄漏。
 
 缺少必要输入时只停止依赖它的判断，其他问题可以继续汇总。

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

@@ -71,6 +71,13 @@
 - 角色名/资产引用进入台词内文；
 - 音效、环境底噪与对白方向没有来源或相互遮蔽。
 
+目标模型画音同轨时（`VID-23`），检查声音内容、时序、发声边界是否符合来源，
+总结是否错误地引入不存在的声音层。无对白镜也应交代需要的底声或静默。
+H3 无非画内配乐时，`non_diegetic_music: N/A` 是有效的空形式。
+
+按实际遗漏、矛盾与影响报告问题，不因出现 `No dialogue` 或第二个否定句判错，
+不把 H3 的小样本表现套到所有同轨模型上。相关证据指向同一个问题时合并报告。
+
 ### 5. 负面补丁淹没动作
 
 为防止模型缺陷叠加大量禁令，真正的起点、动作、表演与终点被挤成几句。

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

@@ -86,6 +86,16 @@
 - 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 (`VID-22`, `VID-23`), check that actions and sound match the
+source and that the timeline accounts for the intended ambience or silence.
+A summary must not introduce a layer absent from the shot. H3's
+`non_diegetic_music: N/A` is a valid empty music layer.
+
+Report a concrete contradiction, omission or ambiguity. A negative clause is
+not a defect by itself; do not impose a clause count or assume that negation
+causes the model to generate the excluded content. Keep model-specific
+observations scoped to their tested model and execution path.
+
 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

@@ -7,7 +7,8 @@ license: MIT
 # 短剧分镜与冻结关键帧
 
 把剧本和视觉事实转成有镜头职责、空间连续性和可冻结起点的 `剧集/<EP>/分镜.md`。
-每镜使用二级标题 `## SHOT-...`，同镜下用 `### 冻结关键帧提示词` 写起始帧正文。
+每镜使用二级标题 `## SHOT-...`，同镜下用 `### 冻结关键帧提示词` 写起始帧正文；
+需要时另加 `### 收尾关键帧提示词` 写终点正文。
 
 ## Quick Start
 
@@ -49,8 +50,13 @@ license: MIT
    先用已接受集长换成明确时间边界再分镜；例如 60 秒作品的“后半段首次出现”不得早于 30 秒。
 3. 每镜写清唯一职责、来源、时长、景别/机位、起点、唯一主要动作、终点和声音；用
    `起点 → 唯一动作 → 终点` 直接说明人物、双手与持物怎样完成本镜状态转换。三条依据留到第 6 步。
+   有对白、VO 或 OS 时，先按原文和人物说话方式估算完整发声时间，再安排不能重叠的动作、停顿与
+   末尾反应；把估时依据简写在本镜「声音」里。具体做法见 [对白估时](references/shot-craft.md#对白估时)。
 4. 锁定人物朝向、位置、视线、持物、出入口、屏幕方向和必要状态；上游已有会限制动作空间的持续关系时，把关系投影进本镜起点与终点。
 5. 冻结关键帧只投影镜头起点；删除终点才出现的文字、动作、姿态或道具状态。
+   镜头的职责落在收尾那一下时，另写 `### 收尾关键帧提示词` 投影**终点**——同一格画面的
+   另一端，规则完全对称：删除起点才有、终点已经不在的东西。它是可选的，写法与取舍见
+   [首尾成对](references/shot-craft.md#首尾成对)。
 6. 关键帧成稿后，先从成稿正文读出这一格里需要保持身份、造型或地理的人物、地点和道具，
    再用同一份清单一次填满三条依据：
 
@@ -69,6 +75,10 @@ license: MIT
 
 - 每镜有唯一职责、明确来源、可见起止状态和合理时长。「来源」以《剧本.md》里真实存在的场景 ID 开头，
   ID 之后可以跟必要短引文，跨场次的镜头用 `、` 连写多条；`creator_markdown_check.py` 会核对每个 ID 都解析得到。
+- 「来源」短引文应对应本镜承担的动作或声音。正文提到画外人物时，可在视觉依据写
+  `；画外：<类别>「<名称>」`；这只声明其不在画面，不能代替必要动作的落实。
+  需要看见的动作应另有镜头承载，或说明为何省略。
+
 - 剧本里的每个场景都要有镜头承载。确实决定不拍某一场时，在《分镜.md》正文开头写一行
   `- 未拍场次：<场景 ID>（理由：……）`，多项用 `；` 连接。SHT-01 一直允许带理由的省略，
   但省略和漏拍在成稿文档里长得一模一样，所以理由要写下来，而不是留在对话里。
@@ -138,6 +148,7 @@ license: MIT
 - 关键场次比较导演方案：[场次视觉计划](references/scene-visual-plan.md)
 - 检查原文是否都有画面承载：[Coverage Audition](references/coverage-audition.md)
 - 多人、群体和复杂空间调度：[调度手册](references/blocking-playbooks.md)
+- 谁被照亮、怎么写才执行得出：[光的设计](references/lighting-craft.md)
 - 冻结瞬间、注意中心和可读性：[关键帧手艺](references/keyframe-craft.md)
 - 漫剧/二维漫画形态的共享画风词汇：[漫剧关键帧词表](references/comic-keyframe-lexicon.md)
 - 剧本事实到关键帧的完整示例：[剧本到关键帧](references/screenplay-to-keyframe-example.md)

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/lighting-craft.md

@@ -0,0 +1,39 @@
+# 光的设计
+
+## 分工
+
+- 《视觉设定.md》的地点条目记录光源、窗户位置和已经确定的光线状态。
+- 分镜选择本镜的注意中心，说明哪些脸、动作或证据必须可读。
+- 提示词把这些选择写成可观察的画面结果。
+
+开灯、停电和时段变化会改变场景事实，应来自剧本或已接受的视觉设定。
+
+## 按镜头职责设计
+
+先确定观众需要看清什么，再选择亮暗关系、光比与背景分离程度。
+需要读表情时保留相关面部细节；需要隐藏身份时可以用剪影或遮暗。
+关注点可以靠亮度、色彩、轮廓或局部对比突出，不要求它总是全画面最亮的部分。
+
+竖屏按实际构图检查人物与背景是否分得开。近景中的脸部光线、多人纵深中的背景光，
+各自承担不同信息；不要仅按画幅省略环境或默认加轮廓光。
+
+## 把光位与画面效果一起写清
+
+光位术语后补充它在画面上的结果，并明确左右指画面还是人物自身。例如：
+
+> 主光来自画面左侧；画面左侧脸颊较亮，另一侧留柔和阴影，眼睛仍可辨认。
+
+仅写「电影感、氛围感强」不足以决定画面。一次图片模型对照中，描述受光结果比只写
+光位更稳定；这可以作为起步写法，不能据此保证其他模型或视频同样执行。
+暗部深度、边缘亮光和背景亮度按本镜需要写，不把例子中的效果全部照搬。
+
+## 参考板与跨镜连续性
+
+参考板的均匀照明用于看清形制，不自动成为每个镜头的打光方案。
+绑定角色板时说明保留身份与造型；本镜的光仍依据场景事实。
+
+同一连续场景维持光源关系与既定色调；视角、取景范围和人物位置变化可以带来正常的
+画面亮度差异。不要要求所有镜头的平均 RGB 相同。
+
+生成后对比相邻镜头中可比较的脸、衣物或场景表面。曝光和白平衡的小幅偏差交给剪辑
+校正；光源方向或剧情光态错误回上游修订。测量用于定位差异，是否有问题仍结合画面判断。

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

@@ -14,8 +14,12 @@
 3. [场面调度与地理](#场面调度与地理)
 4. [景别与摄影机动机](#景别与摄影机动机)
 5. [时长与切镜](#时长与切镜)
-6. [常见问题](#常见问题)
-7. [审查问题](#审查问题)
+6. [视觉方向选择](#视觉方向选择-sht-07)
+7. [相连边界](#相连边界-con-01)
+8. [首尾成对](#首尾成对)
+9. [一镜到底还是切开](#一镜到底还是切开)
+10. [常见问题](#常见问题)
+11. [审查问题](#审查问题)
 
 ## 先落实原文，再追求画面
 
@@ -65,6 +69,14 @@
 镜头可以负责建立空间、让观众站到某个人物一边、展示证据、暂缓信息、转移权力、
 表现反应，或让后果无法回避。“中景展示人物说话”不算足够的镜头目的。
 
+### 承受者的反应
+
+**`SHT-27 · reviewed_invariant`**：打击、否定或翻盘需要观众理解其后果时，
+分镜应安排可读的承受者反应或其他后果载体。
+可以用独立反应镜、双人镜内的调度、清楚的群像反应、声音或物件状态承载。
+现有画面已经清楚就不必补镜；需要保留反应或承受者不在场时，注明叙事安排。
+审查按后果能否被理解判断，不按人数、景别或反应镜数量判断。
+
 ### 观众可见性 (`SHT-12`)
 
 构图同时决定观众此刻能知道什么。每个事实单独写一条观众可见性判断：绑定准确场景 ID，说明
@@ -124,6 +136,22 @@
 要观众读到什么反而没人回答。判断标准始终是必须被读到的信息存在于哪个尺度——证据在
 指节上就给大特写，后果在两人距离上就不该切近。
 
+### 竖屏把可用的景别收窄了
+
+上面那张表是横平竖直的电影景别谱系。**竖屏不是把它裁窄，是让其中两档变得难用**。
+
+机制很简单：远景和全景靠的是**横向铺开的信息**——谁站在谁旁边、队伍有多长、这个人
+离出口有多远。9:16 的横向只有 16:9 的三分之一强，同样的信息铺进去要么挤成一条，
+要么小到读不出。所以竖屏短剧的实际用法以中景、近景、特写为主，远景与全景出现得少。
+
+但这**不是禁令，是换一种排法**：竖屏的空间要靠**纵深**而不是横向来交代——前景、中景、
+后景分层，用门框、桌沿、台阶、人的前后遮挡把关系立起来（见
+[竖屏多人调度](blocking-playbooks.md#1-竖屏多人调度)）。做到了这一点，竖屏一样能给全景；
+做不到就不要用这一档去承担交代空间的职责，改用一个更近的镜头单独给一次。
+
+**竖屏的横向视野窄，观众的视线本来就被逼到画面中央**，这既是小景别好用的原因，
+也是大景别失效的原因——同一件事的两面。
+
 只有注意或关系发生变化时才改变景别和角度。场面声音变大，不等于镜头必须从全景一路
 推到大特写。反过来，一旦决定切镜，新镜就要在景别、角度或人物关系里至少改变一项；
 相邻两镜完全同景别、同角度、同关系时，这次切镜没有职责，应当改变收放或并回一镜。
@@ -156,6 +184,24 @@
 在变化处切镜：新信息、新目光、新决定、新空间关系、新威胁、新证据或节奏变化。
 不要只为换角度而重复同一个动作。给反应留下足够时间，让观众读懂后果。
 
+### 对白估时
+
+**`craft_default`**：先排完整声音事件，再确定镜长。不要先选一个短镜长，再要求人物加快语速把台词塞进去。
+
+- 有同一句、同语言、同表演方式的录音或配音时，使用实际发声区间；文件首尾静默与句内停顿分开核对，
+  不把整个文件长度当作纯说话时间。没有音频时按原文、人物语速、情绪和换气估一个区间，明确标为
+  「文本估计」，不要声称已实测。项目已校准的语速可以辅助估算；数字、缩写按实际读法考虑，不能只数可见字符。
+- 顺序说话的多句或多人对白累加，句间停顿与听者反应按实际顺序加入。边说边抬眼等确能并行的动作
+  与对白共用时间；必须等话说完才发生的动作另占时间。不要重复计算已包含在录音或估计里的停顿。
+- 在本镜「声音」中简写依据，例如「对白按克制语气文本估计 8–10 秒（含句内停顿）；开口前 0.5 秒，
+  说完后的反应 1 秒；抬眼与对白并行」。此例按估计上沿需要 11.5 秒；若目标是 H3，向上取到 12 秒，
+  余下 0.5 秒安排在已有终点停留。数字只是此例的预算，不是统一余量或官方语速。
+- 取容得下时间线的合法时长；超过模型上限时按语义和可见状态闭合点拆镜，并检查整集总时长。
+  已接受镜长或集长固定且放不下时，说明冲突并提出延长、拆镜或剧本修订；不擅自删词或把正常对白改成快读。
+
+文本估计是规划依据，实际生成后还需听完整性、语速和尾音。没有录音、配音或生成结果时，不把估计写成
+秒级准确的声音控制承诺；纯动作镜无需补对白预算。
+
 ## 视觉方向选择 (`SHT-07`)
 
 焦段语言、节奏、固定机位、手持或形式化调度属于 `taste_option`，读取创作者已接受的
@@ -188,3 +234,33 @@
 - 是否绑定了准确的造型、观察视角、道具状态、双手状态和文字政策？
 - 结束边界是否为下一镜提供清楚的开始状态？
 - 删除或合并本镜，会不会丢失故事意义？
+
+## 首尾成对
+
+终点的可见状态对本镜重要，且目标模型支持尾帧时，可以补写
+`### 收尾关键帧提示词`。它只描述终点，不混入起点或中间动作。
+若起终状态相同，或变化发生在画外，通常无需另做尾帧。
+
+Seedance 2.5 的一个镜头对照中，绑定尾帧改善了末帧落位；这不是所有模型和动作的保证。
+生成后仍检查中间动作、节奏和终点，不能只比较最后一帧。
+
+当前生产工具从 `分镜.md` 的 `SHOT-...` 只提取「冻结关键帧提示词」，即首帧。
+要在套件内生产尾帧，交图片提示词阶段建立单独的 `IMG-...` 条目，注明来自本 SHOT 的
+终点、保留已确认的视觉依据，再以该条目作为 image job 的来源。不得用首帧选择器提交尾帧正文。
+实际图片生成后按目标方言绑定 `用途：结束帧`。
+
+## 一镜到底还是切开
+
+先看这场戏需要什么，再考虑生成与修订成本。
+
+- 连续等待、沉默、空间调度或完整表演，可考虑一镜到底。
+- 需要选择不同表演、突出反应或精确安排切点，可考虑分开生成再剪。
+- 长段生成一处失败可能需要重出更多素材；分开生成则需要额外处理跨镜一致性。
+
+一次 Seedance 2.5 对白场次实测出现过长镜头发声时间过早的问题。
+有严格落点时应检查目标模型的时序能力并试听，不能保证分成镜头就能锁定每句发声时间。
+长镜头也可以在剪辑中截取，是否保留完整时长由叙事决定。
+
+多镜容器是在一次生成里安排多个切口；一镜到底则不切镜。
+容器可减少提交次数，但不自动保证跨镜一致性，也仍可在生成后剪辑。
+各镜合并时重新整理参考素材与编号，并核对结果中的实际切点。

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 understanding a beat requires seeing its effect on a character, provide a readable reaction or consequence. A separate shot, staging within a shared shot, sound, or an object may carry it. Judge legibility against the intended reveal; do not require a shot count or exclude group shots by default. |
 
 ### `CON`
 

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

@@ -74,19 +74,25 @@ license: MIT
    多槽参考与首/尾帧在同一请求内互斥的模型，起始帧也随整组走多槽参考，不拆成两套输入。
 5. 核对本镜时长落在目标模型档案的原生区间内；不在区间内就回到分镜修订，不能写完提示词后留给
    adapter 报错，也不能在正文里暗自改变时长。
+   有对白、VO 或 OS 时，同时核对分镜「声音」中的估时依据与实际可用发声窗口；缺少依据就按
+   [对白预算](references/performance-action-timing.md#对白预算) 补做判断。秒段加总正确不代表台词说得完。
 6. 写不能动的边框：图生视频以参考帧和视觉设定锁定；文生视频把必要静态事实写入「静态视觉锚点」和可复制正文。
 7. 原样读取分镜的「起点 → 唯一动作 → 终点」，确认人物、双手和持物的状态转换都发生在镜内。
 8. 写“静态锚点 → 起点 → 唯一动作（触发、接触、落点）→ 次级反应 → 运镜 → 声音 → 终点”，
    必要时用秒数分段；下一镜从这个终点继续，不另造镜外转换。
 9. 只在真实参考帧已经说明静态外观时删除重复描述；《视觉设定.md》连续性锁的锁面不在可删之列。
-10. 把限制动作空间的已确认关系写成贯穿本镜的正向可见状态，只安排关系允许的动作通道；只有分镜明确改变关系时才写变化过程。可复制正文的动作边界只用肯定状态句，不用 `no/not/without + 动作` 改写。
+10. 把限制动作空间的已确认关系写成贯穿本镜的正向可见状态，只安排关系允许的动作通道；只有分镜明确改变关系时才写变化过程。优先用可见状态说明边界，必要时保留明确的排除条件。
 11. 逐镜读取文字义务。除非剧本或创作者明确要求，正文用本镜已解析的视频提示词语言直接写明任何时刻都不生成非画内字幕、caption 和对白文字叠加，不能只写抽象的“文字层为空”；这条默认与旗帜、标牌、屏幕等画内文字独立。画内 `exact_readable` 逐字写明字符、语言、承载面和位置，不能用全局 `no-text` 覆盖。
 12. 声音同轨时，把允许的发声按来源、说话人、口语语言和顺序写成完整时间线；每句从原文首字到末字，
    且逐字对白在单镜可复制正文中只出现一次。视觉动作段只按时间和说话人引用该声音事件，不再抄一遍
    台词。事件外回到已声明的环境声或静默。Brief、剧本或声音方向已经明确禁止外语前导、语气词、
    额外人声或重复时，把这些**已确认的发声边界**在完整时间线末尾合并写一次；不靠“只包含”让执行端
-   猜，也不自行扩充新的禁用类别。完整时间线声明是声音段落终点，其后不再追加第二组声音排除句。
-13. 成稿时逐句把 `no/not/without + 动作或状态变化` 改写为当前持续状态或允许动作；直接改正文，不调用工具或生成检查产物。再检查不跨下一镜、不要求互斥动作、不让人物或道具瞬移变形。
+猜，也不自行扩充新的禁用类别。时间线总结只列本镜实际有的声音层。
+   无对白镜写清底声或静默及其覆盖区间；嘴部动作按剧本表演，不默认强制闭嘴。
+   非画内配乐按目标方言声明，有需要时明确写空。
+13. 成稿时检查动作、声音和限制条件是否清楚且相容。正面状态有助于表达目标，必要的否定条件
+   可以保留；不按否定句数量判错。确认不跨下一镜、不要求互斥动作、不让人物或道具瞬移变形。
+
 14. 用户要整集就完成整集，镜头组只是内部批次。
 15. 同一连续时空中相邻正式生成段、且目标档案支持续接时，默认选择“从上一段生成结果续接”；
     一镜一生成只决定每次装一个镜头，不等于各镜独立文生。只有创作者明确要求独立重生成，或上游
@@ -107,11 +113,12 @@ license: MIT
 - 运镜与人物动作不争夺注意力；复杂运镜必须有叙事理由。
 - 声音只写该镜需要的对白、画外音、环境或转场职责，不擅自补歌词。
 - 非画内字幕、caption 和对白文字叠加默认不生成；正文直接声明全镜任何时刻都不生成这些内容，不用抽象工作流术语代替执行指令。只有剧本或创作者明确要求才开启。画内精确文字是独立允许集合，不因关闭字幕而消失，也不让未批准文字混入。
-- 同轨对白/VO/OS 同时写逐字文本、口语语言和发声边界；完整时间线闭合后，不再枚举不存在的语言、语气或声源，也不追加 `no/not/without + 声音类别`。
+- 同轨对白/VO/OS 同时写逐字文本、口语语言和发声边界；不添加来源没有的声源或重复限制。
+- 无对白镜同样说明底声或静默；时间线总结与实际声音层一致。H3 无非画内配乐时写 `non_diegetic_music: N/A`。
 - 正文里被引号或 `<d>` 包起来的中文必须逐字来自《剧本.md》，画内标牌文字可来自《视觉设定.md》；
   分镜自己写下的画内文字与声音同样算数。`creator_markdown_check.py` 会核对四字以上的引文（VID-25）。
   台词不在剧本里就回到写作技能改剧本，不在提示词里改。
-- 上游持续关系只用贯穿状态和允许动作通道表达；不以 `no/not/without + 动作` 重复同一边界，也不给角色冲突动作。
+- 上游持续关系用贯穿状态和允许动作通道表达，避免重复限制或冲突动作。
 - 本镜命中的连续性锁，锁面原样出现在可复制正文里；颜色、材质、形制这类跨镜不变事实不靠模型记忆。
 - 正文可直接复制，不含占位符、流程说明、文件路径或 QA 结论。
 

package/lib/drama/skills/short-drama-video-prompts/references/camera-audio-continuity.md

@@ -80,6 +80,23 @@ Camera behavior 要回答“观众注意为什么在此刻改变”。常见动
 
 这里不是同时 lock 和 move。若 transition 改变 shot 已接受的 camera design，仍需 storyboard 同意。
 
+### 摄影机与主体的相对运动
+
+主体快跑与摄影机缓推可以同时成立，关键是写清两者的相对关系与画面结果。
+需要跟随时说明跟随方向和构图；需要人物离开画面时，保留缓推或固定机位也可以。
+不能为了消除速度差异而改写上游已确定的运镜。
+
+### 运动说明
+
+按本镜需要说明运动方式、方向、速度或触发时机、终点以及要保持的空间关系。
+与上一节的起点和落点一起核对，不要求每次恰好四项。
+
+### 运镜术语属于方言
+
+推轨、变焦、摇、甩、升降这些词在不同目标模型里的解析并不一致——有的模型的官方指南
+推荐 `push in` 而完全不收录 `dolly in`。**不要把一个模型上验证过的运镜词表照搬到另一个
+模型的正文里**；术语与写法以目标模型的方言文档为准，方言里没有记载的词按未验证对待。
+
 ### 非冲突但可能过载
 
 pan 同时微调焦点、handheld 带自然呼吸、dolly 配合轻微 tilt 未必矛盾；是否太复杂由 reviewer 结合 purpose 判断，不能靠 camera 动词计数硬挡。