@oh-story/dsh 0.1.9 → 0.1.11

package/lib/video-recap/skills/video-recap/scripts/recap_timeline.py

@@ -1,6 +1,5 @@
 """Own recap timeline artifacts, continuation state, and cut QC surfaces."""
 
-import hashlib
 import json
 import os
 import shlex
@@ -15,6 +14,7 @@ from recap_runtime import (
     _multi_run_manifest_payload,
     _run_manifest_payload,
 )
+from recap_source import audio_binding, uses_narration
 
 ASSEMBLY_MANIFEST = "assembly_manifest.json"
 
@@ -23,6 +23,7 @@ PHASE_LEDGER = "recap_phase.json"
 CUT_TIMELINE_CRAFT_BULLETS = [
     "- 片段顺序必须服务同一条故事主线，而不是无序高光；可使用 0–1 个 cold open，随后回到 setup → turn → escalation → payoff。",
     "- 每个片段必须对应 `recap_story_plan.json` 中的一个 change-based beat；删除后不损失因果、人物或情绪的片段通常不保留。",
+    "- 已从源证据确认的必保问答、反应或兑现段，写入同一 `clip_plan.json.required_evidence`（nodes登记id/source绝对路径/start/end原片秒/track/content，before登记必要先后）；只锁具体区间，不锁整个beat。剪点吸附后工具会核验，reason或花字不能代替缺失的源段。",
     "- `reason` 统一写成 `beat_id | function | change | POV | preferred moment | 入点 | 出点`，不能只写 hook、重要剧情或事件摘要。",
     "- 优先保留因果、揭示、决定、关系移动、情绪转向与不可替代的表演/反应；跳过片尾、广告、重复静态画面和水印废片段。",
     "- 片段追求最短但完整：建立镜头可以短，关键表演/反应允许多停一点；在完整台词、完整动作或自然声音边界结束，避免原声从半句中切入或切出。",
@@ -104,24 +105,15 @@ def _print_grounding_qc_pointer(work_dir):
 def _print_narration_review_pointer(work_dir, *, review_ran=True):
     """Surface the advisory narration review produced by this run, if any.
 
-    Review is optional/fail-open. Avoid surfacing a stale narration_review.md from an
-    older run when review was disabled or failed before producing fresh artifacts.
+    Review is optional/fail-open: review_ran=False (disabled or failed) prints nothing so a
+    stale narration_review.md from an older run is never surfaced. When it ran, video-script's
+    review_runner has written both narration_review.json and .md.
     """
     _print_grounding_qc_pointer(work_dir)
     if not review_ran:
         return
     review_md = Path(work_dir) / "narration_review.md"
-    if not review_md.exists():
-        return
-    review_json = Path(work_dir) / "narration_review.json"
-    if not review_json.exists():
-        print(f"[video-recap] 📋 解说评审（建议性，不拦截）→ {review_md}")
-        return
-    try:
-        data = load_json(review_json)
-    except (OSError, ValueError):
-        print(f"[video-recap] 📋 解说评审（建议性，不拦截）→ {review_md}")
-        return
+    data = load_json(Path(work_dir) / "narration_review.json")
     n_err = sum(1 for f in data["findings"] if f["severity"] == "error")
     print(
         f"[video-recap] 📋 解说评审（建议性，不拦截）: {data['verdict']} · "
@@ -152,11 +144,17 @@ def _manifest_mismatches(work_dir, video, args):
     # as a mismatch rather than a crash.
     mismatches = [
         f"{key}: expected {expected[key]!r}, got {actual.get(key)!r}"
-        for key in ("source_video", "source_video_fingerprint")
+        for key in ("source_video", "source_video_identity")
         if actual.get(key) != expected[key]
     ]
     if _settings_for_compare(actual["settings"]) != _settings_for_compare(expected["settings"]):
         mismatches.append("settings: 当前 CLI/env 参数与 Phase A manifest 不匹配")
+    actual_audio = actual.get("audio")
+    expected_audio = audio_binding(args)
+    if actual_audio != expected_audio:
+        mismatches.append(
+            f"audio: expected {expected_audio!r}, got {actual_audio!r}"
+        )
     return mismatches
 
 
@@ -168,15 +166,23 @@ def _multi_manifest_mismatches(work_dir, videos, args, source_records):
     if actual.get("mode") != "multi_source":
         return [f"mode: expected 'multi_source', got {actual.get('mode')!r}"]
     mismatches = []
-    identity = ("source_id", "source_path", "source_video_fingerprint")
-    if [{k: s[k] for k in identity} for s in actual["sources"]] != [
+    identity = ("source_id", "source_path", "source_video_identity")
+    # A 0.5.0 manifest carries `source_video_fingerprint` instead of `source_video_identity`;
+    # .get() reports it as a mismatch rather than a crash.
+    if [{k: s.get(k) for k in identity} for s in actual["sources"]] != [
         {k: s[k] for k in identity} for s in expected["sources"]
     ]:
         mismatches.append(
-            "sources: 当前输入视频列表/顺序/source_id/fingerprint 与 Phase A manifest 不匹配"
+            "sources: 当前输入视频列表/顺序/source_id/identity 与 Phase A manifest 不匹配"
         )
     if _settings_for_compare(actual["settings"]) != _settings_for_compare(expected["settings"]):
         mismatches.append("settings: 当前 CLI/env 参数与 Phase A manifest 不匹配")
+    actual_audio = actual.get("audio")
+    expected_audio = audio_binding(args)
+    if actual_audio != expected_audio:
+        mismatches.append(
+            f"audio: expected {expected_audio!r}, got {actual_audio!r}"
+        )
     return mismatches
 
 
@@ -184,10 +190,6 @@ def _read_assembly_output(work_dir):
     return Path(load_json(Path(work_dir) / ASSEMBLY_MANIFEST)["final_output"])
 
 
-def _file_md5(path):
-    return hashlib.md5(Path(path).read_bytes()).hexdigest()
-
-
 def _read_phase_ledger(work_dir):
     """Phase ledger (cut mode): which artifacts exist and the clip_plan/narration they match.
 
@@ -209,14 +211,17 @@ def _write_phase_ledger(work_dir, **fields):
     return ledger
 
 
-def _cut_narration_is_stale(ledger, current_clip_plan_fp):
+def _cut_narration_is_stale(ledger, current_clip_plan_identity):
     """Two-pass cut: the narration is authored against the rendered cut shown at the A2 pause,
-    i.e. against the clip_plan recorded in the ledger. If clip_plan changed since (a re-cut)
-    while that narration is still present, it describes the OLD cut — stale."""
-    return ledger is not None and ledger["clip_plan_fingerprint"] != current_clip_plan_fp
+    i.e. against the clip_plan recorded in the ledger (its ``{size, mtime_ns}`` identity). If
+    clip_plan.json was rewritten since (a re-cut) while that narration is still present, it
+    describes the OLD cut — stale."""
+    return ledger is not None and ledger["clip_plan_identity"] != current_clip_plan_identity
 
 
 def _continuation_command(video, work_dir, args):
+    # Values a project binding filled in are re-derived from --project on resume.
+    bound = getattr(args, "_bound_from_project", frozenset())
     parts = [
         sys.executable,
         str(_entry("video-recap", "recap.py")),
@@ -232,12 +237,14 @@ def _continuation_command(video, work_dir, args):
         parts += ["--style", args.style]
     if args.edit_mode != "full":
         parts += ["--edit-mode", args.edit_mode]
+    if args.audio_mode != "narration":
+        parts += ["--audio-mode", args.audio_mode]
+    if args.audio_stream_index != 0:
+        parts += ["--audio-stream-index", str(args.audio_stream_index)]
     if args.target_duration:
         parts += ["--target-duration", args.target_duration]
     if args.allow_duration_drift:
         parts.append("--allow-duration-drift")
-    if args.allow_sparse_cut:
-        parts.append("--allow-sparse-cut")
     if args.skip_asr:
         parts.append("--skip-asr")
     if args.mimo_video_overview:
@@ -250,14 +257,17 @@ def _continuation_command(video, work_dir, args):
         parts.append("--no-consolidate")
     if args.consolidate_asr:
         parts.append("--consolidate-asr")
-    if args.mimo_tts_voice:
-        parts += ["--mimo-tts-voice", args.mimo_tts_voice]
-    if args.tts_provider != "auto":
-        parts += ["--tts-provider", args.tts_provider]
-    if args.voice_ref:
-        parts += ["--voice-ref", args.voice_ref]
-    if args.allow_partial_tts:
-        parts.append("--allow-partial-tts")
+    if uses_narration(args):
+        if args.mimo_tts_voice and "mimo_tts_voice" not in bound:
+            parts += ["--mimo-tts-voice", args.mimo_tts_voice]
+        if args.tts_provider != "auto" and "tts_provider" not in bound:
+            parts += ["--tts-provider", args.tts_provider]
+        if args.voice_ref and "voice_ref" not in bound:
+            parts += ["--voice-ref", args.voice_ref]
+        if args.allow_partial_tts:
+            parts.append("--allow-partial-tts")
+        if args.preserve_approved_text:
+            parts.append("--preserve-approved-text")
     if args.burn_subtitles is not None:
         parts.append("--burn-subtitles" if args.burn_subtitles else "--no-burn-subtitles")
     if args.subtitle_y_top is not None:
@@ -272,16 +282,23 @@ def _continuation_command(video, work_dir, args):
         parts.append("--jianying-bundle-media")
     if args.jianying_no_bundle_media:
         parts.append("--jianying-no-bundle-media")
-    if args.review_narration is not None:
-        parts.append("--review-narration" if args.review_narration else "--no-review-narration")
-    if args.require_narration_review:
-        parts.append("--require-narration-review")
-    if args.material_library_dir:
+    if uses_narration(args):
+        if args.review_narration is not None:
+            parts.append(
+                "--review-narration" if args.review_narration else "--no-review-narration"
+            )
+        if args.require_narration_review:
+            parts.append("--require-narration-review")
+    if args.material_library_dir and "material_library_dir" not in bound:
         parts += ["--material-library-dir", args.material_library_dir]
+    if getattr(args, "project", None):
+        parts += ["--project", args.project]
     if args.use_materials:
         parts.append("--use-materials")
     if args.save_materials:
         parts.append("--save-materials")
+    if args.require_final_qc:
+        parts.append("--require-final-qc")
     return " ".join(shlex.quote(part) for part in parts)
 
 
@@ -398,7 +415,6 @@ def _write_multi_source_clip_brief(work_dir, source_records, args):
             f"### {s['source_id']} — {s['source_name']}",
             f"- path: `{s['source_path']}`",
             f"- work_dir: `{swd}`",
-            f"- fingerprint: `{s['source_video_fingerprint']}`",
             f"- material_id: `{s['material_id']}`",
         ]
         excerpt = _brief_excerpt(swd / "agent_narration_brief.md")
@@ -449,11 +465,7 @@ def _write_multi_source_output_speech_evidence(work_dir, source_records, plan):
             when = float(anchor["time"])
             if not (source_start - 0.05 <= when <= source_end + 0.05):
                 continue
-            try:
-                pause = float(anchor["pause_start"])
-            except (TypeError, ValueError):
-                pause = when
-            pause = max(source_start, min(pause, when))
+            pause = max(source_start, min(float(anchor["pause_start"]), when))
             item = dict(anchor)
             item.update(
                 source_id=source_id,
@@ -491,11 +503,6 @@ def _write_multi_source_output_speech_evidence(work_dir, source_records, plan):
         "artifact": "speech_boundary_anchors_output.json",
         "timeline": "cut_output",
         "source_artifact": "multi_source_manifest.json",
-        "clip_plan_fingerprint": hashlib.md5(
-            json.dumps(
-                plan, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str
-            ).encode("utf-8")
-        ).hexdigest(),
         "sentence_anchors": sorted(mapped_anchors, key=lambda row: row["time"]),
         "speech_spans": sorted(mapped_speech, key=lambda row: (row["start"], row["end"])),
         "quiet_windows": sorted(mapped_quiet, key=lambda row: (row["start"], row["end"])),

package/lib/video-recap/skills/video-recap/scripts/resource_lock.py

@@ -0,0 +1,162 @@
+"""Record every resource and template a finished run used: ``work_dir/resource_lock.json``.
+
+Facts come from artifacts the stages already wrote (run manifest, ``tts_meta.json``,
+``assembly_manifest.json``) plus the optional project binding. When a library is
+configured, each file-backed entry is matched to a registered resource by resolved path
+so its licence and consent status travel with the run. Nothing here changes a render.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import library as library_lib
+from materials import file_identity
+
+LOCK_NAME = "resource_lock.json"
+LOCK_SCHEMA = "video-recap.resource-lock.v1"
+
+
+def _read(path: Path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def _file_entry(role: str, path, detail=None) -> dict:
+    entry = {"role": role, "path": None, "size": None, "mtime_ns": None,
+             "detail": detail or {}, "library": None}
+    if path:
+        resolved = Path(path).expanduser().resolve()
+        entry["path"] = str(resolved)
+        if resolved.is_file():
+            entry.update(file_identity(resolved))
+    return entry
+
+
+def _source_entries(work_dir: Path) -> list[dict]:
+    manifest = _read(work_dir / "recap_run_manifest.json") or {}
+    if manifest.get("mode") == "multi_source":
+        return [_file_entry("source_video", s.get("source_path"), {"source_id": s.get("source_id")})
+                for s in manifest.get("sources", [])]
+    if manifest.get("source_video"):
+        return [_file_entry("source_video", manifest["source_video"])]
+    return []
+
+
+def _voice_entry(work_dir: Path) -> dict | None:
+    meta = _read(work_dir / "tts_meta.json")
+    if not isinstance(meta, dict):
+        return None
+    voice = meta.get("voice") or {"provider": meta.get("engine")}
+    reference = voice.get("reference") or {}
+    entry = _file_entry("voice", reference.get("path"), {
+        "provider": voice.get("provider"), "model": voice.get("model"),
+        "voice_id": voice.get("voice_id"),
+    })
+    return entry
+
+
+def _assembly_entries(work_dir: Path) -> list[dict]:
+    manifest = _read(work_dir / "assembly_manifest.json") or {}
+    settings = manifest.get("assembly_settings") or {}
+    entries = []
+    bgm = (settings.get("audio_mix") or {}).get("bgm_path")
+    if bgm:
+        entries.append(_file_entry("bgm", bgm))
+    packaging = (settings.get("video_filters") or {}).get("packaging_layers") or {}
+    for layer in packaging.get("layers", []):
+        entries.append(_file_entry("packaging_layer", layer.get("path"), {"name": layer.get("name")}))
+    style = settings.get("subtitle_style")
+    if isinstance(style, dict):
+        entries.append(_file_entry("subtitle_font", style.get("font_file"),
+                                   {"family": style.get("font_name")}))
+    return entries
+
+
+def _match_library(entries: list[dict], index: dict) -> None:
+    by_path = {}
+    for resource in index["resources"]:
+        for f in resource["files"]:
+            by_path[str(Path(f["path"]).resolve())] = resource
+    voices = [r for r in index["resources"] if r["kind"] == "voice"]
+    records = {r["id"]: json.loads(Path(r["record"]).read_text(encoding="utf-8"))
+               for r in index["resources"]}
+    for entry in entries:
+        resource = by_path.get(entry["path"]) if entry["path"] else None
+        if (resource is None and entry["role"] == "voice" and not entry["path"]
+                and isinstance(entry["detail"].get("voice_id"), str) and entry["detail"]["voice_id"]):
+            detail = entry["detail"]
+            resource = next((v for v in voices
+                             if (records[v["id"]].get("voice") or {}).get("provider") == detail.get("provider")
+                             and (records[v["id"]].get("voice") or {}).get("voice_id") == detail.get("voice_id")), None)
+        if resource is None:
+            continue
+        record = records[resource["id"]]
+        entry["library"] = {"id": resource["id"], "kind": resource["kind"],
+                            "license": resource["license"],
+                            "consent": (record.get("consent") or {}).get("status")}
+
+
+def _attention(entries: list[dict], library_configured: bool) -> list[dict]:
+    items = []
+    for entry in entries:
+        role, lib = entry["role"], entry["library"]
+        if role == "source_video":
+            continue
+        if lib is None:
+            if library_configured and (entry["path"] or role == "voice"):
+                items.append({"code": "unregistered", "role": role,
+                              "message": "资源库中没有登记这项资源，授权状态未知"})
+            continue
+        if lib["license"] in {"unknown", "restricted"}:
+            items.append({"code": f"license_{lib['license']}", "role": role,
+                          "message": f"{lib['id']} 的授权状态为 {lib['license']}，交付前需要人工确认"})
+        if role == "voice" and entry["path"] and lib.get("consent") != "granted":
+            items.append({"code": f"consent_{lib.get('consent') or 'unknown'}", "role": role,
+                          "message": f"{lib['id']} 的参考音频声音授权未确认"})
+    return items
+
+
+def build_resource_lock(work_dir, *, library_dir=None, project=None) -> dict:
+    """Assemble the lock payload from a finished work_dir; ``project`` is a resolved binding."""
+    work_dir = Path(work_dir)
+    entries = _source_entries(work_dir)
+    voice = _voice_entry(work_dir)
+    if voice:
+        entries.append(voice)
+    entries += _assembly_entries(work_dir)
+    entries += list((project or {}).get("resources", []))
+    library_root = None
+    if library_dir and Path(library_dir).is_dir():
+        library_root = str(Path(library_dir).resolve())
+        index, _ = library_lib.scan_library(library_root)
+        _match_library(entries, index)
+    return {
+        "schema": LOCK_SCHEMA,
+        "generated_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
+        "work_dir": str(work_dir.resolve()),
+        "library": library_root,
+        "project": ({"path": project["path"], "name": project.get("name", "")} if project else None),
+        "templates": list((project or {}).get("templates", [])),
+        "resources": entries,
+        "attention": _attention(entries, library_root is not None),
+    }
+
+
+def write_resource_lock(work_dir, *, library_dir=None, project=None) -> dict:
+    lock = build_resource_lock(work_dir, library_dir=library_dir, project=project)
+    path = Path(work_dir) / LOCK_NAME
+    path.write_text(json.dumps(lock, ensure_ascii=False, indent=2), encoding="utf-8")
+    return lock
+
+
+def summary_line(lock: dict) -> str:
+    registered = sum(1 for e in lock["resources"] if e["library"])
+    text = (f"[video-recap] 资源记录: {LOCK_NAME}（{len(lock['resources'])} 项，"
+            f"资源库已登记 {registered} 项）")
+    if lock["attention"]:
+        text += "\n" + "\n".join(f"[video-recap]    ⚠ {a['role']}: {a['message']}" for a in lock["attention"])
+    return text

package/lib/video-recap/skills/video-script/SKILL.md

@@ -1,15 +1,20 @@
 ---
 name: video-script
 description: >
- 对已完成分析的视频进行导演与剪辑策划，再写带时间戳的中文解说并校验。work_dir 已包含
- agent_narration_brief.md 与 vlm_analysis.json 时使用。适用于故事方向、片段选择、画面/原声/旁白分工、
- 解说写作与复核。输入 work_dir 中的理解索引；输出 recap_story_plan.json、visual_audio_board.json、
- 可选 style_card.json、cut 模式需要的 clip_plan.json，以及通过校验的 narration.json。触发词：解说词、写解说、视频旁白、
+ 对已完成分析的视频进行导演与剪辑策划，再写带时间戳的中文解说并校验；也处理已有短片的
+ 宣发标题、花字修订和外部文案回填。普通策划输入 work_dir 的 agent_narration_brief.md 与
+ vlm_analysis.json；文案返修输入当前成片的工程与内容证据。策划输出 recap_story_plan.json、visual_audio_board.json、
+ 可选 style_card.json、cut 模式需要的 clip_plan.json，以及通过校验的 narration.json；仅宣发文案任务交付提案或回填既有包装计划。
+ 触发词：解说词、写解说、视频旁白、宣发标题、花字修订、文案回填、
  narration script、写稿、解说文案、剪辑思路、导演思路。
 ---
 
 ## 1. 定位
 
+只改宣发标题、封面、花字或回填外部文案时，直接读 `references/promotional-copy.md`，
+按当前短片的观看理由和兑现位置处理指定文字层，不重做下述策划/旁白链。
+普通解说写作不因此增加平台调研或包装任务。
+
 本技能负责：创作方向、画面/声音计划、旁白写作与校验。Agent 不是 JSON 填写器，而要依次扮演：
 
 1. 导演
@@ -18,9 +23,9 @@ description: >
 4. 声音/旁白编辑
 5. 第一次观看的观众
 
-Agent 先记录简洁决定，再写时间线产物。`validate.py` 负责对理解索引做机械校验；full 模式还会把旁白对齐到安静窗口。
+Agent 先记录简洁决定，再写时间线产物。`validate.py` 负责对理解索引做机械校验；full 模式默认还会执行预算整理并计算旁白的原声重叠。已有批准稿应加 `--preserve-approved-text`，保留段落顺序、数量、时间、文本、停顿和扩展元数据，仅允许依据现有声音证据更新 `overlaps_speech`。
 
-下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。本技能不从其他技能目录读取参考文件或辅助脚本；外部输入只来自显式路径与 `work_dir` 产物。
+下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。
 
 ### 1.1 创作控制模式
 
@@ -125,7 +130,7 @@ cut 模式先根据 `recap_story_plan.json` 与 `visual_audio_board.json` 写原
 beat_id | function | change | POV | preferred moment | 入点 | 出点
 ```
 
-片段顺序必须构成一条完整故事线，而不是无序高光。可使用 0–1 个 cold open，随后回到因果清楚的 setup → turn → escalation → payoff。片段长度服从具体时刻，不使用统一秒数模板；片尾必须保留完整台词或动作。对短时间内密集的 scene-change 候选，先区分原片切点与本次拼接点：原片无关短镜头整段删，相关短镜头扩展到完整动作/反应；本次拼接点优先移动边界、恢复同源连续运动或合并片段，尽量不制造人工闪切。
+片段顺序必须构成一条完整故事线，而不是无序高光。可使用 0–1 个 cold open，随后回到因果清楚的 setup → turn → escalation → payoff。片段长度服从具体时刻，不使用统一秒数模板；片尾必须保留完整台词或动作。密集 scene-change 候选的来源判断与处理规则由剪辑阶段定义，写计划时遵循同一规则，不制造人工闪切。
 
 ## 4. 撰写旁白
 
@@ -232,17 +237,15 @@ python3 scripts/review.py --work-dir <work_dir>
 
 ```bash
 python3 scripts/validate.py --work-dir <work_dir> --mode full
+python3 scripts/validate.py --work-dir <work_dir> --mode full --preserve-approved-text
 # cut 输出时间线由编排器使用 --mode cut_output
 ```
 
-命令写出 `narration_lint.json`。full 模式还会根据安静窗口重写 `narration.json` 的时间。修复所有 error 后重复运行，直到校验干净，再继续 TTS 与合成。
+命令写出 `narration_lint.json`。full 模式默认执行字符预算整理、去重合并并依据安静窗口计算 `overlaps_speech`，但不会把时间段移动到安静窗口；`--preserve-approved-text` 则保留批准稿的原始时间、文本、停顿、顺序与扩展元数据，只允许更新实测 `overlaps_speech`。修复所有 error 后重复运行，直到校验干净，再继续 TTS 与合成。
 
 片名或题材明确但缺少剧情上下文时，先按本技能的 `references/research-guide.md` 写 `background_research.json`。若理解素材偏薄，brief 中的数量只能当上限：宁可少写、写实，也不要为凑数复述画面。
 
 ## 7. 能力边界
 
-- 不运行 ASR / VLM；只消费视频理解索引。
-- 不合成 TTS，也不渲染视频。
-- 不根据平台分析做优化；先建立内容意图与剪辑一致性。
-- `review.py` 不改写 `narration.json`；是否采用严格门禁由调用方决定。
-- `validate.py` 不改写文本含义，只检查或对齐时间与安静窗口。
+- 不运行 ASR / VLM，不合成 TTS，不渲染视频；只消费视频理解索引。
+- 平台研究仅用于明确的宣发任务；不替代当前片内事实，也不默认改变解说和剪辑。

package/lib/video-recap/skills/video-script/references/creative-editing-playbook.md

@@ -8,7 +8,7 @@
 - **DIRECTED**：用户已经指定结构、镜头、台词或表达，目标是准确落实而不是展示替代创意。
 - **REVISION**：基于已有版本看片修改。最新反馈覆盖旧决定；本轮未点名内容默认冻结。
 
-REVISION 先列本轮修改项与冻结项。表达、节奏、字幕意见写回 `style_card.json`，镜头与声音意见写回 `visual_audio_board.json`；只有故事主线改变才更新 `recap_story_plan.json`。删除内容时也删除过期的计划描述。完成后分别验证“该变的确实变了”和“不该变的没有漂移”。
+REVISION 先列本轮修改项与冻结项。表达、节奏、字幕意见写回 `style_card.json`，镜头与声音意见写回 `visual_audio_board.json`；只有故事主线改变才更新 `recap_story_plan.json`。删除内容时也删除过期的计划描述。只提能定位到 beat、镜头边界或句子的具体局部修法，未点名层继续冻结；完成后分别验证“该变的确实变了”和“不该变的没有漂移”。
 
 ## 决策优先级
 
@@ -53,7 +53,9 @@ beat 不是固定秒数、场景名或一句旁白；beat 是一次可感知的
 - 情绪如何转向；
 - 风险或代价如何升级。
 
-如果移除一个 beat 后，因果、人物或情绪都没有损失，它通常不值得占用成片时间。钩子必须提出这条故事真正会兑现的问题，不能制造正文不回答的夸张承诺。
+如果移除一个 beat 后，因果、人物或情绪都没有损失，它通常不值得占用成片时间。精简不能只保“发生了什么”：还要保住人物动机、接受条件，以及人物为何犹豫或行动；缺前提时回到源证据，用更短的原声或解说补齐，不恢复无关长铺垫。钩子必须提出这条故事真正会兑现的问题，不能制造正文不回答的夸张承诺。
+
+准备移交剪辑时，把这类不可删除的具体源时刻写入同一 `clip_plan.json.required_evidence`：`nodes` 每项记录唯一 `id`、实际文件绝对路径 `source`、原片秒 `start/end`、`track`（audio/video）和 `content`；多源可补 `source_id`。`before` 用 `[前提id, 回应id]` 登记本片必需的顺序。只锁必要区间，不锁整个 beat；不依赖 `reason` 里的“保留前提”一句话。剪辑执行器会在吸附剪点后核对这些要求，缺段时先修选择，再配音包装。
 
 ### 3. 画面剪辑：选择时刻，而不只选择事件
 
@@ -65,16 +67,18 @@ beat 不是固定秒数、场景名或一句旁白；beat 是一次可感知的
 - **不可替代瞬间**：停顿、迟疑、失误、眼神、动作声音中，哪一个让人物变得真实？
 - **节奏**：这一拍需要冲过去，还是需要多停半秒让含义落地？
 - **边界**：优先完整动作、完整台词和自然声音边界；不要机械地把每个片段切成同一长度。
+- **兑现**：以某个可见结果为看点时，只写证据已呈现的结果，不推断更强的结果（例：证据只到受击，就不能写成倒地或胜负）。
 
 进入 `clip_plan.json` 的不是“发生过的所有重要事件”，而是最能让观众经历这条主线的具体时刻。
 
-目标不是绝对最短，而是**最短但完整**：晚进不能丢掉理解动作所需的前提，早出不能吃掉表演的回报。建立空间和事实的镜头通常可以短；关键对视、亲吻、受伤反应、决定落地或沉默可以多停一点，让观众先感受到再离开。
+目标不是绝对最短，而是**最短但完整**：晚进不能丢掉理解动作所需的前提，早出不能吃掉表演的回报。建立空间和事实的镜头通常可以短；关键对视、亲吻、受伤反应、决定落地或沉默可以多停一点，让观众先感受到再离开。有情感回应或知情变化的反应镜不是冗余，不能仅因它是反打或停留较短就机械删除。
 
 场景之间的 IN / OUT 也要有任务：
 
 - 新人物、地点或情绪场景，先给画面一个可感知的建立时刻，再让旁白进入；旁白不必与画面同帧起跑。
 - OUT 优先落在动作完成、反应落地、台词句末、沉默结束或干净硬切前。
 - 不要在原片叠化、闪白或其他转场的中间再切一次。转场至少由画面变化、动作延续、声音接力或叙事跨越中的一项驱动。
+- 跨场镜头只能作明确的并置或主题呼应，不得拼成同场出手、接触、反应的虚假因果；花字只能补有证据的必要前提，不能替补源证据或提前宣布结果。
 
 scene-change score、逐帧亮度和接点 contact sheet 只用于诊断：检查每个接点前后约 0.5–1 秒，定位硬切、白闪或曝光叠化候选。修复优先收进稳定镜头、保留原片完整转场的一侧、扩展源素材，或用相邻有效镜头补足时长；不能为了视觉干净切断台词。最终必须真实播放接点，不能把检测分数当成观看结论。
 
@@ -90,7 +94,7 @@ ffmpeg -i input.mp4 -vf "select='gt(scene,0.35)',showinfo" -an -f null -
 - **本次剪辑制造的切点**：优先移动 IN / OUT、恢复同一源镜头的连续运动、合并相邻片段，或换成有叙事任务的连接镜头；能消除就不保留。溶解、闪白和包装不能用来遮掩坏接点。
 - **有意的原片蒙太奇**：只有当每个短镜头都提供新信息、动作或节奏回报，且正常播放仍清楚可读时才保留；否则按无关或过短镜头处理。
 
-密集度不是单一固定秒数门槛。先找同一短窗内的连续候选，再以正常速度播放判断观众感受到的是有效节奏还是闪烁。
+密集度不是单一固定秒数门槛。反打是否保留取决于它有没有新增信息，例如关系、情感回应、知情变化或空间/动作结果，而不是是否达到统一时长；先找同一短窗内的连续候选，再以正常速度播放判断观众感受到的是有效节奏还是闪烁。
 
 ### 4. 声音与旁白：先分工，再写字
 
@@ -128,7 +132,7 @@ ffmpeg -i input.mp4 -vf "select='gt(scene,0.35)',showinfo" -an -f null -
 再逐 beat 追问：
 
 - 删除它，什么会坏？什么都不坏就删。
-- 换成反应镜头，情绪是否更强？
+- 删除或换掉反应镜头后，是否丢失情感回应、知情变化或新的动作结果？
 - 旁白改成原声或沉默，含义是否更好？
 - 提前揭示或延后揭示，哪一个更符合 POV？
 - 能否晚进、早出，而不损失理解？

package/lib/video-recap/skills/video-script/references/promotional-copy.md

@@ -0,0 +1,68 @@
+# 宣发标题、花字与文案返修
+
+用户要求宣发选题、标题/封面/发布稿、花字优化，或把外部模型的文案回填时使用。
+只写解说或精修剪点时不增加这一步。
+
+## 先确定这条片卖什么
+
+从当前短片而不是整部剧提炼一个具体观看理由：人物做了什么选择、付出什么代价，
+观众将看懂什么或感受到什么。先标出片内兑现的画面/原声位置，再写承诺。
+同一批可以分别卖关系、选择、笑点、动作或推理，不把每条都套成反转或复仇。
+
+用户需要案例研究时，按发行状态选来源：
+
+- **已播剧**：看本剧社媒的真实讨论、传播切片与观众关注点，再判断当前短片能否承接。
+- **未发布剧**：用剧本特色和片内证据形成受众假设，参考近期成功宣发案例；不假设本剧已有热度。
+
+记录参考物料的发布者、链接、发布日期、采集日期、具体做法及可借部分。
+单条播放、整剧热度、话题聚合量分开写；有数字也不等于证明某句标题带来了成绩。
+旧研究需要更新时再查证；未查到的效果不补数字，离线方案明确只依据已有材料。
+
+## 给其他模型的任务包
+
+按共同剧情与观看理由分组，让每组有足够上下文，但每条分别交付。直接用短 Markdown
+任务包即可，不另造视频时间线。每条提供：
+
+1. **当前版本**：具体工程、对应成片和待渲染修改；有版本号时沿用已有值。
+2. **片内内容**：正文结束点、故事起因与回报、当前选镜、原声/解说字幕、时间属于哪版成片。
+3. **现有文案**：两行标题、花字及其位置/时间、时空提示；封面和发布稿存在时一并给出。
+4. **本轮范围**：允许修改的文字层，以及保留的剪点、字幕、旁白、声音、样式和片尾。
+5. **证据缺口**：角色所说与已发生事实的差别、未出现的结果、模糊专名和未核时码。
+
+附一段可直接使用的要求：
+
+> 先解释这条短片为什么值得点开、看完得到什么，再给主推文案；需要备选时按不同观看理由区分，
+> 不只替换近义词。两行常驻标题、封面字和发布标题各司其职。花字、时空提示分别列修改；
+> 每处给原文、建议、成片位置和片内依据。没有必要就不加花字。只看到工程/字幕时，
+> 时间窗是提案，不能声称已看片。若问题只能靠改镜头或声音解决，单列出来，不用加字掩盖。
+
+## 写字时的分工
+
+| 层 | 工作 | 常见修法 |
+|---|---|---|
+| 常驻标题 | 让陌生观众理解人物处境与本片回报 | 用动作和代价降低人名/术语门槛；不提前宣布未呈现的胜负 |
+| 封面字 | 在封面画面上聚焦一个看点 | 不再塞一遍两行标题；文字需与所选封面帧一致 |
+| 发布标题 | 补关系、背景或观看邀请 | 不把解说全文搬过来，不冒充角色原话 |
+| 花字 | 补必要理解、观察方向或克制的情绪批注 | 不重复对白、不遮关键动作；拥挤时优先撤花字 |
+| 时空提示 | 说明当前/往事、地点或画外判断来源 | 跟随画面切换，不跟跨场旁白提前切换 |
+| 对白/旁白字幕 | 忠实承载当前可听见的话 | 不属于宣发改字范围，不拿新花字覆盖或替代 |
+
+“却”“不是……而是……”不是禁词；当素材没有需要纠正的预期时，直接写行动和后果。
+人物许诺不等于事情已成，单向凝望不等于双方相爱，受伤不等于死亡。
+批量检查重复的是观看理由和句式，不把共享镜头但回报不同的片子合并成同题。
+
+## 回填到当前工程
+
+- 先核任务包对应的工程是否仍是本轮采用基础；已有新剪点、换序、换声或待渲染字幕时，
+  把建议重新对到新版本，不把旧全文覆盖回去，也不凭文件修改时间决定采用。
+- 复制当前工程为新候选，只改本轮采用项；未明确改动的文字、ID、时码、位置和可见性保留。
+  **没提到不等于删除**。`notes=[]` 在提案中可表示不新增；回填完整工程时则是清空整轨，
+  必须先把“保留/新增/替换/删除”逐项说明白。
+- 新增或明确调整花字/时空标的时间时，先对照当前成片的真实画面/台词和帧钟确定出入点；
+  CFR核实际帧，VFR用真实PTS找到对应帧号。建议窗只到小数三位时，不当作已核准的帧级锚点。
+- 使用已有包装工程的字段，不再造一套对白轨：标题、花字、时空提示各写回它们原本所在的层，
+  时间最终写整数半开区间的帧号，不是浮点秒数；工程里指向素材、字幕和样式的引用原样保留。
+  封面与发布稿仍放文案交付，不塞进画面渲染计划。
+- 回填后比较修改前后：逐项核已采用的文字变化、未改层一致、时窗未超正文。已有制作工具先做
+  计划校验；用户只要改轨时到此停止。渲染后再核新字实际出现、遮挡和阅读负担，不能把
+  工程已改叫成片已更新。

package/lib/video-recap/skills/video-script/references/research-guide.md

@@ -72,4 +72,4 @@
 | 结果互相矛盾 | 只使用用户提供的上下文或画面/ASR 可验证的信息 |
 | 信息可能剧透后续 | 只用于理解人物关系，不在解说里剧透用户没要求的后续剧情 |
 
-**原则**：背景资料只能补上下文，不能替代 `vlm_analysis.json` / `asr_result.json` 里的画面和对白证据，也不能假装已经被此前的视觉分析消费。
+**原则**：背景资料只能补上下文，不能替代 `vlm_analysis.json` / `asr_result.json` 里的画面和对白证据。