@lemoncat7/dsh-partner 2.8.1 → 2.8.3

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

@@ -0,0 +1,260 @@
+"""Provide subprocess, manifest, and preflight runtime helpers."""
+
+import json
+import math
+import shlex
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import materials as material_lib
+from doctor import ffmpeg_has_subtitles_filter
+from lib import env_bool, env_int, load_json
+from recap_source import audio_binding
+
+BUNDLE = Path(__file__).resolve().parents[2]  # the skills/ directory
+
+RUN_MANIFEST = "recap_run_manifest.json"
+
+MULTI_SOURCE_MANIFEST = "multi_source_manifest.json"
+
+
+def _run(skill, script, *cli_args):
+    cmd = [sys.executable, str(_entry(skill, script)), *map(str, cli_args)]
+    print(f"[video-recap] ▶ {skill}/{script}", flush=True)
+    res = subprocess.run(cmd)
+    if res.returncode != 0:
+        raise SystemExit(f"{skill}/{script} 失败 (exit {res.returncode})")
+
+
+def _optional_env_int(name):
+    """lib.env_int with -1 as the documented "unset" sentinel."""
+    value = env_int(name, None)
+    return None if value == -1 else value
+
+
+def _read_video_duration_or_raise(path):
+    """Return media duration via ffprobe, or hard-fail before downstream TTS/render."""
+    path = Path(path)
+    cmd = [
+        "ffprobe",
+        "-v",
+        "quiet",
+        "-show_entries",
+        "format=duration",
+        "-of",
+        "csv=p=0",
+        str(path),
+    ]
+    res = subprocess.run(cmd, capture_output=True, text=True)
+    if res.returncode != 0:
+        detail = (res.stderr or res.stdout or "ffprobe failed").strip()
+        raise SystemExit(f"无法读取成片时长: {path} ({detail})")
+    try:
+        duration = float(res.stdout.strip())
+    except ValueError:
+        raise SystemExit(f"无法读取成片时长: {path} (ffprobe 输出无效: {res.stdout!r})") from None
+    if not math.isfinite(duration) or duration <= 0:
+        raise SystemExit(f"无法读取成片时长: {path} (duration={duration:.3f})")
+    return duration
+
+
+def _probe_display_height_or_raise(path, *, require_square_pixels=False):
+    """Return ffmpeg's display-coordinate height, accounting for rotation and SAR."""
+    return _probe_display_size_or_raise(path, require_square_pixels=require_square_pixels)[1]
+
+
+def _probe_display_size_or_raise(path, *, require_square_pixels=False):
+    """Return ffmpeg's display-coordinate (width, height), accounting for rotation and SAR."""
+    cmd = [
+        "ffprobe",
+        "-v",
+        "error",
+        "-select_streams",
+        "v:0",
+        "-show_entries",
+        "stream=width,height,sample_aspect_ratio:stream_tags=rotate:stream_side_data=rotation",
+        "-of",
+        "json",
+        str(path),
+    ]
+    res = subprocess.run(cmd, capture_output=True, text=True)
+    try:
+        stream = json.loads(res.stdout)["streams"][0]
+        width, height = int(stream["width"]), int(stream["height"])
+    except (IndexError, KeyError, ValueError):
+        detail = (res.stderr or res.stdout or "ffprobe failed").strip()
+        raise SystemExit(f"无法读取视频画布: {path} ({detail})") from None
+    sar = stream.get("sample_aspect_ratio", "1:1")
+    try:
+        num, den = sar.split(":", 1)
+        sar_ratio = float(num) / float(den)
+    except (ValueError, ZeroDivisionError):
+        sar_ratio = math.nan
+    if require_square_pixels and (
+        not math.isfinite(sar_ratio) or abs(sar_ratio - 1.0) >= 1e-9
+    ):
+        raise SystemExit(
+            f"subtitle Y coordinates currently require square-pixel video (SAR 1:1); got {sar}"
+        )
+    display_width = max(1, round(width * sar_ratio)) if math.isfinite(sar_ratio) else width
+    rotation_values = [
+        stream.get("tags", {}).get("rotate"),
+        *(item.get("rotation") for item in stream.get("side_data_list", [])),
+    ]
+    rotation = next(
+        (int(round(float(value))) % 360 for value in rotation_values if value not in (None, "")),
+        0,
+    )
+    return (height, display_width) if rotation in {90, 270} else (display_width, height)
+
+
+def _analysis_settings(args):
+    return {
+        "context": args.context,
+        "scene_threshold": args.scene_threshold,
+        "style": args.style,
+        "edit_mode": args.edit_mode,
+        "target_duration": args.target_duration,
+        "skip_asr": bool(args.skip_asr),
+        "mimo_video_overview": bool(args.mimo_video_overview),
+        "consolidate": bool(args.consolidate),
+        "consolidate_asr": bool(args.consolidate_asr),
+    }
+
+
+def _coerce_videos(video_or_videos):
+    if isinstance(video_or_videos, (list, tuple)):
+        return [Path(v).resolve() for v in video_or_videos]
+    return [Path(video_or_videos).resolve()]
+
+
+def _run_manifest_payload(video, args):
+    return {
+        "schema_version": 1,
+        "source_video": str(Path(video).resolve()),
+        "source_video_identity": material_lib.file_identity(video),
+        "settings": _analysis_settings(args),
+        "audio": audio_binding(args),
+    }
+
+
+def _write_run_manifest(work_dir, video, args):
+    payload = _run_manifest_payload(video, args)
+    (work_dir / RUN_MANIFEST).write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    return payload
+
+
+def _build_multi_source_records(videos, args):
+    records = []
+    for video in _coerce_videos(videos):
+        identity = material_lib.file_identity(video)
+        records.append(
+            {
+                "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),
+            }
+        )
+    records = material_lib.assign_source_ids(records)
+    for record in records:
+        record["source_work_dir"] = f"sources/{record['source_id']}"
+    return records
+
+
+def _multi_run_manifest_payload(videos, args, source_records):
+    return {
+        "schema_version": 2,
+        "mode": "multi_source",
+        "sources": [
+            {
+                "source_id": s["source_id"],
+                "source_path": s["source_path"],
+                "source_video_identity": s["source_video_identity"],
+                "source_work_dir": s["source_work_dir"],
+                "material_id": s["material_id"],
+            }
+            for s in source_records
+        ],
+        "source_videos": [str(v) for v in _coerce_videos(videos)],
+        "settings": _analysis_settings(args),
+        "audio": audio_binding(args),
+    }
+
+
+def _write_project_run_manifest(work_dir, videos, args, source_records):
+    payload = _multi_run_manifest_payload(videos, args, source_records)
+    (work_dir / RUN_MANIFEST).write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+
+
+def _write_multi_source_manifest(work_dir, source_records):
+    path = Path(work_dir) / MULTI_SOURCE_MANIFEST
+    payload = {
+        "schema_version": 1,
+        "sources": [
+            {
+                "source_id": s["source_id"],
+                "source_path": s["source_path"],
+                "source_name": s["source_name"],
+                "source_video_identity": s["source_video_identity"],
+                "source_work_dir": s["source_work_dir"],
+                "material_id": s["material_id"],
+            }
+            for s in source_records
+        ],
+    }
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    return path
+
+
+def _load_run_manifest(work_dir):
+    """The run manifest, or None before Phase A has written one."""
+    path = Path(work_dir) / RUN_MANIFEST
+    return load_json(path) if path.exists() else None
+
+
+def _burn_subtitles_intended(args):
+    """Effective burn-subtitles state at orchestrator level. Mirrors video-assemble's
+    CONFIG default `env_bool("BURN_SUBTITLES", True)` (burn is ON by default); an explicit
+    CLI flag (--burn-subtitles / --no-burn-subtitles) overrides the env."""
+    if args.burn_subtitles is not None:
+        return args.burn_subtitles
+    return env_bool("BURN_SUBTITLES", True)
+
+
+def _ffmpeg_present_but_cannot_burn():
+    """True only when ffmpeg EXISTS but lacks the libass `subtitles` filter — the specific
+    "subtitle-burn environment unsupported" case. Returns False when ffmpeg is absent
+    entirely: that is a more fundamental problem that surfaces at the first stage (understand
+    calls ffprobe/ffmpeg) and is reported by doctor, so this guard stays narrow — and does
+    not fire in mocked, ffmpeg-less test environments."""
+    if shutil.which("ffmpeg") is None:
+        return False
+    return not ffmpeg_has_subtitles_filter()
+
+
+def _preflight_burn_subtitles(args):
+    """Fail fast BEFORE any understanding/VLM/ASR/TTS spend when subtitle burn-in is on but
+    this ffmpeg can't burn it. Without it the run only dies at the final assemble
+    `-vf subtitles=` step — after the whole expensive pipeline has run. Dub renders through
+    dub.py, which never burns subtitles, so it is exempt."""
+    if args.edit_mode == "dub" or not _burn_subtitles_intended(args):
+        return
+    if _ffmpeg_present_but_cannot_burn():
+        raise SystemExit(
+            "字幕烧录已开启，但当前 ffmpeg 不支持 subtitles/libass 滤镜，整条流程会跑到最后渲染才失败。\n"
+            "  解决其一：(1) 安装带 libass 的 ffmpeg；(2) 加 --no-burn-subtitles 关闭烧录"
+            "（仍输出 .srt 外挂字幕）。\n"
+            f"  自检：python3 {shlex.quote(str(_entry('video-recap', 'doctor.py')))}"
+        )
+
+
+def _entry(skill, script):
+    return BUNDLE / skill / "scripts" / script

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

