Skip to content

zenstory-ai/drama-skills / skills/short-drama-write

short-drama-write

Verified

编写或修订可拍摄的中文短剧、漫剧单集 Markdown 剧本,也负责保留作者原文并把现成剧本整理成标准格式。用户提出“写/改一集短剧”“把大纲写成剧本”“优化场景/对白”“去模板感”“去 AI 味润色”“续写下一集”或提供剧本要求进入后续制作时使用;不负责视觉设定、分镜、生图与视频提示词或终审。

scripts/screenplay_index.py

View on GitHub
#!/usr/bin/env python3
"""Build a byte-accurate, derived index for a short-drama Markdown screenplay.

The indexer recognizes only the screenplay grammar documented by the write
skill.  It never rewrites the screenplay and never guesses through a
split/merge revision.
"""

from __future__ import annotations

import argparse
import json
import os
import re
import sys
import tempfile
from collections import defaultdict
from pathlib import Path
from typing import Any, NamedTuple


# 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
        )
    )

# ---------------------------------------------------------------------------
# REFERENCE RESOLVER -- reference implementation.
#
# Each skill checker carries its own copy of this block. The suite has no shared
# library on purpose: a skill must stay runnable after copying only its own
# directory, so duplicating these few lines across skills is the correct shape.
# Copy the block verbatim; do not import it.
# ---------------------------------------------------------------------------

SOURCES_RECORD_TYPE = "sources"
SOURCES_SCHEMA_VERSION = "1.0.0"
SOURCES_KEY = "sources"


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
# ---------------------------------------------------------------------------

SCHEMA_VERSION = "1.0.0"

# An index declares its upstream screenplay once, on the meta record, and every
# reference in the file names it by key. A rebuild against a previous index adds
# a second key only when the previous screenplay is a different snapshot.
SCREENPLAY_SOURCE_KEY = "screenplay"
PREVIOUS_SCREENPLAY_SOURCE_KEY = "previous-screenplay"

SUPPORTED_TAGS = ("VO", "OS", "SFX", "画面文字", "连续性", "转场")
KIND_CODES = {
    "scene_heading": "H",
    "action": "A",
    "dialogue": "D",
    "production_tag": "P",
    "comment": "C",
    "code_fence": "F",
}

# Three digits through EP999, then unpadded — the same single spelling per
# episode number the lifecycle tool enforces on `episodes/<EP>/`. A fixed three
# digits would have made EP1000 a legal directory but an illegal heading.
_EPISODE = r"EP(?:[0-9]{3}|[1-9][0-9]{3,})"
_SCENE = r"SC(?:[0-9]{3}|[1-9][0-9]{3,})"
_WS = r"[ \t\u3000]"
EPISODE_HEADING_RE = re.compile(
    rf"^#{_WS}+(?P<episode>{_EPISODE})"
    rf"(?![0-9])(?!{_WS}*(?:——|[·::–—-])?{_WS}*SC[0-9])"
    rf"(?:{_WS}*(?:——|[·::–—-])(?:{_WS}*.+)?|{_WS}+.+)?$"
)
# A project that scopes ids by season writes `S01-EP001-SC001`; the episode is
# still the `EP` segment, and the cross-document checker accepts the same form.
# Whitespace around `·` is optional so `内·客厅·夜` and `内 · 客厅 · 夜` both
# parse instead of silently dropping the scene's blocks.
SCENE_HEADING_RE = re.compile(
    rf"^##{_WS}+(?P<scene>(?:[A-Za-z0-9]+-)*?(?P<episode>{_EPISODE})-{_SCENE})"
    rf"(?:{_WS}+|{_WS}*·{_WS}*)"
    rf"(?P<space>内外|内|外){_WS}*·{_WS}*(?P<location>[^\s·](?:.*?[^\s·])?){_WS}*·{_WS}*"
    r"(?P<time>[^\s·](?:.*[^\s·])?)$"
)
CAST_LINE_RE = re.compile(
    rf"^{_WS}*(?:[-*+]{_WS}+)?(?:"
    rf"人物{_WS}*[::]"
    rf"|\*\*\*人物(?:{_WS}*\*\*\*{_WS}*[::]|{_WS}*[::]{_WS}*\*\*\*)"
    rf"|___人物(?:{_WS}*___{_WS}*[::]|{_WS}*[::]{_WS}*___)"
    rf"|\*\*人物(?:{_WS}*\*\*{_WS}*[::]|{_WS}*[::]{_WS}*\*\*)"
    rf"|__人物(?:{_WS}*__{_WS}*[::]|{_WS}*[::]{_WS}*__)"
    rf"|\*人物(?:{_WS}*\*{_WS}*[::]|{_WS}*[::]{_WS}*\*)"
    rf"|_人物(?:{_WS}*_{_WS}*[::]|{_WS}*[::]{_WS}*_)"
    rf"){_WS}*(?P<body>.*)$"
)
CAST_PLACEHOLDERS = frozenset(
    {
        "无",
        "暂无",
        "待定",
        "待补",
        "待确认",
        "待填",
        "填写",
        "未定",
        "略",
        "空",
        "未知",
        "tbd",
        "todo",
        "tba",
        "none",
        "null",
        "n/a",
        "na",
        "nil",
    }
)
_HTML_COMMENT_RE = re.compile(r"<!--[\s\S]*?-->")
_FENCE_OPEN_RE = re.compile(r"^[ \t\u3000]{0,3}(`{3,}|~{3,})([^\r\n]*)$")
CLOCK_PREFIX_RE = re.compile(r"^\d{1,2}[::]\d{2}(?=\D|$)")
_NOT_CLOCK_PREFIX = r"(?!\d{1,2}[::]\d{2}(?:\D|$))"
_NOT_URL_PREFIX = r"(?![A-Za-z][A-Za-z0-9+.-]*://)(?!(?:https?|ftp|mailto|file|ws|wss):(?://|\s|$))"
MAX_SPEAKER_LENGTH = 40
_SPEAKER_TOKEN = r"[^\s::()()\[\]#,。!?;,!?;—]+"
_SPEAKER_LABEL = (
    rf"(?=.{{1,{MAX_SPEAKER_LENGTH}}}(?:{_WS}*[((]|:|:))"
    rf"{_SPEAKER_TOKEN}(?: {_SPEAKER_TOKEN}){{0,3}}"
)
_OPTIONAL_CUE = rf"(?:{_WS}*(?:((?P<cue_fw>[^()\r\n]+))|\((?P<cue_hw>[^()\r\n]+)\)))?"
_OPTIONAL_CUE_UNNAMED = rf"(?:{_WS}*(?:([^()\r\n]+)|\([^()\r\n]+\)))?"
DIALOGUE_RE = re.compile(
    rf"^{_NOT_CLOCK_PREFIX}{_NOT_URL_PREFIX}(?P<speaker>{_SPEAKER_LABEL}){_OPTIONAL_CUE}:{_WS}*(?P<text>\S[\s\S]*)$"
)
KNOWN_SPEAKER_DIALOGUE_RE = re.compile(
    rf"^{_NOT_CLOCK_PREFIX}{_NOT_URL_PREFIX}(?P<speaker>{_SPEAKER_LABEL}){_OPTIONAL_CUE}[::]{_WS}*(?P<text>\S[\s\S]*)$"
)
ASCII_DIALOGUE_RE = re.compile(
    rf"^{_NOT_CLOCK_PREFIX}{_NOT_URL_PREFIX}{_SPEAKER_LABEL}{_OPTIONAL_CUE_UNNAMED}:{_WS}*\S"
)
TAG_RE = re.compile(r"^\[(?P<tag>VO|OS|SFX|画面文字|连续性|转场)\]\s*(?P<body>\S[\s\S]*)$")
ANY_TAG_RE = re.compile(r"^\[(?P<tag>[^\]\r\n]+)\]")
# Production dialects write tags with full-width brackets (【特写】/【闪回】).
# Without this the paragraph matches nothing and is emitted as a plain action
# block with no issue, so the owner never learns the source needs
# normalization. The block is still emitted (see below) because block IDs are
# the durable cross-artifact reference; only the diagnosis is added.
# The lookahead keeps dialect dialogue on the dialogue path. The dialect writes
# the performance cue with ASCII parens and a full-width colon
# (【角色名】(表演括注):台词, production-format-dialect.md), so both paren
# styles must be exempted here.
FULLWIDTH_TAG_RE = re.compile(
    r"^【(?P<tag>[^】\r\n]+)】"
    r"(?!\s*(?:([^()\r\n]*)|\([^()\r\n]*\))?\s*[::])"
)
MALFORMED_TAG_RE = re.compile(r"^\[(?:VO|OS|SFX|画面文字|连续性|转场)(?:\s|:|:)")
# A voiced tag carries the same optional performance cue as plain dialogue
# (``[OS] 角色(提示):台词`` or ``[VO] Elena: ...``).
VOICE_TAG_BODY_RE = re.compile(
    rf"^{_NOT_CLOCK_PREFIX}{_NOT_URL_PREFIX}(?P<speaker>{_SPEAKER_LABEL}){_OPTIONAL_CUE}[::]{_WS}*(?P<text>\S[\s\S]*)$"
)
BLOCK_ID_RE = re.compile(r"^BLK-(?P<scope>.+)-(?P<code>[HADPCF])(?P<number>\d+)$")


