@oh-story/dsh 0.1.11 → 0.1.13

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

@@ -3,18 +3,22 @@
 import json
 import os
 import shlex
+import shutil
 import sys
 from pathlib import Path
 
 from lib import load_json
+from lib import file_identity, ffmpeg_filters, read_json_object
+import resources.project_binding as project_binding
+from library import LIBRARY_ENV
 from recap_runtime import (
-    _coerce_videos,
     _entry,
     _load_run_manifest,
     _multi_run_manifest_payload,
+    _resume_argv,
     _run_manifest_payload,
 )
-from recap_source import audio_binding, uses_narration
+from recap_source import audio_binding
 
 ASSEMBLY_MANIFEST = "assembly_manifest.json"
 
@@ -66,6 +70,41 @@ def _canonical_visual_overlay(overlay, segment):
     return item
 
 
+def _canonical_visual_overlays(narration_path):
+    return [
+        item
+        for segment in load_json(narration_path)
+        for overlay in segment.get("visual_overlays", [])
+        if (item := _canonical_visual_overlay(overlay, segment)) is not None
+    ]
+
+
+def _preflight_visual_overlays(work_dir, *, narration):
+    """Fail before TTS and render when the run will draw text overlays but this ffmpeg has
+    no drawtext (libfreetype; stock Homebrew ffmpeg lacks it). Overlays are authored content,
+    never a default, so they are not dropped silently the way a default subtitle burn
+    degrades: the message says how to remove them. Narration runs read narration.json (the
+    overlays are only written after TTS); source modes read an existing visual_overlays.json."""
+    work_dir = Path(work_dir)
+    if shutil.which("ffmpeg") is None:
+        return
+    if narration:
+        narration_path = work_dir / "narration.json"
+        overlays = _canonical_visual_overlays(narration_path) if narration_path.exists() else []
+        remedy = "删掉 narration.json 各段的 visual_overlays"
+    else:
+        data = read_json_object(work_dir / _VISUAL_OVERLAYS) or {}
+        overlays = data.get("overlays") if isinstance(data.get("overlays"), list) else []
+        remedy = f"删掉 {_VISUAL_OVERLAYS} 里的 overlays"
+    if not overlays or "drawtext" in ffmpeg_filters():
+        return
+    raise SystemExit(
+        f"本次运行有 {len(overlays)} 个画面文字叠加（visual_overlays），但当前 ffmpeg 不支持 drawtext"
+        " 滤镜（需要 libfreetype），会在最后渲染时失败。\n"
+        f"  解决其一：(1) 安装带 drawtext/libfreetype 的 ffmpeg；(2) {remedy} 后续跑。"
+    )
+
+
 def _write_canonical_visual_overlays(work_dir, narration_path):
     """Write assemble's canonical work_dir/visual_overlays.json recap handoff.
 
@@ -76,32 +115,13 @@ def _write_canonical_visual_overlays(work_dir, narration_path):
     empty overlay list.
     """
     path = Path(work_dir) / _VISUAL_OVERLAYS
-    overlays = [
-        item
-        for segment in load_json(narration_path)
-        for overlay in segment.get("visual_overlays", [])
-        if (item := _canonical_visual_overlay(overlay, segment)) is not None
-    ]
+    overlays = _canonical_visual_overlays(narration_path)
     payload = {"schema_version": 1, "overlays": overlays}
     path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
     print(f"[video-recap] 🧩 visual overlays: {len(overlays)} → {path}", flush=True)
     return path
 
 
