zenstory-ai/drama-skills / skills/short-drama-write
short-drama-write
Verified编写或修订可拍摄的中文短剧、漫剧单集 Markdown 剧本,也负责保留作者原文并把现成剧本整理成标准格式。用户提出“写/改一集短剧”“把大纲写成剧本”“优化场景/对白”“去模板感”“去 AI 味润色”“续写下一集”或提供剧本要求进入后续制作时使用;不负责视觉设定、分镜、生图与视频提示词或终审。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.2 KB |
| agents/openai.yaml | config | 288 B |
| references/dialogue-craft.md | markdown | 12.0 KB |
| references/production-format-dialect.md | markdown | 2.0 KB |
| references/screenplay-format.md | markdown | 7.8 KB |
| references/script-craft.md | markdown | 19.3 KB |
| references/stage-contract.md | markdown | 7.2 KB |
| scripts/duration_estimate.py | script | 44.0 KB |
| scripts/screenplay_index.py | script | 57.7 KB |
| scripts/selftest.py | script | 7.1 KB |
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())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| 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: 194k | Updated | Claude CodeCodex | Verified | Install |