@oh-story/dsh 0.1.6 → 0.1.7

package/lib/drama/skills/short-drama/scripts/creator_markdown_check.py

@@ -39,6 +39,18 @@ REF_RE = re.compile(
     r"（(?:用途：([^；）\n]+)；)?控制：([^；）]+)；不得控制：([^）]+)）",
     re.IGNORECASE,
 )
+# The same slot grammar, but the locator is a document entry instead of a file.
+# A creator who generates in an external tool never has the file inside the
+# project, and the copyable body only ever needed 顺序 and 用途 -- the path is a
+# production input, not a prompt input. PLAN says "this picture does not exist
+# here; attach it yourself in this order", which is a different claim from
+# 「已有图片」 and from 「待补」.
+PLAN_RE = re.compile(
+    r"(PLAN-[A-Z0-9-]+)（顺序：([1-9]\d*)）· "
+    r"((?:IMG|SHOT)-[A-Z0-9-]+)《([^》\n]+)》"
+    r"（(?:用途：([^；）\n]+)；)?控制：([^；）]+)；不得控制：([^）]+)）",
+    re.IGNORECASE,
+)
 # One picture answers one question. 「同一张图承担两个作用时分开说明」 in
 # references/reference-roles.md is what makes a slot translatable into a
 # provider role, so the vocabulary is closed rather than free prose.
@@ -53,6 +65,32 @@ REF_PURPOSES = (
     "结束帧",
     "风格",
 )
+# `EP001-SC001` is the documented shape, but a project that scopes ids by season
+# writes `S01-EP001-SC001`. Both are one stable scene id, so the pattern takes
+# any hyphenated prefix rather than exactly one segment.
+SLOT_HEAD_RE = re.compile(
+    r"(?:REF|PLAN)-[A-Za-z0-9][A-Za-z0-9-]*（顺序：", re.IGNORECASE
+)
+SCENE_ID_PATTERN = r"(?:[A-Za-z0-9]+-)+SC[0-9]+"
+SCENE_HEADING_RE = re.compile(
+    r"^## (" + SCENE_ID_PATTERN + r")\b", re.MULTILINE
+)
+SCENE_ID_RE = re.compile(SCENE_ID_PATTERN)
+# A scene the storyboard decided not to film. SHT-01 has always allowed the
+# omission and always required a reason; without a place to write it the
+# omission and an oversight look identical in the finished document.
+UNFILMED_LINE_RE = re.compile(
+    r"^[ \t\u3000]*[-*+][ \t\u3000]*未拍场次[：:](.*)$", re.MULTILINE
+)
+UNFILMED_ENTRY_RE = re.compile(
+    r"(" + SCENE_ID_PATTERN + r")（理由：([^）\n]+)）"
+)
+# Dialogue reaches the model as a quoted run, either inside the H3 `<d>` tag or
+# inside quotation marks. Runs shorter than four Han characters are in-frame
+# labels and interjections far more often than they are lines, so the check
+# stays off them rather than inventing an escape hatch for signage.
+SPOKEN_SPAN_RE = re.compile(r"<d>([^<]*)</d>|[\"“]([^\"”]*)[\"”]|「([^」]*)」")
+SPOKEN_RUN_RE = re.compile(r"[\u3400-\u9fff]{4,}")
 EXPLICIT_TEXT_TO_VIDEO = "无（创作者已明确选择文生视频）"
 PENDING_REFERENCE_SUFFIX_RE = re.compile(r"；待补参考图：[^；。\n]+。?$")
 VISUAL_CATEGORIES = ("人物", "造型", "地点", "道具")
@@ -151,9 +189,22 @@ def _contains_ref_token(value: str) -> bool:
     return "ref-" in value.casefold()
 
 
+def _contains_plan_token(value: str) -> bool:
+    return "plan-" in value.casefold()
+
+
+def _contains_slot_token(value: str) -> bool:
+    return _contains_ref_token(value) or _contains_plan_token(value)
+
+
 def _is_none(value: str) -> bool:
-    return not _contains_ref_token(value) and bool(
-        re.fullmatch(r"无(?:（[^）]+）)?", _plain(value))
+    # `[^）]+` would stop at the first closing bracket, so a gap list that names
+    # an entry in brackets -- 「江晨人物图（IMG-...）」 -- fell through to the REF
+    # syntax error, whose obvious repair is deleting the gap record. That is the
+    # silent downgrade this contract exists to prevent, so the note takes any
+    # content as long as it is bracketed.
+    return not _contains_slot_token(value) and bool(
+        re.fullmatch(r"无(?:（.+）)?", _plain(value), re.DOTALL)
     )
 
 
@@ -169,7 +220,7 @@ def _has_pending_references(value: str) -> bool:
 
 
 def _is_no_external_reference(value: str) -> bool:
-    return not _contains_ref_token(value) and bool(
+    return not _contains_slot_token(value) and bool(
         re.fullmatch(r"无(?:外部参考)?(?:；[^\n]*)?。?", value.strip())
     )
 
@@ -205,20 +256,53 @@ def _inside(path: Path, root: Path) -> bool:
     return resolved == root or root in resolved.parents
 
 
-def _references(value: str, owner: str, project_root: Path, errors: list[str]) -> None:
+class EntryIndex(NamedTuple):
+    """The document entries a `PLAN-...` locator is allowed to name."""
+
+    images: dict[str, str]
+    shots: frozenset
+
+
+def _slot_matches(value: str) -> list:
+    """Every `REF-...` and `PLAN-...` slot in `value`, in written order.
+
+    The two patterns cannot match the same span: a REF locator has to be an
+    image path and a PLAN locator has to be an `IMG-`/`SHOT-` id.
+    """
+    found = []
+    for kind, pattern in (("REF", REF_RE), ("PLAN", PLAN_RE)):
+        for match in pattern.finditer(value):
+            found.append((match.start(), match.end(), kind, match.groups()))
+    found.sort(key=lambda item: item[0])
+    return found
+
+
+def _references(
+    value: str,
+    owner: str,
+    project_root: Path,
+    errors: list[str],
+    entries: Optional[EntryIndex] = None,
+) -> frozenset:
+    """Validate one 输入参考图/参考 declaration; return the slot kinds it uses."""
     if _is_none(value):
-        return
+        return frozenset()
     reference_value = PENDING_REFERENCE_SUFFIX_RE.sub("", value.strip())
-    matches = list(REF_RE.finditer(value))
+    matches = _slot_matches(reference_value)
     cursor = 0
     separators_are_valid = True
-    for index, match in enumerate(matches):
-        if reference_value[cursor : match.start()] != ("" if index == 0 else "；"):
+    for index, (start, end, _kind, _groups) in enumerate(matches):
+        if reference_value[cursor:start] != ("" if index == 0 else "；"):
             separators_are_valid = False
-        cursor = match.end()
+        cursor = end
     trailing = reference_value[cursor:]
+    # Counted as slot heads on the same text the slots were matched in. A bare
+    # token count would read the `ref-` in a real path like
+    # `输入/参考图/ref-江晨.png` as a second slot and reject a correct declaration.
+    declared = len(SLOT_HEAD_RE.findall(reference_value))
+    kinds = frozenset(item[2] for item in matches)
     if (
-        len(matches) != len(re.findall(r"\bREF-[A-Z0-9-]+\b", value))
+        len(matches) != declared
         or not matches
         or not separators_are_valid
         or trailing not in {"", "。"}
@@ -231,34 +315,38 @@ def _references(value: str, owner: str, project_root: Path, errors: list[str]) -
                 f"{owner}: 待补参考图必须写在最后一个 REF 槽位之后，"
                 "缺口之间只用、分隔"
             )
+        elif _contains_plan_token(value) and not _contains_ref_token(value):
+            errors.append(f"{owner}: 输入参考图必须使用完整 PLAN 语法")
         else:
             errors.append(f"{owner}: 输入参考图必须使用完整 REF 语法")
-        return
-    refs = [(match.group(1), int(match.group(2)), match.group(3)) for match in matches]
-    slots = [item[0] for item in refs]
-    orders = [item[1] for item in refs]
-    paths = [item[2] for item in refs]
+        return kinds
+    groups = [item[3] for item in matches]
+    slot_kinds = [item[2] for item in matches]
+    slots = [group[0] for group in groups]
+    orders = [int(group[1]) for group in groups]
+    locators = [group[2] for group in groups]
+    purposes = [(group[4] or "").strip() for group in groups]
+    # A declaration made only of PLAN slots is not a REF declaration, so its
+    # diagnostics must not send the creator looking for a REF line.
+    noun = "PLAN" if kinds == frozenset({"PLAN"}) else "REF"
     if len(slots) != len(set(slots)):
-        errors.append(f"{owner}: REF 槽位重复")
+        errors.append(f"{owner}: {noun} 槽位重复")
     if len(orders) != len(set(orders)) or sorted(orders) != list(
         range(1, len(orders) + 1)
     ):
-        errors.append(f"{owner}: REF 顺序必须唯一且从 1 连续编号")
-    purposes = [
-        match.group(5).strip() if match.group(5) else "" for match in matches
-    ]
-    path_purposes = list(zip(paths, purposes))
-    if len(path_purposes) != len(set(path_purposes)):
-        errors.append(f"{owner}: REF 路径与用途完全重复")
+        errors.append(f"{owner}: {noun} 顺序必须唯一且从 1 连续编号")
+    locator_purposes = list(zip(locators, purposes))
+    if len(locator_purposes) != len(set(locator_purposes)):
+        errors.append(f"{owner}: {noun} 路径与用途完全重复")
     for slot, purpose in zip(slots, purposes):
         if not purpose:
             errors.append(
-                f"{owner}: REF 缺少用途: {slot}；用途只能是"
+                f"{owner}: {noun} 缺少用途: {slot}；用途只能是"
                 f"{'、'.join(REF_PURPOSES)}其中一个"
             )
         elif purpose not in REF_PURPOSES:
             errors.append(
-                f"{owner}: REF 用途不在允许集合内: {slot}（{purpose}）；"
+                f"{owner}: {noun} 用途不在允许集合内: {slot}（{purpose}）；"
                 f"只能是{'、'.join(REF_PURPOSES)}"
             )
     for role in ("起始帧", "结束帧"):
@@ -266,28 +354,72 @@ def _references(value: str, owner: str, project_root: Path, errors: list[str]) -
             errors.append(f"{owner}: 同一条目只能有一张{role}参考图")
     if "结束帧" in purposes and "起始帧" not in purposes:
         errors.append(f"{owner}: 绑定结束帧参考图时必须同时绑定起始帧")
-    for match, (_, _, raw_path) in zip(matches, refs):
-        label, may_control, must_not_control = (
-            match.group(4),
-            match.group(6),
-            match.group(7),
-        )
-        if not _portable_path(raw_path):
-            errors.append(f"{owner}: REF 路径不是安全的项目相对路径: {raw_path}")
+    for index, (kind, group) in enumerate(zip(slot_kinds, groups)):
+        slot, raw_locator, label = group[0], group[2], group[3]
+        may_control, must_not_control = group[5], group[6]
+        if kind == "REF":
+            if not _portable_path(raw_locator):
+                errors.append(
+                    f"{owner}: REF 路径不是安全的项目相对路径: {raw_locator}"
+                )
+            else:
+                reference_path = project_root / raw_locator
+                if not _inside(reference_path, project_root):
+                    errors.append(f"{owner}: REF 路径越出项目根目录: {raw_locator}")
+                elif not reference_path.is_file():
+                    errors.append(f"{owner}: REF 文件不存在: {raw_locator}")
         else:
-            reference_path = project_root / raw_path
-            if not _inside(reference_path, project_root):
-                errors.append(f"{owner}: REF 路径越出项目根目录: {raw_path}")
-            elif not reference_path.is_file():
-                errors.append(f"{owner}: REF 文件不存在: {raw_path}")
+            _plan_locator(
+                raw_locator, label, owner, slot, purposes[index], entries, errors
+            )
         if not re.search(r"[\u4e00-\u9fff]", label):
-            errors.append(f"{owner}: REF 缺少中文名称: {match.group(1)}")
+            errors.append(f"{owner}: {kind} 缺少中文名称: {slot}")
         if not may_control.strip() or not must_not_control.strip():
-            errors.append(f"{owner}: REF 必须同时声明控制与不得控制: {match.group(1)}")
+            errors.append(f"{owner}: {kind} 必须同时声明控制与不得控制: {slot}")
         allowed = {item.strip() for item in re.split(r"[、,，]", may_control)}
         prohibited = {item.strip() for item in re.split(r"[、,，]", must_not_control)}
         if "" in allowed or "" in prohibited or allowed & prohibited:
-            errors.append(f"{owner}: REF 控制与不得控制范围冲突: {match.group(1)}")
+            errors.append(f"{owner}: {kind} 控制与不得控制范围冲突: {slot}")
+    return kinds
+
+
+def _plan_locator(
+    locator: str,
+    label: str,
+    owner: str,
+    slot: str,
+    purpose: str,
+    entries: Optional[EntryIndex],
+    errors: list[str],
+) -> None:
+    """A planned picture still has to name an entry that exists today.
+
+    The picture itself is the creator's to supply, but what it depicts is
+    already decided by an `IMG-...` board or a `SHOT-...` frozen keyframe. A
+    locator that resolves to neither is a reference nobody can act on.
+    """
+    if entries is None:
+        return
+    if locator.startswith("IMG-"):
+        if locator not in entries.images:
+            errors.append(f"{owner}: PLAN 指向不存在的 IMG 条目: {locator}")
+        elif label != entries.images[locator]:
+            errors.append(f"{owner}: PLAN 中文名称与 IMG 标题不一致: {slot}")
+    elif locator.startswith("SHOT-"):
+        if locator not in entries.shots:
+            errors.append(f"{owner}: PLAN 指向不存在的 SHOT 条目: {locator}")
+        elif purpose == "起始帧":
+            # The picture that opens this shot is this shot's own frozen
+            # keyframe. Another shot's keyframe opens a different moment.
+            own = re.sub(r"^(?:SHOT|MOTION)-", "SHOT-", owner)
+            if own.startswith("SHOT-") and locator != own:
+                errors.append(
+                    f"{owner}: 起始帧 PLAN 必须指向本镜的冻结关键帧: {locator}"
+                )
+    else:
+        errors.append(
+            f"{owner}: PLAN 定位符只能是 IMG-... 或 SHOT-...: {locator}"
+        )
 
 
 def _excerpt(value: str, limit: int = 60) -> str:
@@ -777,6 +909,112 @@ def _check_continuity_locks(
                 errors.append(f"{lock_id}: {image_id} 可复制提示词缺少锁面")
 
 
+def _storyboard_head(storyboard: str) -> str:
+    """The part of 分镜.md that belongs to the episode rather than to a shot."""
+    match = re.search(r"^## SHOT-", storyboard, re.MULTILINE)
+    return storyboard if match is None else storyboard[: match.start()]
+
+
+def _shot_sources(
+    value: str, owner: str, scenes: "frozenset", errors: list[str]
+) -> list:
+    """Resolve one shot's 来源 against the scene ids that exist in 剧本.md."""
+    plain = _plain(value)
+    if not plain:
+        errors.append(f"{owner}: 缺少来源字段")
+        return []
+    # 《镜头手艺》 asks for the scene id plus a short quote of the source line,
+    # and a quote contains commas of its own. So the ids are read out of the
+    # field rather than by cutting it into pieces on punctuation.
+    if SCENE_ID_RE.match(plain) is None:
+        errors.append(
+            f"{owner}: 来源必须以《剧本.md》的场景 ID 开头: {_excerpt(plain, 24)}"
+        )
+        return []
+    resolved = []
+    for scene_id in _unique(SCENE_ID_RE.findall(plain)):
+        if scene_id not in scenes:
+            errors.append(f"{owner}: 来源场景不在《剧本.md》中: {scene_id}")
+        else:
+            resolved.append(scene_id)
+    return resolved
+
+
+def _unfilmed_scenes(
+    storyboard: str, scenes: "frozenset", errors: list[str]
+) -> dict:
+    """Scenes 分镜.md declares it deliberately does not film, with reasons."""
+    head = _storyboard_head(storyboard)
+    declared: dict = {}
+    # The line belongs to the episode, not to a shot. Placed inside a SHOT
+    # section it would be read as that shot's field and quietly do nothing,
+    # which looks exactly like forgetting to write it.
+    if len(UNFILMED_LINE_RE.findall(storyboard)) != len(
+        UNFILMED_LINE_RE.findall(head)
+    ):
+        errors.append("分镜.md: 未拍场次要写在第一个 SHOT 之前的正文开头")
+    for value in UNFILMED_LINE_RE.findall(head):
+        value = value.strip()
+        entries = UNFILMED_ENTRY_RE.findall(value)
+        remainder = UNFILMED_ENTRY_RE.sub("", value).strip("；;。 ")
+        if not entries or remainder:
+            errors.append(
+                "分镜.md: 未拍场次必须写成 <场景 ID>（理由：……），多项用；分隔"
+            )
+            continue
+        for scene_id, reason in entries:
+            if not reason.strip():
+                errors.append(f"分镜.md: 未拍场次缺少理由: {scene_id}")
+            elif scene_id not in scenes:
+                errors.append(f"分镜.md: 未拍场次不在《剧本.md》中: {scene_id}")
+            else:
+                declared[scene_id] = reason.strip()
+    return declared
+
+
+def _spoken_key(value: str) -> str:
+    """Drop punctuation and spacing so quoting choices do not decide identity."""
+    return re.sub(r"[^\u3400-\u9fff0-9A-Za-z]", "", value)
+
+
+def _quoted_speech(prompt: str) -> list:
+    # The body is one prompt; a quote that happens to wrap across lines is the
+    # same quote. Chinese does not separate words with spaces, so rejoining the
+    # lines reconstructs the run exactly.
+    joined = prompt.replace("\n", "")
+    runs: list = []
+    for match in SPOKEN_SPAN_RE.finditer(joined):
+        span = next((group for group in match.groups() if group), "")
+        # An unpaired quotation mark can pair with one much later and swallow
+        # the narration between them. That span is not a quotation, so it is
+        # not evidence of an invented line either.
+        if len(span) > 200:
+            continue
+        runs.extend(SPOKEN_RUN_RE.findall(span))
+    return runs
+
+
+def _check_spoken_lines(
+    prompt: str, owner: str, sources: "tuple", errors: list[str]
+) -> None:
+    """Quoted Chinese in a copyable body has to come from an upstream document.
+
+    The video stage already owes the screenplay verbatim dialogue. Checking it
+    here is what stops a prompt from writing the line the shot wishes the
+    character had said. 视觉设定.md and 分镜.md count as sources too: a location
+    or prop entry carries the exact text on a sign, and a shot's own fields
+    carry the on-screen text and sound this shot was designed around. What no
+    upstream document contains is a line the prompt made up.
+    """
+    for run in _quoted_speech(prompt):
+        key = _spoken_key(run)
+        if key and not any(key in source for source in sources):
+            errors.append(
+                f"{owner}: 可复制提示词的引文在《剧本.md》《视觉设定.md》《分镜.md》里都找不到: "
+                f"{_excerpt(run, 24)}"
+            )
+
+
 def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list[str]:
     """Return all deterministic contract errors for ``episode``."""
     episode = episode.resolve()
@@ -790,6 +1028,22 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
     storyboard = (episode / "分镜.md").read_text(encoding="utf-8")
     video = (episode / "视频提示词.md").read_text(encoding="utf-8")
     visual = (episode / "视觉设定.md").read_text(encoding="utf-8")
+    screenplay = (episode / "剧本.md").read_text(encoding="utf-8")
+    scene_headings = SCENE_HEADING_RE.findall(screenplay)
+    scenes = frozenset(scene_headings)
+    if not scenes:
+        errors.append(
+            "剧本.md: 没有可解析的场景标题；场景标题写成 ## <场景 ID> 内|外 · 地点 · 时间"
+        )
+    if len(scene_headings) != len(scenes):
+        errors.append("剧本.md: 场景 ID 重复")
+    spoken_sources = (
+        _spoken_key(screenplay),
+        _spoken_key(visual),
+        _spoken_key(storyboard),
+    )
+    unfilmed = _unfilmed_scenes(storyboard, scenes, errors)
+    claimed_scenes: set = set()
     locks = _continuity_locks(visual, errors)
     visual_entries = _visual_entries(visual, errors)
     other_headings = {
@@ -797,8 +1051,12 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
         for match in OTHER_SETTING_HEADING_RE.finditer(visual)
         if match.group(1).strip() not in VISUAL_CATEGORIES
     }
+    shots = _sections(storyboard, "SHOT")
     image_pairs = re.findall(r"^## (IMG-[A-Z0-9-]+) · (.+)$", images, re.MULTILINE)
     image_headings = dict(image_pairs)
+    # A planned picture names the board or keyframe that already decides what it
+    # depicts, so both indexes have to exist before any declaration is read.
+    entries = EntryIndex(images=image_headings, shots=frozenset(shots))
     all_image_headings = re.findall(r"^## (IMG-[A-Z0-9-]+)\b", images, re.MULTILINE)
     if len(image_pairs) != len(all_image_headings):
         errors.append("图片提示词.md: IMG 标题必须包含中文名称")
@@ -823,7 +1081,9 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
         elif _is_no_external_reference(reference_value):
             pass
         elif "REF-" in reference_value:
-            _references(reference_value, match.group(1), project_root, errors)
+            _references(
+                reference_value, match.group(1), project_root, errors, entries
+            )
         else:
             errors.append(
                 f"{match.group(1)}: 参考必须声明无外部参考或使用完整 REF 语法"
@@ -833,7 +1093,6 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
         if image_prompt is None:
             errors.append(f"{match.group(1)}: 缺少唯一且非空的可复制提示词")
 
-    shots = _sections(storyboard, "SHOT")
     motions = _sections(video, "MOTION")
     shot_ids = re.findall(r"^## (SHOT-[A-Z0-9-]+)\b", storyboard, re.MULTILINE)
     motion_ids = re.findall(r"^## (MOTION-[A-Z0-9-]+)\b", video, re.MULTILINE)
@@ -883,6 +1142,9 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
 
     for shot_id, shot_body in shots.items():
         fields = _fields(shot_body, owner=shot_id, errors=errors)
+        claimed_scenes.update(
+            _shot_sources(fields.get("来源", ""), shot_id, scenes, errors)
+        )
         image_value = fields.get("图片提示词项", "")
         if not image_value:
             errors.append(f"{shot_id}: 缺少图片提示词项字段")
@@ -902,7 +1164,7 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
         shot_input = fields.get("输入参考图", "")
         if not shot_input:
             errors.append(f"{shot_id}: 缺少输入参考图字段")
-        _references(shot_input, shot_id, project_root, errors)
+        _references(shot_input, shot_id, project_root, errors, entries)
 
         basis_value = fields.get("视觉依据", "")
         if not basis_value:
@@ -927,19 +1189,27 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
             continue
         motion_id, motion_body, copyable_prompt = motion
         motion_fields = _fields(motion_body, owner=motion_id, errors=errors)
+        if copyable_prompt is not None:
+            _check_spoken_lines(
+                copyable_prompt, motion_id, spoken_sources, errors
+            )
         motion_input = motion_fields.get("输入参考图", "")
-        _references(motion_input, motion_id, project_root, errors)
+        _references(motion_input, motion_id, project_root, errors, entries)
         if _plain(motion_input) != _plain(shot_input):
             errors.append(f"{motion_id}: 输入参考图与 {shot_id} 不一致")
 
         if _has_pending_references(shot_input):
             errors.append(f"{motion_id}: 仍有待补参考图，不能生成最终视频提示词")
 
-        has_real_image = not _is_none(shot_input)
-        expected_mode = "图生视频" if has_real_image else "文生视频"
+        # A `PLAN-...` slot is not a file, but the prompt is still written for
+        # image-conditioned generation: the creator attaches those pictures at
+        # generation time. What decides 生成方式 is whether the shot sends
+        # pictures at all, not whether this suite can read them.
+        sends_pictures = not _is_none(shot_input)
+        expected_mode = "图生视频" if sends_pictures else "文生视频"
         if _plain(motion_fields.get("生成方式", "")) != expected_mode:
             errors.append(f"{motion_id}: 生成方式应为{expected_mode}")
-        if not has_real_image:
+        if not sends_pictures:
             if not _is_explicit_text_to_video(shot_input):
                 errors.append(
                     f"{motion_id}: 无真实输入参考图时不能静默降级为文生视频；"
@@ -965,6 +1235,16 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
                     anchor, motion_id, "静态视觉锚点", basis, visual_entries, errors
                 )
 
+    for scene_id in scene_headings:
+        if scene_id in claimed_scenes or scene_id in unfilmed:
+            continue
+        errors.append(
+            f"分镜.md: 没有镜头承载场景 {scene_id}；"
+            "拍它就写进某一镜的来源，不拍就写进未拍场次并给出理由"
+        )
+    for scene_id in sorted(set(unfilmed) & claimed_scenes):
+        errors.append(f"分镜.md: 场景 {scene_id} 既被镜头承载又记为未拍")
+
     _check_language_designators(
         project_root, entries=visual_entries, errors=errors
     )

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

@@ -16,13 +16,16 @@ license: MIT
 取出本次提示词，建立一个有边界的运行 job。creator-first job 的 `source` 必须指向拥有这条提示词的
 当前 Markdown，`source_entry` 必须点名该文档允许的二级标题：`图片提示词.md` 用 `IMG-*`，
 `视频提示词.md` 用 `MOTION-*`，`分镜.md` 用 `SHOT-*`（modality 为 `image`，正文取该镜的
-`### 冻结关键帧提示词`）。分镜这一路是本套件里唯一能把某一镜的起始画面渲染成文件的入口；
+`### 冻结关键帧提示词`）。分镜这一路是本套件里唯一能把某一镜的起始画面渲染成文件的入口，但不是创作者获得起始帧的唯一办法——
+在自己的工具里出图再放进项目同样成立，图片始终不进项目时走分镜的 `PLAN-...`；
 产出落在 `剧集/<EP>/制作成果/images/` 后，分镜 owner 才能把它绑成 `用途：起始帧` 的 `REF-...`。存在真实参考图时，
 还必须逐张填写 `reference_bindings` 的槽位、顺序、路径、中文名、用途以及允许/禁止控制范围；
 内置视频 adapter 把这里的 `用途` 字段读成供应商自己的 role，只接受它公布的取值
 （MiniMax 为 `first_frame`/`last_frame`/`reference_image`/`reference_video`/`reference_audio`，
 Seedance 为三个 `reference_*`）；带参考图却没有绑定的 job 会直接失败，不替它猜一个 role。
 本地图片由内置 adapter 按 base64 data URI 直接送出，不需要自建上传服务。
+条目的「输入参考图」写成 `PLAN-...` 时，那些图片在创作者自己的工具里，项目内没有文件可送：
+`prepare` 直接失败并说明先把真实文件放进项目、改写成 `REF-...`，不拿计划当输入，也不静默丢掉参考。
 `references` 可以省略并由绑定顺序生成，也可以作为相同顺序的显式镜像。输出放在
 `剧集/<EP>/制作成果/`；这个 job 是生产工具的临时输入，不是第六份创作文档：
 

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

@@ -129,6 +129,13 @@ CREATOR_SOURCE_ENTRIES = {
 }
 
 REF_SLOT_RE = re.compile(r"REF-[A-Z0-9][A-Z0-9-]{0,79}")
+# A slot head, not a bare substring: a real reference file may legitimately be
+# named `plan-sheet.png`, and that is not a creator-supplied declaration.
+PLAN_SLOT_HEAD_RE = re.compile(r"PLAN-[A-Za-z0-9][A-Za-z0-9-]{0,79}（顺序：")
+PLAN_SLOT_RE = re.compile(
+    r"PLAN-[A-Za-z0-9][A-Za-z0-9-]{0,79}（顺序：[1-9]\d*）· "
+    r"(?:IMG|SHOT)-[A-Za-z0-9-]+《[^》\n]+》（[^）\n]*）"
+)
 SOURCE_ENTRY_RE = re.compile(r"[A-Z][A-Z0-9-]{1,99}")
 REFERENCE_SUFFIX_RE = r"(?:png|jpe?g|webp)"
 # 用途 is the creator-facing question "what does this picture decide here"; the
@@ -806,8 +813,12 @@ def _contains_ref_token(value: str) -> bool:
     return "ref-" in value.casefold()
 
 
+def _contains_plan_token(value: str) -> bool:
+    return "plan-" in value.casefold()
+
+
 def _markdown_reference_bindings(
-    section: str, *, field_name: str
+    section: str, *, field_name: str, creator_supplied_ok: bool = False
 ) -> list[dict[str, Any]]:
     lines = re.findall(
         rf"^- {re.escape(field_name)}：(.+)$", section, re.MULTILINE
@@ -829,6 +840,21 @@ def _markdown_reference_bindings(
         and re.fullmatch(r"无(?:外部参考)?(?:；[^\n]*)?。?", value)
     ):
         return []
+    # A `PLAN-...` slot is a picture the creator attaches in their own tool, so
+    # this suite has no file to send. The rendering job that draws a shot's own
+    # start frame is unaffected -- it works from the frozen keyframe text, the
+    # way it already does for 「待补参考图」 -- so only the job that would have
+    # sent these pictures as model inputs refuses. Matched as a slot head rather
+    # than a bare substring, or a real file named `plan-sheet.png` would refuse.
+    if PLAN_SLOT_HEAD_RE.search(value):
+        if not creator_supplied_ok:
+            raise ValueError(
+                "source entry declares creator-supplied references (PLAN-...); "
+                "bind the real files as REF-... before producing"
+            )
+        value = PLAN_SLOT_RE.sub("", value).strip("；;。 ")
+        if not value:
+            return []
     matches = list(REFERENCE_LINE_RE.finditer(value))
     if not matches:
         raise ValueError("source entry input-reference declaration is invalid")
@@ -869,7 +895,13 @@ def _verify_markdown_source(
     _, heading, field_name = CREATOR_SOURCE_ENTRIES[source_path.name]
     if _copyable_prompt(section, heading) != prompt.strip():
         raise ValueError("job prompt does not match the selected source entry")
-    declared = _markdown_reference_bindings(section, field_name=field_name)
+    declared = _markdown_reference_bindings(
+        section,
+        field_name=field_name,
+        # 分镜.md is the entry that renders a shot's own start frame. Its
+        # reference field records creative intent, not this job's inputs.
+        creator_supplied_ok=source_path.name == "分镜.md",
+    )
     comparable = [
         {key: binding[key] for key in (
             "slot_id",