-def _print_grounding_qc_pointer(work_dir):
-    qc_path = Path(work_dir) / "grounding_qc.json"
-    if not qc_path.exists():
-        return
-    data = load_json(qc_path)
-    ranges = data["review_coverage"]["time_ranges"]
-    warnings = data["warnings"]
-    suffix = f" · warnings {len(warnings)}" if warnings else ""
-    print(
-        f"[video-recap] 🧭 Grounding QC: {data['verdict']} · ranges {len(ranges)}{suffix} → {qc_path}",
-        flush=True,
-    )
-
-
 def _print_narration_review_pointer(work_dir, *, review_ran=True):
     """Surface the advisory narration review produced by this run, if any.
 
@@ -109,7 +129,6 @@ def _print_narration_review_pointer(work_dir, *, review_ran=True):
     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"
@@ -191,20 +210,16 @@ def _read_assembly_output(work_dir):
 
 
 def _read_phase_ledger(work_dir):
-    """Phase ledger (cut mode): which artifacts exist and the clip_plan/narration they match.
-
-    Lets resume be driven by recorded phase state rather than bare file existence — the
-    prerequisite for the cut-first/narrate-second two-pause flow, and the guard that keeps a
-    narration written for one clip_plan from silently driving a different cut into TTS.
-    None before the first cut pass has recorded anything.
+    """Phase ledger (cut mode with narration): the clip_plan identity the narration is
+    written against — the guard that keeps a narration written for one clip_plan from
+    silently driving a different cut into TTS. None before pass 2 has recorded it.
     """
     path = Path(work_dir) / PHASE_LEDGER
     return load_json(path) if path.exists() else None
 
 
-def _write_phase_ledger(work_dir, **fields):
-    ledger = _read_phase_ledger(work_dir) or {}
-    ledger.update(fields)
+def _write_phase_ledger(work_dir, clip_plan_identity):
+    ledger = {"clip_plan_identity": clip_plan_identity}
     (Path(work_dir) / PHASE_LEDGER).write_text(
         json.dumps(ledger, ensure_ascii=False, indent=2), encoding="utf-8"
     )
@@ -219,86 +234,9 @@ def _cut_narration_is_stale(ledger, current_clip_plan_identity):
     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")),
-        *[str(v) for v in _coerce_videos(video)],
-        "--work-dir",
-        str(work_dir),
-    ]
-    if args.context:
-        parts += ["--context", args.context]
-    if args.scene_threshold is not None:
-        parts += ["--scene-threshold", str(args.scene_threshold)]
-    if args.style != "纪录片":
-        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.skip_asr:
-        parts.append("--skip-asr")
-    if args.mimo_video_overview:
-        parts.append("--mimo-video-overview")
-    if args.mimo_qc != "off":
-        parts += ["--mimo-qc", args.mimo_qc]
-    if args.mimo_qc_refresh:
-        parts.append("--mimo-qc-refresh")
-    if not args.consolidate:  # default is ON; only the opt-out needs to round-trip
-        parts.append("--no-consolidate")
-    if args.consolidate_asr:
-        parts.append("--consolidate-asr")
-    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:
-        parts += ["--subtitle-y-top", str(args.subtitle_y_top)]
-    if args.subtitle_y_bot is not None:
-        parts += ["--subtitle-y-bot", str(args.subtitle_y_bot)]
-    if args.output_dir:
-        parts += ["--output-dir", args.output_dir]
-    if args.export_jianying:
-        parts.append("--export-jianying")
-    if args.jianying_bundle_media:
-        parts.append("--jianying-bundle-media")
-    if args.jianying_no_bundle_media:
-        parts.append("--jianying-no-bundle-media")
-    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")
+def _continuation_command(work_dir, args):
+    """Shell command that resumes this run: the original argv, replayable from any cwd."""
+    parts = [sys.executable, str(_entry("video-recap", "recap.py")), *_resume_argv(work_dir, args)]
     return " ".join(shlex.quote(part) for part in parts)
 
 
@@ -454,26 +392,57 @@ def _write_multi_source_output_speech_evidence(work_dir, source_records, plan):
             )
         return cache[source_id]
 
+    spans_by_source = {}
+    for clip in plan["clips"]:
+        spans_by_source.setdefault(clip["source_id"], []).append(
+            (float(clip["source_start"]), float(clip["source_end"])))
+
     mapped_anchors, mapped_speech, mapped_quiet = [], [], []
+    output_duration = max(float(clip["output_end"]) for clip in plan["clips"])
     for clip in plan["clips"]:
         source_id = clip["source_id"]
         source_start = float(clip["source_start"])
         source_end = float(clip["source_end"])
         output_start = float(clip["output_start"])