@@ -0,0 +1,278 @@
+"""Validate recap audio ownership without importing another skill."""
+
+import json
+from pathlib import Path
+
+
+AUDIO_MODES = ("narration", "source-mix", "adopted-packet-copy")
+
+_TTS_OPTIONS = frozenset({
+    "--tts-provider",
+    "--mimo-tts-voice",
+    "--voice-ref",
+    "--allow-partial-tts",
+    "--preserve-approved-text",
+    "--review-narration",
+    "--no-review-narration",
+    "--require-narration-review",
+})
+
+_LOCAL_ADOPTION_OPTIONS = (
+    ("tts_meta", "--tts-meta"),
+    ("narration_adoption", "--narration-adoption"),
+    ("audio_mix_adoption", "--audio-mix-adoption"),
+)
+
+_LOCAL_ADOPTION_CONFLICTS = _TTS_OPTIONS | frozenset({
+    "--mimo-qc",
+    "--mimo-qc-refresh",
+    "--export-jianying",
+    "--jianying-bundle-media",
+    "--jianying-no-bundle-media",
+})
+
+
+def uses_narration(args):
+    return args.audio_mode == "narration"
+
+
+def uses_local_adoption(args):
+    return all(getattr(args, field) is not None for field, _ in _LOCAL_ADOPTION_OPTIONS)
+
+
+def needs_voiceover(args):
+    return uses_narration(args) and not uses_local_adoption(args)
+
+
+def audio_binding(args):
+    binding = {
+        "mode": args.audio_mode,
+        "selected_stream_index": args.audio_stream_index,
+    }
+    if uses_local_adoption(args):
+        binding["local_adoption"] = {
+            field: {"path": str(Path(getattr(args, field)).resolve())}
+            for field, _ in _LOCAL_ADOPTION_OPTIONS
+        }
+    return binding
+
+
+def _resolve_local_file(parser, value, option):
+    path = Path(value).expanduser().resolve()
+    if not path.is_file():
+        parser.error(f"{option} does not exist or is not a file: {path}")
+    return str(path)
+
+
+def validate_local_adoption(parser, args):
+    """Validate and resolve the assembly-only local adoption boundary."""
+    supplied = [getattr(args, field) is not None for field, _ in _LOCAL_ADOPTION_OPTIONS]
+    if any(supplied) and not all(supplied):
+        parser.error("--tts-meta, --narration-adoption and --audio-mix-adoption are all-or-none")
+    if not all(supplied):
+        return
+    if args.edit_mode != "full" or args.audio_mode != "narration":
+        parser.error("local audio adoption requires --edit-mode full and --audio-mode narration")
+    if args.audio_stream_index != 0:
+        parser.error("local audio adoption requires --audio-stream-index 0")
+    if len(args.video) != 1:
+        parser.error("local audio adoption requires exactly one input video")
+    if args.work_dir is None:
+        parser.error("local audio adoption requires explicit --work-dir")
+    conflicts = sorted(set(args._explicit_options).intersection(_LOCAL_ADOPTION_CONFLICTS))
+    if conflicts:
+        parser.error("local audio adoption cannot use: " + ", ".join(conflicts))
+    for field, option in _LOCAL_ADOPTION_OPTIONS:
+        setattr(args, field, _resolve_local_file(parser, getattr(args, field), option))
+
+    work_dir = Path(args.work_dir).expanduser().resolve()
+    if work_dir.exists():
+        parser.error("local audio adoption requires a new --work-dir")
+    output_dir = (
+        Path(args.output_dir).expanduser().resolve()
+        if args.output_dir is not None else work_dir.parent
+    )
+    # Pre-run guard only: mirrors the assembler's `recap_<stem>.mp4` naming so an existing
+    # delivery is refused before work starts. The authoritative published path is read back
+    # from the child's assembly_manifest.json after the run.
+    delivery = output_dir / f"recap_{Path(args.video[0]).stem}.mp4"
+    if delivery.exists():
+        parser.error(f"local audio adoption will not overwrite delivery: {delivery}")
+    args.work_dir = str(work_dir)
+    args.output_dir = str(output_dir)
+
+    # Ambient authoring configuration is irrelevant because this route never synthesizes
+    # or reviews narration. Explicit forms were rejected above.
+    args.tts_provider = "auto"
+    args.mimo_tts_voice = None
+    args.voice_ref = None
+    args.mimo_qc = "off"
+
+
+def load_local_assembly_evidence(work_dir):
+    """Load the assembler's binding records for the adopted local bundle."""
+    work_dir = Path(work_dir)
+    try:
+        return {
+            name: json.loads((work_dir / filename).read_text(encoding="utf-8"))
+            for name, filename in (
+                ("assembly", "assembly_manifest.json"),
+                ("narration", "narration_input_binding.json"),
+                ("mix", "audio_mix_binding.json"),
+            )
+        }
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise SystemExit("assembler did not publish readable local adoption evidence") from exc
+
+
+def _same_file(declared, expected):
+    return Path(declared).resolve() == Path(expected).resolve()
+
+
+def verify_local_assembly_evidence(evidence, manifest):
+    """The child bindings must reference the same adoption files and picture recap ran with."""
+    try:
+        local = manifest["audio"]["local_adoption"]
+        narration = evidence["narration"]
+        mix = evidence["mix"]
+        matches = (
+            _same_file(narration["adoption"]["path"], local["narration_adoption"]["path"])
+            and _same_file(narration["adoption"]["tts_meta"]["path"], local["tts_meta"]["path"])
+            and _same_file(mix["adoption"]["path"], local["audio_mix_adoption"]["path"])
+            and _same_file(mix["picture"]["path"], manifest["source_video"])
+        )
+    except (KeyError, TypeError):
+        matches = False
+    if not matches:
+        raise SystemExit("assembler bindings do not match the local adoption manifest")
+
+
+def owned_local_delivery(evidence):
+    """Return a stable ownership token only when all child reports bind the published file."""
+    try:
+        expected = Path(evidence["assembly"]["final_output"]).resolve()
+    except (KeyError, TypeError) as exc:
+        raise SystemExit(
+            "assembly manifest does not declare final_output; cannot own the delivery"
+        ) from exc
+    try:
+        declared = [
+            Path(evidence["narration"]["final_output"]["path"]).resolve(),
+            Path(evidence["mix"]["final_output"]["path"]).resolve(),
+        ]
+    except (KeyError, TypeError):
+        return None
+    if declared != [expected, expected] or not expected.is_file():
+        return None
+    stat = expected.stat()
+    return {"path": expected, "device": stat.st_dev, "inode": stat.st_ino}
+
+
+def remove_owned_local_delivery(token):
+    if token is None:
+        return
+    path = token["path"]
+    if not path.is_file():
+        return
+    stat = path.stat()
+    if (stat.st_dev, stat.st_ino) == (token["device"], token["inode"]):
+        path.unlink()
+
+
+def reject_unbound_narration_workdir(work_dir, args):
+    """Do not reinterpret an unbound narrated work directory as source-owned audio."""
+    work_dir = Path(work_dir)
+    if (
+        not uses_narration(args)
+        and not (work_dir / "recap_run_manifest.json").exists()
+        and (work_dir / "narration.json").exists()
+    ):
+        raise SystemExit(
+            "当前 work_dir 含 narration.json 但缺少可验证的音频运行策略；"
+            "非解说模式请使用新的 --work-dir"
+        )
+
+
+def validate_audio_routing(parser, args):
+    """Reject combinations the current pipeline cannot execute truthfully."""
+    validate_local_adoption(parser, args)
+    mode = args.audio_mode
+    stream = args.audio_stream_index
+    if stream < 0:
+        parser.error("--audio-stream-index must be a non-negative integer")
+    if args.edit_mode == "dub" and mode != "narration":
+        parser.error("--edit-mode dub cannot be combined with a non-narration --audio-mode")
+    # index-tts + MiMo voice/--voice-ref is rejected once, in recap_runner.main, after the
+    # ambient VOICE_REF/MIMO_TTS_VOICE have been folded in.
+    if args.tts_provider == "index-tts" and args.edit_mode == "dub":
+        parser.error("--edit-mode dub does not support --tts-provider index-tts")
+    if mode == "narration":
+        if stream != 0:
+            parser.error("narration currently requires --audio-stream-index 0")
+        return
+
+    conflicts = sorted(set(args._explicit_options).intersection(_TTS_OPTIONS))
+    if conflicts:
+        detail = ", ".join(conflicts)
+        parser.error(f"--audio-mode {mode} cannot use TTS/strict narration options: {detail}")
+    if args.mimo_qc != "off":
+        parser.error(f"--audio-mode {mode} currently requires --mimo-qc off")
+    if args.edit_mode == "cut" and stream != 0:
+        parser.error("cut audio modes currently require --audio-stream-index 0")
+    if args.export_jianying and stream != 0:
+        parser.error("JianYing export currently requires --audio-stream-index 0")
+    # Environment defaults are irrelevant once source audio owns the run. Normalizing
+    # prevents an invalid ambient provider from leaking into later state or continuation.
+    args.tts_provider = "auto"
+
+
+def extend_assemble_args(cli_args, args):
+    mode = args.audio_mode
+    stream = args.audio_stream_index
+    if mode != "narration":
+        cli_args += ["--audio-mode", mode]
+    if stream != 0:
+        cli_args += ["--audio-stream-index", str(stream)]
+    return cli_args
+
+
+def reject_unsupported_subtitle_track(work_dir, args):
+    if args.audio_mode == "source-mix" and (Path(work_dir) / "subtitle_track.json").exists():
+        raise SystemExit(
+            "source-mix 当前不能绑定显式 subtitle_track.json；请使用新的 work_dir，"
+            "或选择 adopted-packet-copy"
+        )
+
+
+def begin_non_narration_qc(work_dir, args, write_stage):
+    """Start a clean run-local QC ledger without reading or deleting old TTS."""
+    (Path(work_dir) / "preflight_qc.json").unlink(missing_ok=True)
+    return write_stage(
+        work_dir,
+        "pre_assemble",
+        metadata={
+            "audio_mode": args.audio_mode,
+            "selected_audio_stream_index": args.audio_stream_index,
+            "tts": "not_applicable",
+            "narration_validation": "not_applicable",
+            "narration_review": "not_applicable",
+            "visual_overlays": "preserved_not_authored_by_this_run",
+        },
+    )
+
+
+def begin_local_adoption_qc(work_dir, write_stage):
+    """Record that authoring was intentionally skipped for adopted local assets."""
+    return write_stage(
+        work_dir,
+        "pre_assemble",
+        metadata={
+            "audio_mode": "narration",
+            "selected_audio_stream_index": 0,
+            "tts": "adopted_local_not_generated",
+            "narration_validation": "not_run",
+            "narration_review": "not_run",
+            "semantic_validation": "video-assemble",
+            "visual_overlays": "not_authored_not_present",
+        },
+    )

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

