@lemoncat7/dsh-partner 2.8.1 → 2.8.3

package/resources/skills/video-recap-production/upstream/skills/video-cut/scripts/shot_review.py

@@ -0,0 +1,357 @@
+#!/usr/bin/env python3
+"""Read-only internal-shot recall on the actual rendered video; never repair an EDL."""
+import argparse
+from bisect import bisect_left
+from fractions import Fraction
+import json
+import math
+import os
+from pathlib import Path
+import re
+import subprocess
+import tempfile
+
+from cut_contract import edited_source_render_cache_payload
+from lib import file_identity
+
+
+def _positive(value, name, *, integer=False):
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError(f"{name} must be a positive number")
+    if not math.isfinite(value) or value <= 0 or (integer and not isinstance(value, int)):
+        raise ValueError(f"invalid {name}")
+
+
+def _validate_clock(pts, end):
+    if not pts or any(not isinstance(p, Fraction) for p in [*pts, end]):
+        raise ValueError("frame clock requires exact rational PTS")
+    if pts[0] != 0 or any(a >= b for a, b in zip(pts, pts[1:])) or end <= pts[-1]:
+        raise ValueError("invalid/nonmonotonic frame clock")
+
+
+def summarize_candidates(pts, end, cut_frames, *, max_short_frames=None,
+                         max_short_seconds=1.0, dense_window_seconds=2.0,
+                         min_dense_cuts=4):
+    """Half-open frame spans including the head and tail; thresholds are recall policy."""
+    _validate_clock(pts, end)
+    _positive(max_short_seconds, "max_short_seconds")
+    if max_short_frames is None:
+        # A fixed frame count only coincides with the seconds limit at one frame rate, so
+        # derive it from the measured clock; --max-short-frames stays an explicit override.
+        measured_fps = Fraction(len(pts), 1) / end
+        max_short_frames = max(1, round(measured_fps * Fraction(str(max_short_seconds))))
+    _positive(max_short_frames, "max_short_frames", integer=True)
+    _positive(dense_window_seconds, "dense_window_seconds")
+    _positive(min_dense_cuts, "min_dense_cuts", integer=True)
+    if any(type(f) is not int or not 0 < f < len(pts) for f in cut_frames):
+        raise ValueError("invalid candidate frame index")
+    cuts = sorted(set(cut_frames))
+    boundaries = [0, *cuts, len(pts)]
+    clock = [*pts, end]
+    short = []
+    for start, stop in zip(boundaries, boundaries[1:]):
+        duration = clock[stop] - clock[start]
+        if stop - start <= max_short_frames and duration <= Fraction(str(max_short_seconds)):
+            short.append({
+                "start_frame": start, "end_frame": stop, "frame_count": stop - start,
+                "start_exact": str(clock[start]), "end_exact": str(clock[stop]),
+                "duration_exact": str(duration), "duration_seconds": float(duration),
+                "review_status": "NEEDS_DYNAMIC_REVIEW",
+            })
+    windows = []
+    right = 0
+    window_duration = Fraction(str(dense_window_seconds))
+    for left in range(len(cuts)):
+        right = max(right, left)
+        while right < len(cuts) and pts[cuts[right]] - pts[cuts[left]] <= window_duration:
+            right += 1
+        if right - left < min_dense_cuts:
+            continue
+        members = cuts[left:right]
+        if windows and members[0] <= windows[-1]["cut_frames"][-1]:
+            windows[-1]["cut_frames"] = sorted(set(windows[-1]["cut_frames"]) | set(members))
+        else:
+            windows.append({"cut_frames": members, "review_status": "NEEDS_DYNAMIC_REVIEW"})
+    for window in windows:
+        window.update({"start_exact": str(pts[window["cut_frames"][0]]),
+                       "end_exact": str(pts[window["cut_frames"][-1]])})
+    return {
+        "status": "NEEDS_REVIEW" if short or windows else "NO_CANDIDATES",
+        "normal_speed_review": "NOT_CHECKED", "automatic_repairs": [],
+        "candidates": [{"frame": f, "pts_exact": str(pts[f]), "origin": "UNKNOWN"} for f in cuts],
+        "short_spans": short, "dense_windows": windows,
+        "policy": {"max_short_frames": max_short_frames, "max_short_seconds": max_short_seconds,
+                   "dense_window_seconds": dense_window_seconds, "min_dense_cuts": min_dense_cuts},
+    }
+
+
+def probe_frame_clock(video):
+    result = subprocess.run([
+        "ffprobe", "-v", "error", "-select_streams", "v:0", "-show_frames",
+        "-show_entries", "stream=time_base,start_pts,duration_ts:frame=pts,duration,pkt_duration",
+        "-of", "json", str(video),
+    ], capture_output=True, text=True, timeout=600)
+    if result.returncode or result.stderr.strip():
+        raise RuntimeError(f"frame decode probe failed: {result.stderr[-2000:]}")
+    try:
+        data = json.loads(result.stdout)
+        stream = data["streams"][0]
+        tb = Fraction(stream["time_base"])
+        if tb <= 0:
+            raise ValueError("nonpositive time base")
+        frames = data["frames"]
+        absolute = [int(f["pts"]) * tb for f in frames]
+        origin = absolute[0]
+        pts = [p - origin for p in absolute]
+        last_duration = frames[-1].get("duration", frames[-1].get("pkt_duration"))
+        if last_duration is None or int(last_duration) <= 0:
+            raise ValueError("missing/invalid terminal frame duration")
+        decoded_end = pts[-1] + int(last_duration) * tb
+        if "duration_ts" in stream:
+            end = (int(stream.get("start_pts", frames[0]["pts"])) + int(stream["duration_ts"])) * tb - origin
+            if abs(end - decoded_end) > tb:
+                raise ValueError("decoded frame coverage does not reach declared stream end")
+        else:
+            end = decoded_end
+        _validate_clock(pts, end)
+    except (KeyError, IndexError, ValueError, TypeError, ZeroDivisionError) as exc:
+        raise ValueError(f"cannot establish exact frame clock: {exc}") from exc
+    return pts, end, origin
+
+
+def _validate_scene_roi(roi, video):
+    """Validate an ROI (four ints from the CLI) against the video's auto-oriented native frame."""
+    if len(roi) != 4:
+        raise ValueError("scene ROI must contain exactly four integers")
+    x, y, width, height = roi
+    if x < 0 or y < 0 or width <= 0 or height <= 0:
+        raise ValueError("scene ROI requires x/y >= 0 and width/height > 0")
+
+    from media_geometry import _probe_video_geometry
+    facts = _probe_video_geometry(video).facts
+    rotation = facts["rotation"]
+    if rotation not in {0, 90, 180, 270}:
+        raise ValueError("scene ROI requires a right-angle video rotation")
+    canvas_width, canvas_height = (
+        (facts["coded_height"], facts["coded_width"]) if rotation in {90, 270}
+        else (facts["coded_width"], facts["coded_height"])
+    )
+    if x + width > canvas_width or y + height > canvas_height:
+        raise ValueError(
+            f"scene ROI exceeds auto-oriented native frame {canvas_width}x{canvas_height}"
+        )
+
+
+def detect_scene_pts(video, threshold, roi=None):
+    """No seek or float pts_time: showinfo integer pts + its actual filter timebase.
+
+    The single library-side check of threshold/ROI; the CLIs pre-check with parser.error."""
+    if isinstance(threshold, bool) or not isinstance(threshold, (int, float)) or not math.isfinite(threshold) or not 0 <= threshold <= 1:
+        raise ValueError("scene threshold must be finite and in [0,1]")
+    filters = []
+    if roi is not None:
+        _validate_scene_roi(roi, video)
+        x, y, width, height = roi
+        filters.append(f"crop={width}:{height}:{x}:{y}:exact=1")
+    filters.extend([f"select='gt(scene,{threshold})'", "showinfo"])
+    result = subprocess.run([
+        "ffmpeg", "-hide_banner", "-nostdin", "-v", "info", "-xerror", "-copyts",
+        "-threads", "2", "-i", str(video), "-map", "0:v:0",
+        "-vf", ",".join(filters),
+        "-an", "-fps_mode", "passthrough", "-f", "null", "-",
+    ], capture_output=True, text=True, timeout=600)
+    if result.returncode:
+        raise RuntimeError(f"scene decode failed: {result.stderr[-2000:]}")
+    bases = set(re.findall(r"config in time_base:\s*([0-9]+/[0-9]+)", result.stderr))
+    if len(bases) != 1:
+        raise ValueError("ambiguous or missing scene filter timebase")
+    tb = Fraction(bases.pop())
+    if tb <= 0:
+        raise ValueError("invalid scene filter timebase")
+    values = re.findall(r"\bn:\s*\d+\s+pts:\s*(-?\d+)\s+pts_time:", result.stderr)
+    return [int(p) * tb for p in values]
+
+
+def load_bound_plan(video, plan_path):
+    """Only associate with the current cut-render cache: plan, render settings, sources."""
+    from cut_contract import _edited_source_meta_path
+    try:
+        plan = json.loads(Path(plan_path).read_text(encoding="utf-8"))
+        meta = json.loads(_edited_source_meta_path(video).read_text(encoding="utf-8"))
+        sources = meta["sources"]
+        if not isinstance(sources, dict) or not sources:
+            raise ValueError("source identities missing")
+        if not Path(video).is_file() or Path(video).stat().st_size == 0:
+            raise ValueError("rendered media missing")
+        if (meta["plan"] != plan["clips"]
+                or meta["render_cache"] != edited_source_render_cache_payload()
+                or any(file_identity(p) != identity for p, identity in sources.items())):
+            raise ValueError("stale media, plan or render settings")
+        declared = {c["source_path"] for c in plan["clips"] if "source_path" in c}
+        if declared and declared != set(sources):
+            raise ValueError("source set mismatch")
+        if not declared and len(sources) != 1:
+            raise ValueError("ambiguous single source")
+    except (OSError, KeyError, ValueError, TypeError) as exc:
+        raise ValueError(f"cut plan binding failed: {exc}") from exc
+    return plan
+
+
+def _associate_plan(report, plan, pts, end):
+    """Legacy seconds are only a coarse locator, not exact source-frame proof."""
+    spans = []
+    previous = Fraction(0)
+    for clip in plan["clips"]:
+        start, stop = Fraction(str(clip["output_start"])), Fraction(str(clip["output_end"]))
+        if start != previous or stop <= start:
+            raise ValueError("bound cut plan must be contiguous and ordered")
+        spans.append((start, stop, clip))
+        previous = stop
+    tolerance = max(b - a for a, b in zip(pts, [*pts[1:], end]))
+    if not spans or abs(previous - end) > tolerance:
+        raise ValueError("bound plan duration disagrees with actual frame clock")
+    joins = [bisect_left(pts, s[0]) for s in spans[1:]]
+    for candidate in report["candidates"]:
+        f, t = candidate["frame"], pts[candidate["frame"]]
+        if any(abs(f - join) <= 1 for join in joins):
+            candidate["origin"] = "EDIT_JOIN_CANDIDATE"
+        else:
+            for start, stop, clip in spans:
+                if start < t < stop:
+                    candidate["inside_bound_clip"] = clip["clip_id"]
+                    candidate["source_time_estimate"] = str(Fraction(str(clip["source_start"])) + t - start)
+                    candidate["mapping_precision"] = "legacy_seconds_estimate"
+                    # No source scan: motion, exposure, overlay animation and native cuts
+                    # remain indistinguishable from output scene score alone.
+                    break
+    report["plan_joins"] = joins
+
+
+def scan_video(video, *, threshold=0.35, plan_path=None, roi=None, **policy):
+    video = Path(video).resolve()
+    plan = load_bound_plan(video, plan_path) if plan_path is not None else None
+    pts, end, origin = probe_frame_clock(video)
+    scenes = detect_scene_pts(video, threshold, roi)
+    frames_by_pts = {p + origin: i for i, p in enumerate(pts)}
+    if any(p not in frames_by_pts for p in scenes):
+        raise ValueError("scene candidate does not match a unique decoded frame PTS")
+    report = summarize_candidates(pts, end, [frames_by_pts[p] for p in scenes if frames_by_pts[p] > 0], **policy)
+    if plan is not None:
+        _associate_plan(report, plan, pts, end)
+    report.update({
+        "schema_version": 1, "artifact": "shot_review", "algorithm": "scene-frame-recall-v1", "scan_complete": True,
+        "media": {"path": str(video), "frame_count": len(pts),
+                  "origin_pts_exact": str(origin), "duration_exact": str(end)},
+        "plan_binding": {"path": str(Path(plan_path).resolve())} if plan is not None else None,
+        "scene_threshold": threshold,
+        "scene_roi": None if roi is None else list(roi),
+        "limits": ["scene score is not a confirmed shot or flash-frame defect",
+                   "source-origin confirmation requires independent source footage review",
+                   "NO_CANDIDATES is not perceptual approval or listening evidence"],
+    })
+    return report
+
+
+def _atomic_json(path, data):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temp = None
+    try:
+        with tempfile.NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as handle:
+            temp = Path(handle.name)
+            json.dump(data, handle, ensure_ascii=False, indent=2)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temp, path)
+    finally:
+        if temp is not None:
+            temp.unlink(missing_ok=True)
+
+
+def _report_target(video, output, plan_path):
+    """Unknown existing files are never report targets, even with corrupt source metadata."""
+    from cut_contract import _edited_source_meta_path
+    protected = {Path(video).resolve(), _edited_source_meta_path(video).resolve()}
+    if plan_path is not None:
+        protected.add(Path(plan_path).resolve())
+    target = Path(output).resolve()
+    if target in protected:
+        raise ValueError("report must not overwrite media, source, plan or render metadata")
+    if Path(output).exists():
+        try:
+            old = json.loads(Path(output).read_text(encoding="utf-8"))
+            if (not isinstance(old, dict) or type(old.get("schema_version")) is not int
+                    or old["schema_version"] != 1 or old.get("artifact") != "shot_review"):
+                raise ValueError("not a shot-review artifact")
+        except (OSError, UnicodeError, ValueError) as exc:
+            raise ValueError("report must not overwrite an unknown existing file") from exc
+    return target
+
+
+def _protect_declared_sources(video, plan_path, target):
+    """Use both plan and metadata declarations, even when they disagree."""
+    from cut_contract import _edited_source_meta_path
+    if plan_path is None:
+        return
+    paths, errors = set(), []
+    for path, kind in [(Path(plan_path), "plan"), (_edited_source_meta_path(video), "meta")]:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if kind == "plan":
+                paths.update(c["source_path"] for c in data["clips"] if "source_path" in c)
+            else:
+                paths.update(data["sources"])
+        except (OSError, ValueError, KeyError, TypeError) as exc:
+            errors.append(exc)
+    if target in {Path(p).resolve() for p in paths}:
+        raise UnsafeReportTarget("report must not overwrite a declared source")
+    if errors:
+        raise ValueError(f"cannot verify declared source protection: {errors[0]}")
+
+
+class UnsafeReportTarget(ValueError):
+    """Do not write even failure evidence to an input file."""
+
+
+def write_scan(video, output, **options):
+    target = _report_target(video, output, options.get("plan_path"))
+    roi = options.get("roi")
+    base = {"schema_version": 1, "artifact": "shot_review", "scan_complete": False,
+            "normal_speed_review": "NOT_CHECKED",
+            "scene_threshold": options.get("threshold", 0.35),
+            "scene_roi": None if roi is None else list(roi)}
+    try:
+        _protect_declared_sources(video, options.get("plan_path"), target)
+        _atomic_json(output, {**base, "status": "SCANNING"})
+        report = scan_video(video, **options)
+    except UnsafeReportTarget:
+        raise
+    except (OSError, ValueError, RuntimeError, KeyError, TypeError, subprocess.SubprocessError) as exc:
+        _atomic_json(output, {**base, "status": "SCAN_FAILED", "error": str(exc)})
+        raise
+    _atomic_json(output, report)
+    return report
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("video")
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--plan", default=None, help="optional current clip_plan_validated.json; stale bindings fail")
+    parser.add_argument("--threshold", type=float, default=0.35)
+    parser.add_argument("--roi", nargs=4, type=int, metavar=("X", "Y", "WIDTH", "HEIGHT"))
+    parser.add_argument("--max-short-frames", type=int, default=None,
+                        help="explicit frame cap; default derives round(fps * max_short_seconds)")
+    parser.add_argument("--max-short-seconds", type=float, default=1.0)
+    parser.add_argument("--dense-window-seconds", type=float, default=2.0)
+    parser.add_argument("--min-dense-cuts", type=int, default=4)
+    args = parser.parse_args()
+    report = write_scan(args.video, args.output, threshold=args.threshold, plan_path=args.plan, roi=args.roi,
+                        max_short_frames=args.max_short_frames, max_short_seconds=args.max_short_seconds,
+                        dense_window_seconds=args.dense_window_seconds, min_dense_cuts=args.min_dense_cuts)
+    print(json.dumps({"status": report["status"], "short_spans": len(report["short_spans"]),
+                      "dense_windows": len(report["dense_windows"]), "report": args.output}))
+
+
+if __name__ == "__main__":
+    main()