+        output_end = float(clip["output_end"])
+
+        def to_output(when):
+            # A source time on this clip's OUTPUT clock, never past its own span: the next
+            # clip on the output timeline plays a different range (or source).
+            when = min(max(when, source_start), source_end)
+            return round(min(output_start + when - source_start, output_end), 3)
+
         anchors, speech_rows, quiet_rows = load_source(source_id)
         for anchor in anchors:
             when = float(anchor["time"])
             if not (source_start - 0.05 <= when <= source_end + 0.05):
                 continue
-            pause = max(source_start, min(float(anchor["pause_start"]), when))
+            # The 0.05 s source slack can carry an anchor past the output's ends (a clip
+            # end frame-snapped 181.42 -> 181.40): narration cannot start there.
+            if not 0 <= round(output_start + when - source_start, 3) <= output_duration:
+                continue
+            # A pause end just past a frame-snapped edge belongs to this clip at that edge,
+            # unless another clip of the same source plays that instant itself.
+            if not source_start <= when <= source_end and any(
+                    start <= when <= end for start, end in spans_by_source[source_id]):
+                continue
+            # Same default as the single-source remap in video-understanding's timeline brief.
+            pause = max(source_start, min(float(anchor.get("pause_start", when - 0.12)), when))
             item = dict(anchor)
             item.update(
                 source_id=source_id,
                 source_time=round(when, 3),
-                time=round(output_start + when - source_start, 3),
-                source_pause_start=round(pause, 3),
-                pause_start=round(output_start + pause - source_start, 3),
+                time=to_output(when),
+                source_pause_start=round(min(pause, source_end), 3),
+                pause_start=to_output(pause),
+                # `time` IS the pause end; keep the source value apart (one clock per field).
+                source_pause_end=round(float(anchor.get("pause_end", when)), 3),
             )
+            item["pause_end"] = item["time"]
+            if "expected_time" in anchor:
+                expected = float(anchor["expected_time"])
+                item["source_expected_time"] = round(expected, 3)
+                item["expected_time"] = to_output(expected)
             mapped_anchors.append(item)
         for rows, destination, require_text in (
             (speech_rows, mapped_speech, True),
@@ -493,8 +462,8 @@ def _write_multi_source_output_speech_evidence(work_dir, source_records, plan):
                     source_id=source_id,
                     source_start=round(start, 3),
                     source_end=round(end, 3),
-                    start=round(output_start + start - source_start, 3),
-                    end=round(output_start + end - source_start, 3),
+                    start=to_output(start),
+                    end=to_output(end),
                 )
                 destination.append(item)
 
@@ -503,6 +472,8 @@ 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",
+        # video-script's cut_output lint trusts this evidence only for this exact plan file.
+        "clip_plan_identity": file_identity(Path(work_dir) / "clip_plan_validated.json"),
         "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"])),
@@ -552,14 +523,31 @@ def _write_multi_source_output_brief(work_dir, source_records, validated_plan_pa
             f"{c['source_id']} `{src['source_path']}` "
             f"source {_fmt_range(c['source_start'], c['source_end'])}{reason}"
         )