@@ -0,0 +1,160 @@
+"""Write shift-left, MiMo, and final QC stage reports."""
+
+import json
+from pathlib import Path
+
+import final_qc
+import mimo_qc
+import qc_contract
+
+ASSEMBLY_MANIFEST = "assembly_manifest.json"
+PREFLIGHT_QC = "preflight_qc.json"
+
+
+def _load_preflight_stage_reports(work_dir):
+    path = Path(work_dir) / PREFLIGHT_QC
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8"))["metadata"]["stages"]
+
+
+def _write_shift_left_stage_qc(work_dir, stage, metadata, findings=None):
+    """Write/roll up local shift-left QC for one pipeline stage.
+
+    This is a local contract artifact only: no MiMo/deep eval calls, no repair, and no
+    credential persistence (qc_contract redacts every report it builds).
+    """
+    stage_report = qc_contract.build_report(
+        artifact=PREFLIGHT_QC, stage=stage, findings=findings, metadata=metadata
+    )
+    stage_reports = _load_preflight_stage_reports(work_dir)
+    stage_reports[stage] = stage_report
+    top_metadata = dict(stage_report["metadata"])
+    top_metadata["latest_stage"] = stage
+    top_metadata["stages"] = stage_reports
+    top_report = qc_contract.build_report(
+        artifact=PREFLIGHT_QC,
+        stage=stage,
+        findings=[f for report in stage_reports.values() for f in report["findings"]],
+        metadata=top_metadata,
+    )
+    (Path(work_dir) / PREFLIGHT_QC).write_text(
+        json.dumps(top_report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    return top_report
+
+
+def _tts_qc_metadata(work_dir):
+    """Called after video-voiceover exited 0, which always writes tts_meta.json."""
+    work_dir = Path(work_dir)
+    metadata = {"tts_meta": json.loads((work_dir / "tts_meta.json").read_text(encoding="utf-8"))}
+    tts_dir = work_dir / "tts_segments"
+    if tts_dir.is_dir():
+        metadata["tts_segments"] = [
+            p.relative_to(work_dir).as_posix() for p in sorted(tts_dir.iterdir()) if p.is_file()
+        ]
+    return metadata
+
+
+def _post_render_qc_metadata(work_dir, final_output):
+    """Called after video-assemble exited 0, which always writes assembly_manifest.json."""
+    manifest = Path(work_dir) / ASSEMBLY_MANIFEST
+    return {
+        "final_output": str(final_output),
+        "assembly_manifest": json.loads(manifest.read_text(encoding="utf-8")),
+    }
+
+
+def _write_final_qc_reports(work_dir, final_output):
+    """Write report-only final QC artifacts after render.
+
+    final_qc.run converts ffprobe unavailability/failure into deterministic
+    blockers; only unexpected schema/write errors propagate.
+    """
+    return final_qc.run(work_dir, final_output=final_output)
+
+
+def _print_final_qc_pointer(result):
+    """Surface a report-only final_qc/golden_eval FAIL so the shift-left QC is
+    not a silent no-op. Advisory only: it never changes the exit status."""
+    problems = [
+        f"{key} blocker_count={result[key].get('blocker_count', '?')}"
+        for key in ("final_qc", "golden_eval")
+        if result[key].get("ok") is False
+    ]
+    if problems:
+        print(
+            "[video-recap] ⚠️  最终 QC 未通过（仅报告，不阻断）: "
+            + "; ".join(problems)
+            + "；详见 final_qc.json / golden_eval.json"
+        )
+
+
+def _require_final_qc(result, work_dir):
+    """Fail closed unless both final summaries are literal blocker-free passes."""
+    paths = [Path(work_dir) / name for name in ("final_qc.json", "golden_eval.json")]
+    print("[video-recap] 最终 QC 报告: " + "; ".join(map(str, paths)))
+    invalid = []
+    for name in ("final_qc", "golden_eval"):
+        summary = result.get(name) if isinstance(result, dict) else None
+        blockers = summary.get("blocker_count") if isinstance(summary, dict) else None
+        if not isinstance(summary, dict) or summary.get("ok") is not True or \
+                type(blockers) is not int or blockers != 0:
+            invalid.append(name)
+    if invalid:
+        raise SystemExit(
+            "严格最终 QC 未通过或摘要格式无效: " + ", ".join(invalid)
+        )
+
+
+def _mimo_qc_stage_enabled(args, stage):
+    return (
+        args.mimo_qc == "both"
+        or (args.mimo_qc == "pre-assemble" and stage == "pre_assemble")
+        or (args.mimo_qc == "post-render" and stage == "post_render")
+    )
+
+
+def _prepare_mimo_qc(work_dir, args):
+    """Remove an old advisory artifact when this run has MiMo QC disabled."""
+    if args.mimo_qc == "off":
+        mimo_qc.clear_report(work_dir)
+
+
+def _print_mimo_qc_pointer(result, stage):
+    report = result["report"]
+    metadata = report["metadata"]
+    status = metadata["status"]
+    stage_findings = [f for f in report["findings"] if f["stage"] == stage]
+    if status in {"failed", "unavailable"}:
+        print(
+            f"[video-recap] ⚠ MiMo QC {stage}: {status} ({metadata['error']})；建议性检查不可用，继续流水线"
+        )
+        return
+    print(
+        f"[video-recap] ℹ MiMo QC {stage}: {status}, {len(stage_findings)} 条建议；详见 {result['path']}"
+    )
+    for finding in stage_findings[:5]:
+        print(f"[video-recap]   - {finding['message']}")
+
+
+def _run_mimo_qc_stage(work_dir, args, stage, *, final_output=None):
+    """Run one selected advisory stage and never propagate a failure."""
+    if not _mimo_qc_stage_enabled(args, stage):
+        return None
+    try:
+        result = mimo_qc.run(
+            work_dir,
+            stage=stage,
+            live=True,
+            refresh=args.mimo_qc_refresh,
+            final_output=final_output,
+        )
+    except Exception as exc:
+        print(
+            f"[video-recap] ⚠ MiMo QC {stage}: {type(exc).__name__}；"
+            "建议性检查失败，继续流水线"
+        )
+        return None
+    _print_mimo_qc_pointer(result, stage)
+    return result