@lemoncat7/dsh-partner 2.8.1 → 2.8.2

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

@@ -0,0 +1,696 @@
+"""Orchestrate single- and multi-source recap pipelines."""
+
+import json
+import os
+from pathlib import Path
+
+import materials as material_lib
+import project_binding
+import resource_lock
+
+from recap_cli import TTS_PROVIDERS, parse_args
+from recap_review import run_narration_review
+from recap_runtime import (
+    _analysis_settings,
+    _build_multi_source_records,
+    _coerce_videos,
+    _entry,
+    _optional_env_int,
+    _preflight_burn_subtitles,
+    _probe_display_height_or_raise,
+    _probe_display_size_or_raise,
+    _read_video_duration_or_raise,
+    _run,
+    _write_multi_source_manifest,
+    _write_project_run_manifest,
+    _write_run_manifest,
+)
+from recap_stage_qc import (
+    _post_render_qc_metadata,
+    _prepare_mimo_qc,
+    _print_final_qc_pointer,
+    _require_final_qc,
+    _run_mimo_qc_stage,
+    _tts_qc_metadata,
+    _write_final_qc_reports,
+    _write_shift_left_stage_qc,
+)
+from recap_source import (
+    begin_local_adoption_qc,
+    begin_non_narration_qc,
+    extend_assemble_args,
+    load_local_assembly_evidence,
+    needs_voiceover,
+    owned_local_delivery,
+    reject_unbound_narration_workdir,
+    reject_unsupported_subtitle_track,
+    uses_local_adoption,
+    uses_narration,
+    validate_audio_routing,
+    verify_local_assembly_evidence,
+    remove_owned_local_delivery,
+)
+from recap_timeline import (
+    _continuation_command,
+    _cut_narration_is_stale,
+    _manifest_mismatches,
+    _material_library_dir,
+    _materials_enabled,
+    _multi_manifest_mismatches,
+    _pause_for_agent,
+    _print_narration_review_pointer,
+    _read_assembly_output,
+    _read_phase_ledger,
+    _save_materials_enabled,
+    _source_work_dir,
+    _surface_cut_qc,
+    _understand_args_for_source,
+    _write_canonical_visual_overlays,
+    _write_multi_source_clip_brief,
+    _write_multi_source_output_brief,
+    _write_phase_ledger,
+)
+
+RUN_MANIFEST = "recap_run_manifest.json"
+
+
+def _voiceover_args(work_dir, narration_path, args):
+    """Build the shared full/cut invocation for video-voiceover."""
+    result = ["--work-dir", str(work_dir), "--narration", str(narration_path)]
+    if args.tts_provider != "auto":
+        result += ["--tts-provider", args.tts_provider]
+    if args.mimo_tts_voice:
+        result += ["--mimo-voice", args.mimo_tts_voice]
+    if args.voice_ref:
+        result += ["--voice-ref", args.voice_ref]
+    if args.allow_partial_tts:
+        result.append("--allow-partial-tts")
+    if args.preserve_approved_text:
+        result.append("--preserve-approved-text")
+    return result
+
+
+def _approved_validation_args(args):
+    return ["--preserve-approved-text"] if args.preserve_approved_text else []
+
+
+def _record_resources(work_dir, args):
+    """Write resource_lock.json for the finished render and surface anything needing a person."""
+    library_dir = getattr(args, "material_library_dir", None) or os.environ.get(
+        "VIDEO_RECAP_MATERIAL_LIBRARY_DIR"
+    )
+    try:
+        lock = resource_lock.write_resource_lock(
+            work_dir, library_dir=library_dir, project=getattr(args, "resolved_project", None)
+        )
+    except (OSError, ValueError, TypeError, KeyError) as exc:  # a record must never fail a finished render
+        print(f"[video-recap] ⚠ 未能写出 resource_lock.json: {type(exc).__name__}: {exc}", flush=True)
+        return
+    print(resource_lock.summary_line(lock), flush=True)
+
+
+def _finish_recap(work_dir, final_output, args):
+    final_qc_result = _write_final_qc_reports(work_dir, final_output)
+    if args.require_final_qc:
+        _require_final_qc(final_qc_result, work_dir)
+    print(f"[video-recap] ✅ 完成: {final_output}")
+    _print_final_qc_pointer(final_qc_result)
+
+
+def _run_local_adoption(video, work_dir, args):
+    """Run the strict local bundle directly through the authoritative assembler."""
+    work_dir.mkdir(parents=True, exist_ok=False)
+    manifest = _write_run_manifest(work_dir, video, args)
+    def record_failure(exc):
+        failed = {**manifest, "local_adoption_run": {
+            "status": "FAILED", "error_type": type(exc).__name__,
+        }}
+        (work_dir / RUN_MANIFEST).write_text(
+            json.dumps(failed, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+    begin_local_adoption_qc(work_dir, _write_shift_left_stage_qc)
+    assemble_args = [
+        str(video),
+        "--work-dir", str(work_dir),
+        "--recap-stem", video.stem,
+        "--output-dir", args.output_dir,
+        "--tts-meta", args.tts_meta,
+        "--narration-adoption", args.narration_adoption,
+        "--audio-mix-adoption", args.audio_mix_adoption,
+    ]
+    if args.burn_subtitles is not None:
+        assemble_args.append(
+            "--burn-subtitles" if args.burn_subtitles else "--no-burn-subtitles"
+        )
+    if args.subtitle_y_top is not None:
+        assemble_args += [
+            "--subtitle-y-top", str(args.subtitle_y_top),
+            "--subtitle-y-bot", str(args.subtitle_y_bot),
+        ]
+    owned_delivery = None
+    try:
+        _run("video-assemble", "assemble.py", *assemble_args)
+        evidence = load_local_assembly_evidence(work_dir)
+        owned_delivery = owned_local_delivery(evidence)
+        verify_local_assembly_evidence(evidence, manifest)
+    except BaseException as exc:
+        remove_owned_local_delivery(owned_delivery)
+        record_failure(exc)
+        raise
+    final_output = _read_assembly_output(work_dir)
+    _record_resources(work_dir, args)
+    _write_shift_left_stage_qc(
+        work_dir,
+        "post_render",
+        metadata=_post_render_qc_metadata(work_dir, final_output),
+    )
+    _finish_recap(work_dir, final_output, args)
+
+
+def _run_or_restore_understanding(source_record, source_work_dir, args):
+    """Run video-understanding for one source, or restore it from the material library."""
+    source_work_dir = Path(source_work_dir)
+    source_work_dir.mkdir(parents=True, exist_ok=True)
+    source_path = source_record["source_path"]
+    source_identity = source_record["source_video_identity"]
+    settings = source_record["settings"]
+    lib_dir = _material_library_dir(args)
+    restored = False
+    if _materials_enabled(args):
+        result = material_lib.restore_material(
+            lib_dir,
+            source_work_dir,
+            source_path=source_path,
+            source_identity=source_identity,
+            settings=settings,
+        )
+        restored = result["restored"]
+        if restored:
+            print(
+                f"[video-recap] ♻️  复用素材库: {result['material_id']} → {source_work_dir}",
+                flush=True,
+            )
+        else:
+            print(
+                f"[video-recap] 素材库未复用 {source_record['source_name']}: {result['reason']}",
+                flush=True,
+            )
+    if not restored:
+        _run(
+            "video-understanding",
+            "understand.py",
+            *_understand_args_for_source(source_record, source_work_dir, args),
+        )
+    _write_run_manifest(source_work_dir, source_record["source_path"], args)
+    if _save_materials_enabled(args):
+        meta = material_lib.save_material(
+            lib_dir,
+            source_work_dir,
+            source_path,
+            source_identity,
+            settings,
+            source_id=source_record["source_id"],
+            material_id=source_record["material_id"],
+        )
+        source_record["material_id"] = meta["material_id"]
+        print(
+            f"[video-recap] 💾 已沉淀素材: {meta['material_id']} → {lib_dir}",
+            flush=True,
+        )
+    return restored
+
+
+def _single_source_record(video, args):
+    """Identity + settings for the one source of a single-video run."""
+    identity = material_lib.file_identity(video)
+    return {
+        "source_id": material_lib.source_id_for(video),
+        "source_path": str(video),
+        "source_name": video.name,
+        "source_video_identity": identity,
+        "settings": _analysis_settings(args),
+        "material_id": material_lib.material_id_for(video, identity),
+    }
+
+
+def _rebuild_understanding_brief(source_record, source_work_dir, args):
+    """Rebuild agent_narration_brief.md from cached/restored analysis only.
+    Cut pass 2 needs an OUTPUT-time brief after edited_source.mp4 exists. A
+    material restore may have supplied pass-1 analysis artifacts (and even a
+    source-time brief), but it must not skip this phase-specific brief rebuild.
+    """
+    _run(
+        "video-understanding",
+        "understand.py",
+        *_understand_args_for_source(source_record, source_work_dir, args),
+        "--brief-only",
+    )
+
+
+def _reject_stale(mismatches, label):
+    if mismatches:
+        details = "\n  - ".join(mismatches)
+        raise SystemExit(
+            f"work_dir 与当前{label}recap 输入不匹配，拒绝复用既有 narration/clip_plan；"
+            "请使用新的 --work-dir，或删除旧产物后重新运行 Phase A。\n"
+            f"  - {details}"
+        )
+
+
+def _reject_stale_multi_manifest(work_dir, videos, args, source_records):
+    _reject_stale(_multi_manifest_mismatches(work_dir, videos, args, source_records), "多视频 ")
+
+
+def _render_cut(video_arg, work_dir, args, *extra):
+    """Render edited_source.mp4 from clip_plan.json and record the post-cut QC stage."""
+    crender = [str(video_arg), "--work-dir", str(work_dir), *extra]
+    if args.target_duration:
+        crender += ["--target-duration", args.target_duration]
+    if args.allow_duration_drift:
+        crender.append("--allow-duration-drift")
+    _run("video-cut", "cut.py", *crender)
+    cut_qc = _surface_cut_qc(work_dir)
+    _write_shift_left_stage_qc(work_dir, "post_cut", metadata={"cut_qc": cut_qc})
+
+
+def _reject_stale_cut_narration(work_dir, clip_plan_identity):
+    if _cut_narration_is_stale(_read_phase_ledger(work_dir), clip_plan_identity):
+        raise SystemExit(
+            "clip_plan.json 已改变，但 narration.json 仍是对旧剪辑写的，会与剪后画面对不上。"
+            "请删除 narration.json，重跑后按新成片重新写解说。"
+        )
+
+
+def _validate_cut_output_narration(work_dir, args):
+    output_duration = _read_video_duration_or_raise(work_dir / "edited_source.mp4")
+    _run(
+        "video-script", "validate.py", "--work-dir", work_dir,
+        "--mode", "cut_output", "--output-duration", f"{output_duration:.3f}",
+        *_approved_validation_args(args),
+    )
+
+
+def _narrate(work_dir, args, timeline):
+    """Review -> TTS -> visual overlays for a validated narration.json."""
+    narration_json = work_dir / "narration.json"
+    review_ran = run_narration_review(work_dir, args, run=_run, timeline=timeline)
+    _write_shift_left_stage_qc(
+        work_dir, "pre_tts", metadata={"review_ran": review_ran, "timeline": timeline}
+    )
+    _run(
+        "video-voiceover", "voiceover.py",
+        *_voiceover_args(work_dir, narration_json, args),
+    )
+    _write_shift_left_stage_qc(work_dir, "post_tts", metadata=_tts_qc_metadata(work_dir))
+    overlays_path = _write_canonical_visual_overlays(work_dir, narration_json)
+    _write_shift_left_stage_qc(
+        work_dir, "pre_assemble", metadata={"visual_overlays": str(overlays_path)}
+    )
+    _run_mimo_qc_stage(work_dir, args, "pre_assemble")
+    return review_ran
+
+
+def _deliver(work_dir, args, assemble_video, recap_stem, timeline, extra_assemble_args=()):
+    """Shared tail of every full/cut run: narration (if owned) -> assemble -> final QC."""
+    project = getattr(args, "resolved_project", None)
+    if project and project["templates"]:
+        project_binding.check_canvas(project, *_probe_display_size_or_raise(assemble_video))
+    project_binding.sync_packaging_layers(work_dir, project)
+    review_ran = _narrate(work_dir, args, timeline) if uses_narration(args) else None
+    aargs = [str(assemble_video), "--work-dir", str(work_dir), "--recap-stem", recap_stem]
+    extend_assemble_args(aargs, args)
+    if args.output_dir:
+        aargs += ["--output-dir", args.output_dir]
+    if args.burn_subtitles is not None:
+        aargs.append(
+            "--burn-subtitles" if args.burn_subtitles else "--no-burn-subtitles"
+        )
+    if args.subtitle_y_top is not None:
+        aargs += [
+            "--subtitle-y-top", str(args.subtitle_y_top),
+            "--subtitle-y-bot", str(args.subtitle_y_bot),
+        ]
+    # env-only burn intent (BURN_SUBTITLES) is propagated implicitly: assemble re-derives it
+    # via the same env_bool default the preflight used, so the two agree by shared env.
+    aargs += extra_assemble_args
+    if args.export_jianying:  # env EXPORT_JIANYING is honored by assemble.py itself
+        aargs.append("--export-jianying")
+    if args.jianying_bundle_media:
+        aargs.append("--jianying-bundle-media")
+    if args.jianying_no_bundle_media:
+        aargs.append("--jianying-no-bundle-media")
+    _run("video-assemble", "assemble.py", *aargs)
+
+    final_output = _read_assembly_output(work_dir)
+    _record_resources(work_dir, args)
+    _write_shift_left_stage_qc(
+        work_dir,
+        "post_render",
+        metadata=_post_render_qc_metadata(work_dir, final_output),
+    )
+    if uses_narration(args):
+        _run_mimo_qc_stage(work_dir, args, "post_render", final_output=final_output)
+    _finish_recap(work_dir, final_output, args)
+    if uses_narration(args):
+        _print_narration_review_pointer(work_dir, review_ran=review_ran)
+
+
+def _run_multi_cut(videos, work_dir, args):
+    """Multi-video MVP: cut-first/narrate-second over a project work_dir."""
+    videos = _coerce_videos(videos)
+    work_dir = Path(work_dir)
+    work_dir.mkdir(parents=True, exist_ok=True)
+    reject_unbound_narration_workdir(work_dir, args)
+    reject_unsupported_subtitle_track(work_dir, args)
+    source_records = _build_multi_source_records(videos, args)
+    narration_json = work_dir / "narration.json"
+    clip_plan_json = work_dir / "clip_plan.json"
+    edited_source = work_dir / "edited_source.mp4"
+    inspect_py = _entry("video-recap", "recap_inspect.py")
+    # If a project manifest already exists, it must match before any Phase-B reuse.
+    if (work_dir / RUN_MANIFEST).exists():
+        _reject_stale_multi_manifest(work_dir, videos, args, source_records)
+    manifest_path = _write_multi_source_manifest(work_dir, source_records)
+    if not uses_narration(args):
+        begin_non_narration_qc(work_dir, args, _write_shift_left_stage_qc)
+    if not clip_plan_json.exists():
+        for record in source_records:
+            _run_or_restore_understanding(
+                record, _source_work_dir(work_dir, record), args
+            )
+        # Rewrite: _run_or_restore_understanding fills in material_id per record.
+        manifest_path = _write_multi_source_manifest(work_dir, source_records)
+        _write_project_run_manifest(work_dir, videos, args, source_records)
+        _write_multi_source_clip_brief(work_dir, source_records, args)
+        _pause_for_agent(
+            work_dir,
+            f"{clip_plan_json}（多视频剪辑计划；每个 clip 必须带 source_id）",
+            _continuation_command(videos, work_dir, args),
+            inspect_hint=f"python3 {inspect_py} --work-dir {work_dir} state",
+        )
+        return
+
+    _reject_stale_multi_manifest(work_dir, videos, args, source_records)
+    cp_identity = material_lib.file_identity(clip_plan_json)
+    _render_cut(videos[0], work_dir, args, "--sources-manifest", str(manifest_path))
+    if uses_narration(args):
+        if not narration_json.exists():
+            _write_multi_source_output_brief(
+                work_dir, source_records, work_dir / "clip_plan_validated.json"
+            )
+            _write_phase_ledger(
+                work_dir,
+                clip_plan_identity=cp_identity,
+                edited_source_rendered=True,
+                multi_source=True,
+            )
+            _pause_for_agent(
+                work_dir,
+                f"{narration_json}（用成片 OUTPUT 时间轴写解说，对着 {edited_source}）",
+                _continuation_command(videos, work_dir, args),
+                inspect_hint=(
+                    f"python3 {inspect_py} --work-dir {work_dir} "
+                    "clip-map --output-start <s> --output-end <e>"
+                ),
+            )
+            return
+        _reject_stale_cut_narration(work_dir, cp_identity)
+        _write_phase_ledger(
+            work_dir,
+            clip_plan_identity=cp_identity,
+            narration_written=True,
+            multi_source=True,
+        )
+        _validate_cut_output_narration(work_dir, args)
+
+    _deliver(work_dir, args, edited_source, f"multi_{videos[0].stem}", "cut_output")
+
+
+def main():
+    ap, args = parse_args()
+
+    if args.require_final_qc and args.edit_mode == "dub":
+        ap.error("--require-final-qc is only supported in full/cut modes, not dub")
+    # argparse `choices` does not cover the TTS_PROVIDER env default; source-owned audio and
+    # local adoption never synthesise, so an ambient provider is irrelevant there.
+    if (args.doctor or needs_voiceover(args)) and args.tts_provider not in TTS_PROVIDERS:
+        ap.error("TTS_PROVIDER/--tts-provider must be one of: " + ", ".join(TTS_PROVIDERS))
+
+    if args.doctor:
+        if any(
+            getattr(args, field) is not None
+            for field in ("tts_meta", "narration_adoption", "audio_mix_adoption")
+        ):
+            ap.error("--doctor cannot be combined with local adoption inputs")
+        doctor_args = []
+        if args.tts_provider != "auto":
+            doctor_args += ["--tts-provider", args.tts_provider]
+        _run("video-recap", "doctor.py", *doctor_args)
+        return
+    if not uses_local_adoption(args) and args.mimo_qc not in {
+        "off", "pre-assemble", "post-render", "both"
+    }:
+        ap.error(
+            "MIMO_QC/--mimo-qc must be one of: off, pre-assemble, post-render, both"
+        )
+    if not args.video:
+        ap.error("video is required (unless --doctor)")
+    validate_audio_routing(ap, args)
+    args.resolved_project = None
+    if args.project:
+        args.project = str(project_binding.project_path(args.project))
+        if uses_local_adoption(args) or args.edit_mode == "dub":
+            ap.error("--project applies to full/cut runs, not dub or local adoption bundles")
+        project_binding.apply_project(
+            project_binding.resolve_project(
+                args.project, args, include_voice=needs_voiceover(args)
+            ),
+            args,
+        )
+
+    if needs_voiceover(args) and args.voice_ref is None:
+        args.voice_ref = os.environ.get("VOICE_REF", "").strip() or None
+    elif not needs_voiceover(args):
+        # Source-owned audio must not inherit ambient narration configuration. Explicit
+        # narration flags were already rejected by validate_audio_routing().
+        args.voice_ref = None
+    try:
+        if args.subtitle_y_top is None:
+            args.subtitle_y_top = _optional_env_int("SUBTITLE_Y_TOP")
+        if args.subtitle_y_bot is None:
+            args.subtitle_y_bot = _optional_env_int("SUBTITLE_Y_BOT")
+    except ValueError as exc:
+        ap.error(str(exc))
+
+    if needs_voiceover(args):
+        explicit_mimo_voice = (
+            args.mimo_tts_voice or os.environ.get("MIMO_TTS_VOICE", "").strip()
+        )
+        if explicit_mimo_voice and args.voice_ref:
+            ap.error("--mimo-tts-voice and --voice-ref are mutually exclusive")
+        if args.tts_provider in {"fish-audio", "index-tts"} and (
+            explicit_mimo_voice or args.voice_ref
+        ):
+            ap.error(
+                "--mimo-tts-voice/--voice-ref are only supported by --tts-provider mimo-tts"
+            )
+    if args.edit_mode == "dub" and args.voice_ref:
+        ap.error(
+            "--voice-ref is only supported in full/cut modes; dub clones the source voice automatically"
+        )
+    if args.edit_mode == "dub" and args.tts_provider == "fish-audio":
+        ap.error(
+            "--tts-provider fish-audio is only supported in full/cut modes; "
+            "dub uses MiMo voice cloning"
+        )
+    if args.edit_mode == "dub" and args.subtitle_y_top is not None:
+        ap.error(
+            "--subtitle-y-top/--subtitle-y-bot are only supported in full/cut modes"
+        )
+    if args.edit_mode == "dub" and args.burn_subtitles:
+        ap.error("--burn-subtitles is only supported in full/cut modes; dub never burns subtitles")
+    if (args.subtitle_y_top is None) != (args.subtitle_y_bot is None):
+        ap.error("--subtitle-y-top and --subtitle-y-bot must be provided together")
+    if args.subtitle_y_top is not None:
+        if args.subtitle_y_top < 0 or args.subtitle_y_bot <= args.subtitle_y_top:
+            ap.error("subtitle Y coordinates must satisfy 0 <= top < bot")
+
+    videos = _coerce_videos(args.video)
+    if len(videos) > 1 and args.edit_mode != "cut":
+        raise SystemExit(
+            "多视频输入当前 MVP 只支持 --edit-mode cut；full/dub 请一次输入一个视频。"
+        )
+    if len(videos) > 1 and args.subtitle_y_top is not None:
+        ap.error("多视频 cut 暂不支持全局 subtitle Y 坐标；各源字幕带可能不同")
+    if args.subtitle_y_top is not None:
+        canvas_height = _probe_display_height_or_raise(
+            videos[0], require_square_pixels=True
+        )
+        if args.subtitle_y_bot > canvas_height:
+            ap.error(
+                f"subtitle Y coordinates exceed display canvas height {canvas_height}: "
+                f"bot={args.subtitle_y_bot}"
+            )
+    if args.voice_ref:
+        voice_ref = Path(args.voice_ref).expanduser().resolve()
+        if not voice_ref.is_file():
+            ap.error(f"reference audio does not exist or is not a file: {voice_ref}")
+        args.voice_ref = str(voice_ref)
+
+    _execute_pipeline(args, videos)
+
+
+def _execute_pipeline(args, videos):
+    # Fail fast before any expensive understanding/VLM/ASR/TTS work if the run will burn
+    # subtitles but this ffmpeg can't (otherwise it only blows up at the final render).
+    _preflight_burn_subtitles(args)
+
+    if uses_local_adoption(args):
+        _run_local_adoption(videos[0], Path(args.work_dir), args)
+        return
+
+    if len(videos) > 1:
+        work_dir = (
+            Path(args.work_dir).resolve()
+            if args.work_dir
+            else videos[0].parent / f"work_dir_multi_{videos[0].stem}"
+        )
+        # Validate the work-directory audio policy before any run-local QC state is reset.
+        reject_unbound_narration_workdir(work_dir, args)
+        _prepare_mimo_qc(work_dir, args)
+        _run_multi_cut(videos, work_dir, args)
+        return
+
+    video = videos[0]
+    work_dir = (
+        Path(args.work_dir).resolve()
+        if args.work_dir
+        else video.parent / f"work_dir_{video.stem}"
+    )
+    work_dir.mkdir(parents=True, exist_ok=True)
+    reject_unbound_narration_workdir(work_dir, args)
+    reject_unsupported_subtitle_track(work_dir, args)
+    _prepare_mimo_qc(work_dir, args)
+    if args.edit_mode == "dub":
+        _run_dub(video, work_dir, args)
+    else:
+        _run_single(video, work_dir, args)
+
+
+def _run_dub(video, work_dir, args):
+    """EN->ZH translation-dub in the original cloned voice (replaces speech, not overlay).
+    One pause: prepare (ASR + sentence-seg + reference) -> agent writes the Chinese
+    translation (dub_script.json) -> render (clone TTS + full-replace mux)."""
+    dub_script = work_dir / "dub_script.json"
+    dub_args = ["--video", str(video), "--work-dir", str(work_dir)]
+    if not dub_script.exists():
+        _run("video-voiceover", "dub.py", "--stage", "prepare", *dub_args)
+        _write_run_manifest(work_dir, video, args)
+        cont = _continuation_command(video, work_dir, args)
+        print("=" * 50)
+        print(
+            f"[video-recap] ⏸  阅读 {work_dir / 'dub_brief.md'}，把英文原声转写切分并翻译成中文，写入 {dub_script}"
+        )
+        print(
+            '[video-recap]    格式 [{"start": 起秒, "end": 止秒, "zh": "译文"}]（按 start 升序）；逐句忠实、跟原声节奏一致、保留原音色'
+        )
+        print(f"[video-recap]    写完后重跑继续: {cont}")
+        print("=" * 50)
+        return
+    _reject_stale(_manifest_mismatches(work_dir, video, args), " ")
+    _run("video-voiceover", "dub.py", "--stage", "render", *dub_args)
+    print(f"[video-recap] ✅ 配音完成: {work_dir / ('dub_' + video.stem + '.mp4')}")
+
+
+def _run_single(video, work_dir, args):
+    """Single-video full or cut run; returns early at each agent pause."""
+    cut = args.edit_mode == "cut"
+    narration_json = work_dir / "narration.json"
+    clip_plan_json = work_dir / "clip_plan.json"
+    edited_source = work_dir / "edited_source.mp4"
+    inspect_py = _entry("video-recap", "recap_inspect.py")
+    state_hint = f"python3 {inspect_py} --work-dir {work_dir} state"
+
+    def _understand():
+        _run_or_restore_understanding(_single_source_record(video, args), work_dir, args)
+
+    def _pause(need_text, inspect_hint):
+        # Same banner as the multi-source flow; only the continuation command differs.
+        _pause_for_agent(
+            work_dir,
+            need_text,
+            _continuation_command(video, work_dir, args),
+            inspect_hint=inspect_hint,
+        )
+
+    def _reject_stale_manifest():
+        _reject_stale(_manifest_mismatches(work_dir, video, args), " ")
+
+    if not cut:
+        # Full mode: a single pause (understand -> agent writes narration.json -> produce).
+        if uses_narration(args):
+            if not narration_json.exists():
+                _understand()
+                _write_run_manifest(work_dir, video, args)
+                _pause(f"{narration_json}", state_hint)
+                return
+            _reject_stale_manifest()
+            _run(
+                "video-script", "validate.py", "--work-dir", work_dir,
+                "--mode", "full", *_approved_validation_args(args),
+            )
+        elif (work_dir / RUN_MANIFEST).exists():
+            _reject_stale_manifest()
+        else:
+            _write_run_manifest(work_dir, video, args)
+        if not uses_narration(args):
+            begin_non_narration_qc(work_dir, args, _write_shift_left_stage_qc)
+        _deliver(work_dir, args, video, video.stem, "source")
+        return
+
+    # Cut mode: cut-first / narrate-second (two pauses), so narration is authored against the
+    # REAL output timeline — no source-time mapping exists that could drop/clamp/desync.
+    if not clip_plan_json.exists():
+        # PASS 1: understand -> agent writes clip_plan.json ONLY.
+        if not uses_narration(args) and (work_dir / RUN_MANIFEST).exists():
+            _reject_stale_manifest()
+        if not uses_narration(args):
+            begin_non_narration_qc(work_dir, args, _write_shift_left_stage_qc)
+        _understand()
+        _write_run_manifest(work_dir, video, args)
+        _pause(f"{clip_plan_json}（只写剪辑计划；解说下一步对着剪好的成片写）", state_hint)
+        return
+    _reject_stale_manifest()
+    if not uses_narration(args):
+        begin_non_narration_qc(work_dir, args, _write_shift_left_stage_qc)
+    cp_identity = material_lib.file_identity(clip_plan_json)
+    _render_cut(video, work_dir, args)
+    if uses_narration(args):
+        if not narration_json.exists():
+            # PASS 2: rebuild the brief (now an OUTPUT-timeline variant) and pause for narration.
+            _rebuild_understanding_brief(_single_source_record(video, args), work_dir, args)
+            _write_phase_ledger(
+                work_dir, clip_plan_identity=cp_identity, edited_source_rendered=True
+            )
+            _pause(
+                f"{narration_json}（用成片 OUTPUT 时间轴写解说，对着 {edited_source}）",
+                f"python3 {inspect_py} --work-dir {work_dir} "
+                "clip-map --output-start <s> --output-end <e>  # 核对输出↔原片时间轴",
+            )
+            return
+        _reject_stale_cut_narration(work_dir, cp_identity)
+        _write_phase_ledger(work_dir, clip_plan_identity=cp_identity, narration_written=True)
+        _validate_cut_output_narration(work_dir, args)
+    else:
+        _write_phase_ledger(
+            work_dir,
+            clip_plan_identity=cp_identity,
+            edited_source_rendered=True,
+            audio_mode=args.audio_mode,
+            audio_stream_index=args.audio_stream_index,
+        )
+    # let the timeline / 剪映 export reference the original clips, not edited_source.mp4
+    _deliver(
+        work_dir, args, edited_source, video.stem, "cut_output",
+        ["--source-video", str(video)],
+    )