def _extract_cue(match: re.Match[str]) -> str | None:
    return match.group("cue_fw") or match.group("cue_hw")


def _fence_open(line_text: str) -> tuple[str, int] | None:
    match = _FENCE_OPEN_RE.match(line_text)
    if match is None:
        return None
    marker = match.group(1)
    if marker[0] == "`" and "`" in match.group(2):
        return None
    return marker[0], len(marker)


def _fence_close(line_text: str, fence_char: str, min_length: int) -> bool:
    return (
        re.match(
            rf"^[ \t\u3000]{{0,3}}{re.escape(fence_char)}{{{min_length},}}[ \t\u3000]*$",
            line_text,
        )
        is not None
    )


def _scan_comment_end(lines: list[dict[str, Any]], start_index: int) -> int | None:
    """Return the first line index >= start_index where all opened ``<!--`` close."""
    chunks: list[str] = []
    for cursor in range(start_index, len(lines)):
        chunks.append(lines[cursor]["text"])
        remainder = _HTML_COMMENT_RE.sub("", "\n".join(chunks))
        if "<!--" not in remainder:
            return cursor
    return None


def _is_placeholder_cast_token(token: str) -> bool:
    if not token:
        return True
    lowered = token.lower()
    if lowered in CAST_PLACEHOLDERS:
        return True
    if token.startswith(("【", "[", "<", "〈", "《", "{")) or token.endswith(
        ("】", "]", ">", "〉", "》", "}")
    ):
        return True
    if token.startswith("__") and token.endswith("__"):
        return True
    return re.fullmatch(r"[-–—.~…??**__]+", token) is not None


def _parse_cast_speakers(raw_body: str) -> set[str]:
    """Extract valid speaker names from a ``人物:`` declaration body."""
    cleaned = _HTML_COMMENT_RE.sub("", raw_body).strip()
    previous: str | None = None
    while previous != cleaned:
        previous = cleaned
        cleaned = re.sub(r"([^()]*)|\([^()]*\)", "", cleaned)
    cleaned = re.sub(r"(?i)\bn\s*/\s*a\b", "", cleaned)
    cleaned = re.sub(r"[。.;;,,、\s]+$", "", cleaned).strip()
    if not cleaned or _is_placeholder_cast_token(cleaned):
        return set()
    speakers: set[str] = set()
    for raw_item in re.split(
        r"[、,,;;||/]+|(?<![A-Za-z.\-])\s+(?![A-Za-z])",
        cleaned,
    ):
        item = re.sub(r"[。.]+$", "", raw_item.strip()).strip()
        normalized = " ".join(item.split())
        if _is_placeholder_cast_token(normalized):
            continue
        if (
            len(normalized) <= MAX_SPEAKER_LENGTH
            and DIALOGUE_RE.fullmatch(f"{normalized}:占位") is not None
        ):
            speakers.add(normalized)
    return speakers


