@lemoncat7/dsh-partner 2.4.2 → 2.7.0

package/resources/skills/drama-production/upstream/skills/short-drama-video-prompts/scripts/music_spec_check.py

@@ -0,0 +1,327 @@
+#!/usr/bin/env python3
+"""Validate provider-neutral, timeline-level short-drama music specs."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import re
+import sys
+from pathlib import Path
+from typing import Any, NamedTuple
+
+MINIMUM_PYTHON = (3, 9)
+if sys.version_info < MINIMUM_PYTHON:
+    raise SystemExit("music_spec_check.py requires Python 3.9 or newer")
+
+
+# ---------------------------------------------------------------------------
+# REFERENCE RESOLVER
+#
+# Each skill carries its own copy of this block. A skill must stay runnable
+# after copying only its own directory, so the suite has no shared library and
+# this file imports nothing from outside its own skill.
+# ---------------------------------------------------------------------------
+
+SOURCES_RECORD_TYPE = "sources"
+SOURCES_SCHEMA_VERSION = "1.0.0"
+
+
+class ResolvedRef(NamedTuple):
+    """An upstream reference with its snapshot resolved, whichever form it used."""
+
+    owner: str
+    artifact: str
+    record_id: str | None
+    field: str | None
+    authority: str | None
+
+
+class RefFinding(NamedTuple):
+    """A structural defect in a reference object."""
+
+    code: str
+    location: str
+    detail: str
+
+
+def load_sources(document: Any) -> dict[str, dict[str, Any]]:
+    """Return the ``sources`` declaration of a parsed file, or ``{}`` if absent.
+
+    Accepts a parsed ``.json`` document (a dict) or the parsed record list of a
+    ``.jsonl`` file, whose declaration lives on the first record.
+    """
+    if isinstance(document, list):
+        document = document[0] if document else None
+    if not isinstance(document, dict):
+        return {}
+    declared = document.get("sources")
+    if not isinstance(declared, dict):
+        return {}
+    return {key: value for key, value in declared.items() if isinstance(value, dict)}
+
+
+def resolve_ref(
+    ref: Any, sources: dict[str, dict[str, Any]], location: str
+) -> tuple[ResolvedRef | None, RefFinding | None]:
+    """Resolve a reference object written in either the compact or expanded form."""
+    if not isinstance(ref, dict):
+        return None, RefFinding("REF_IS_NOT_AN_OBJECT", location, f"got {type(ref).__name__}")
+    src = ref.get("src")
+    if isinstance(src, str):
+        entry = sources.get(src)
+        if entry is None:
+            return None, RefFinding(
+                "REF_SRC_IS_NOT_DECLARED", location, f"src {src!r} has no sources entry"
+            )
+        owner, artifact = entry.get("owner"), entry.get("artifact")
+        if not (isinstance(owner, str) and isinstance(artifact, str)):
+            return None, RefFinding(
+                "SOURCE_ENTRY_IS_INCOMPLETE",
+                location,
+                f"sources[{src!r}] needs owner/artifact",
+            )
+    elif all(isinstance(ref.get(key), str) for key in ("owner", "artifact")):
+        owner, artifact = ref["owner"], ref["artifact"]
+    else:
+        return None, RefFinding(
+            "REF_HAS_NO_UPSTREAM_BINDING", location, "needs src, or owner+artifact"
+        )
+    optional = {
+        key: ref[key]
+        for key in ("record_id", "field", "authority")
+        if isinstance(ref.get(key), str)
+    }
+    return (
+        ResolvedRef(
+        owner,
+        artifact,
+            optional.get("record_id"),
+            optional.get("field"),
+            optional.get("authority"),
+        ),
+        None,
+    )
+
+
+# ---------------------------------------------------------------------------
+# END REFERENCE RESOLVER
+# ---------------------------------------------------------------------------
+
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+HASH_RE = re.compile(r"[0-9a-f]{64}")
+VENDOR_FIELDS = {
+    "provider",
+    "model",
+    "endpoint",
+    "api_key",
+    "task_id",
+    "remote_id",
+    "callback_url",
+}
+TOP_LEVEL_FIELDS = {
+    "music_id",
+    "scope",
+    "source_refs",
+    "narrative_function",
+    "prompt",
+    "mode",
+    "lyrics",
+    "mix_intent",
+    "status",
+}
+SCOPE_FIELDS = {"episode_id", "start_seconds", "end_seconds"}
+REFERENCE_FIELDS = {"src", "owner", "artifact", "record_id", "field", "authority"}
+SOURCES_HEADER_FIELDS = {"record_type", "schema_version", "sources"}
+SOURCE_ENTRY_FIELDS = {"owner", "artifact"}
+MIX_FIELDS = {"entry", "exit", "duck_under_dialogue", "loop"}
+MUSIC_ID_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,79}")
+EPISODE_ID_RE = re.compile(r"EP(?:[0-9]{3}|[1-9][0-9]{3,})")
+
+
+class ValidationError(ValueError):
+    """A music spec cannot be handed to production safely."""
+
+
+def resolve_input(value: str | Path) -> Path:
+    path = Path(value).expanduser()
+    if path.exists() or path.is_absolute():
+        return path
+    return SKILL_ROOT / path
+
+
+def load_jsonl(value: str | Path) -> list[dict[str, Any]]:
+    path = resolve_input(value)
+    records: list[dict[str, Any]] = []
+    for number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
+        if not line.strip():
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise ValidationError(f"{path}:{number}: invalid JSON") from exc
+        if not isinstance(record, dict):
+            raise ValidationError(f"{path}:{number}: each record must be an object")
+        records.append(record)
+    if not records:
+        raise ValidationError(f"{path}: no music specs")
+    return records
+
+
+def _text(value: object, label: str, *, maximum: int = 10_000) -> str:
+    if not isinstance(value, str) or not value.strip() or len(value) > maximum:
+        raise ValidationError(f"{label} must be non-empty text up to {maximum} characters")
+    return value
+
+
+def _number(value: object, label: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValidationError(f"{label} must be a number")
+    number = float(value)
+    if not math.isfinite(number):
+        raise ValidationError(f"{label} must be finite")
+    return number
+
+
+def _exact_fields(value: dict[str, Any], allowed: set[str], label: str) -> None:
+    unknown = sorted(set(value) - allowed)
+    if unknown:
+        raise ValidationError(f"{label} has unsupported fields: {', '.join(unknown)}")
+
+
+def _reject_vendor_fields(value: object, label: str) -> None:
+    if isinstance(value, dict):
+        leaked = sorted(str(key) for key in value if str(key).casefold() in VENDOR_FIELDS)
+        if leaked:
+            raise ValidationError(f"{label}: provider execution fields are forbidden: {', '.join(leaked)}")
+        for key, child in value.items():
+            _reject_vendor_fields(child, f"{label}.{key}")
+    elif isinstance(value, list):
+        for index, child in enumerate(value):
+            _reject_vendor_fields(child, f"{label}[{index}]")
+
+
+def _validate_ref(value: object, label: str, sources: dict[str, dict[str, Any]]) -> None:
+    if not isinstance(value, dict):
+        raise ValidationError(f"{label} must be a reference object")
+    _exact_fields(value, REFERENCE_FIELDS, label)
+    resolved, finding = resolve_ref(value, sources, label)
+    if finding is not None:
+        raise ValidationError(f"{finding.location}: {finding.code}: {finding.detail}")
+    if resolved is None:
+        raise ValidationError(f"{label} could not be resolved")
+    for key, text in (
+        ("owner", resolved.owner),
+        ("artifact", resolved.artifact),
+    ):
+        _text(text, f"{label}.{key}")
+    if not isinstance(value.get("record_id") or value.get("field"), str):
+        raise ValidationError(f"{label} needs record_id or field")
+
+
+def split_sources_header(
+    records: list[dict[str, Any]],
+) -> tuple[dict[str, dict[str, Any]], list[dict[str, Any]]]:
+    """Split a leading ``sources`` header off the file's own records.
+
+    The header declares each upstream snapshot once, so a reference only names
+    the snapshot key and the record it points at.
+    """
+    if not records or records[0].get("record_type") != SOURCES_RECORD_TYPE:
+        return {}, list(records)
+    header, *specs = records
+    _exact_fields(header, SOURCES_HEADER_FIELDS, "sources header")
+    if header.get("schema_version") != SOURCES_SCHEMA_VERSION:
+        raise ValidationError(f"sources header schema_version must be {SOURCES_SCHEMA_VERSION}")
+    declared = header.get("sources")
+    if not isinstance(declared, dict) or not declared:
+        raise ValidationError("sources header must declare at least one source")
+    for key, entry in declared.items():
+        label = f"sources[{key!r}]"
+        if not isinstance(entry, dict):
+            raise ValidationError(f"{label} must be an object")
+        _exact_fields(entry, SOURCE_ENTRY_FIELDS, label)
+        for field in sorted(SOURCE_ENTRY_FIELDS):
+            _text(entry.get(field), f"{label}.{field}")
+    return load_sources(header), specs
+
+
+def validate_records(records: list[dict[str, Any]]) -> dict[str, Any]:
+    sources, specs = split_sources_header(records)
+    if not specs:
+        raise ValidationError("no music specs")
+    identifiers: set[str] = set()
+    for index, record in enumerate(specs, 1):
+        label = f"music[{index}]"
+        _reject_vendor_fields(record, label)
+        _exact_fields(record, TOP_LEVEL_FIELDS, label)
+        music_id = _text(record.get("music_id"), f"{label}.music_id", maximum=80)
+        if MUSIC_ID_RE.fullmatch(music_id) is None:
+            raise ValidationError(f"{label}.music_id must be a portable identifier")
+        if music_id in identifiers:
+            raise ValidationError(f"duplicate music_id: {music_id}")
+        identifiers.add(music_id)
+
+        scope = record.get("scope")
+        if not isinstance(scope, dict):
+            raise ValidationError(f"{label}.scope must be an object")
+        _exact_fields(scope, SCOPE_FIELDS, f"{label}.scope")
+        episode_id = _text(
+            scope.get("episode_id"), f"{label}.scope.episode_id", maximum=40
+        )
+        if EPISODE_ID_RE.fullmatch(episode_id) is None:
+            raise ValidationError(f"{label}.scope.episode_id is invalid")
+        start = _number(scope.get("start_seconds"), f"{label}.scope.start_seconds")
+        end = _number(scope.get("end_seconds"), f"{label}.scope.end_seconds")
+        if start < 0 or end <= start:
+            raise ValidationError(f"{label}.scope must have 0 <= start < end")
+
+        refs = record.get("source_refs")
+        if not isinstance(refs, list) or not refs:
+            raise ValidationError(f"{label}.source_refs must be a non-empty list")
+        for ref_index, ref in enumerate(refs, 1):
+            _validate_ref(ref, f"{label}.source_refs[{ref_index}]", sources)
+
+        _text(record.get("narrative_function"), f"{label}.narrative_function")
+        _text(record.get("prompt"), f"{label}.prompt", maximum=2_000)
+        mode = record.get("mode")
+        if mode not in {"instrumental", "song"}:
+            raise ValidationError(f"{label}.mode must be instrumental or song")
+        lyrics = record.get("lyrics")
+        if mode == "instrumental" and lyrics not in {None, ""}:
+            raise ValidationError(f"{label}: instrumental music must not carry lyrics")
+        if mode == "song":
+            _text(lyrics, f"{label}.lyrics", maximum=3_500)
+
+        mix = record.get("mix_intent")
+        if not isinstance(mix, dict):
+            raise ValidationError(f"{label}.mix_intent must be an object")
+        _exact_fields(mix, MIX_FIELDS, f"{label}.mix_intent")
+        if not isinstance(mix.get("duck_under_dialogue"), bool):
+            raise ValidationError(f"{label}.mix_intent.duck_under_dialogue must be boolean")
+        if not isinstance(mix.get("loop"), bool):
+            raise ValidationError(f"{label}.mix_intent.loop must be boolean")
+        _text(mix.get("entry"), f"{label}.mix_intent.entry")
+        _text(mix.get("exit"), f"{label}.mix_intent.exit")
+        if record.get("status") not in {"candidate", "accepted", "revise"}:
+            raise ValidationError(f"{label}.status must be candidate, accepted, or revise")
+
+    return {"status": "valid", "music_specs": len(specs)}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("specs")
+    args = parser.parse_args(argv)
+    try:
+        result = validate_records(load_jsonl(args.specs))
+    except (OSError, UnicodeError, ValidationError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 2
+    print(json.dumps(result, ensure_ascii=True, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/resources/skills/drama-production/upstream/skills/short-drama-video-prompts/scripts/selftest.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Offline self-test for standalone video and music prompt tooling."""
+
+from __future__ import annotations
+
+import copy
+import sys
+
+from music_spec_check import SKILL_ROOT, ValidationError, load_jsonl, validate_records
+
+MINIMUM_PYTHON = (3, 9)
+if sys.version_info < MINIMUM_PYTHON:
+    raise SystemExit("selftest.py requires Python 3.9 or newer")
+
+
+def require(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def fail(records: list[dict], marker: str) -> None:
+    try:
+        validate_records(records)
+    except ValidationError as exc:
+        require(marker in str(exc), f"expected {marker!r}, got {exc!s}")
+    else:
+        raise AssertionError(f"expected failure containing {marker!r}")
+
+
+def main() -> int:
+    records = load_jsonl(SKILL_ROOT / "examples/minimal-music-specs.jsonl")
+    require(validate_records(records)["music_specs"] == 1, "valid fixture count")
+    header, spec = records[0], records[1]
+    require(spec["source_refs"][0]["src"] == "screenplay", "fixture uses a source key")
+
+    # A file that was written before sources declarations existed still carries
+    # the snapshot on every reference, and still validates.
+    expanded = copy.deepcopy(spec)
+    expanded["source_refs"] = [
+        {**header["sources"]["screenplay"], "record_id": "EP001-SC001"}
+    ]
+    require(validate_records([expanded])["music_specs"] == 1, "inline snapshot accepted")
+
+    undeclared = copy.deepcopy(spec)
+    undeclared["source_refs"] = [{"src": "screenplai", "record_id": "EP001-SC001"}]
+    fail([header, undeclared], "REF_SRC_IS_NOT_DECLARED")
+
+    unbound = copy.deepcopy(spec)
+    unbound["source_refs"] = [{"record_id": "EP001-SC001"}]
+    fail([header, unbound], "REF_HAS_NO_UPSTREAM_BINDING")
+
+    duplicate = [header, spec, copy.deepcopy(spec)]
+    fail(duplicate, "duplicate music_id")
+
+    leaked = [header, copy.deepcopy(spec)]
+    leaked[1]["model"] = "example"
+    fail(leaked, "provider execution fields")
+
+    song_without_lyrics = [header, copy.deepcopy(spec)]
+    song_without_lyrics[1]["mode"] = "song"
+    fail(song_without_lyrics, "lyrics")
+
+    invalid_scope = [header, copy.deepcopy(spec)]
+    invalid_scope[1]["scope"]["end_seconds"] = 0
+    fail(invalid_scope, "0 <= start < end")
+
+    unsupported = [header, copy.deepcopy(spec)]
+    unsupported[1]["token"] = "not provider-neutral"
+    fail(unsupported, "unsupported fields")
+
+    # A source entry now names an upstream artifact and nothing else; a stray
+    # byte digest is an unsupported field rather than a malformed hash.
+    stale_source = [copy.deepcopy(header), spec]
+    stale_source[0]["sources"]["screenplay"]["hash"] = "not-a-sha256"
+    fail(stale_source, "unsupported fields")
+
+    print("10 self-tests passed")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/resources/skills/drama-production/upstream/skills/short-drama-write/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: short-drama-write
+description: 编写或修订可拍摄的中文短剧、漫剧单集 Markdown 剧本，也负责保留作者原文地规范化现成剧本。用户提出“写/改一集短剧”“把大纲写成剧本”“优化场景/对白”“去模板感”“去 AI 味润色”“续写下一集”或提供剧本要求进入后续制作时使用；不负责资产、分镜、媒体提示词或终审。
+license: MIT
+---
+
+# 短剧写作
+
+把单集意图写成可表演、可拍摄、会改变故事状态的 `剧集/<EP>/剧本.md`。
+
+## Quick Start
+
+只维护一份剧本 Markdown，不另建 episode card、beats、block index、录音表、QA 或接受记录。
+一级标题使用 `# EP001 集名`，场景标题使用 `## EP001-SC001 内 · 地点 · 时间/天气`。
+对白写 `角色（可选表演提示）：台词`；生产标签使用 `[VO]`、`[OS]`、`[SFX]`、`[画面文字]`、
+`[连续性]`、`[转场]`。不要把含冒号的动作叙述误写成对白。
+
+## 入口
+
+- 有分集规划：读取本集进入状态、目标、转折、回报和交接事实。
+- 只有想法/大纲：在上下文形成最小单集契约和因果节拍，再直接写剧本。
+- 已有剧本：保留作者语言，只做用户点名的定点修订。
+- 非规范文本要进入制作：保留原文，只做必要的场景、动作、对白和生产标签规范化。
+
+开发大纲和长篇分析都是可选上游；当前材料足够时直接写。
+
+## 工作流
+
+1. 锁定本集承诺的观看体验、谁现在要什么、阻力、当集兑现和退出状态。
+2. 只识别本集实际存在的发动机：若主打艰难选择，检查两边价值；若判断转折依赖争议证据，检查证明边界；若前景化精确死线，检查动作容量；若题面限定次数、轮次、呼吸或节拍，检查每个单位是否在边界内完成所需状态。没有时不强行补齐；输入已经以它为主发动机时，要让它真正改变行动、关系或结果，不只在台词中点名。
+3. 在上下文排“因为—行动—结果—下一股压力”，不落盘节拍表；让物件、对白、沉默、空间或声音按本集题材承担必要工作，不预设某一种载体。
+4. 逐场确定不可替代的功能、可见变化与场尾状态；由争取或冲突组织的场景再明确焦点议程与阻力。承担主要戏剧功能的配角要有自己的策略，事务性或环境性角色保持简洁即可。
+5. 把动作、对白、画外音、声音事实和画面文字写入同一份剧本。
+6. 用户要求整集就写完整集，场景批次自动续跑。
+7. 交稿前静默反查：只看剧本能否接收到本集承诺、人物行动是否有因果、题材语气是否一致；再对本集确实使用的选择、证据、有限单位或精确死线做专项检查。若自检让剧本长出输入没有要求的机关，撤掉机关而不是替它找理由。
+8. 局部修订保留无关段落；明确问题直接修正，只把真实剧情分叉交给用户。
+
+## 写作要求
+
+- 先服从输入已经给出的事实、`必须/禁止`、题材观看契约和退出状态；本技能的审查项与手艺默认只帮助实现这些要求，不能反过来补造题面没有的精确数字、记录、资源、程序、关系或机关。
+- 每场改变信息、权力、关系、情绪、物理状态或风险；无变化的场删掉或合并。核心阻力的转向要有可追溯的事实、筹码、权限、代价或人物行动，不能只靠对手停止反应。
+- 对白必须在争取、回避、试探、逼迫或重新定义关系；用可见、可听、可触的行为表现状态，不用解释替代行动，也不把已经演清的机制再说一遍。
+- 观众理解当前行动所必需的赌注要进入剧本，但载体服从题材；选择、证据、有限单位、精确死线等专项规则只在输入真正以它为发动机时启用，并按需读取[剧作手艺](references/script-craft.md)，普通决定、普通物件和模糊时间压力不升级成同一套机关。
+- 压缩过程时只保留会改变策略、关系、风险或结果的节点。资源与外部反应必须来自输入或前文建立，且不能替人物完成最难的戏剧行动。
+- 承担主要冲突的角色要保持相称的目标、判断或策略；事务性、环境性角色保持简洁，不为检查表硬加秘密、反转或人物弧。
+- 已建立的代价、不可逆后果、关键持物、空间和知识状态要进入可追溯的退出状态；结尾可推进、留白、反讽、安静收束或形成余韵，不强制追加外部事件。
+- `[连续性]` 只交接由前文动作已经建立、又容易在下游丢失的状态；不能用作者标签证明镜头外从未发生某事，也不复述正文已清楚呈现的结果。
+- 交稿前静默做一次经济性检查：是否增加了输入没有要求的精确数字或记录链；是否用标签/对白重复动作；是否在回报后堆了多个同方向后果。没有新作用的内容删掉，knowhow 本身不删。
+- 输入给出目标时长时按真实表演、动作和停顿通读压稿，先删重复验证、解释和同义收尾；不用统一字数、镜头数或节拍数填模板。
+- 用户原文优先；“去 AI 味”是定点修订，不抹平作者个性。
+
+## 按需知识
+
+默认只读本 SKILL 和直接输入。出现下列明确信号时，在写正文前读取对应知识；同一输入有多个不同问题
+可以分别读取，但不遍历无关引用：
+
+- 阶段边界与规则分级：[阶段契约](references/stage-contract.md)
+- 场景标题、对白和生产标签语法，或把创作者带来的现成剧本[规范化](references/screenplay-format.md#7-现有文本的规范化入口)：[剧本格式](references/screenplay-format.md)
+- 项目特有的制作稿方言：[制作格式方言](references/production-format-dialect.md)
+- 输入含[核心选择](references/script-craft.md#35-把一拍写成艰难选择时两个方向都要活着)、[有限次数/轮次/呼吸/节拍](references/script-craft.md#64-有限单位按完成状态计数)、[精确倒计时](references/script-craft.md#63-倒计时先算动作不要只写数字)或[会改变人物判断的关键物证](references/script-craft.md#53-证据先改变判断再改变关系)：[剧作手艺](references/script-craft.md)
+- 过去关系必须通过对白进入，或关键人物容易只剩说明功能：[对白手艺](references/dialogue-craft.md)
+- 声源、留白与 sound bridge：[场景声音戏剧](references/scene-sound-dramaturgy.md)
+- 同一故事义务的不同可拍实现：[可替代实现](references/substitutable-realization.md)
+- 长单集跨上下文时的最小交接：[场景交接胶囊](references/scene-handoff-capsule.md)，只留在上下文
+
+## 时长估算（按需）
+
+用户问时长时才把索引写入系统临时目录。先用 Python 查询跨平台临时目录，把第一条命令打印的完整
+路径原样替换进后两条命令的引号内。以下每条都是一行完整命令，不依赖 shell 变量或续行符；Windows
+没有 `python3` 命令时使用 `py -3`。`--speaker` 的示例值必须替换为本集实际说话者。
+`--project short-drama.json` **只加在第三条命令上**（`duration_estimate.py` 才接受它，
+`screenplay_index.py` 没有这个参数，加上去会直接报 `unrecognized arguments`），且只在项目
+配置确实存在时加：
+
+```text
+python3 -c "from pathlib import Path; import tempfile, uuid; print(Path(tempfile.gettempdir()) / ('short-drama-' + uuid.uuid4().hex + '.jsonl'))"
+python3 "{技能目录}/scripts/screenplay_index.py" "剧集/EP001/剧本.md" --output "粘贴第一条命令输出的完整路径" --speaker "本集角色一" --speaker "本集角色二"
+python3 "{技能目录}/scripts/duration_estimate.py" "剧集/EP001/剧本.md" --index "粘贴第一条命令输出的完整路径"
+```
+
+**改稿后重跑**：第二条命令写过一次的输出路径不能直接再写一次，会以 `already holds an index` 失败。
+要保留原有块 ID 就加 `--previous-index <同一路径>`，要从头重编号就加 `--no-previous`；
+或者干脆回到第一条命令另取一个临时路径。
+
+估时前区分计数口径：`dialogue_characters` 包含标点，视频提示词中的参考语速按可发声字数计算。
+按语速换算时排除标点，并按实际读法处理数字和缩写；不把两个计数混用。
+
+估算是参考，不是门禁；没有语速或动作段速率时只报告可数事实，不猜秒数。但任务已给目标时长时，
+写作者仍须用真实朗读和动作通读判断能否容纳，并直接压缩重复节拍；“不能精确估秒”不是忽略目标的理由。
+
+## 完成
+
+点名范围已写入、场景因果连贯、对白与行动可表演、承诺有兑现或有意延迟、结尾完成本集预定的戏剧或情绪功能，即完成。最后一拍可以推进，也可以安静收束、形成余韵或让既有动作变义；判断它是否有效，不用“是否又发生一件事”代替。
+资产、分镜、审查与生产只有用户点名时开始。
+五份创作文档齐备后，可转 `$short-drama` 对跨文档结构做一次机械核对；内容质量仍由创作者审查。
+
+## 安装维护
+
+只有安装、升级或排障时运行 `python3 scripts/selftest.py`。

package/resources/skills/drama-production/upstream/skills/short-drama-write/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "短剧写作"
+  short_description: "创作因果清楚、人物声音鲜明、动作可表演的中文短剧剧本"
+  default_prompt: "使用 $short-drama-write 创作或修订我的单集卡、因果节拍和中文 Markdown 短剧剧本。"

package/resources/skills/drama-production/upstream/skills/short-drama-write/assets/beats.jsonl

@@ -0,0 +1,2 @@
+{"record_type": "sources", "schema_version": "1.0.0", "sources": {"episode-map": {"owner": "short-drama-develop", "artifact": "项目开发/episode-map.jsonl"}}}
+{"beat_id": "BEAT-001", "episode_id": "EP001", "starts_new_thread": false, "focus_character": "__FILL__", "character_goal": "__FILL__", "opposition": "__FILL__", "observable_action": "__FILL__", "dramatic_result": {"goal_outcome": "__SUCCESS_FAILURE_OR_REDIRECTION__", "new_fact_or_cost": "__FILL__", "next_action_changed": "__FILL__"}, "rhythm": {"external_pressure": "__LOW_MEDIUM_HIGH_WITH_REASON__", "emotional_load": "__LOW_MEDIUM_HIGH_WITH_REASON__"}, "state_change": {"information": "__FILL_OR_REMOVE__", "power": "__FILL_OR_REMOVE__", "relationship": "__FILL_OR_REMOVE__", "emotion_as_action": "__FILL_OR_REMOVE__", "physical": "__FILL_OR_REMOVE__", "risk": "__FILL_OR_REMOVE__"}, "setup_refs": [], "payoff_refs": [], "next_pressure": "__FILL__", "replaceable_realization": {"marked_by": "__CREATOR_OR_REMOVE__", "dramatic_function": "__WHO_IS_PROVEN_OR_CHANGED__", "current_depiction": "__FILL__", "fallback_depiction": "__DELIVERS_THE_SAME_FUNCTION__", "cost_preserved": "__FILL__", "downstream_still_satisfied": "__PAYOFF_AND_NEXT_ENTRY_STATE__"}, "candidate_scene_id": "EP001-SC001", "notes": "__FILL_OR_REMOVE__", "because_of_ids": ["BEAT-<prior-id>"], "because_of_refs": [], "setup_ids": [], "payoff_ids": []}

package/resources/skills/drama-production/upstream/skills/short-drama-write/assets/episode-card-standalone.json

@@ -0,0 +1,120 @@
+{
+  "episode_id": "EP001",
+  "contract_authority": {
+    "mode": "write_standalone",
+    "source_ref": null
+  },
+  "owned_contract": {
+    "incoming_state": {
+      "knowledge": [
+        "__FILL_OR_REMOVE__"
+      ],
+      "power": [
+        "__FILL_OR_REMOVE__"
+      ],
+      "relationship": [
+        "__FILL_OR_REMOVE__"
+      ],
+      "physical": [
+        "__FILL_OR_REMOVE__"
+      ],
+      "active_action": [
+        "__FILL_OR_REMOVE__"
+      ]
+    },
+    "active_pressure": "__FILL__",
+    "objective": {
+      "character": "__FILL__",
+      "desired_change": "__FILL__",
+      "why_now": "__FILL__"
+    },
+    "opposition": {
+      "actor_or_constraint": "__FILL__",
+      "goal": "__FILL__",
+      "leverage": "__FILL__"
+    },
+    "causal_escalation": [
+      {
+        "because_of": "__FILL__",
+        "choice": "__FILL__",
+        "countermove": "__FILL__",
+        "state_change": "__FILL__",
+        "next_pressure": "__FILL__"
+      }
+    ],
+    "turn": {
+      "trigger": "__FILL__",
+      "old_plan_that_stops_working": "__FILL__",
+      "new_direction": "__FILL__"
+    },
+    "local_dramatic_result": {
+      "goal_outcome": "__SUCCESS_FAILURE_OR_REDIRECTION__",
+      "state_change": "__FILL__",
+      "cost_paid": "__FILL__"
+    },
+    "promised_payoff": "__FILL__",
+    "character_progression": [
+      {
+        "character_id": "__FILL__",
+        "strategy_before": "__FILL__",
+        "pressure_test": "__FILL__",
+        "choice_or_retreat": "__FILL__",
+        "visible_strategy_after": "__FILL__"
+      }
+    ],
+    "information_release": [
+      {
+        "fact_id": "__FILL__",
+        "audience_before": "__KNOWN_SUSPECTED_OR_UNKNOWN__",
+        "character_permissions_before": {
+          "__CHARACTER_ID__": "__KNOWN_MISTAKEN_OR_UNKNOWN__"
+        },
+        "visible_carrier": "__ACTION_OBJECT_DIALOGUE_OR_CONSEQUENCE__",
+        "supported_claim": "__STRONGEST_CLAIM_DIRECTLY_SUPPORTED_BY_CARRIER__",
+        "unresolved_inference": "__UNPROVED_IDENTITY_CAUSE_MOTIVE_OR_MECHANISM_OR_NONE__",
+        "audience_after": "__KNOWN_SUSPECTED_OR_UNKNOWN__",
+        "character_permissions_after": {
+          "__CHARACTER_ID__": "__KNOWN_MISTAKEN_OR_UNKNOWN__"
+        }
+      }
+    ],
+    "rhythm_plan": {
+      "external_pressure": "__LOW_MEDIUM_HIGH_WITH_REASON__",
+      "emotional_load": "__LOW_MEDIUM_HIGH_WITH_REASON__",
+      "relationship_to_previous": "__CONTINUE_CONTRAST_OR_LAND__",
+      "landing_space": "__WHERE_CONSEQUENCE_IS_PROCESSED_OR_NONE_WITH_REASON__"
+    },
+    "outgoing_pressure": {
+      "decision_danger_or_question_already_in_motion": "__FILL__",
+      "caused_by_this_episode": "__FILL__"
+    },
+    "handoff_state": {
+      "knowledge": [
+        "__FILL_OR_REMOVE__"
+      ],
+      "power": [
+        "__FILL_OR_REMOVE__"
+      ],
+      "relationship": [
+        "__FILL_OR_REMOVE__"
+      ],
+      "physical": [
+        "__FILL_OR_REMOVE__"
+      ],
+      "active_action": [
+        "__FILL_OR_REMOVE__"
+      ]
+    },
+    "setup_refs": [],
+    "payoff_refs": []
+  },
+  "execution_plan": {
+    "viewpoint_and_audience_alignment": "__FILL__",
+    "opening_action_carrier": "__FILL__",
+    "scene_jobs": [],
+    "production_requirements": []
+  },
+  "source_refs": [],
+  "open_questions": [],
+  "creator_status": "draft"
+}