@lemoncat7/dsh-partner 2.4.2 → 2.7.0

package/resources/skills/drama-production/upstream/skills/short-drama-write/references/stage-contract.md

@@ -0,0 +1,36 @@
+# 剧本阶段契约
+
+本阶段只拥有 `剧集/<EP>/剧本.md`：场景、动作、对白、画外音、声音事实、画面文字、连续性提示与转场。
+它继承项目/分集决定，但不决定人物视觉身份、镜头构图、提示词或媒体生产。
+
+所有来源都用文档中可见的集号与场景 ID 定位；不建立第二份节拍、block、审批或状态文件。格式标签
+只负责区分生产语义，不借格式补造剧情。输入明确给出的事实、必须/禁止、题材观看契约与退出状态优先于本表；规则不能补造题面没有的精确数字、记录、资源、程序或机关。
+
+## 本阶段规则
+
+### `SCR`
+
+| ID | Class | Knowledge |
+|---|---|---|
+| SCR-01 | reviewed_invariant | When a scene is organized around active pursuit or conflict, it has a current agenda, opposing force, directional turn, and exit state. A traceable fact, leverage change, cost, authority, or choice makes the prior strategy fail; an opponent's unexplained silence, inaction, or departure does not substitute for the turn. Atmospheric, ritual, montage, transition, and consequence-processing scenes may instead justify themselves through a necessary change in knowledge, relationship, pressure, rhythm, or production state; they must not manufacture an opponent merely to satisfy this rule. |
+| SCR-02 | craft_default | Prefer choices and consequences over coincidence for major turns. |
+| SCR-03 | reviewed_invariant | Private thought is expressed through behavior, evidence, or deliberate VO/OS. |
+| SCR-04 | craft_default | Dialogue carries agenda, relationship, subtext, and a change—not only information. |
+| SCR-05 | structural_invariant | Existing production tags use supported, closed syntax and resolvable references. A continuity tag records a state established by shown action; it cannot establish that an unseen event or contact never occurred. |
+| SCR-06 | taste_option | Silence, slang, interruption, narration, and sentence rhythm remain character/style choices. |
+| SCR-07 | reviewed_invariant | Story-critical text, VO/OS, SFX, transition, and continuity requirements are not left indistinguishable from ordinary prose. |
+| SCR-08 | craft_default | When abstract emotion obscures performance, translate it into character-specific behavior, object handling, distance, silence, or delivery. Dialogue turn length and tactic follow the scene agenda rather than a universal attack-defense cadence. |
+| SCR-09 | craft_default | Break a long speech with a visible action beat that changes the speaker's tactic, giving downstream a sourced cut point and the performance a breath; a speech with no internal turn is shortened rather than split. |
+| SCR-10 | reviewed_invariant | When the creator marks a beat's realization as replaceable under later pressure, the record separates the dramatic function from the current depiction and names a fallback depiction that delivers the same function: same person proven or changed, downstream payoff refs and next-episode entry state still satisfied, cost not erased, no new setup required. Deleting the beat is never a fallback. An unmarked beat leaves the rule inactive—the suite carries no platform standard, predicts no outcome, and pre-emptive sanding is the more expensive mistake. |
+| SCR-11 | craft_default | When sound carries story information, spatial pressure, off-screen presence, a deliberate silence, or a scene bridge, the screenplay identifies the necessary source/event and its dramatic target; it does not prescribe per-shot mixing, add decorative sound to every scene, or use music to replace performance. |
+| SCR-12 | craft_default | A crowded scene first makes clear who is contending with whom—by cutting non-essential presence, staggering entrances, splitting the scene so one opponent holds the focus at a time, or handing attention from one character to the next—rather than naming every present character in action paragraphs. Deliberately chaotic ritual, siege, or farce may override this once the disorder is a visible choice and one followable thread remains. |
+| SCR-13 | reviewed_invariant | When a beat is framed as a consequential choice, at least two executable values remain live until the character acts, and the screenplay makes the relevant stakes and newly caused cost perceptible. This rule is inactive for ordinary decisions, habits, or single-path pursuits; it must not manufacture a dilemma the episode does not need. |
+| SCR-14 | reviewed_invariant | When a belief change hinges on contested evidence, the conclusion stays within what the evidence and any shown test support. If that evidence is a primary episode engine, at least one audience-followable state change changes which explanations remain live or changes the next action; routine photographing, bagging, numbering, or logging does not count by itself. The scene may test the strongest live counter-explanation, preserve uncertainty, or intentionally delay verification; this rule does not require a forensic procedure for uncontested facts, comic misunderstanding, subjective narration, or clues whose ambiguity is the point. |
+| SCR-15 | craft_default | A local payoff leaves a legible result or aftereffect without replacing the episode's meaning with a slogan. A cost framed as central pressure has a material exit-state effect rather than automatically resetting once the action succeeds. The result may be plot change, relationship response, irony, stillness, tonal afterimage, or an intentionally open state; a new external event is not mandatory. |
+| SCR-16 | reviewed_invariant | When a literal precise deadline is foregrounded and audience-auditable, its action chain fits the stated time and established resources, or the screenplay makes compression, failure, or a changed objective legible. Qualitative urgency is not upgraded into invented minutes, timestamps, notifications, or records. Montage, ellipsis, subjective time, and declared stylization follow their own established convention rather than an automatic real-time test. |
+| SCR-17 | reviewed_invariant | When the brief defines a limited number of attempts, turns, breaths, beats, or other units, each unit is counted by its visible end-state. A label, count, request, authorization, preparation step, or cleanup after the boundary does not substitute for the required completion; intentional partial completion or failure remains valid when it is the legible result of that unit. |
+| SCR-18 | craft_default | An action paragraph does not open with a noun phrase followed by a full-width colon. `第二格：一只手把杯子推过去。` is byte-for-byte the dialogue form `角色名：台词`, so the indexer can only return `ambiguous_dialogue_or_action` and hand it back for a human read; every such line costs one round trip for nothing. A dash, a comma, or a verb removes the collision. Colons inside a sentence are unaffected — only the start of the line collides. |
+
+规则分级由高到低：`structural_invariant`（结构缺陷，阻断）、
+`reviewed_invariant`（需证据判断）、`craft_default`（常用做法，可覆盖）、
+`taste_option`（创作者选择，不作缺陷）。创作者已接受的事实优先于本表。