package/resources/skills/video-recap-production/upstream/skills/video-recap/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: video-recap
+description: >
+ 从输入视频生成中文解说成片或原声剧情短片。用户提供 .mp4 / .mov / .mkv / .webm，并要求剪辑、添加旁白、
+ 配音、总结、短剧/电视剧/电影/纪录片/科普解说时使用。负责编排 video-* 技能链：视频理解 →
+ Agent 制定故事与视听方案 → 剪辑 → 配音 → 合成。触发词：视频解说、视频旁白、生成解说、
+ 视频 recap、video recap、voiceover、narration、auto-dub、recap。
+---
+
+## 1. 定位与流程
+
+本技能是五个独立技能的轻量编排器。各技能只通过 `work_dir` 中的 JSON / MP4 产物通信，不共享代码：
+
+```text
+video-understanding ─▶ Agent 按 video-script 制定方案并写稿 ─▶ [video-cut] ─▶ video-voiceover ─▶ video-assemble
+```
+
+流程支持断点续跑：写好 `narration.json` 后重复同一条命令即可继续。第二阶段会比对
+`recap_run_manifest.json` 记录的源视频路径、文件大小/修改时间与运行参数，拒绝复用来自其他源视频或其他参数的旧工作目录；视频理解产物也只在来源一致时复用。
+
+画面流程 `--edit-mode full|cut|dub` 与声音策略 `--audio-mode` 是两个独立开关；
+`narration` 保留上述解说流程，`source-mix` 不做配音，`adopted-packet-copy` 冻结当前输入的已采用 AAC 音轨。
+组合只有下面几条路径，其余组合在启动时直接报错：
+
+| 输入 | `--edit-mode` | `--audio-mode` | Agent 暂停点 | 流程 | 详见 |
+|---|---|---|---|---|---|
+| 单视频 | full | narration | 1：`narration.json` | 理解 → 写稿 → 校验 → 配音 → 合成 | §4 |
+| 单视频 | cut | narration | 2：`clip_plan.json`，再对着成片写 `narration.json` | 理解 → 剪辑 → 重建输出时间 brief → 写稿 → 配音 → 合成 | §4 |
+| 多视频 | cut | narration | 2：同上，clip 必须带 `source_id` | 逐源理解 → 剪辑 → 写稿 → 配音 → 合成 | §4.3 |
+| 单视频 | full | source-mix / adopted-packet-copy | 无 | 直接合成当前整段 | §4.7 |
+| 单 / 多视频 | cut | source-mix / adopted-packet-copy | 1：`clip_plan.json` | 理解 → 剪辑 → 合成，不写稿 | §4.7 |
+| 单视频 | dub | narration | 1：`dub_script.json` | 英文转写 → 译稿 → 克隆音色整轨替换 | §5 |
+| 已剪好的母版 | full | narration + 三个采用 JSON | 无 | 只做严格合成 | 下文 |
+
+所有 full/cut 路径共用同一段收尾：（有旁白时）评审 → TTS → 合成 → 成片 QC。使用原声模式时读
+`references/audio-routing.md`。
+
+已有预制画面和本地采用的完整声音三件套时，可走严格 assembly-only 路径：
+
+```bash
+python3 scripts/recap.py picture.mp4 --edit-mode full --work-dir NEW_WORK \
+  --output-dir DELIVERY \
+  --tts-meta tts_meta.json \
+  --narration-adoption narration_adoption.json \
+  --audio-mix-adoption audio_mix_adoption.json
+```
+
+三个 JSON 参数必须同时出现。该入口只接受单视频、full、narration、音轨 0、新工作目录和未存在的
+交付文件；不运行理解、写稿、解说评审、TTS、cut、MiMo QC 或剪映导出。语义与媒体形状仍由
+video-assemble 严格验证，recap 只核对子技能绑定记录引用的是同一批采用文件与母版路径，不把调用方
+采用的声音或混音声明成自动创作或发布批准。详见 `references/audio-routing.md`。
+
+这里的单视频是**已经剪好的母版**。重剪后可以复用未改动的 WAV 与 `tts_meta.json`，但必须按新母版
+重新写混音采用文件里的落点与准备好的音床；衔接步骤见 `references/audio-routing.md` 的 “Keep adopted voice after a cut”。
+
+## 2. 创作职责
+
+这不是单纯的 JSON / 渲染流水线。Agent 是本次内容的创作负责人。先判断本轮的**创作控制模式**（CREATE / DIRECTED / REVISION，与 `--edit-mode` 无关），再在进入昂贵的下游处理前完成五次判断：
+
+1. **导演判断**：观众承诺、POV、戏剧问题、情绪终点与揭示节奏。
+2. **故事编辑**：beat 定义为“发生了什么变化”，不是场景摘要。
+3. **画面剪辑**：选择真正值得保留的具体时刻、反应、入点与出点。
+4. **声音/旁白**：先分配画面、原声、沉默和旁白的任务，再写解说词。
+5. **观众复核**：分别检查无旁白、只听声音和第一次观看的体验。
+
+三种控制模式的定义、REVISION 的修改/冻结规则、创作方法以及 `recap_story_plan.json` / `visual_audio_board.json` / `style_card.json` 的写法，全部按 `video-script` 执行；它会要求先读创作手册。这些文件只记录可审计的当前决定，不增加服务或渲染依赖。
+
+## 3. 环境与脚本路径
+
+```bash
+# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
+export MIMO_API_KEY=***
+```
+
+同一个 MiMo key 驱动：
+
+- ASR：`mimo-v2.5-asr`
+- VLM：`mimo-v2.5`
+- TTS：`mimo-v2.5-tts`
+
+TTS 供应商由 `--tts-provider mimo-tts|fish-audio|index-tts`（或 `TTS_PROVIDER`）透传给配音技能；Fish Audio 与自托管 index-tts 各自的环境变量、默认音色和能力限制见该技能。ASR/VLM 始终使用 MiMo。`--doctor` 只做离线配置检查。
+
+`tp-*` Token Plan 密钥默认使用中国区集群，可用 `MIMO_TOKEN_PLAN_CLUSTER` 覆盖。
+
+可选能力：
+
+- `--mimo-video-overview`：按场景块补充 MiMo 视频理解。
+- `--mimo-qc pre-assemble|post-render|both`：在合成前、成片后或两个阶段给出建议型复核。
+
+MiMo QC 默认关闭；每个选定阶段最多请求一次，写入 `mimo_qc.json`。任何凭证缺失、限流、超时、格式错误或采样失败都只记录状态，不阻断流程。可覆盖配置见 `references/config-playbook.md`，QC 报告的最小契约见 `references/shift-left-qc-schema.md`。
+
+下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本启动后会自行定位兄弟技能和资源。
+
+## 4. 标准解说流程（audio-mode narration）
+
+### 4.1 背景调研
+
+若能识别影片、剧集或主题，先按 video-understanding 技能的调研指南 `research-guide.md` 调研并写入
+`work_dir/background_research.json`。视频理解会把人物名和剧情背景折入 VLM 上下文，避免只得到“黑衣男子”一类模糊描述。无法识别来源时可跳过。
+
+### 4.2 分析并暂停创作
+
+```bash
+python3 scripts/recap.py <video> --work-dir <work_dir> --context "背景"
+```
+
+命令完成视频理解、写出 `agent_narration_brief.md`，然后暂停。此时按以下顺序执行 `video-script`：
+
+1. 查看创作 brief 与原片故事板。
+2. 写 `recap_story_plan.json` 和 `visual_audio_board.json`。
+3. full 模式写 `narration.json`；cut 模式第一阶段只写 `clip_plan.json`。
+4. cut 模式第二阶段查看剪后故事板，补充输出时间与声音分工，再写 `narration.json`。
+
+不要从标题或旁白句子开始；先锁定故事体验和素材选择。
+
+时间线有两条不可降级的硬约束：原声只能在可靠句末/静音边界被切入、切出或恢复；旁白必须使用
+完整逐段音频，任何 clip 映射裁段、TTS 裁尾或剪映引用更长的加速前素材都阻断。Agent 收到
+`interrupts_source_sentence` / `unsafe_clip_sentence_boundary` / `no_safe_fit` /
+`timeline_audio_mismatch` 时，应移动边界、缩短整句或删除该块，而不是增加抢断 override。
+
+### 4.3 多视频与素材库
+
+多视频只支持 cut 模式。项目 brief 会列出稳定的 `source_id`，`clip_plan.json` 中每个片段都必须填写来源：
+
+```bash
+python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep
+```
+
+可选文件系统素材库：
+
+```bash
+python3 scripts/recap.py ep1.mp4 --material-library-dir .video-materials --save-materials
+python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --material-library-dir .video-materials --use-materials
+```
+
+素材检索只是对 JSON / MD / JSONL 做 grep，例如 `grep -R "keyword" .video-materials`。当前版本不复制原始媒体，也不提供数据库、向量或语义搜索。
+
+同一根目录还可以登记可复用的资源（BGM、音效、音色、字体、图片）、带版本与采用记录的模板（字幕样式、包装图层）和样片。
+格式与 `scripts/library.py check|list|show` 只读工具见 `references/resource-library.md`。用 `--project recap_project.json` 把已采用的字幕样式、音色与 BGM 绑定到这次运行；
+每次 full / cut 合成后 `work_dir/resource_lock.json` 记下实际用到的资源与授权状态。
+
+### 4.4 继续生成成片
+
+写好所需产物后，重复同一条命令：
+
+```bash
+python3 scripts/recap.py <video> --work-dir <work_dir>  # 可追加 --edit-mode cut / --no-burn-subtitles
+```
+
+流程会校验当前阶段的硬输入（`clip_plan.json` / `narration.json`）；两份创作计划仍是 Agent 与建议型评审使用的工作记录，不是渲染门禁。cut 模式随后生成 `edited_source.mp4`，再合成旁白并输出 `recap_<name>.mp4`。
+
+若需要建议型 MiMo 复核：
+
+```bash
+python3 scripts/recap.py <video> --work-dir <work_dir> --mimo-qc both
+```
+
+合成前复核会读取脚本、计划和 TTS 元数据；成片后还会读取最多六张临时 JPEG。输入文件的大小/修改时间、模型与提示都未变时直接复用上次报告，`--mimo-qc-refresh` 可强制刷新。帧的 base64 与凭证不会写入磁盘。
+
+已有批准解说稿时加 `--preserve-approved-text`：校验与 TTS 原样保留批准稿（只更新 `overlaps_speech`），装不下时间窗即失败，不缩稿、不降级为部分成功。
+
+### 4.5 字幕与克隆旁白
+
+若要把旁白字幕固定在原片字幕区域，先在仓库根目录运行：
+
+```bash
+python3 tools/measure_subtitle.py <video>
+```
+
+再传入测得的 `--subtitle-y-top/--subtitle-y-bot`。坐标基于 ffmpeg 自动旋转后的显示画布，区间为半开 `[top, bot)`，并要求底对齐 ASS 样式；显式设置后，该区域默认使用 60% 透明度的旁白窗口遮罩。
+
+解说模式如需克隆参考声音，使用 `--voice-ref <audio>`；它与 dub 模式不同。
+
+### 4.6 最终观看与交付复核
+
+脚本、接点检测、样帧和 QC 报告都不能替代观看。每轮准备交付前，必须检查**本轮实际要交付的最终文件**，而不是旧别名、无字幕母版或中间代理：
+
+1. 正常速度完整播放一次短片，不边看边改；先记录真实观看问题。
+2. 播放每个拼接点前后约 0.5–1 秒，检查闪帧、原片叠化被截断、动作跳变和半句原声。
+3. 完整只听声音一次，检查旁白是否碎成一句一停、场景间声音是否接得上、关键原声是否完整。
+4. 单独复看开头、核心情绪/表演点和结尾，确认进入时机、回报停留和收束都成立。
+5. REVISION 分别验证本轮修改项已经改变、冻结项没有意外变化；然后再做解码、时长、音画规格等机械检查。
+
+scene score、亮度统计、contact sheet 与自动 QC 只负责定位候选问题；最终判断以真实播放为准。密集切点的来源判断与处理规则按剪辑技能执行。修复失败时回到剪点、声音或文案层，不用更多包装掩盖。
+
+full/cut 交付如需让确定性的最终检查影响命令退出状态，显式传
+`--require-final-qc`。只有 `final_qc.json` 与 `golden_eval.json` 的摘要均为
+`ok: true` 且整数 `blocker_count: 0` 才打印完成并返回成功；缺失、畸形或 blocker
+会保留报告和已渲染诊断媒体，但命令非零退出且不打印完成。默认仍是仅报告、不阻断。
+该参数不支持 `--edit-mode dub`；dub 未传该参数时的准备和渲染行为不变。
+
+### 4.7 不需要解说的片子
+
+```bash
+# 对当前整段输入直接合成；不隐式跑理解/ASR/TTS
+python3 scripts/recap.py locked_picture.mp4 --work-dir source_work --audio-mode source-mix
+# 剪辑计划仍按 cut 流程产生，剪完不再暂停等待 narration.json
+python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --work-dir cut_work --audio-mode source-mix
+# 只换包装时冻结当前整片 AAC；不允许同时加 BGM/TTS
+python3 scripts/recap.py adopted.mp4 --work-dir packaging_work --audio-mode adopted-packet-copy
+```
+
+`source-mix` 仍会混音和重编码；`cut + adopted-packet-copy` 冻结的是剪后中间片的声音，不是原片的 AAC 包。
+当前严格字幕轨只支持 adopted 模式；其他字幕来源没有因此变成精确对齐。切换声音模式须新工作目录，不得把旧 TTS、QC 或自动生成的解说花字混入本轮原声生产。细节见 `references/audio-routing.md`。
+
+## 5. 英译中原声复刻模式
+
+`--edit-mode dub` 把英文视频翻译为中文，并用原说话者的克隆音色替换人声；它不是在压低原声上叠加解说。
+
+```bash
+python3 scripts/recap.py <video> --edit-mode dub --work-dir <work_dir>
+```
+
+准备阶段会转写英文、提取一段参考音频，并写出 `dub_brief.md` 与 `dub_transcript.json`。Agent 随后写：
+
+```json
+[{"start": 0.0, "end": 2.0, "zh": "中文译文"}]
+```
+
+要求：
+
+- 逐句忠实翻译，不删钩子、不合并、不擅自压缩；原文重复，译文也按时间重复。
+- 每句沿用原声 `[start, end]`，相邻句不重叠。
+- 译文尽量控制在约 5 字/秒，使其能在原时间窗内说完。
+
+重复同一命令后输出 `dub_<name>.mp4`。每句单独克隆并贴回原时间线；只有即将覆盖下一句时才局部加速。当前版本只支持单说话者、整轨替换，不分离背景音乐。
+
+## 6. 自检与只读 dashboard
+
+```bash
+python3 scripts/recap.py --doctor
+```
+
+### 6.1 只读 dashboard
+
+```bash
+python3 scripts/dashboard_server.py --root <目录> [--port 0] [--open]
+```
+
+前台运行并打印本机地址（只绑定 127.0.0.1，Agent 启动时放到后台）。它在 `--root` 下按 `library.json`、`recap_project.json`、
+`recap_run_manifest.json` 发现资源库、项目与运行，按阶段显示剪辑节奏、旁白、成片与时间线、QC 和 `resource_lock.json`。
+严格只读：只接受 GET / HEAD，不写任何文件；页面上的「复制给助手」只复制一句请求，改动回到对话里做。
+
+## 7. 输出与参数
+
+主要输出：
+
+- `recap_<video>.mp4`：最终成片。
+- `subtitles.srt` / `subtitles.ass`：字幕。
+- `work_dir/`：全部中间产物，契约见 `references/data-schema.md`。
+- `work_dir/recap_story_plan.json` / `visual_audio_board.json`：Agent 创作意图与剪辑决定。
+- `work_dir/mimo_qc.json`：可选的建议型复核，不作为发布门禁。
+
+完整参数列表以 `python3 scripts/recap.py --help` 为准。`--style` 是原样传给 Agent 的自由文本指导，不是 preset、枚举、开关或有限风格分类。
+
+## 8. 能力边界
+
+- 语义评审默认建议型、失败开放；只有调用方显式启用严格解说评审时，事实矛盾、残句或评审不可用才会在 TTS 前阻断。确定性校验阶段始终负责硬校验。
+- MiMo QC 不能阻断、自动修复或改变退出状态，只提供定位建议。
+- 宣发标题、花字或外部文案回填见 `video-script` 的 references/promotional-copy.md。