def _declared_script_speakers(
    lines: list[dict[str, Any]],
) -> tuple[bool, set[str]]:
    """Collect speakers from ``人物:`` lines before the first scene and at scene heads."""
    declared: set[str] = set()
    episode_id: str | None = None
    scene_id: str | None = None
    seen_scene_heading = False
    at_scene_head = False
    index = 0

    while index < len(lines):
        text = lines[index]["text"]
        stripped = text.strip()
        if not stripped:
            index += 1
            continue

        if stripped.startswith("<!--"):
            end_index = _scan_comment_end(lines, index)
            if end_index is None:
                break
            chunk = "\n".join(lines[i]["text"] for i in range(index, end_index + 1))
            if _HTML_COMMENT_RE.sub("", chunk).strip():
                at_scene_head = False
            index = end_index + 1
            continue

        fence = _fence_open(text)
        if fence is not None:
            fence_char, fence_len = fence
            end_index = index + 1
            while end_index < len(lines) and not _fence_close(
                lines[end_index]["text"], fence_char, fence_len
            ):
                end_index += 1
            if end_index >= len(lines):
                break
            index = end_index + 1
            continue

        after_closed = _HTML_COMMENT_RE.sub("", text)
        if "<!--" in after_closed:
            end_index = _scan_comment_end(lines, index)
            if end_index is None:
                break
            at_scene_head = False
            index = end_index + 1
            continue

        clean_stripped = after_closed.strip()
        if not clean_stripped:
            index += 1
            continue

        if clean_stripped.startswith("##"):
            seen_scene_heading = True
            match = SCENE_HEADING_RE.fullmatch(clean_stripped)
            if match and not (episode_id and episode_id != match.group("episode")):
                episode_id = match.group("episode")
                scene_id = match.group("scene")
                at_scene_head = True
            else:
                scene_id = None
                at_scene_head = False
            index += 1
            continue

        if clean_stripped.startswith("#"):
            match = EPISODE_HEADING_RE.fullmatch(clean_stripped)
            if match:
                episode_id = match.group("episode")
                scene_id = None
                seen_scene_heading = False
                at_scene_head = False
            else:
                scene_id = None
                seen_scene_heading = True
                at_scene_head = False
            index += 1
            continue

        if not seen_scene_heading or (at_scene_head and scene_id is not None):
            cast_match = CAST_LINE_RE.match(after_closed)
            if cast_match is not None:
                declared.update(_parse_cast_speakers(cast_match.group("body")))
                index += 1
                continue

        end_index = index
        while end_index + 1 < len(lines):
            next_text = lines[end_index + 1]["text"]
            next_stripped = next_text.strip()
            if (
                not next_stripped
                or next_stripped.startswith("<!--")
                or _fence_open(next_text) is not None
            ):
                break
            next_after_closed = _HTML_COMMENT_RE.sub("", next_text)
            next_clean = next_after_closed.strip()
            if next_clean.startswith("#") or (
                not seen_scene_heading
                and CAST_LINE_RE.match(next_after_closed) is not None
            ):
                break
            end_index += 1
        at_scene_head = False
        index = end_index + 1

    return bool(declared), declared


def _newline_style(data: bytes) -> str:
    crlf = data.count(b"\r\n")
    bare_lf = data.count(b"\n") - crlf
    bare_cr = data.count(b"\r") - crlf
    styles = sum(bool(count) for count in (crlf, bare_lf, bare_cr))
    if styles > 1:
        return "mixed"
    if crlf:
        return "crlf"
    if bare_lf:
        return "lf"
    if bare_cr:
        return "cr"
    return "none"


def _line_table(data: bytes) -> list[dict[str, Any]]:
    raw_lines = data.splitlines(keepends=True)
    if not raw_lines and data == b"":
        return []
    if raw_lines and sum(map(len, raw_lines)) < len(data):
        raw_lines.append(data[sum(map(len, raw_lines)) :])
    lines: list[dict[str, Any]] = []
    offset = 0
    for number, raw in enumerate(raw_lines, 1):
        if raw.endswith(b"\r\n"):
            content = raw[:-2]
        elif raw.endswith((b"\n", b"\r")):
            content = raw[:-1]
        else:
            content = raw
        line_start = offset
        if number == 1 and content.startswith(b"\xef\xbb\xbf"):
            line_start += 3
            content = content[3:]
        lines.append(
            {
                "number": number,
                "start": line_start,
                "content_end": line_start + len(content),
                "end": offset + len(raw),
                "raw": raw,
                "content": content,
                "text": content.decode("utf-8"),
            }
        )
        offset += len(raw)
    return lines


def _span(
    data: bytes,
    lines: list[dict[str, Any]],
    start_index: int,
    end_index: int,
) -> dict[str, Any]:
    start = lines[start_index]["start"]
    end = lines[end_index]["content_end"]
    raw = data[start:end]
    return {
        "byte_start": start,
        "byte_end": end,
        "line_start": lines[start_index]["number"],
        "line_end": lines[end_index]["number"],
        "_raw": raw,
        "_text": raw.decode("utf-8"),
    }


def _issue(
    span: dict[str, Any],
    code: str,
    message: str,
) -> dict[str, Any]:
    return {
        **{key: span[key] for key in ("byte_start", "byte_end", "line_start", "line_end")},
        "issue_code": code,
        "severity": "review_required",
        "message": message,
    }


def _looks_like_markdown(text: str) -> bool:
    stripped = text.lstrip()
    return bool(
        stripped.startswith(("#", "```", "~~~", ">", "- ", "* ", "+ "))
        or re.match(r"\d+[.)]\s", stripped)
        or re.fullmatch(r"[-*_]{3,}", stripped)
    )


