@oh-story/dsh 0.1.4 → 0.1.6

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

@@ -0,0 +1,335 @@
+"""Provide subprocess, manifest, review, and preflight runtime helpers."""
+
+import hashlib
+
+import json
+
+import math
+
+import os
+
+import shlex
+
+import subprocess
+
+import sys
+
+from pathlib import Path
+
+
+from doctor import ffmpeg_has_subtitles_filter
+
+import materials as material_lib
+
+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 _env_bool(name, default=False):
+    raw = os.environ.get(name)
+    if raw is None or raw == "":
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "y", "on"}
+
+
+def _optional_env_int(name):
+    raw = os.environ.get(name)
+    if raw is None or raw.strip() == "":
+        return None
+    try:
+        value = int(raw)
+    except ValueError as exc:
+        raise ValueError(f"{name} must be an integer; got {raw!r}") from exc
+    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 (TypeError, ValueError):
+        raise SystemExit(f"无法读取成片时长: {path} (ffprobe 输出无效: {res.stdout!r})")
+    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."""
+    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 or "{}").get("streams") or [])[0]
+        width, height = int(stream["width"]), int(stream["height"])
+    except (IndexError, KeyError, TypeError, ValueError, json.JSONDecodeError):
+        detail = (res.stderr or res.stdout or "ffprobe failed").strip()
+        raise SystemExit(f"无法读取视频画布: {path} ({detail})")
+    sar = str(stream.get("sample_aspect_ratio") or "1:1")
+    try:
+        num, den = sar.split(":", 1)
+        sar_ratio = float(num) / float(den)
+        display_width = max(1, int(round(width * sar_ratio)))
+    except (TypeError, ValueError, ZeroDivisionError):
+        sar_ratio = math.nan
+        display_width = width
+    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}"
+        )
+    rotation_values = [
+        (stream.get("tags") or {}).get("rotate"),
+        *(
+            item.get("rotation")
+            for item in stream.get("side_data_list") or []
+            if isinstance(item, dict)
+        ),
+    ]
+    rotation = 0
+    for value in rotation_values:
+        if value not in (None, ""):
+            try:
+                rotation = int(round(float(value))) % 360
+                break
+            except (TypeError, ValueError):
+                pass
+    return display_width if rotation in {90, 270} else height
+
+
+_FILE_FINGERPRINT_MEMO = {}
+
+
+def _file_identity(path):
+    """(device, inode, size, mtime_ns) — changes whenever the bytes could have changed."""
+    st = os.stat(os.fspath(path))
+    return (st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns)
+
+
+def _file_fingerprint(path, chunk_size=1024 * 1024):
+    """Return a full-content fingerprint for cache-correct identity checks.
+
+    The digest covers CONTENT only — never the path or mtime — so a copied video or
+    artifact is still recognised as the same asset, while any byte change invalidates
+    the cache even if timestamps, size, head, or tail bytes are misleading.
+
+    Identity metadata is used ONLY to memoize within a single process. One understanding
+    run fingerprints the same source video 8-10 times and the whole extracted frame set
+    2-3 times; on a 40-minute video at fps=1 that is gigabytes of redundant reads before
+    any real work starts. A file rewritten in place gets a new (size, mtime_ns) and is
+    re-hashed, so the memo can never serve a stale digest.
+    """
+    key = _file_identity(path)
+    memoized = _FILE_FINGERPRINT_MEMO.get(key)
+    if memoized is not None:
+        return memoized
+    h = hashlib.sha256()
+    with open(os.fspath(path), "rb") as f:
+        for chunk in iter(lambda: f.read(chunk_size), b""):
+            h.update(chunk)
+    digest = h.hexdigest()
+    _FILE_FINGERPRINT_MEMO[key] = digest
+    return digest
+
+
+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 _material_settings_fingerprint(args):
+    return material_lib.settings_fingerprint(_analysis_settings(args))
+
+
+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_fingerprint": _file_fingerprint(video),
+        "settings": _analysis_settings(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"
+    )
+
+
+def _build_multi_source_records(videos, args):
+    records = []
+    for video in _coerce_videos(videos):
+        fp = _file_fingerprint(video)
+        records.append(
+            {
+                "source_path": str(video),
+                "source_name": video.name,
+                "source_video_fingerprint": fp,
+                "settings_fingerprint": _material_settings_fingerprint(args),
+                "material_id": material_lib.material_id_for(video, fp),
+            }
+        )
+    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.get("source_id"),
+                "source_path": s.get("source_path"),
+                "source_video_fingerprint": s.get("source_video_fingerprint"),
+                "source_work_dir": s.get("source_work_dir"),
+                "material_id": s.get("material_id"),
+            }
+            for s in source_records
+        ],
+        "source_videos": [str(v) for v in _coerce_videos(videos)],
+        "settings": _analysis_settings(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_fingerprint": s["source_video_fingerprint"],
+                "source_work_dir": s["source_work_dir"],
+                "material_id": s.get("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):
+    path = Path(work_dir) / RUN_MANIFEST
+    if not path.exists():
+        return None
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError, TypeError):
+        return None
+
+
+def _load_json(path):
+    try:
+        return json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, ValueError, TypeError):
+        return 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 getattr(args, "burn_subtitles", None) is not None:
+        return bool(args.burn_subtitles)
+    raw = os.environ.get("BURN_SUBTITLES")
+    if raw is None or raw == "":
+        return True
+    return raw.strip().lower() in {"1", "true", "yes", "y", "on"}
+
+
+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."""
+    import shutil
+
+    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."""
+    if 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/lib/video-recap/skills/video-recap/scripts/recap_stage_qc.py

@@ -0,0 +1,217 @@
+"""Write shift-left, MiMo, and final QC stage reports."""
+
+import json
+
+
+from pathlib import Path
+
+import qc_contract
+
+import final_qc
+
+import mimo_qc
+
+
+from recap_runtime import _load_json
+
+ASSEMBLY_MANIFEST = "assembly_manifest.json"
+
+
+def _json_safe(value):
+    """Return a JSON-serializable, secret-redacted copy for local QC metadata."""
+
+    def convert(item):
+        if isinstance(item, Path):
+            return str(item)
+        if isinstance(item, dict):
+            return {str(k): convert(v) for k, v in item.items()}
+        if isinstance(item, (list, tuple)):
+            return [convert(v) for v in item]
+        return item
+
+    return qc_contract.redact_secrets(convert(value))
+
+
+def _load_preflight_stage_reports(work_dir):
+    path = Path(work_dir) / "preflight_qc.json"
+    if not path.exists():
+        return {}
+    data = _load_json(path)
+    if not isinstance(data, dict):
+        raise qc_contract.QCContractError("preflight_qc.json must be a JSON object")
+    qc_contract.validate_report(data)
+    stages = None
+    metadata = data.get("metadata")
+    if isinstance(metadata, dict) and isinstance(metadata.get("stages"), dict):
+        stages = metadata.get("stages")
+    elif isinstance(data.get("stages"), dict):
+        stages = data.get("stages")
+    if stages is None:
+        return {data["stage"]: data}
+    stage_reports = {}
+    for stage, report in stages.items():
+        if not isinstance(report, dict):
+            raise qc_contract.QCContractError(
+                f"preflight stage report must be an object: {stage}"
+            )
+        qc_contract.validate_report(report)
+        if report.get("stage") != stage:
+            raise qc_contract.QCContractError(
+                f"preflight stage key does not match report stage: {stage}"
+            )
+        stage_reports[stage] = report
+    return stage_reports
+
+
+def _write_shift_left_stage_qc(work_dir, stage, metadata=None, 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. Any validation/write failure is allowed to raise.
+    """
+    work_dir = Path(work_dir)
+    path = work_dir / "preflight_qc.json"
+    stage_report = qc_contract.build_report(
+        artifact="preflight_qc.json",
+        stage=stage,
+        findings=findings or [],
+        metadata=_json_safe(metadata or {}),
+    )
+    stage_reports = _load_preflight_stage_reports(work_dir)
+    stage_reports[stage] = stage_report
+    aggregate_findings = []
+    for report in stage_reports.values():
+        aggregate_findings.extend(dict(f) for f in report.get("findings", []))
+    top_metadata = dict(stage_report.get("metadata") or {})
+    top_metadata["latest_stage"] = stage
+    top_metadata["stages"] = stage_reports
+    top_report = qc_contract.build_report(
+        artifact="preflight_qc.json",
+        stage=stage,
+        findings=aggregate_findings,
+        metadata=_json_safe(top_metadata),
+    )
+    qc_contract.validate_report(top_report)
+    path.write_text(
+        json.dumps(top_report, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    qc_contract.validate_report(_load_json(path))
+    return top_report
+
+
+def _tts_qc_metadata(work_dir):
+    work_dir = Path(work_dir)
+    metadata = {}
+    tts_meta = _load_json(work_dir / "tts_meta.json")
+    if tts_meta is not None:
+        metadata["tts_meta"] = tts_meta
+    tts_dir = work_dir / "tts_segments"
+    if tts_dir.exists() and 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):
+    work_dir = Path(work_dir)
+    metadata = {"final_output": str(final_output) if final_output is not None else None}
+    assembly_manifest = _load_json(work_dir / ASSEMBLY_MANIFEST)
+    if assembly_manifest is not None:
+        metadata["assembly_manifest"] = assembly_manifest
+    return metadata
+
+
+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."""
+    if not isinstance(result, dict):
+        return
+    problems = []
+    for key in ("final_qc", "golden_eval"):
+        section = result.get(key)
+        if isinstance(section, dict) and section.get("ok") is False:
+            problems.append(f"{key} blocker_count={section.get('blocker_count', '?')}")
+    if problems:
+        print(
+            "[video-recap] ⚠️  最终 QC 未通过（仅报告，不阻断）: "
+            + "; ".join(problems)
+            + "；详见 final_qc.json / golden_eval.json"
+        )
+
+
+def _mimo_qc_stage_enabled(args, stage):
+    mode = getattr(args, "mimo_qc", "off") or "off"
+    return (
+        mode == "both"
+        or (mode == "pre-assemble" and stage == "pre_assemble")
+        or (mode == "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 getattr(args, "mimo_qc", "off") == "off":
+        mimo_qc.clear_report(work_dir)
+
+
+def _print_mimo_qc_pointer(result, stage):
+    report = result.get("report", {}) if isinstance(result, dict) else {}
+    metadata = report.get("metadata", {}) if isinstance(report, dict) else {}
+    status = metadata.get("status", "unknown")
+    path = (
+        result.get("path", "mimo_qc.json")
+        if isinstance(result, dict)
+        else "mimo_qc.json"
+    )
+    stage_findings = [
+        finding
+        for finding in report.get("findings", [])
+        if isinstance(finding, dict) and finding.get("stage") == stage
+    ]
+    if status in {"failed", "unavailable"}:
+        reason = metadata.get("error") or "unavailable"
+        print(
+            f"[video-recap] ⚠ MiMo QC {stage}: {status} ({reason})；建议性检查不可用，继续流水线"
+        )
+        return
+    print(
+        f"[video-recap] ℹ MiMo QC {stage}: {status}, {len(stage_findings)} 条建议；详见 {path}"
+    )
+    for finding in stage_findings[:5]:
+        print(
+            f"[video-recap]   - {finding.get('message') or finding.get('decision_reason')}"
+        )
+
+
+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=bool(getattr(args, "mimo_qc_refresh", False)),
+            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