@oh-story/dsh 0.1.8 → 0.1.10

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

@@ -94,8 +94,14 @@ SPOKEN_RUN_RE = re.compile(r"[\u3400-\u9fff]{4,}")
 EXPLICIT_TEXT_TO_VIDEO = "无（创作者已明确选择文生视频）"
 PENDING_REFERENCE_SUFFIX_RE = re.compile(r"；待补参考图：[^；。\n]+。?$")
 VISUAL_CATEGORIES = ("人物", "造型", "地点", "道具")
+# A malformed entry always tries to name something; a heading that is only the
+# category word is a section divider ("## 人物"), and rejecting it left the
+# document with no way to group entries at all.
 VISUAL_SETTING_LINE_RE = re.compile(
-    r"^#{2,4}[ \t　]*(?:" + "|".join(VISUAL_CATEGORIES) + r")[^\n]*$", re.MULTILINE
+    r"^#{2,4}[ \t　]*(?:"
+    + "|".join(VISUAL_CATEGORIES)
+    + r")(?![ \t　]*$)[^\n]*$",
+    re.MULTILINE,
 )
 VISUAL_SETTING_HEADING_RE = re.compile(
     r"^## (" + "|".join(VISUAL_CATEGORIES) + r") · (.+?)[ \t　]*$", re.MULTILINE
@@ -175,6 +181,10 @@ def _fields(section: str, *, owner: str, errors: list[str]) -> dict[str, str]:
     pairs = re.findall(r"^- ([^：\n]+)：(.+)$", section, re.MULTILINE)
     fields: dict[str, str] = {}
     for key, value in pairs:
+        # `- **参考**：…` is ordinary Markdown and reads as the same field to a
+        # human. Taking the emphasis literally turned it into a different key,
+        # so the author got "缺少参考字段" while looking straight at 参考.
+        key = re.sub(r"^(?:\*\*|__|\*|_)(.+?)(?:\*\*|__|\*|_)$", r"\1", key.strip())
         if key in fields:
             errors.append(f"{owner}: 字段重复: {key}")
         fields[key] = value
@@ -242,6 +252,43 @@ def _copyable_prompt(
     return prompt or None
 
 
+def _copyable_prompt_cause(
+    section: str, heading: str = r"可复制(?:通用)?提示词"
+) -> str:
+    """Why `_copyable_prompt` returned None, as a suffix for the error.
+
+    "缺少唯一且非空的可复制提示词" is true of four different documents and tells
+    the author nothing about which one they wrote. The expensive case is a
+    single stray line -- a separator, an HTML comment, a note -- inside an
+    otherwise complete block: the prompt is visibly right there, so the message
+    reads as a checker bug and the real line goes unlooked at.
+    """
+
+    # Name the heading the author actually has to write, not this one's default:
+    # the keyframe caller passes a different one, and pointing at the wrong
+    # heading is worse than saying nothing.
+    label = "### " + re.sub(r"\(\?:([^)]*)\)\?", "", heading).replace("\\", "")
+    markers = list(re.finditer(rf"^### {heading}\s*$", section, re.MULTILINE))
+    if not markers:
+        return f"：没有 `{label}` 小节标题"
+    if len(markers) > 1:
+        return f"：`{label}` 出现了 {len(markers)} 次，只能有一个"
+    body = section[markers[0].end() :]
+    following = re.search(r"^###\s+|^##\s+", body, re.MULTILINE)
+    if following is not None:
+        body = body[: following.start()]
+    lines = [line for line in body.splitlines() if line.strip()]
+    if not lines:
+        return f"：`{label}` 下面是空的"
+    intruders = [line for line in lines if not line.startswith(">")]
+    if intruders:
+        return (
+            "：小节内有不以 `>` 开头的行，整块因此不算引用块——"
+            f"把它移到小节外，或删掉：{_excerpt(intruders[0])}"
+        )
+    return "：引用块里只有空白"
+
+
 def _portable_path(value: str) -> bool:
     if not value or "\\" in value or re.match(r"^[A-Za-z]:", value):
         return False
@@ -566,7 +613,11 @@ def _visual_entries(document: str, errors: list[str]) -> list[VisualEntry]:
 
 
 def _named_entries(
-    prompt: str, entries: list[VisualEntry], *, fold_case: bool = False
+    prompt: str,
+    entries: list[VisualEntry],
+    *,
+    fold_case: bool = False,
+    by_entry_name: bool = False,
 ) -> set[tuple[str, str]]:
     """Which declared entries does this frozen keyframe actually call by name?
 
@@ -578,7 +629,16 @@ def _named_entries(
         haystack = haystack.casefold()
     owners: dict[str, list[VisualEntry]] = {}
     for entry in entries:
-        for designator in entry.designators:
+        # 来源 quotes 剧本.md, which is written in the project's own language and
+        # calls people by their entry names — not by the 画面代称 a prompt body
+        # uses. Matching a Chinese screenplay quote against an English designator
+        # would never fire, so that text is matched by entry name instead. An
+        # entry that opted out with `画面代称：无` opted out of being found by
+        # name at all, and stays out of both.
+        needles = (
+            [entry.name] if by_entry_name and entry.designators else entry.designators
+        )
+        for designator in needles:
             needle = re.sub(r"\s+", " ", designator).strip()
             if fold_case:
                 needle = needle.casefold()
@@ -665,13 +725,17 @@ def _check_named_coverage(
     basis: "VisualBasis",
     entries: list[VisualEntry],
     errors: list[str],
+    *,
+    by_entry_name: bool = False,
 ) -> None:
     """Every entry this text calls by name is either in frame or declared 画外."""
     # Matching is case-sensitive so an ordinary English word never impersonates a
     # character called May or Will. A body that writes the name in another case
     # would otherwise fall out of the check silently, so it is reported here.
-    named = _named_entries(prompt, entries)
-    folded = _named_entries(prompt, entries, fold_case=True)
+    named = _named_entries(prompt, entries, by_entry_name=by_entry_name)
+    folded = _named_entries(
+        prompt, entries, fold_case=True, by_entry_name=by_entry_name
+    )
     for category, name in sorted(folded - named):
         errors.append(
             f"{owner}: {where}里的名字与画面代称大小写不一致: {category}「{name}」；"
@@ -870,6 +934,17 @@ def _check_language_designators(
             )
 
 
+def _declared_seconds(value: str) -> Optional[float]:
+    """The number of seconds a 时长 field declares, however it is spelled.
+
+    `4s`, `4 秒` and `4秒` are the same duration. Returning None for anything
+    else keeps an unparseable value out of the comparison instead of turning a
+    formatting difference into a false duration conflict.
+    """
+    match = re.search(r"(\d+(?:\.\d+)?)", value or "")
+    return float(match.group(1)) if match else None
+
+
 def _check_continuity_locks(
     locks: list[ContinuityLock],
     *,
@@ -1091,7 +1166,10 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
         image_prompt = _copyable_prompt(body)
         image_prompts[match.group(1)] = image_prompt
         if image_prompt is None:
-            errors.append(f"{match.group(1)}: 缺少唯一且非空的可复制提示词")
+            errors.append(
+                f"{match.group(1)}: 缺少唯一且非空的可复制提示词"
+                + _copyable_prompt_cause(body)
+            )
 
     motions = _sections(video, "MOTION")
     shot_ids = re.findall(r"^## (SHOT-[A-Z0-9-]+)\b", storyboard, re.MULTILINE)
@@ -1122,9 +1200,11 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
         errors.append("视频提示词.md: 没有 MOTION 条目")
 
     motion_by_shot: dict[str, tuple[str, str, Optional[str]]] = {}
+    motion_duration: dict[str, str] = {}
     for motion_id, body in motions.items():
         fields = _fields(body, owner=motion_id, errors=errors)
         shot_id = _plain(fields.get("分镜", ""))
+        motion_duration[shot_id] = _plain(fields.get("时长", ""))
         copyable_prompt = _copyable_prompt(body)
         if not shot_id:
             errors.append(f"{motion_id}: 缺少分镜字段")
@@ -1135,16 +1215,34 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
         if motion_id.removeprefix("MOTION-") != shot_id.removeprefix("SHOT-"):
             errors.append(f"{motion_id}: ID 必须与分镜 {shot_id} 一一对应")
         if copyable_prompt is None:
-            errors.append(f"{motion_id}: 缺少唯一且非空的可复制提示词")
+            errors.append(
+                f"{motion_id}: 缺少唯一且非空的可复制提示词"
+                + _copyable_prompt_cause(body)
+            )
 
     if set(motion_by_shot) != set(shots):
         errors.append("分镜.md/视频提示词.md: SHOT 与 MOTION 未一一对应")
 
     for shot_id, shot_body in shots.items():
         fields = _fields(shot_body, owner=shot_id, errors=errors)
+        source_value = fields.get("来源", "")
         claimed_scenes.update(
-            _shot_sources(fields.get("来源", ""), shot_id, scenes, errors)
+            _shot_sources(source_value, shot_id, scenes, errors)
         )
+        shot_seconds = _declared_seconds(_plain(fields.get("时长", "")))
+        motion_seconds = _declared_seconds(motion_duration.get(shot_id, ""))
+        if (
+            shot_seconds is not None
+            and motion_seconds is not None
+            and shot_seconds != motion_seconds
+        ):
+            # 时长 is the value actually sent to the execution end and the term
+            # VID-04/VID-13 arithmetic is built on. A downstream copy that drifts
+            # from its accepted upstream is invisible in every other check.
+            errors.append(
+                f"{shot_id}: 分镜时长 {shot_seconds:g} 秒与视频提示词 "
+                f"{motion_seconds:g} 秒不一致；视频提示词只能原样照抄已接受的镜头时长"
+            )
         image_value = fields.get("图片提示词项", "")
         if not image_value:
             errors.append(f"{shot_id}: 缺少图片提示词项字段")
@@ -1178,11 +1276,44 @@ def validate_episode(episode: Path, project_root: Optional[Path] = None) -> list
         # shot without one would make the coverage check below vacuous.
         keyframe = _copyable_prompt(shot_body, heading=r"冻结关键帧提示词")
         if keyframe is None:
-            errors.append(f"{shot_id}: 缺少唯一且非空的冻结关键帧提示词")
+            errors.append(
+                f"{shot_id}: 缺少唯一且非空的冻结关键帧提示词"
+                + _copyable_prompt_cause(shot_body, heading=r"冻结关键帧提示词")
+            )
         elif basis.parsed:
             _check_named_coverage(
                 keyframe, shot_id, "冻结关键帧提示词", basis, visual_entries, errors
             )
+        # The closing keyframe is optional — many shots end where they began —
+        # but a heading that is present and malformed is a defect, not a shot
+        # that quietly has no closing frame.
+        if re.search(r"^### 收尾关键帧提示词\s*$", shot_body, re.MULTILINE):
+            closing = _copyable_prompt(shot_body, heading=r"收尾关键帧提示词")
+            if closing is None:
+                errors.append(
+                    f"{shot_id}: 收尾关键帧提示词不是唯一且非空的可复制正文"
+                    + _copyable_prompt_cause(shot_body, heading=r"收尾关键帧提示词")
+                )
+            elif basis.parsed:
+                _check_named_coverage(
+                    closing, shot_id, "收尾关键帧提示词", basis, visual_entries, errors
+                )
+        if basis.parsed and source_value:
+            # A shot's 来源 is its claim on the screenplay: whatever it quotes,
+            # this shot is the one that films it. Quoting an action performed by
+            # someone the frame never shows takes that action off everyone's
+            # list — no other shot claims it, and nothing reports it missing, so
+            # it simply never gets filmed. Same rule as the keyframe: in frame,
+            # or declared 画外.
+            _check_named_coverage(
+                source_value,
+                shot_id,
+                "来源引文",
+                basis,
+                visual_entries,
+                errors,
+                by_entry_name=True,
+            )
 
         motion = motion_by_shot.get(shot_id)
         if not motion:

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

@@ -48,6 +48,11 @@ CREATOR_DOCUMENTS = (
     "图片提示词.md",
     "视频提示词.md",
 )
+# The cut list is written after the media exists, so an episode that never
+# reached editing is complete without one. It travels with a handover when it is
+# there -- without it the next person has to re-cut the film from scratch -- but
+# it is never reported as a missing creator document.
+POST_PRODUCTION_DOCUMENTS = ("剪辑单.md",)
 EXPORT_MEDIA_DIRECTORY = "制作成果"
 EXPORT_SCHEMA = "1.0"
 EPISODE_ID_RE = re.compile(r"EP(?:[0-9]{3}|[1-9][0-9]{3,})")
@@ -1948,6 +1953,12 @@ def _export_episode(
             continue
         digest = _export_regular_file(source, target / name)
         files.append({"path": name, "sha256": digest})
+    for name in POST_PRODUCTION_DOCUMENTS:
+        source = episode_directory / name
+        if not source.exists():
+            continue
+        digest = _export_regular_file(source, target / name)
+        files.append({"path": name, "sha256": digest})
     media_root = episode_directory / EXPORT_MEDIA_DIRECTORY
     if include_media and media_root.exists():
         media_details = os.lstat(media_root)

package/lib/drama/skills/short-drama-assets/references/character-and-look.md

@@ -18,6 +18,24 @@
 把两者拆开，是为了换装、受伤、湿污和年龄变化时仍能复用人物身份，同时让图片提示
 词与分镜精确选择一个相容造型。
 
+
+## 画面代称要覆盖每一种正文语言
+
+`画面代称` 是下游覆盖检查唯一用来匹配的字符串：冻结关键帧、图片提示词、视频提示词里出现了这个词，
+才算「这一镜点了这个资产的名」。匹配是逐字的，不做翻译。
+
+问题在于三份正文的语言不一定相同：图片提示词与冻结关键帧跟 `format/prompt_language`，
+视频提示词优先跟已接受的 `video_prompt_language`。而校验器只按后者的解析结果决定要不要强制
+「代称不能等于名字」——于是一个 zh + en 混配的项目很容易写成**只有英文代称**，
+然后中文正文里这个资产永远匹配不上。
+
+**这种失败是静默的**：匹配不上不会报错，只会让覆盖检查对这条资产整个不生效，
+看起来一路绿灯。所以：
+
+- 一个资产的 `画面代称` 要**把它在各份正文里实际会出现的写法都列上**（中文名与英文代称并列），
+  不是二选一；
+- 正文里确实不该靠名字识别时才写 `画面代称：无`，那是明确的弃权，不是省事。
+
 ## Character：最小稳定识别集
 
 从剧本与 creator reference 中选择足以区别此人的持久锚点：
@@ -110,6 +128,16 @@ Character 拥有，换鞋、加厚外套、盘发都不改写它（那些属于
 | 剪影与线条 | 轮廓与肩背重心、发型剪影与发际形状、固定配饰外形、服装廓形、步态负重 | 细微的五官不对称、浅色小痣、依赖真实皮肤纹理的痕迹 |
 | 材质与表面 | 皮肤/毛发/布料的可比较表面状态、长期使用痕迹 | 需要柔和过渡才能读出的体积差 |
 
+### 写实细节与身份连续性
+
+**`craft_default`**：写实项目可以在稳定识别特征之外，补充皮肤纹理、自然不对称或使用痕迹。
+远景中不易读出的细节，不宜单独承担跨镜识别。
+
+痣、疤和牙齿形态等如果是人物既定特征，仍须保持；不能因它们难生成就允许随镜变化。
+毛孔、细纹等微观纹理不必逐像素一致。是否需要这些细节由画面尺度与已接受风格决定。
+
+**`taste_option`**：偶像化、漫画或其他风格可采用更平滑的表面，不以写实程度判错。
+
 ### 边界：形态选通道，身份定事实
 
 - **`reviewed_invariant`**：形态可以改变锚点的**表达通道与颗粒度**，不得改写身份事实本身。

package/lib/drama/skills/short-drama-assets/references/continuity-lock.md

@@ -40,8 +40,14 @@
 
 `锁面` 是**要被逐字带进提示词正文的那一小段字**，不是描述，也不是给人读的说明：
 
-- 用项目的提示词语言写（`short-drama.json#/format/prompt_language`，没有配置时是 `en`），
-  因为它要落进可复制正文，不是落进创作者说明；
+- 锁面必须**逐字出现在它管到的每一份可复制正文里**。校验器会在三处查同一个字符串：
+  图片提示词正文、冻结关键帧提示词、视频提示词正文。
+- 图片与冻结关键帧使用 `format/prompt_language`，视频可能使用另选的 `video_prompt_language`。
+  语言不同时，优先使用确实适合各份正文的共同色值、型号或专名。
+  当前 `镜头：` 同时约束本镜首帧与视频正文，不能靠拆成两把锁分别约束两种语言。
+  没有合适共同词组时，在视觉设定中保留事实并报告此限制，暂不声明这把逐字锁；
+  不缩小事实实际出现的镜头范围来绕过检查，也不自行改变用户选择的正文语言。
+
 - 只保留最小可辨识名词短语，通常是「颜色 + 材质/形制 + 物体」，例如
   `pale blue chunky knit wool sweater`；
 - 不含句号、动作、状态、数量、镜头信息和剧情；

package/lib/drama/skills/short-drama-assets/references/voice-direction.md

@@ -3,6 +3,7 @@
 ## 目录
 
 - [参考音频是载体](#参考音频是载体)
+- [参考可以是合成出来的](#参考可以是合成出来的)
 - [身份与表演的界线](#身份与表演的界线)
 - [一段参考音频可以决定什么](#一段参考音频可以决定什么)
 - [绑定不等于听过](#绑定不等于听过)
@@ -27,6 +28,20 @@
 `reference: null` 并写明「待选型」——**不要用一段文字描述冒充音色身份**。
 下游拿着一段形容词去找声音，找回来的每次都不一样，而记录看起来是完整的。
 
+### 参考可以是合成出来的
+
+使用声音库时，确认所选音色及其使用范围符合供应商提供的许可。
+项目没有配音演员、也不打算克隆谁的时候，这条路是让 `reference` 从 `待选型` 变成实际路径的
+办法——**挑一个预置音色，合成一条，绑上去**。合成由 `$short-drama-produce` 的 `tts` 模态执行。
+
+合成出来的参考和录音来的参考在本文档里受同样的约束：它一样要写用途边界，一样要有
+`admission_status`，一样不能用形容词代替。差别只有一处——**它的选型判据是拿来挑预置音色的，
+不是拿来判克隆像不像的**，所以「与谁最易混」这条要在同一批预置音色里回答，而不是在角色之间
+凭空回答。预置库里两个音色听起来就是同一个人时，换一个，不要靠判据文字假装区分。
+
+音色 ID 本身写进 `reference` 那一行，和路径、用途边界一起。它是创作决定：同一个角色在两集之间
+换 ID 就是换人说话，这件事必须在文档里看得见、diff 里查得出。
+
 ## 身份与表演的界线
 
 一句话判定：**这个特征在角色安静地坐着说一句无关紧要的话时还在吗**？
@@ -115,6 +130,15 @@ CHAR-A 与 CHAR-B 最易混：两条参考同为中低音区、语速偏慢。
 
 角色多时按易混组分批选型，而不是按出场顺序。
 
+### 对比选择预置音色
+
+用同一组有代表性的台词试听候选，比较角色间是否易混，以及同一角色在不同情绪下是否稳定。
+音色名称仅供检索，选择依据是实际声音。
+
+需要测量时，F0 和谱特征可辅助定位近似音色；同一候选应有多句样本，才能估计自身变化。
+不把音高间距或「组间距离大于组内极差」设为通用门槛。最终按角色需求与回听结果选择，
+不为追求数字分离而改变已接受的声音方向。
+
 ## 专名发音
 
 已接受的专名发音只能有一种拼法（`AST-10`）。
@@ -149,3 +173,7 @@ CHAR-A 与 CHAR-B 最易混：两条参考同为中低音区、语速偏慢。
 
 临时情绪、呼吸、重音、音量和空间混响仍由剧本/镜头/视频提示词拥有。声音方向是生产输入，不是
 合成结果保证；实际 TTS 仍由 `$short-drama-produce` 在精确预览并显式确认后执行。
+
+参考音频落地之后，它在下游有两个去处：作为视频模型的音色参考绑定（见目标模型的方言文档），
+以及作为配音本的实际人声。配音使用同一已选音色逐句合成；参考音频用于选型或模型绑定，不能直接充当不同台词的成品音轨。
+是否保持角色声音，仍需在生成后回听确认。

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

@@ -0,0 +1,146 @@
+---
+name: short-drama-edit
+description: 将已生成的短剧镜头剪成成片，记录入出点、镜序、声音、字幕与交付规格。用于套剪、加字幕、统一响度、调整节奏或导出精修素材；需要补素材或修改故事时转回对应创作阶段。
+license: MIT
+---
+
+# 短剧剪辑与成片
+
+把 `剧集/<EP>/制作成果/` 里的逐镜素材装配成一条成片，取舍写进 `剧集/<EP>/剪辑单.md`。
+每段使用二级标题 `## CUT-...`，各自绑定一个 `MOTION-...` 和一个真实媒体文件。
+
+根据实际素材选择可用片段，按剧本与分镜核对叙事。素材与意图不一致时，记录取舍和缺口。
+
+## Quick Start
+
+```text
+用 $short-drama-edit 把 EP001 已生产的镜头剪成成片
+```
+
+## 入口
+
+进入条件是**素材已经存在且可读**：`剧集/<EP>/制作成果/` 里有本次要用的视频文件。
+提示词写完、job 确认过、adapter 返回成功，都不等于素材可用；本阶段只认当前能打开的文件字节。
+
+素材不全时可以先剪已有连续段落；用户要求完整成片时，将这一版标为片段并列出缺口。
+在「未采用镜头」说明缺文件、质量不可用或叙事取舍。
+
+`剧集/<EP>/分镜.md` 与 `视频提示词.md` 是镜序和职责的来源。剪辑可以**取舍**它们，不能**改写**
+它们：删一镜、缩一镜、换顺序都属于本阶段；改台词、改镜头职责、改起终状态要回上游发修订请求。
+
+内置渲染直接拼接编码后的分段，输入素材的画幅与帧率须一致。`check` 在可探测媒体时核对；
+不同规格先通过外部工具按交付要求统一，保留构图并记录裁切或留边，再更新剪辑单的路径与时间。
+
+渲染与测量需要 `ffmpeg` / `ffprobe` 在 PATH 上。没有时 `edit_tool.py` 直接失败并说明，
+不用别的手段近似，也不把「没测」写成「通过」。
+
+## 工作流
+
+1. **逐段看完整素材，先标可用带，再谈剪辑。** 每个文件从头到尾看一遍，写下它实际能用的时间
+   区间，以及区间之外发生了什么（起势静止、结尾漂移、发白、动作回弹、多余的重复表演）。
+   这一步的产出是事实，不是决定。做法见 [生成素材的可用带](references/generated-footage.md)。
+2. **有台词的镜先定位发声区间。** 保留完整字音和所需停顿。内置工具同步切画面与声音；
+   需要在连续对白上换画面时，使用外部剪辑工具分开处理。
+3. **在可用区间内选叙事入出点。** 按动作、反应或停顿的需要选择入点，出点取信息完成之后、缺陷
+   开始之前。逐段写清入点理由和出点理由。做法见 [入出点与镜序](references/cut-craft.md)。
+4. **排镜序并检查相邻关系。** 检查动作、空间、揭示与声音是否连贯；重复信息没有新增作用时再删。
+5. **比较相邻段的画面。** 按同场景、同光态比较可比区域；有可见偏差时在对应段写 `画面`。
+   做法见 [接镜与色彩一致性](references/generated-footage.md#接镜与色彩一致性)。
+6. **处理声音接缝与响度。** 拼接后回听；需要混音时通过外部工具执行并记录。
+   做法见 [声音、字幕与音乐](references/sound-and-subtitles.md)。
+7. **写字幕。** 字幕的每一个字都取自 `剧本.md` 的台词原文，不取自转写结果；标点可按字幕惯例调整，
+   字不能改。转写只用来定位时间。
+8. **写出 `剪辑单.md`，再渲染。** 先有文档后有成片：文档是可审查、可修订、可复现的那一份，
+   成片是它的产物。
+9. **按可测项验收成片，再交付。** 见 [交付与验收](references/delivery-verify.md)。
+
+## 剪辑单要求
+
+- 正文开头写交付规格：`成片目标时长`、`画幅与帧率`、`交付响度`、`字幕`。目标时长是意图，
+  实际时长与目标的差写在报告里。用户明确要求固定时长时，应满足要求或报告缺少的素材。
+- 每段一个 `## CUT-<EP>-<序号> · <中文名称>`，块内逐行写：
+
+  - `- 来源：<MOTION-...> · <项目相对路径>`——`MOTION-...` 必须是 `视频提示词.md` 里真实存在
+    的条目，路径必须是当前可读的文件。
+  - `- 入点：<秒>` / `- 出点：<秒>` / `- 时长：<秒>`——三者必须自洽，`出点 - 入点 == 时长`。
+    全部用秒，保留两位小数，不写时间码，不写帧号。
+  - `- 取舍：入点=<理由>；出点=<理由>`——理由写画面上发生了什么，不写「节奏需要」。
+    理由应能对应实际素材与本镜叙事需要。
+  - `- 声音：<本段声音怎么处理>`——记录保留原声或外部处理。此行不驱动内置 render 的混音。
+  - `- 画面：<接镜校正>` 或 `- 画面：无`——只在这一段与相邻段明显对不上时写，
+    格式是「亮度 <数>」「饱和 <数>」「色温 <数>」三项的任意组合，用 `；` 分隔。
+    详见 [接镜与色彩一致性](references/generated-footage.md#接镜与色彩一致性)。
+  - `- 字幕：<逐字台词原文>` 或 `- 字幕：无`。本段有多句台词时改用编号写法，
+    每句自带时间：`- 字幕 1：0.20-1.50 请进`、`- 字幕 2：2.30-4.30 门没有锁`。
+    编号从 1 连续，时间相对本 CUT 入点，且不得重叠。
+- 素材里没有被采用的镜头，在正文开头写一行 `- 未采用镜头：<MOTION-...>（理由：……）`，
+  多项用 `；` 连接。理由区分两类：**文件缺失**（还没生产 / 生产失败）和**质量不可用**
+  （生成结果不能用），也可说明叙事取舍。补素材前先判断需要重出还是修订上游。
+- 同一个 `MOTION-...` 可以拆成多个 `CUT-...`（同一段素材的两处分别使用），也可以整段不用。
+  不能凭空出现没有素材来源的 `CUT-...`。
+- 一段素材被用两次时，两个 `CUT-...` 的区间不得重叠：同一批帧在成片里出现两次是重复镜头，
+  不是复用。确需重复出现（闪回、强调）时写明它是有意重复，并说明第二次为什么仍然成立。
+
+## 边界
+
+- **不生成新素材。** 需要补拍、重出、换参考图，回 `$short-drama-produce`；需要改提示词，
+  回 `$short-drama-video-prompts` 或 `$short-drama-image-prompts`。
+- **不改上游语义。** 剪辑单可以让某句台词不出现在成片里（整镜未采用），不能改这句台词是什么。
+  发现剧本层面的问题就点名报告，交回 `$short-drama-write`。
+- **沿用剧本的声音设计。** 保留已有对白、VO 和 OS，不自行增加解说；需要新增叙述时回写作阶段。
+- **不把技术成功写成质量结论。** 渲染完成、时长对上、文件存在，都不是「这条片子能看」。
+  成片质量的判断交给 `$short-drama-review`，或交给创作者本人。
+- **按已授权目标完成。** 继续修复影响交付的问题；新增创作方向或补素材需求交给创作者决定。
+
+## 命令
+
+命令由 [edit_tool.py](scripts/edit_tool.py) 提供：
+
+```text
+python3 <本技能目录>/scripts/edit_tool.py check <剧集/EP001> --project-root <project>
+python3 <本技能目录>/scripts/edit_tool.py render <剧集/EP001> --project-root <project> [--no-subtitles] [--subtitles ffmpeg|remotion] [--remotion-concurrency N]
+python3 <本技能目录>/scripts/edit_tool.py verify <剧集/EP001> --project-root <project>
+```
+
+`check` 只核对不渲染：素材是否比剪辑单新（重出之后字幕时间必须重测）、区间自洽、`MOTION-...` 解析、文件存在、区间不越过素材时长、
+同源区间不重叠、字幕文字能在 `剧本.md` 里找到。其中「区间不越过素材时长」需要 `ffprobe`，
+没有时这一项报「未测」并说明原因，不静默跳过。`render` 按剪辑单切段、拼接、烧字幕、统一响度，
+输出 `剧集/<EP>/制作成果/成片/`。`verify` 只测量已经渲染出来的成片并回报数字，不改文件、
+不给质量结论。
+
+字幕默认由带 libass 的 ffmpeg 烧录。`--subtitles remotion` 换成一条排版可调的
+路线，代价是装一次 Node 依赖，而且叠层要**逐帧过无头浏览器**渲整部成片——慢且吃内存，
+并发默认压在 2（`--remotion-concurrency` 可调，调高前先量本机）。取舍见
+[声音、字幕与音乐](references/sound-and-subtitles.md)，装法见
+[Remotion 字幕叠层](assets/remotion/README.md)。
+
+`render` 保留切好的中间文件。它只切段、硬拼接、统一字幕样式、接镜校正和整片响度，
+不执行 `声音` 行中的混音方案，也不按交付规格自动缩放或改帧率。需要混音、逐镜字幕避让、
+转场或画幅转换时用外部工具完成并记录，验收实际交付文件。
+
+## 按需知识
+
+先读本 SKILL、当前分镜、视频提示词和素材；有字幕时读取剧本原文。按需要打开参考资料：
+
+- 阶段边界与规则分级：[阶段契约](references/stage-contract.md)
+- 可用带、生成缺陷与逐镜取舍：[生成素材的可用带](references/generated-footage.md)
+- 入出点、镜序与节奏：[入出点与镜序](references/cut-craft.md)
+- 声音接缝、字幕与音乐落点：[声音、字幕与音乐](references/sound-and-subtitles.md)
+- 成片可测项与验收：[交付与验收](references/delivery-verify.md)
+- 剪辑单成稿样例：[剪辑单样例](assets/剪辑单.md)
+- 可选的 Remotion 字幕排版：[Remotion 字幕叠层](assets/remotion/README.md)
+
+## 修订
+
+保留未受影响的 `CUT-...` ID。改一段的入出点不触碰其它段；删一段时说明它承担的信息由哪一段
+接住，或明确说明这条信息在成片里不再出现。重新渲染前先更新剪辑单，不要让成片领先于文档。
+
+## 完成
+
+每个 `CUT-...` 都绑定真实素材与自洽区间，台词在成片里完整可听，字幕逐字等于剧本原文，
+剪辑点没有可听的音床硬切，成片响度落在交付目标上，未采用镜头都写明理由并区分了缺文件与缺质量，
+即完成。目标时长与实际时长的差、以及仍然值得再剪一版的地方，写在末尾报告里交给创作者判断。
+
+## 安装维护
+
+只有安装、升级或排障时运行 `python3 scripts/selftest.py`。

package/lib/drama/skills/short-drama-edit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "短剧剪辑"
+  short_description: "把逐镜生成的素材按分镜装配成有节奏、台词完整、可交付的短剧成片"
+  default_prompt: "使用 $short-drama-edit 把 EP001 已生产的镜头素材剪成成片。"

package/lib/drama/skills/short-drama-edit/assets/remotion/README.md

@@ -0,0 +1,60 @@
+# Remotion 字幕叠层
+
+`$short-drama-edit` 的**可选**字幕渲染路线。默认路线是 ffmpeg + libass，零依赖；这一条排版
+更好，但要装 Node 依赖，而且慢得多、吃内存——先看下面的「代价」。
+
+## 为什么会有第二条路
+
+ASS 的字号是相对 `PlayRes` 的单位，渲染时再缩放一次，这层间接每次都要重推一遍，推错了
+在数字上看不出来（见[声音、字幕与音乐](../../references/sound-and-subtitles.md)）。这里字号、
+描边、行距、安全区、折行都是 CSS，写的是画面像素，改完在 `npx remotion studio` 当场能看。
+
+## 装一次
+
+工作区在**项目之外**（默认 `~/.cache/short-drama-edit/remotion`）。`edit_tool.py` 每次运行都会
+把本目录的源码同步过去，所以要改排版就改这里的 `src/`，不要改工作区里的副本——它会被覆盖。
+
+```bash
+cd ~/.cache/short-drama-edit/remotion && npm install
+```
+
+`node_modules` 不进项目也不进本仓库。
+
+## 用
+
+```bash
+python3 <本技能目录>/scripts/edit_tool.py render <剧集/EP001> --project-root <project> --subtitles remotion
+```
+
+它渲染出一段**透明**的字幕层（VP8 + alpha），再由 ffmpeg 叠到未经改动的画面上。画面本身
+不经过浏览器重绘，所以不多一次画质损失。
+
+## 代价
+
+叠层**逐帧**渲，长度等于整部成片：一分钟竖屏片一千多帧 1080×1920，每帧一次无头浏览器
+截图，没字幕的帧照渲。透明还要求 PNG 抓帧加 VP8 编码，Remotion 的性能文档把这两样都列为
+慢环节。默认路线是一次滤镜的事，这条是分钟级。
+
+内存才是会出事的地方。Remotion 默认按 CPU 核数开浏览器实例，每个各持一整帧——10 核 8 GB
+的机器上内存打满，整机停止响应，本套件就这么卡死过一次。所以 `edit_tool.py` 固定传
+`--concurrency`，默认 2。要提高先量本机，别凭核数拍：
+
+```bash
+cd ~/.cache/short-drama-edit/remotion && npx remotion benchmark
+```
+
+## 许可证
+
+Remotion 个人与小团队免费，超出规模需商业授权，条款以 [remotion.dev](https://www.remotion.dev/)
+为准。本套件是 MIT，不包含也不代理这项授权，也不会替你安装它——缺依赖时只报错并给出命令。
+默认路线不涉及这件事。
+
+## 文件
+
+| 文件 | 作用 |
+|---|---|
+| `src/schema.ts` | 叠层的输入形状：cues、画幅、fps、字号与安全区比例 |
+| `src/Subtitles.tsx` | 排版本身。所有尺寸都是画面高度的比例，同一组数值对 768×1344 和 1080×1920 都成立 |
+| `src/Root.tsx` | 合成注册；画幅、帧率、时长由调用方通过 `--props` 传入 |
+| `src/font.ts` | 渲染前等字体就绪，并验证字体族真的存在——装不上时报错，而不是悄悄换一款字体出片 |
+| `remotion.config.ts` | 固定成带 alpha 的输出，叠层必须透明 |

package/lib/drama/skills/short-drama-edit/assets/remotion/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "short-drama-subtitles",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Remotion subtitle layer for short-drama-edit. Renders a transparent overlay from cues.json.",
+  "scripts": {
+    "render": "remotion render Subtitles"
+  },
+  "dependencies": {
+    "@remotion/cli": "4.0.418",
+    "react": "19.0.0",
+    "react-dom": "19.0.0",
+    "remotion": "4.0.418"
+  }
+}

package/lib/drama/skills/short-drama-edit/assets/remotion/remotion.config.ts

@@ -0,0 +1,6 @@
+import { Config } from "@remotion/cli/config";
+
+// The overlay is composited onto untouched picture, so it must carry alpha.
+Config.setVideoImageFormat("png");
+Config.setPixelFormat("yuva420p");
+Config.setCodec("vp8");

package/lib/drama/skills/short-drama-edit/assets/remotion/src/Root.tsx

@@ -0,0 +1,26 @@
+import React from "react";
+import { Composition } from "remotion";
+import { Subtitles } from "./Subtitles";
+import { defaultProps, SubtitleProps } from "./schema";
+
+export const RemotionRoot: React.FC = () => {
+  return (
+    <Composition
+      id="Subtitles"
+      component={Subtitles}
+      defaultProps={defaultProps}
+      // The caller passes the real frame, fps and length through --props; these
+      // stand in only when the composition is opened in the studio by hand.
+      durationInFrames={Math.max(1, Math.round(defaultProps.durationInSeconds * defaultProps.fps))}
+      fps={defaultProps.fps}
+      width={defaultProps.width}
+      height={defaultProps.height}
+      calculateMetadata={({ props }: { props: SubtitleProps }) => ({
+        durationInFrames: Math.max(1, Math.round(props.durationInSeconds * props.fps)),
+        fps: props.fps,
+        width: props.width,
+        height: props.height,
+      })}
+    />
+  );
+};