def _parse_screenplay(
    data: bytes,
    speaker_names: frozenset[str],
) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
    # Decode once up front so invalid UTF-8 fails before any output is written.
    data.decode("utf-8")
    lines = _line_table(data)
    active_speakers = speaker_names
    if "人物" not in speaker_names:
        _, cast_speakers = _declared_script_speakers(lines)
        if cast_speakers:
            active_speakers = speaker_names | frozenset(cast_speakers)
    blocks: list[dict[str, Any]] = []
    issues: list[dict[str, Any]] = []
    episode_id: str | None = None
    scene_id: str | None = None
    seen_scene_heading = False
    at_scene_head = False
    index = 0

    def append_block(kind: str, span: dict[str, Any], **fields: Any) -> None:
        blocks.append(
            {
                "kind": kind,
                "episode_id": episode_id,
                "scene_id": scene_id,
                **span,
                **fields,
                "_order": len(blocks),
            }
        )

    while index < len(lines):
        text = lines[index]["text"]
        stripped = text.strip()
        if not stripped:
            index += 1
            continue

        if stripped.startswith("<!--"):
            end_index = _scan_comment_end(lines, index)
            if end_index is None:
                span = _span(data, lines, index, len(lines) - 1)
                issues.append(_issue(span, "malformed_comment", "Markdown 注释缺少闭合的 -->。"))
                break
            span = _span(data, lines, index, end_index)
            remainder = _HTML_COMMENT_RE.sub("", span["_text"]).strip()
            if remainder:
                at_scene_head = False
                issues.append(
                    _issue(span, "mixed_comment_content", "注释与正文混写在同一段落,不能机械分块。")
                )
            else:
                append_block("comment", span, production=False)
            index = end_index + 1
            continue

        fence = _fence_open(text)
        if fence is not None:
            fence_char, fence_len = fence
            end_index = index + 1
            while end_index < len(lines) and not _fence_close(
                lines[end_index]["text"], fence_char, fence_len
            ):
                end_index += 1
            if end_index >= len(lines):
                span = _span(data, lines, index, len(lines) - 1)
                issues.append(_issue(span, "unsupported_markdown", "代码块缺少闭合围栏。"))
                break
            span = _span(data, lines, index, end_index)
            append_block("code_fence", span, production=False)
            index = end_index + 1
            continue

        after_closed = _HTML_COMMENT_RE.sub("", text)
        clean_stripped = after_closed.strip()

        if clean_stripped.startswith("##"):
            seen_scene_heading = True
            if "<!--" in after_closed:
                close_index = _scan_comment_end(lines, index)
                if close_index is None:
                    span = _span(data, lines, index, len(lines) - 1)
                    issues.append(_issue(span, "malformed_comment", "Markdown 注释缺少闭合的 -->。"))
                    break
                span = _span(data, lines, index, close_index)
                scene_id = None
                at_scene_head = False
                issues.append(
                    _issue(span, "mixed_comment_content", "场景标题中混有多行注释,不能机械分块。")
                )
                index = close_index + 1
                continue
            span = _span(data, lines, index, index)
            match = SCENE_HEADING_RE.fullmatch(clean_stripped)
            if not match:
                scene_id = None
                at_scene_head = False
                issues.append(
                    _issue(
                        span,
                        "invalid_scene_heading",
                        "场景标题必须为 ## <EP001-SC001> <内|外|内外> · <地点> · <时间/天气>。",
                    )
                )
            else:
                scene_id = match.group("scene")
                heading_episode = match.group("episode")
                if episode_id and episode_id != heading_episode:
                    issues.append(
                        _issue(span, "episode_scene_mismatch", "场景 ID 与当前集标题的集 ID 不一致。")
                    )
                    scene_id = None
                    at_scene_head = False
                else:
                    episode_id = heading_episode
                    at_scene_head = True
                    append_block(
                        "scene_heading",
                        span,
                        space=match.group("space"),
                        location=match.group("location"),
                        time_weather=match.group("time"),
                    )
            index += 1
            continue

        if clean_stripped.startswith("#"):
            if "<!--" in after_closed:
                close_index = _scan_comment_end(lines, index)
                if close_index is None:
                    span = _span(data, lines, index, len(lines) - 1)
                    issues.append(_issue(span, "malformed_comment", "Markdown 注释缺少闭合的 -->。"))
                    break
                span = _span(data, lines, index, close_index)
                scene_id = None
                seen_scene_heading = True
                at_scene_head = False
                issues.append(
                    _issue(span, "mixed_comment_content", "集标题中混有多行注释,不能机械分块。")
                )
                index = close_index + 1
                continue
            span = _span(data, lines, index, index)
            match = EPISODE_HEADING_RE.fullmatch(clean_stripped)
            if match:
                episode_id = match.group("episode")
                scene_id = None
                seen_scene_heading = False
                at_scene_head = False
            else:
                scene_id = None
                seen_scene_heading = True
                at_scene_head = False
                issues.append(_issue(span, "invalid_episode_heading", "集标题必须以 # EP001 开头(EP 加三位数字,超过 EP999 后不补零)。"))
            index += 1
            continue

        if (
            (not seen_scene_heading or at_scene_head)
            and (scene_id is None or "人物" not in speaker_names)
            and "<!--" not in after_closed
            and CAST_LINE_RE.match(after_closed) is not None
        ):
            index += 1
            continue

        end_index = index
        unclosed_comment = False
        while True:
            chunk = "\n".join(lines[i]["text"] for i in range(index, end_index + 1))
            if "<!--" in _HTML_COMMENT_RE.sub("", chunk):
                if end_index + 1 >= len(lines):
                    unclosed_comment = True
                    break
                end_index += 1
                continue
            if end_index + 1 >= len(lines):
                break
            next_text = lines[end_index + 1]["text"]
            next_stripped = next_text.strip()
            if (
                not next_stripped
                or next_stripped.startswith("<!--")
                or _fence_open(next_text) is not None
            ):
                break
            next_after_closed = _HTML_COMMENT_RE.sub("", next_text)
            next_clean = next_after_closed.strip()
            if next_clean.startswith("#") or (
                not seen_scene_heading
                and "<!--" not in next_after_closed
                and CAST_LINE_RE.match(next_after_closed) is not None
            ):
                break
            end_index += 1

        if unclosed_comment:
            span = _span(data, lines, index, len(lines) - 1)
            issues.append(_issue(span, "malformed_comment", "Markdown 注释缺少闭合的 -->。"))
            break

        at_scene_head = False
        span = _span(data, lines, index, end_index)
        paragraph = _HTML_COMMENT_RE.sub("", span["_text"]).strip()

        if scene_id is None:
            issues.append(
                _issue(span, "content_outside_scene", "动作、对白和生产标签只能位于合法场景标题之后。")
            )
            index = end_index + 1
            continue

        paragraph_lines = [line.strip() for line in paragraph.splitlines() if line.strip()]
        if len(paragraph_lines) > 1:
            later_fw = [
                match
                for line in paragraph_lines[1:]
                if (match := DIALOGUE_RE.fullmatch(line)) is not None
            ]
            later_any = [
                match
                for line in paragraph_lines[1:]
                if (match := KNOWN_SPEAKER_DIALOGUE_RE.fullmatch(line)) is not None
            ]
            if any(match.group("speaker") in active_speakers for match in later_any) or any(
                ASCII_DIALOGUE_RE.match(line)
                or TAG_RE.fullmatch(line)
                or ANY_TAG_RE.match(line)
                or MALFORMED_TAG_RE.match(line)
                for line in paragraph_lines[1:]
            ):
                issues.append(
                    _issue(
                        span,
                        "missing_block_separator",
                        "动作、对白与生产标签之间需要空行,不能把不同语法块合成动作段落。",
                    )
                )
                index = end_index + 1
                continue
            if later_fw:
                issues.append(
                    _issue(
                        span,
                        "ambiguous_dialogue_or_action",
                        "冒号前缀不在本次说话者清单中;由 write owner 判断是动作、画面文字还是对白。",
                    )
                )
                index = end_index + 1
                continue

        tag_match = TAG_RE.fullmatch(paragraph)
        if tag_match:
            tag = tag_match.group("tag")
            body = tag_match.group("body")
            fields: dict[str, Any] = {"tag": tag, "production": True}
            if tag in {"VO", "OS"}:
                voice_match = VOICE_TAG_BODY_RE.fullmatch(body)
                if not voice_match:
                    issues.append(
                        _issue(
                            span,
                            "invalid_voice_tag_syntax",
                            f"[{tag}] 写成「[{tag}] 角色(可选提示):台词」:要有说话者与冒号,提示可用全角或半角括号。",
                        )
                    )
                    index = end_index + 1
                    continue
                fields["speaker"] = voice_match.group("speaker")
                cue = _extract_cue(voice_match)
                if cue:
                    fields["performance_cue"] = cue
            append_block("production_tag", span, **fields)
            index = end_index + 1
            continue

        any_tag = ANY_TAG_RE.match(paragraph)
        if any_tag:
            issues.append(
                _issue(
                    span,
                    "unsupported_production_tag",
                    f"不支持生产标签 [{any_tag.group('tag')}];仅支持 {', '.join(SUPPORTED_TAGS)}。",
                )
            )
            index = end_index + 1
            continue
        if MALFORMED_TAG_RE.match(paragraph):
            issues.append(_issue(span, "malformed_production_tag", "生产标签缺少闭合的 ]。"))
            index = end_index + 1
            continue

        known_dialogue_match = KNOWN_SPEAKER_DIALOGUE_RE.fullmatch(paragraph)
        if known_dialogue_match and known_dialogue_match.group("speaker") in active_speakers:
            append_block(
                "dialogue",
                span,
                speaker=known_dialogue_match.group("speaker"),
                performance_cue=_extract_cue(known_dialogue_match),
                production=False,
            )
            index = end_index + 1
            continue
        dialogue_match = DIALOGUE_RE.fullmatch(paragraph)
        if dialogue_match:
            issues.append(
                _issue(
                    span,
                    "ambiguous_dialogue_or_action",
                    "冒号前缀不在本次说话者清单中;由 write owner 判断是动作、画面文字还是对白。",
                )
            )
            index = end_index + 1
            continue
        if ASCII_DIALOGUE_RE.match(paragraph):
            issues.append(
                _issue(span, "invalid_dialogue_syntax", "未知说话者后不能使用半角冒号 :;请改用全角冒号 : 或声明说话者。")
            )
            index = end_index + 1
            continue
        if _looks_like_markdown(paragraph):
            issues.append(
                _issue(span, "unsupported_markdown", "该 Markdown 结构不属于受支持的剧本块。")
            )
            index = end_index + 1
            continue

        # Diagnosed last, so only paragraphs that would already be plain action
        # are reported. Anything a dialect writes with a colon (【音效:…】,
        # 【角色名】(括注):台词) has been claimed by the dialogue paths above
        # and keeps main's disposition, and the block is still emitted here, so
        # no block ID moves in either direction.
        fullwidth_tag = FULLWIDTH_TAG_RE.match(paragraph)
        if fullwidth_tag:
            issues.append(
                _issue(
                    span,
                    "unsupported_production_tag",
                    f"【{fullwidth_tag.group('tag')}】 是生产方言写法,不是本套件的生产标签;"
                    f"受支持的标签是半角 [ ] 加 {', '.join(SUPPORTED_TAGS)}。"
                    "先经规范化入口判断它应当成为动作、画面文字还是转场,再发布。",
                )
            )

        append_block("action", span, production=False)
        index = end_index + 1

    return blocks, issues