-    anchors = speech_evidence["sentence_anchors"]
-    if anchors:
-        lines += ["", "## 原声句末安全切入点"]
-        lines.extend(
-            f"- {row['time']:.3f}s ({row['source_id']})"
-            for row in anchors
-            if row["confidence"] in {"high", "medium"}
+    anchors = []
+    for row in speech_evidence["sentence_anchors"]:
+        # Schema-1 anchors (no `boundary_use`) came from the old coarse estimator: high/medium
+        # labels there are usable but unverified.
+        use = row.get("boundary_use") or (
+            "unverified" if row["confidence"] in {"high", "medium"} else "none"
         )
+        if use != "none":
+            anchors.append((row, use))
+    if anchors:
+        lines += [
+            "",
+            "## 原声句末安全切入点",
+            "",
+            "`unverified` 点是粗粒度 ASR 窗口里的标点位置估计、再吸附到短停顿：不切断单词，"
+            "但不保证原声句子已说完（误差上限见 `±`）；门禁照常生效。",
+        ]
+        for row, use in anchors:
+            if use == "verified":
+                label = row["confidence"]
+            elif "timing_bound_seconds" in row:
+                label = f"unverified ±{float(row['timing_bound_seconds']):.1f}s"
+            else:  # schema-1 anchors carry no error bound
+                label = "unverified"
+            lines.append(f"- {row['time']:.3f}s [{label}] ({row['source_id']})")
     lines += ["", "## Source work dirs"]
     for s in source_records:
         lines.append(f"- {s['source_id']}: `{_source_work_dir(work_dir, s)}`")
@@ -595,7 +583,7 @@ def _fmt_range(start, end):
 
 
 def _material_library_dir(args):
-    return args.material_library_dir or os.environ.get("VIDEO_RECAP_MATERIAL_LIBRARY_DIR") or None
+    return args.material_library_dir or os.environ.get(LIBRARY_ENV) or None
 
 
 def _materials_enabled(args):
@@ -606,7 +594,7 @@ def _save_materials_enabled(args):
     return bool(_material_library_dir(args) and args.save_materials)
 
 
-def _pause_for_agent(work_dir, need_text, cont, inspect_hint=None):
+def _pause_for_agent(work_dir, need_text, cont, inspect_hint=None, project=None):
     brief = Path(work_dir) / "agent_narration_brief.md"
     print("=" * 50)
     if "Research the story FIRST" in brief.read_text(encoding="utf-8"):
@@ -617,5 +605,8 @@ def _pause_for_agent(work_dir, need_text, cont, inspect_hint=None):
     print(f"[video-recap] ⏸  阅读 {brief}（按 video-script 规则）后写入 {need_text}")
     if inspect_hint:
         print(f"[video-recap]    先核对状态/时间轴（建议性）: {inspect_hint}")
+    reference_note = project_binding.bound_reference_note(work_dir, project)
+    if reference_note:
+        print(f"[video-recap]    {reference_note}")
     print(f"[video-recap]    写完后重跑继续: {cont}")
     print("=" * 50)

package/lib/video-recap/skills/video-recap/scripts/resources/__init__.py

@@ -0,0 +1,4 @@
+"""Resource-library consumers on the run path: project binding and the per-run resource lock.
+
+The library entry itself stays top-level as ``library.py`` (a ``library/`` package would shadow it).
+"""

package/lib/video-recap/skills/video-recap/scripts/{resource_lock.py → resources/lock.py}

@@ -12,7 +12,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 import library as library_lib
-from materials import file_identity
+from lib import file_identity
 
 LOCK_NAME = "resource_lock.json"
 LOCK_SCHEMA = "video-recap.resource-lock.v1"

package/lib/video-recap/skills/video-recap/scripts/{project_binding.py → resources/project_binding.py}

@@ -2,7 +2,8 @@
 
 Only video-recap reads the library. A bound subtitle style becomes ``SUBTITLE_*`` env for
 video-assemble, a bound voice becomes the voiceover provider / voice arguments, a bound
-BGM becomes ``BGM_PATH``. Stage skills keep seeing concrete paths and values; they never
+BGM becomes ``BGM_PATH``, a bound production reference becomes a marked copy in the work_dir
+that only the writing agent reads. Stage skills keep seeing concrete paths and values; they never
 learn about templates. Anything the caller already set explicitly must agree with the
 binding — a silent override would make the delivered file disagree with the project.
 """
@@ -17,7 +18,8 @@ import library as library_lib
 PROJECT_FILE = "recap_project.json"
 PROJECT_SCHEMA = "video-recap.project.v1"
 PROJECT_KEYS = {"schema", "name", "library", "bindings", "notes"}
-BINDING_KINDS = ("subtitle_style", "packaging", "voice", "bgm")
+BINDING_KINDS = ("subtitle_style", "packaging", "voice", "bgm", "production_reference")
+GEOMETRY_ROLES = {"subtitle_style", "packaging"}
 
 
 class BindingError(SystemExit):
@@ -188,6 +190,14 @@ def resolve_project(value, args, environ=None, *, include_voice=True) -> dict:
         used_templates.append({"role": "packaging", "id": packaging["id"],
                                "version": packaging["version"], "status": packaging["status"],
                                "canvas": packaging["canvas"]})
+    reference = template("production_reference")
+    if reference:
+        used_templates.append({"role": "production_reference", "id": reference["id"],
+                               "version": reference["version"], "status": reference["status"],
+                               "canvas": reference["canvas"]})
+        reference = {"template": {"id": reference["id"], "version": reference["version"]},
+                     "payload": json.loads((Path(reference["record"]).parent / library_lib.REFERENCE_FILE)
+                                           .read_text(encoding="utf-8"))}
     voice = resource("voice") if include_voice else None
     if voice:
         voice_updates, voice_env = _voice_updates(voice, args)
@@ -221,6 +231,7 @@ def resolve_project(value, args, environ=None, *, include_voice=True) -> dict:
         "templates": used_templates,
         "resources": [],
         "packaging": packaging and {"record": _record(packaging), "resources": resources},
+        "production_reference": reference,
     }
 
 
@@ -244,6 +255,8 @@ def apply_project(resolved, args, environ=None) -> None:
 def check_canvas(resolved, width, height) -> None:
     """Templates only apply to the canvas they were calibrated on."""
     for template in resolved["templates"]:
+        if template["role"] not in GEOMETRY_ROLES:  # a production reference carries no geometry
+            continue
         canvas = template["canvas"]
         if (canvas["width"], canvas["height"]) != (width, height):
             raise BindingError(
@@ -253,34 +266,82 @@ def check_canvas(resolved, width, height) -> None:
 
 
 PACKAGING_LAYERS = "packaging_layers.json"
+REFERENCE_COPY = "production_reference.json"
 _WRITTEN_BY = "video-recap --project"
 
 
-def sync_packaging_layers(work_dir, resolved) -> None:
-    """Write the bound packaging template's layers for video-assemble, or retire our old copy.
+def _read_json(path):
+    try:
+        return json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
 
-    A caller-authored ``packaging_layers.json`` (no ``written_by`` marker) is left alone.
+def _ours(data) -> bool:
+    return isinstance(data, dict) and data.get("written_by") == _WRITTEN_BY
+
+
+def _sync_bound_file(work_dir, name, payload) -> None:
+    """Write ``payload`` with our marker, or retire our old copy when nothing is bound.
+
+    A caller-authored file (no ``written_by`` marker) is never deleted.
     """
-    path = Path(work_dir) / PACKAGING_LAYERS
+    path = Path(work_dir) / name
+    if payload is None:
+        if path.exists() and _ours(_read_json(path)):
+            path.unlink()
+        return
+    # The marker goes last so a payload key of the same name can never unmark our copy.
+    path.write_text(json.dumps({**payload, "written_by": _WRITTEN_BY}, ensure_ascii=False, indent=2),
+                    encoding="utf-8")
+
+
+def sync_packaging_layers(work_dir, resolved) -> None:
+    """Write the bound packaging template's layers for video-assemble, or retire our old copy."""
     packaging = (resolved or {}).get("packaging")
     if not packaging:
-        if path.exists():
-            try:
-                plan = json.loads(path.read_text(encoding="utf-8"))
-            except ValueError:
-                plan = None
-            ours = isinstance(plan, dict) and plan.get("written_by") == _WRITTEN_BY
-            if ours:
-                path.unlink()
+        _sync_bound_file(work_dir, PACKAGING_LAYERS, None)
         return
     record, resources = packaging["record"], packaging["resources"]
     layers = [{"name": layer["name"],
                "path": resources[layer["image"]["resource"]]["files"][0]["path"],
                "rect": layer["rect"]}
               for layer in record["params"]["layers"]]
-    path.write_text(json.dumps({
-        "written_by": _WRITTEN_BY,
+    _sync_bound_file(work_dir, PACKAGING_LAYERS, {
         "template": {"id": record["id"], "version": record["version"]},
         "canvas": record["canvas"],
         "layers": layers,
-    }, ensure_ascii=False, indent=2), encoding="utf-8")
+    })
+
+
+def sync_production_reference(work_dir, resolved) -> None:
+    """Hand the bound reference to the writing agent before its first pause; no script reads it.
+
+    A caller's own copy is never rewritten: identical to the binding it is left as is, different
+    from it is a conflict, like any other setting.
+    """
+    bound = (resolved or {}).get("production_reference")
+    path = Path(work_dir) / REFERENCE_COPY
+    if bound and path.exists():
+        current = _read_json(path)
+        if not _ours(current):
+            if current == bound["payload"]:
+                return
+            template = bound["template"]
+            raise BindingError(f"{path} 不是 --project 写的，与绑定的 {template['id']}@v{template['version']} "
+                               "不同；删掉其中一处")
+    _sync_bound_file(work_dir, REFERENCE_COPY,
+                     bound and {**bound["payload"], "template": bound["template"]})
+
+
+def bound_reference_note(work_dir, resolved=None) -> str | None:
+    """The pause-banner line for the bound reference in work_dir (our copy or the caller's identical one)."""
+    data = _read_json(Path(work_dir) / REFERENCE_COPY)
+    bound = (resolved or {}).get("production_reference")
+    if _ours(data):
+        template = data.get("template") or {}
+    elif bound and data == bound["payload"]:
+        template = bound["template"]
+    else:
+        return None
+    return f"本轮带制作参考 {template.get('id')}@v{template.get('version')}（可选，取舍写入 reference_methods）"

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

@@ -0,0 +1,108 @@
+---
+name: video-reference
+user-invocable: true
+description: >
+ 按需把一部成片拆成可复用的制作参考：测镜头节奏与响度，标注段落与音轨分工，把原片事实与可迁移方法分开，
+ 导出不含原片人名台词的 production_reference.json 供下次制作参考。不在默认生产路径上。
+ 触发词：拆片、拆解成片、制作参考、参考模板、production reference。
+---
+
+## 1. 定位
+
+本技能把一部**已完成的成片**拆成下一次制作能直接参考的方法与数值。它是按需的参考分析，不是生产阶段，也不是质检：
+不调用 MiMo，不改其他产物，不给任何运行打分或拦截。
+
+Agent 的角色是**拆片编辑**：先如实记录"这部片子怎么做的"（事实），再提炼"换一部素材还能怎么用"（方法）。
+两者必须分开：事实只留在本地工作目录，导出物只含方法和测得的数值。
+
+## 2. 输入
+
+- 成片文件（`.mp4 / .mov / .mkv / .webm`）。
+- 对**这部成片**跑出的视频理解产物目录 `U`（建议 `ASR_SEGMENT_SECONDS=5`，窗口越短，旁白语速越准）。
+  本技能读取其中可选的 `asr_result.json`、`asr_timing_evidence.json`、`background_research.json`、`understanding_index.json`
+  （其 `characters` 的名字、别名与 ASR 提及都进入人名泄漏扫描）；
+  标注时 Agent 还应看故事板 / contact sheet 与 `vlm_analysis.json`。
+
+没有理解产物也能跑，但旁白语速为空，泄漏扫描只剩 Agent 自己写的 `entities`，check 会给出警告；
+看画面改用 `frames --span 0,<时长> --step 2` 的接触表。
+
+下面的 `scripts/...` 均相对于本技能目录。
+
+## 3. 流程
+
+```bash
+python3 scripts/reference.py measure <成片> --work-dir U        # 一次 ffmpeg：切点 + 响度，按文件身份缓存
+python3 scripts/reference.py frames  <成片> --work-dir U --review          # 逐帧看被压下的疑似切点
+python3 scripts/reference.py frames  <成片> --work-dir U --longest 5       # 看最长镜头里有没有漏切
+python3 scripts/reference.py check   --work-dir U [--json]      # 校验并打印派生值
+python3 scripts/reference.py export  --work-dir U --out <下次运行的 work_dir>/production_reference.json
+```
+
+1. **measure** 写 `U/reference_measurements.json`（只由脚本写）：镜头切点、镜长分布、每分钟切点数、10 秒切点曲线、
+   整体响度 / LRA / 真峰值、逐秒短期响度。它要解码整片：5 分钟 720p 约 15–70 秒，4K 约 7 分钟；成片不变时复用，
+   只改 `--soft-score/--hard-score` 不重新解码。切点规则：scdet 分数 ≥10 必算；≥4 且是前后 0.3 秒内其他帧（相邻帧除外）
+   两倍以上的孤立峰才算。运动镜头、急推拉、闪光会被压下，并列进 `shots.review_windows`；scdet 分数会减去前一帧的帧差，
+   从快速运动切进静止镜头的硬切可能只有 1 分，所以帧差本身的单侧峰（`mafd_peaks`）也进待复核窗口，但不会自动算切点。
+2. **复核切点**：固定阈值在真实成片上两头都错（暗场硬切只有 5–7 分；快速运动的单个镜头每 0.2 秒一个 7–8 分的峰），
+   所以每次都要看图。`frames --review` 逐帧拼出每个待复核窗口，`frames --longest 5` 在最长的 5 个镜头里均匀取 12 帧；
+   页面在 `U/reference_frames/`，命令打印每格对应的秒数。看完写 `labels.cut_fixes`：`add` 漏掉的切点秒数，
+   `remove` 误报的切点秒数（±0.1 秒内对上测得的切点）；看过无需改动就写 `{}`。重新 `measure` 后待复核窗口数变了，旧的 `cut_fixes` 不再算数，按新窗口重看一遍。之后所有镜头数值、段内切点密度和导出都用复核后的切点。
+3. **标注**：Agent 写 `U/reference_breakdown.json` 的 `labels`——音轨归属 `audio_spans`、叙事段落 `sections`、
+   字幕形态 `subtitles`、标注依据 `basis`。`audio_spans` 的边界放在**声音实际起止**处（听得到的人声起点与止点），
+   不放在字幕或旁白块的开始处（按字幕出现帧定的旁白结束点实测晚 0.24–0.42 秒）。`U/speech_boundary_anchors.json` 存在时，
+   用它的 `acoustic_pauses`（`start` 是人声停下处，`end` 是下一句开口处）对齐边界；`switch_on_cut_share` 只容差 ±0.25 秒，
+   边界放错它就只反映标注习惯。原片自带的画外音、内心独白也是原片音轨，记 `original_dialogue`；要区分时写进 fact 和方法。
+   只有 labels 时就可以跑 check，它会打印 `derived`（各音轨占比、段内切点密度、
+   旁白语速、声音切换与画面切点的对齐比例、分数位置的结构、第一次原声出现位置）。
+4. **事实与方法**：在同一文件写 `source_facts`（带时间或测量锚点、显式 `entities`）和 `methods`
+   （`rule`、`applies_when`、`avoid_when`、`applies_to`、`evidence`、`targets`）。`targets` 只写 `{"from": "<测量路径>"}`，
+   数值由 export 从当前测量填入，Agent 永远不手写数字。
+5. **check → export**：零 error 才导出；导出后对产物再做一次泄漏扫描。
+
+字段、枚举和好/坏方法示例见 `references/reference-schema.md`。
+
+## 4. 分离规则
+
+check 的 error（退出码 1）：
+
+| 规则 | 要求 |
+|---|---|
+| R1 | 顶层、labels、fact、method、target、`cut_fixes` 都是封闭键集与封闭枚举；fact 不能带方法字段，method 不能带事实字段；id 为 `f1…` / `m1…` 且唯一；`subtitles` 值类型固定；`skipped_dimensions` 的值都是非空字符串 |
+| R2 | `audio_spans`、`sections` 按时间排序、不重叠、间隙 ≤0.5s、覆盖整片；字幕证据时间在时长内；`cut_fixes.remove` 对得上测得的切点，`add` 不与测得的切点重复 |
+| R3 | 每条 fact 二选一锚定：`t:[a,b]` 在时长内，或 `measure:[路径]` 解析到 `shots` / `loudness` / `derived` 下的非字符串值；必须显式写 `entities` |
+| R4 | 每条 method 至少一条证据：已有 fact id 或同样只认这三个根的 `measure:<路径>` |
+| R5 | target 只写 `from`：`shots` / `loudness` / `derived` 下的数值叶子，或白名单派生对象（见 schema）；不得带列表下标 |
+| R6 | `rule` / `applies_when` / `avoid_when` 和 `skipped_dimensions` 的原因不得含：原片实体名（忽略空白）、与台词、背景资料或事实共有的连续 8 个汉字（标点隔开、跨相邻 ASR 窗口也算）或 5 个英文词、绝对时间码、"第 N 秒"或"N 分 M 秒"（含中文数字）、绝对路径 |
+| R7 | 五个维度各至少一条 method，或在 `skipped_dimensions` 写明原因 |
+| R8 | 导出物的每个键和字符串再扫一遍 R6，且不得出现 `source_facts`、`labels`、`entities`、`evidence`、`statement`、`from`、`path` 键 |
+
+实体名来自 fact `entities`、`understanding_index.json` 的 `characters` / `entities` / `research_glossary` 名字与别名、`background_research.json` 的角色与
+`character_details` 别名、≤5 字的 `cultural_notes` 条目，以及资料里《》「」引号中的短词。与事实共有 8 字时错误会注明来自
+source_facts：通用剪辑措辞改写任一侧即可。
+
+警告不阻断：method 缺 `applies_when`、rule 正文写了数字、ASR 不是 `AVAILABLE_COARSE`、有中文对白但理解产物与背景资料都没给出名字（此时只扫 fact `entities`）、`basis` 为空、
+理解产物记录的成片身份与测量的成片不一致、有待复核窗口却没写 `cut_fixes`。
+
+R6 只能拦住字面泄漏，拦不住改写过的剧情；写方法时要写"什么情况下怎么做"，不要复述"这部片里发生了什么"。
+规则也不判断语义：方法的方向必须与 check 打印的派生值一致（例如先看各音轨的 `cuts_per_min` 再写"哪类段落切得密"）。
+
+## 5. 交付与使用
+
+`production_reference.json` 只含：时长与画布、`cut_detection`（切点规则的参数与 Agent 增删的切点数）、
+`profile`（节奏数值，`provenance` 为 `measured` / `reviewed`（写了 `cut_fixes`，`{}` 也算）/ `labeled`）、
+分数位置的 `structure`、字幕形态、`methods`、`skipped_dimensions`。
+
+使用方式：把它复制进下一次制作的 `work_dir`。写稿阶段只在文件存在时阅读它，
+并可在 `recap_story_plan.json` 的可选字段 `reference_methods` 记录每条方法的 adopt / adapt / skip。
+它是参考，不是配额：与新素材的证据冲突时以素材为准。没有任何脚本读取它，也不会因为它的存在改变任何阶段的通过与否。
+
+`U/` 里的 breakdown 与 `reference_frames/` 含原片事实和画面，只留在本地，不要复制或提交。
+
+## 6. 能力边界
+
+- 不调用 MiMo 或任何 LLM，不改动理解产物，不给成片打分，不做"新片与参考的差距"判定。
+- 切点来自 ffmpeg `scdet` 分数：慢叠化测不到；相隔 0.3 秒内分数相近的两个真切点、刚好压在 soft 线上的切点（不同 ffmpeg 构建
+  4.00 与 3.989 分）、运动后的暗场硬切（0.9 分）都不算切点，只进待复核窗口。在一部 5 分钟剧集解说上测得 82 个切点，
+  11 个待复核窗口里 4 个含漏掉的 5 个真切点，其余是急推拉、翻页和运动镜头；补上后，三段逐帧真值（开场、暗场、中段共 27 个）全部对上、无误报。
+- 旁白占比与语速是 `labeled` 精度：来自 Agent 的音轨标注与粗 ASR 窗口，不是逐词对齐。
+- 泄漏扫描基于字面匹配，Agent 仍需自查方法是否在复述原片剧情。