package/resources/skills/drama-production/upstream/skills/short-drama-write/references/substitutable-realization.md

@@ -0,0 +1,107 @@
+# 可替换实现：让「要改」的时候改的是实现方式，不是戏
+
+## 目录
+
+- [这条规则不做什么](#这条规则不做什么)
+- [真正的失效形状](#真正的失效形状)
+- [功能与实现分开写](#功能与实现分开写)
+- [什么样的备选算数](#什么样的备选算数)
+- [哪些位置值得看一眼](#哪些位置值得看一眼)
+- [两种更常见的错误做法](#两种更常见的错误做法)
+- [合成示例](#合成示例)
+- [自检](#自检)
+
+## 这条规则不做什么
+
+**本套件不内置任何平台的审核标准，不预测任何内容能否通过，也不给出题材禁令**。
+标准随平台、地区、时间和分发方式变化，写进技能只会同时做到两件坏事：过时，以及把
+创作者本可以拍的东西提前劝退。
+
+它只做一件事：当某个兑现**只有一种实现方式**、而这种实现方式后来必须更换时，让更换
+发生在**实现层**而不是**戏剧层**。要不要标、标哪些，由创作者判断；套件负责的是——
+标了之后，改动是有备而来的。
+
+## 真正的失效形状
+
+昂贵的返工不是「某个镜头被要求换掉」，而是**换掉它之后这集不成立了**。
+
+具体过程：某个兑现依赖一个特定呈现（一件证物上的字、一次身体接触的力度、一个场所的
+性质、一段自白的具体内容）。这个呈现被下游一路消费——资产变体按它建、关键帧按它冻结、
+运动规格按它写、相邻集的进入状态按它接。等到必须更换时，能改的只剩最后一环，于是
+唯一可行的操作变成**把这场删了**。删掉之后，它承担的功能没有别处兑现，前面所有铺垫
+变成空转。
+
+改动窗口的关键性质是**它会关闭**：呈现刚写下时替换成本接近零，被下游消费之后成本
+指数上升。所以标注要发生在剧本层，事后补标没有意义。
+
+## 功能与实现分开写
+
+标注一个节拍时，把三件事分开：
+
+| 字段 | 回答什么 | 常见错误 |
+|---|---|---|
+| 功能 | 这个节拍在故事里**兑现了什么**：谁的什么被证明、谁的处境如何改变 | 写成情绪词（"高潮""爽点"），无法据此判断备选是否等价 |
+| 当前实现 | 现在**用什么呈现**兑现它 | 与功能混写成一句，导致换实现就得换功能 |
+| 备选实现 | 换一种呈现，**同样兑现该功能** | 写成"改温和些"，这是削弱不是替换 |
+
+分开写本身就有诊断价值：如果一个节拍的功能写不出来，问题不在合规，在这个节拍本来
+就没兑现什么。
+
+## 什么样的备选算数
+
+备选必须**兑现同一个功能**，判据是：
+
+1. **同一个人被证明或被改变**。换了受影响的人，就是另一个节拍。
+2. **后续依赖仍然成立**。看这个节拍的 `payoff_refs` 与下一集的进入状态：备选执行后，
+   它们是否仍然被满足？有一条落空就不是备选。
+3. **代价没有消失**。兑现通常带着代价（暴露、失去、欠下）。备选把代价抹掉时，后面的
+   压力也就没了来源。
+4. **不需要新的铺垫**。备选如果要求一个前面没建立的事实，它不是备选，是改稿。
+
+**「删掉这场」永远不是备选**——删除消掉的正是功能本身。可接受的写法是把功能移交给
+另一个已经存在的节拍，并写清移交后那个节拍要多承担什么。
+
+## 哪些位置值得看一眼
+
+按**机制**看，不按题材看。以下三种结构最容易在更换时连累戏剧层：
+
+- **兑现与呈现焊死**：这个兑现只有这一种拍法。焊死本身不是缺点（很多好戏正是如此），
+  但它意味着一旦要换就是重写，所以值得提前写下备选。
+- **风险在链条上游**：被标注的呈现是后面多个节拍的依据。上游改一处，下游全线要重接，
+  此时备选必须连带说明下游怎么接。
+- **窗口即将关闭**：该呈现马上要进入资产、关键帧或运动规格。这是最后一次低成本标注的
+  机会；再往后标注只剩记录价值。
+
+## 两种更常见的错误做法
+
+**提前自我阉割**。 把所有可能敏感的地方统一磨平。代价是确定的（戏没了），收益是不确定的
+（并不针对任何具体标准）。短剧的兑现本来就建立在越界、失衡和代价上，统一磨平之后剩下的
+是一集没有人会看完的合格品。标注的意义恰恰是**保住当前实现**——先按最想要的拍法写，
+备选只在真的需要时启用。
+
+**假备选**。 备选栏写"视情况调整""改得含蓄一点""删减部分内容"。这类写法在需要时提供不了
+任何可执行的东西，等于没标。备选必须具体到能直接改写成场景动作。
+
+## 合成示例
+
+（虚构情境：社区食堂的排班员被指控偷改排班。）
+
+- **功能**：证明排班员确实改过记录，且是为保护一个不能公开的人；她的可信度与她的动机
+  同时暴露。
+- **当前实现**：她当众把手写排班本摊开，指出被涂改的那一行，说出被保护者的名字。
+- **备选实现**：她把排班本交给指控者本人翻，指控者读到那一行时停住不念——名字由**反应**
+  交代而不由台词交代。功能相同：改动被证明、动机被暴露、可信度同时受损；被保护者的
+  身份仍然进入后续依赖，只是载体从台词换成了他人的反应。
+- **不算备选**：把这场改成她私下解释（受影响的人变了，公开暴露的代价消失）；把这场
+  删掉（功能无处兑现）。
+
+## 自检
+
+只在创作者标注过的节拍上执行；未标注时本节不生效，也不要因为没标注而提缺陷。
+
+1. 功能是否写成了「谁的什么被证明或被改变」，而不是情绪词？
+2. 备选执行后，本节拍的 `payoff_refs` 与下一集进入状态是否仍然成立？
+3. 代价是否仍在？还是被备选一起抹掉了？
+4. 备选是否需要一个前面没有建立的事实？
+5. 备选是否具体到可以直接写成场景动作，而不是一句"酌情处理"？
+6. 这个呈现是否已经被下游消费？若是，标注只剩记录价值，替换要走修订请求。

package/resources/skills/drama-production/upstream/skills/short-drama-write/scripts/duration_estimate.py

@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+"""Estimate how long a screenplay runs, using the project's own declared rates.
+
+This reports a number; it never judges one. The suite carries no cross-project
+speech rate and no tolerance band, because a 90-second episode of dense argument
+and a 90-second episode of silent work do not convert at the same ratio. The
+creator declares the two rates their project actually uses, and this script
+applies them.
+
+Without declared rates the script still counts dialogue characters and action
+paragraphs -- those counts are facts about the text -- and says the seconds
+cannot be derived yet. That is the honest output, not a guess from a default.
+
+What counts as a line and what counts as a paragraph is decided by
+``screenplay-index.jsonl``, never re-derived here. This script used to carry its
+own reader of the screenplay format, and a second reader of one format is a
+second set of answers: it timed ``[VO]`` at zero, billed a Markdown comment as
+speech, read ``他写下两个字：军宣。`` as dialogue because of the colon, and
+counted one multi-line action paragraph once per line. The index already
+classifies all four correctly. Reading it means this script cannot disagree with
+the artifact the rest of the pipeline cites.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+
+# Creators run these scripts on whatever interpreter their machine provides, so
+# an unsupported version must say so instead of failing inside an import.
+MINIMUM_PYTHON = (3, 9)
+if sys.version_info < MINIMUM_PYTHON:
+    raise SystemExit(
+        "short-drama needs Python {}.{} or newer; this interpreter is {}.{}".format(
+            *MINIMUM_PYTHON, sys.version_info.major, sys.version_info.minor
+        )
+    )
+
+
+# [VO] and [OS] are spoken off-camera. The format contract writes them as
+# ``[VO] 角色：台词`` -- a real line. Timing them at zero silently shortens every
+# episode that carries its interiority in voice-over, and the estimate then reads
+# as a deficit the writer pads to fill.
+VOICED_TAGS = {"VO", "OS"}
+VOICE_TAG_PREFIX = re.compile(r"^\[(?:VO|OS)\]\s*")
+# ``角色（提示）：台词`` -- the speaker label may carry a parenthesised direction.
+# Only the spoken half is timed; the direction is a note to the performer.
+DIALOGUE = re.compile(r"^(?P<who>[^：:（(\[\]]{1,24})(?:（[^）]*）|\([^)]*\))?[：:](?P<line>.+)$")
+
+
+class StaleIndex(Exception):
+    """The index does not describe the screenplay it was handed."""
+
+
+def _spoken_characters(line: str) -> int:
+    """Count what is actually voiced: no whitespace, no bracketed directions."""
+    stripped = re.sub(r"（[^）]*）|\([^)]*\)", "", line)
+    return len(re.sub(r"\s", "", stripped))
+
+
+def _is_voiced(block: Mapping[str, Any]) -> bool:
+    """Speech is a dialogue block, or a production tag that is spoken aloud."""
+    kind = block.get("kind")
+    if kind == "dialogue":
+        return True
+    return kind == "production_tag" and block.get("tag") in VOICED_TAGS
+
+
+def _block_text(screenplay: bytes, block: Mapping[str, Any]) -> str | None:
+    """Return the block's own bytes, or None when its span does not fit."""
+    start, end = block.get("byte_start"), block.get("byte_end")
+    if (
+        not isinstance(start, int)
+        or not isinstance(end, int)
+        or not 0 <= start < end <= len(screenplay)
+    ):
+        return None
+    try:
+        return screenplay[start:end].decode("utf-8").strip()
+    except UnicodeDecodeError:
+        # A span that begins or ends mid-character is a stale offset, not a
+        # crash: report it the same way as any other span that does not fit.
+        return None
+
+
+def measure(screenplay: bytes, blocks: Iterable[Mapping[str, Any]]) -> dict[str, Any]:
+    """Count the timed material, taking every classification from the index."""
+    dialogue_lines = 0
+    dialogue_characters = 0
+    action_paragraphs = 0
+    tag_lines = 0
+    unreadable_blocks: list[str] = []
+
+    for block in blocks:
+        if block.get("record_type") != "block":
+            continue
+        kind = block.get("kind")
+
+        if kind == "action":
+            # One paragraph is one block however many lines it occupies. The
+            # format contract lets an action paragraph run several lines.
+            action_paragraphs += 1
+            continue
+
+        if not _is_voiced(block):
+            # Scene headings, comments and instruction-only tags carry no
+            # performed duration. Comments are not production content at all.
+            if kind == "production_tag":
+                tag_lines += 1
+            continue
+
+        text = _block_text(screenplay, block)
+        if text is None:
+            unreadable_blocks.append(str(block.get("block_id")))
+            continue
+        spoken = DIALOGUE.match(VOICE_TAG_PREFIX.sub("", text))
+        if spoken is None:
+            # The index recorded it as speech but it does not use the documented
+            # line grammar. Guessing a duration here is how a wrong number gets
+            # reported as a fact; the block is named instead.
+            unreadable_blocks.append(str(block.get("block_id")))
+            continue
+        dialogue_lines += 1
+        dialogue_characters += _spoken_characters(spoken.group("line"))
+
+    counts: dict[str, Any] = {
+        "dialogue_lines": dialogue_lines,
+        "dialogue_characters": dialogue_characters,
+        "action_paragraphs": action_paragraphs,
+        "production_tag_lines": tag_lines,
+    }
+    if unreadable_blocks:
+        counts["unreadable_blocks"] = sorted(unreadable_blocks)
+    return counts
+
+
+def index_blocks(
+    index: list[dict[str, Any]], screenplay: bytes
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    """Return the index's blocks and its own review state.
+
+    An index built from other bytes is refused rather than measured: its spans
+    would land on text it never classified.
+    """
+    meta = next(
+        (row for row in index if row.get("record_type") == "screenplay_index_meta"),
+        None,
+    )
+    if meta is None:
+        raise StaleIndex("the index carries no screenplay_index_meta record")
+    declared = meta.get("source_byte_length")
+    if not isinstance(declared, int):
+        raise StaleIndex("the index declares no source_byte_length")
+    if declared != len(screenplay):
+        raise StaleIndex(
+            "the index was built from {} bytes but this screenplay is {}; "
+            "rebuild it with screenplay_index.py before estimating".format(
+                declared, len(screenplay)
+            )
+        )
+    review = {
+        "review_status": meta.get("review_status"),
+        "source_issue_count": meta.get("source_issue_count"),
+    }
+    return [row for row in index if row.get("record_type") == "block"], review
+
+
+def declared_rates(project: dict[str, Any] | None) -> dict[str, Any]:
+    """Read the project's own pacing rates, or report that it declared none."""
+    pacing = ((project or {}).get("format") or {}).get("pacing") or {}
+    per_second = pacing.get("spoken_characters_per_second")
+    per_action = pacing.get("seconds_per_action_paragraph")
+    usable = isinstance(per_second, (int, float)) and per_second > 0 and (
+        isinstance(per_action, (int, float)) and per_action >= 0
+    )
+    return {
+        "declared": bool(usable),
+        "spoken_characters_per_second": per_second if usable else None,
+        "seconds_per_action_paragraph": per_action if usable else None,
+    }
+
+
+def estimate(
+    screenplay: bytes,
+    blocks: Iterable[Mapping[str, Any]],
+    project: dict[str, Any] | None = None,
+    review: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    counts = measure(screenplay, blocks)
+    rates = declared_rates(project)
+    target = ((project or {}).get("format") or {}).get("target_seconds_per_episode")
+
+    result: dict[str, Any] = {"counts": counts, "rates": rates, "seconds": None}
+    result["target_seconds"] = target if isinstance(target, (int, float)) else None
+
+    # Material the index could not classify is material this estimate did not
+    # time. Reporting the seconds without that fact is how an incomplete number
+    # gets read as a complete one.
+    issues = (review or {}).get("source_issue_count")
+    unreadable = counts.get("unreadable_blocks") or []
+    if isinstance(issues, int) and issues > 0 or unreadable:
+        result["incomplete"] = {
+            "index_review_status": (review or {}).get("review_status"),
+            "source_issue_count": issues,
+            "unreadable_blocks": unreadable,
+            "note": (
+                "the index left some of this screenplay unclassified, so the "
+                "counts below cover less than the whole text; resolve the index "
+                "issues before reading these seconds as the episode's length"
+            ),
+        }
+
+    if not rates["declared"]:
+        result["note"] = (
+            "the project declares no format.pacing rates, so seconds cannot be "
+            "derived; the counts above are still exact"
+            if "incomplete" not in result
+            else "the project declares no format.pacing rates, so seconds "
+            "cannot be derived; the counts above are exact for the blocks the "
+            "index classified, which is not all of this screenplay"
+        )
+        return result
+
+    seconds = (
+        counts["dialogue_characters"] / rates["spoken_characters_per_second"]
+        + counts["action_paragraphs"] * rates["seconds_per_action_paragraph"]
+    )
+    result["seconds"] = round(seconds, 1)
+    if result["target_seconds"]:
+        delta = seconds - result["target_seconds"]
+        result["delta_seconds"] = round(delta, 1)
+        result["delta_ratio"] = round(delta / result["target_seconds"], 3)
+        result["note"] = (
+            "informational only: the suite sets no tolerance band, because the "
+            "right spread depends on the project's own scenes"
+        )
+    else:
+        result["note"] = (
+            "no format.target_seconds_per_episode is declared, so there is "
+            "nothing to compare the estimate against"
+        )
+    return result
+
+
+def _load_jsonl(path: Path) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        if not line.strip():
+            continue
+        try:
+            row = json.loads(line)
+        except json.JSONDecodeError as error:
+            raise SystemExit("{}:{}: {}".format(path, number, error))
+        if isinstance(row, dict):
+            rows.append(row)
+    return rows
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Estimate screenplay duration from the project's declared rates."
+    )
+    parser.add_argument("screenplay", type=Path)
+    parser.add_argument(
+        "--index",
+        type=Path,
+        required=True,
+        help="screenplay-index.jsonl built from this screenplay by screenplay_index.py",
+    )
+    parser.add_argument(
+        "--project",
+        type=Path,
+        default=None,
+        help="short-drama.json carrying format.pacing and target_seconds_per_episode",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.screenplay.is_file():
+        raise SystemExit("screenplay not found: {}".format(args.screenplay))
+    if not args.index.is_file():
+        raise SystemExit("screenplay index not found: {}".format(args.index))
+
+    project = None
+    if args.project is not None:
+        if not args.project.is_file():
+            raise SystemExit("project file not found: {}".format(args.project))
+        project = json.loads(args.project.read_text(encoding="utf-8"))
+
+    screenplay = args.screenplay.read_bytes()
+    try:
+        blocks, review = index_blocks(_load_jsonl(args.index), screenplay)
+    except StaleIndex as error:
+        raise SystemExit("{}: {}".format(args.index, error))
+
+    report = estimate(screenplay, blocks, project, review)
+    print(json.dumps(report, ensure_ascii=True, indent=2, sort_keys=True))
+    # An estimate is never a verdict, so this exits successfully even when the
+    # episode lands far from its target. Blocking here would turn a reported
+    # number into the cross-project threshold this suite refuses to carry.
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())