def _read_jsonl(path: Path) -> list[dict[str, Any]]:
    records: list[dict[str, Any]] = []
    for line_number, line in enumerate(path.read_text(encoding="utf-8").splitlines(), 1):
        if not line.strip():
            continue
        try:
            value = json.loads(line)
        except json.JSONDecodeError as error:
            raise ValueError(f"{path.name}:{line_number}: invalid JSONL: {error.msg}") from error
        if not isinstance(value, dict):
            raise ValueError(f"{path.name}:{line_number}: JSONL record must be an object")
        records.append(value)
    return records


def _resolve_previous_snapshot(
    records: list[dict[str, Any]],
    previous_source_path: Path,
) -> dict[str, str]:
    sources = load_sources(records)
    body = [record for record in records if record.get("record_type") != SOURCES_RECORD_TYPE]
    if not body or body[0].get("record_type") != "screenplay_index_meta":
        raise ValueError("previous index is missing screenplay_index_meta")
    resolved, _defect = resolve_ref(body[0].get("source_ref"), sources, "previous_index")
    if resolved is None:
        raise ValueError("previous index does not name its screenplay")
    return {
        "owner": resolved.owner,
        "artifact": _portable_source_ref(previous_source_path, resolved.artifact),
    }


def _load_previous(
    records: list[dict[str, Any]],
    previous_source_path: Path,
) -> list[dict[str, Any]]:
    # Without the previous screenplay's bytes a block's identity is its content
    # digest and nothing more: exact-content reuse still holds, split/merge
    # detection does not. A rewritten body block then loses its ID instead of
    # exception by design — they are reused on a stable scene_id, so an edited
    # heading keeps its ID; the scene is the same scene, and the blocks under it
    # are what carry the content.
    source_data = previous_source_path.read_bytes()
    sources = load_sources(records)
    body = [record for record in records if record.get("record_type") != SOURCES_RECORD_TYPE]
    if not body or body[0].get("record_type") != "screenplay_index_meta":
        raise ValueError("previous index is missing screenplay_index_meta")
    declared_length = body[0].get("source_byte_length")
    if (
        not isinstance(declared_length, int)
        or isinstance(declared_length, bool)
        or declared_length != len(source_data)
    ):
        raise ValueError(
            "previous index source_byte_length does not match previous source"
        )
    # The previous index must name the screenplay it was built from.
    resolved, _defect = resolve_ref(body[0].get("source_ref"), sources, "previous_index")
    if resolved is None:
        raise ValueError("previous index does not name its screenplay")
    _portable_source_ref(previous_source_path, resolved.artifact)
    previous_speakers = previous_index_speakers(records)
    parsed_blocks, _ = _parse_screenplay(source_data, previous_speakers)
    parsed_by_span = {
        (block["byte_start"], block["byte_end"], block["kind"]): block
        for block in parsed_blocks
    }
    previous: list[dict[str, Any]] = []
    seen_ids: set[str] = set()
    for record in records:
        if record.get("record_type") != "block":
            continue
        block_id = record.get("block_id")
        if not isinstance(block_id, str) or not BLOCK_ID_RE.fullmatch(block_id):
            raise ValueError("previous index contains an invalid block_id")
        if block_id in seen_ids:
            raise ValueError("previous index contains duplicate block_id values")
        seen_ids.add(block_id)
        byte_start = record.get("byte_start")
        byte_end = record.get("byte_end")
        kind = record.get("kind")
        if (
            not isinstance(byte_start, int)
            or not isinstance(byte_end, int)
            or isinstance(byte_start, bool)
            or isinstance(byte_end, bool)
            or not 0 <= byte_start < byte_end <= len(source_data)
            or kind not in KIND_CODES
        ):
            raise ValueError(f"previous block {block_id} does not resolve against previous source")
        parsed = parsed_by_span.get((byte_start, byte_end, kind))
        if parsed is None:
            raise ValueError(f"previous block {block_id} does not resolve against previous source")
        previous.append({**record, "_text": parsed["_text"], "_order": parsed["_order"]})
    return previous


def previous_index_speakers(records: list[dict[str, Any]]) -> frozenset[str]:
    """Recover the dialogue speaker roster an earlier index already resolved."""
    return frozenset(
        speaker.strip()
        for record in records
        if record.get("record_type") == "block"
        and record.get("kind") == "dialogue"
        and isinstance((speaker := record.get("speaker")), str)
        and speaker.strip()
    )


def _fingerprint(block: dict[str, Any]) -> tuple[Any, ...]:
    # Content identity comes from the prose, re-read from the previous screenplay.
    # No digest is stored in the index, so a rebuild without those bytes has
    # nothing to compare and renumbers by position.
    return (
        block["kind"],
        block.get("episode_id"),
        block.get("scene_id"),
        _normalized(block["_text"]),
    )


def _normalized(text: str) -> str:
    return re.sub(r"\s+", "", text)


def _mark_revision_mappings(
    current: list[dict[str, Any]],
    previous: list[dict[str, Any]],
) -> list[dict[str, Any]]:
    matched_current: set[int] = set()
    matched_previous: set[int] = set()

    old_headings: dict[tuple[str, str], list[int]] = defaultdict(list)
    new_headings: dict[tuple[str, str], list[int]] = defaultdict(list)
    for index, block in enumerate(previous):
        if block["kind"] == "scene_heading" and block.get("scene_id"):
            old_headings[(block["kind"], block["scene_id"])].append(index)
    for index, block in enumerate(current):
        if block["kind"] == "scene_heading" and block.get("scene_id"):
            new_headings[(block["kind"], block["scene_id"])].append(index)
    for key, new_indices in new_headings.items():
        old_indices = old_headings.get(key, [])
        if len(old_indices) == len(new_indices) == 1:
            old_index, new_index = old_indices[0], new_indices[0]
            current[new_index]["block_id"] = previous[old_index]["block_id"]
            current[new_index]["mapping"] = {
                "status": "reused",
                "reason": "stable_scene_id",
                "previous_block_ids": [previous[old_index]["block_id"]],
            }
            matched_current.add(new_index)
            matched_previous.add(old_index)

    old_groups: dict[tuple[Any, ...], list[int]] = defaultdict(list)
    new_groups: dict[tuple[Any, ...], list[int]] = defaultdict(list)
    for index, block in enumerate(previous):
        if index not in matched_previous:
            old_groups[_fingerprint(block)].append(index)
    for index, block in enumerate(current):
        if index not in matched_current:
            new_groups[_fingerprint(block)].append(index)
    duplicate_requests: list[dict[str, Any]] = []
    for fingerprint, new_indices in new_groups.items():
        old_indices = old_groups.get(fingerprint, [])
        pairs: list[tuple[int, int]] = []
        if len(old_indices) == len(new_indices) == 1:
            pairs = [(old_indices[0], new_indices[0])]
        elif len(old_indices) == len(new_indices) and old_indices:
            # Reuse repeated identical blocks only when their exact spans did not move.
            # Once a duplicate group moves, occurrence identity is ambiguous.
            by_start = {previous[old]["byte_start"]: old for old in old_indices}
            if all(current[new]["byte_start"] in by_start for new in new_indices):
                pairs = [(by_start[current[new]["byte_start"]], new) for new in new_indices]
        for old_index, new_index in pairs:
            current[new_index]["block_id"] = previous[old_index]["block_id"]
            current[new_index]["mapping"] = {
                "status": "reused",
                "reason": "exact_content",
                "previous_block_ids": [previous[old_index]["block_id"]],
            }
            matched_current.add(new_index)
            matched_previous.add(old_index)

        if old_indices and new_indices and not pairs:
            duplicate_requests.append(
                {
                    "reason": "duplicate_exact_match",
                    "previous_indices": old_indices,
                    "current_indices": new_indices,
                }
            )
            matched_current.update(new_indices)
            matched_previous.update(old_indices)

    return duplicate_requests + _find_split_merge_requests(
        current, previous, matched_current, matched_previous
    )


def _find_split_merge_requests(
    current: list[dict[str, Any]],
    previous: list[dict[str, Any]],
    matched_current: set[int],
    matched_previous: set[int],
) -> list[dict[str, Any]]:
    requests: list[dict[str, Any]] = []
    claimed_new: set[int] = set()
    claimed_old: set[int] = set()

    def compatible(blocks: list[dict[str, Any]]) -> bool:
        return bool(blocks) and all(
            block["kind"] == blocks[0]["kind"]
            and block.get("scene_id") == blocks[0].get("scene_id")
            and block["kind"] in {"action", "dialogue", "production_tag", "comment", "code_fence"}
            for block in blocks
        )

    for old_index, old in enumerate(previous):
        if old_index in matched_previous:
            continue
        old_text = _normalized(old["_text"])
        for start in range(len(current)):
            new_indices: list[int] = []
            new_parts: list[str] = []
            for item in range(start, len(current)):
                if item in matched_current or item in claimed_new:
                    break
                block = current[item]
                if not compatible([old, block]):
                    break
                new_indices.append(item)
                new_parts.append(_normalized(block["_text"]))
                combined = "".join(new_parts)
                if not old_text.startswith(combined):
                    break
                if len(new_indices) < 2:
                    continue
                if combined != old_text:
                    continue
                requests.append(
                    {
                        "reason": "split",
                        "previous_indices": [old_index],
                        "current_indices": new_indices,
                    }
                )
                claimed_old.add(old_index)
                claimed_new.update(new_indices)
                break
            if old_index in claimed_old:
                break

    for new_index, new in enumerate(current):
        if new_index in matched_current or new_index in claimed_new:
            continue
        new_text = _normalized(new["_text"])
        for start in range(len(previous)):
            old_indices: list[int] = []
            old_parts: list[str] = []
            for item in range(start, len(previous)):
                if item in matched_previous or item in claimed_old:
                    break
                block = previous[item]
                if not compatible([new, block]):
                    break
                old_indices.append(item)
                old_parts.append(_normalized(block["_text"]))
                combined = "".join(old_parts)
                if not new_text.startswith(combined):
                    break
                if len(old_indices) < 2:
                    continue
                if combined != new_text:
                    continue
                requests.append(
                    {
                        "reason": "merge",
                        "previous_indices": old_indices,
                        "current_indices": [new_index],
                    }
                )
                claimed_old.update(old_indices)
                claimed_new.add(new_index)
                break
            if new_index in claimed_new:
                break
    return requests


def _scope(block: dict[str, Any]) -> str:
    if block.get("scene_id"):
        return str(block["scene_id"])
    if block.get("episode_id"):
        return f"{block['episode_id']}-GLOBAL"
    return "GLOBAL"


def _assign_new_ids(
    current: list[dict[str, Any]],
    previous: list[dict[str, Any]],
    high_water: dict[str, int] | None = None,
) -> dict[str, int]:
    """Give every unmatched block an ID no earlier revision has used.

    Retirement has to outlive the revision that retired an ID. Seeding the
    counter from the previous index alone makes it one generation deep: once
    every block of one kind in a scene is gone, the counter restarts at zero and
    the next new block is handed a retired ID. A downstream artifact still
    citing it resolves cleanly and silently means something else -- which is
    exactly what resolving cleanly is supposed to rule out.

    So the highest number ever issued per (scene, kind) rides along in the index
    meta and is carried forward here.
    """

    reserved = {str(block["block_id"]) for block in previous}
    counters: dict[tuple[str, str], int] = defaultdict(int)
    for name, number in (high_water or {}).items():
        scope, _, code = name.rpartition("|")
        if scope and isinstance(number, int):
            counters[(scope, code)] = max(counters[(scope, code)], number)
    for block_id in reserved:
        match = BLOCK_ID_RE.fullmatch(block_id)
        assert match
        key = (match.group("scope"), match.group("code"))
        counters[key] = max(counters[key], int(match.group("number")))
    for block in current:
        if "block_id" in block:
            continue
        scope = _scope(block)
        code = KIND_CODES[block["kind"]]
        key = (scope, code)
        while True:
            counters[key] += 1
            candidate = f"BLK-{scope}-{code}{counters[key]:02d}"
            if candidate not in reserved:
                break
        reserved.add(candidate)
        block["block_id"] = candidate
        block["mapping"] = {
            "status": "new",
            "reason": "no_previous_exact_match",
            "previous_block_ids": [],
        }
    # Every ID this revision kept also counts, so a block reused from the
    # previous index cannot be reissued after it later disappears.
    for block in current:
        match = BLOCK_ID_RE.fullmatch(str(block.get("block_id", "")))
        if match:
            key = (match.group("scope"), match.group("code"))
            counters[key] = max(counters[key], int(match.group("number")))
    return {f"{scope}|{code}": number for (scope, code), number in counters.items()}


def _public_block(block: dict[str, Any], source_ref: dict[str, str]) -> dict[str, Any]:
    omitted = {"_raw", "_text", "_order"}
    return {
        "record_type": "block",
        "schema_version": SCHEMA_VERSION,
        **{key: value for key, value in block.items() if key not in omitted},
        "source_ref": source_ref,
    }


def _atomic_jsonl(path: Path, records: list[dict[str, Any]]) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    body = "".join(
        json.dumps(record, ensure_ascii=False, separators=(",", ":"), allow_nan=False) + "\n"
        for record in records
    ).encode("utf-8")
    descriptor, temporary_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
    temporary = Path(temporary_name)
    try:
        with os.fdopen(descriptor, "wb") as handle:
            handle.write(body)
            handle.flush()
            os.fsync(handle.fileno())
        os.replace(temporary, path)
    finally:
        temporary.unlink(missing_ok=True)


def _portable_source_ref(source: Path, source_ref: str | None) -> str:
    value = source.name if source_ref is None else source_ref
    if not isinstance(value, str) or not value:
        raise ValueError("source_ref must be a portable project-relative path")
    segments = value.split("/")
    candidate = Path(value)
    if (
        candidate.is_absolute()
        or any(segment in {"", ".", ".."} for segment in segments)
        or "://" in value
        or "\\" in value
        or re.match(r"^[A-Za-z]:", value)
    ):
        raise ValueError("source_ref must be a portable project-relative path")
    return candidate.as_posix()


def build_index(
    source_path: str | Path,
    output_path: str | Path,
    *,
    previous_index_path: str | Path | None = None,
    previous_source_path: str | Path | None = None,
    source_ref: str | None = None,
    authority: str = "accepted",
    speakers: list[str] | tuple[str, ...] | set[str] | frozenset[str] | None = None,
    no_previous: bool = False,
) -> dict[str, Any]:
    """Parse ``source_path`` and atomically publish its derived JSONL index."""
    source = Path(source_path)
    output = Path(output_path)
    if source.resolve() == output.resolve():
        raise ValueError("output path must not be the screenplay source path")
    if (previous_index_path is None) != (previous_source_path is None):
        raise ValueError("--previous-index and --previous-source must be supplied together")
    # Rebuilding over an existing index without naming a previous version
    # renumbers every block from scratch. Surviving text keeps whatever ID its
    # position now yields, so a rewritten block can reclaim the retired ID and
    # every downstream reference to it silently resolves to different content --
    # the exact failure the content-stable path exists to prevent. Refuse, and
    # name the file, rather than produce that index quietly.
    if previous_index_path is None and not no_previous and output.exists():
        raise ValueError(
            f"{output} already holds an index; pass --previous-index {output} "
            f"--previous-source <the screenplay before this revision> to keep block "
            f"IDs stable by content, or --no-previous to renumber from scratch"
        )
    if authority not in {"accepted", "candidate"}:
        raise ValueError("authority must be accepted or candidate")
    raw_speakers = tuple(speakers or ())
    if any(not isinstance(speaker, str) or not speaker.strip() for speaker in raw_speakers):
        raise ValueError("speaker names must be non-empty text")
    speaker_names = frozenset(" ".join(speaker.split()) for speaker in raw_speakers)
    if any(
        len(speaker) > MAX_SPEAKER_LENGTH
        or DIALOGUE_RE.fullmatch(f"{speaker}:占位") is None
        for speaker in speaker_names
    ):
        raise ValueError("speaker names must match the screenplay dialogue label grammar")

    source_data = source.read_bytes()
    declared_sources: dict[str, dict[str, str]] = {
        SCREENPLAY_SOURCE_KEY: {
            "owner": "short-drama-write",
            "artifact": _portable_source_ref(source, source_ref),
        }
    }
    source_artifact_ref: dict[str, str] = {"src": SCREENPLAY_SOURCE_KEY}
    if authority == "candidate":
        source_artifact_ref["authority"] = "candidate"
    previous_records: list[dict[str, Any]] = []
    if previous_index_path is not None:
        previous_records = _read_jsonl(Path(previous_index_path))
        # Union, not replacement: a reviser who adds one new speaker passes only
        # that name, and dropping the rest would turn every other dialogue line
        # back into an ambiguous block and change its ID.
        speaker_names |= previous_index_speakers(previous_records)
    current, source_issues = _parse_screenplay(source_data, speaker_names)
    previous: list[dict[str, Any]] = []
    raw_requests: list[dict[str, Any]] = []
    previous_source_ref: dict[str, str] | None = None
    # Carried from the previous index so a retired ID stays retired even after
    # every block that was using it has gone.
    previous_high_water: dict[str, int] = {}
    for record in previous_records:
        if record.get("record_type") == "screenplay_index_meta":
            declared = record.get("block_id_high_water")
            if isinstance(declared, dict):
                previous_high_water = {
                    str(name): number
                    for name, number in declared.items()
                    if isinstance(number, int) and not isinstance(number, bool)
                }
            break
    if previous_index_path is not None and previous_source_path is not None:
        previous_source = Path(previous_source_path)
        previous = _load_previous(previous_records, previous_source)
        previous_snapshot = _resolve_previous_snapshot(previous_records, previous_source)
        previous_key = SCREENPLAY_SOURCE_KEY
        if previous_snapshot != declared_sources[SCREENPLAY_SOURCE_KEY]:
            previous_key = PREVIOUS_SCREENPLAY_SOURCE_KEY
            declared_sources[previous_key] = previous_snapshot
        previous_source_ref = {"src": previous_key}
        if authority == "candidate":
            previous_source_ref["authority"] = "candidate"
        raw_requests = _mark_revision_mappings(current, previous)
    block_id_high_water = _assign_new_ids(
        current, previous, previous_high_water
    )

    review_requests: list[dict[str, Any]] = []
    for number, request in enumerate(raw_requests, 1):
        old_ids = [previous[index]["block_id"] for index in request["previous_indices"]]
        new_ids = [current[index]["block_id"] for index in request["current_indices"]]
        for index in request["current_indices"]:
            current[index]["mapping"] = {
                "status": "unresolved",
                "reason": request["reason"],
                "previous_block_ids": old_ids,
            }
        review_requests.append(
            {
                "record_type": "mapping_review_request",
                "schema_version": SCHEMA_VERSION,
                "request_id": f"MAP-REVIEW-{number:03d}",
                "reason": request["reason"],
                "status": "unresolved",
                "previous_block_ids": old_ids,
                "current_block_ids": new_ids,
                "instruction": "创作者或 write owner 必须显式选择重映射;索引器不会猜测。",
            }
        )

    issue_records = [
        {
            "record_type": "source_issue",
            "schema_version": SCHEMA_VERSION,
            "issue_id": f"SOURCE-ISSUE-{number:03d}",
            **issue,
            "source_ref": source_artifact_ref,
        }
        for number, issue in enumerate(source_issues, 1)
    ]
    review_status = "review_required" if issue_records or review_requests else "clean"
    meta = {
        "record_type": "screenplay_index_meta",
        "schema_version": SCHEMA_VERSION,
        "source_ref": source_artifact_ref,
        "source_byte_length": len(source_data),
        "newline_style": _newline_style(source_data),
        "previous_source_ref": previous_source_ref,
        "block_count": len(current),
        "source_issue_count": len(issue_records),
        "mapping_review_count": len(review_requests),
        "review_status": review_status,
        # The highest block number ever issued per scene and kind. Carried
        # forward so a retired ID stays retired after the blocks that were
        # using it are gone.
        "block_id_high_water": dict(sorted(block_id_high_water.items())),
        SOURCES_KEY: declared_sources,
    }
    records = [meta]
    records.extend(_public_block(block, source_artifact_ref) for block in current)
    records.extend(issue_records)
    records.extend(review_requests)
    _atomic_jsonl(output, records)
    return {
        "output": str(output),
        "block_count": len(current),
        "source_issue_count": len(issue_records),
        "mapping_review_count": len(review_requests),
        "review_status": review_status,
    }


def _parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        description="Build a byte-accurate derived screenplay-index.jsonl without editing 剧本.md."
    )
    parser.add_argument("source", type=Path, help="UTF-8 Markdown screenplay source")
    parser.add_argument("--output", type=Path, help="output JSONL path")
    parser.add_argument("--previous-index", type=Path)
    parser.add_argument("--previous-source", type=Path)
    parser.add_argument(
        "--no-previous",
        action="store_true",
        help="renumber block IDs from scratch, abandoning the IDs downstream artifacts cite",
    )
    parser.add_argument(
        "--source-ref",
        help="portable project-relative source reference; defaults to the source basename",
    )
    parser.add_argument(
        "--authority",
        choices=("accepted", "candidate"),
        default="accepted",
        help="mark source refs candidate for a provisional normalization preview",
    )
    parser.add_argument(
        "--speaker",
        action="append",
        default=[],
        help="repeat for each agent-resolved dialogue speaker label",
    )
    parser.add_argument(
        "--fail-on-review",
        action="store_true",
        help="return exit code 2 after writing when source or mapping review is required",
    )
    return parser


def main(argv: list[str] | None = None) -> int:
    args = _parser().parse_args(argv)
    output = args.output or args.source.with_name("screenplay-index.jsonl")
    try:
        summary = build_index(
            args.source,
            output,
            previous_index_path=args.previous_index,
            previous_source_path=args.previous_source,
            source_ref=args.source_ref,
            authority=args.authority,
            speakers=args.speaker,
            no_previous=args.no_previous,
        )
    except (OSError, UnicodeDecodeError, ValueError) as error:
        print(
            json.dumps({"error": str(error)}, ensure_ascii=True, allow_nan=False),
            file=sys.stderr,
        )
        return 1
    print(json.dumps(summary, ensure_ascii=True, sort_keys=True, allow_nan=False))
    if args.fail_on_review and summary["review_status"] != "clean":
        return 2
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall