@oh-story/dsh 0.1.3 → 0.1.5

package/lib/video-recap/skills/video-script/scripts/review_runner.py

@@ -0,0 +1,200 @@
+"""Run narration review and write its advisory artifacts."""
+
+import argparse
+
+import json
+
+
+from pathlib import Path
+
+from lib import CONFIG, log, api_call
+
+from evidence_bundle import build_evidence_bundle
+from review_grounding import (
+    _load,
+    _load_cut_clip_spans,
+    _load_review_grounding,
+    remap_grounding_to_output_timeline,
+)
+from review_response import (
+    _append_warning_once,
+    _bundle_fingerprint,
+    _bundle_fingerprint_warning,
+    _chunk_evidence_bundle,
+    _load_review_research_context,
+    _merge_chunk_reviews,
+    _write_grounding_qc,
+    build_review_messages,
+    format_review_md,
+    parse_review_response,
+)
+
+EVIDENCE_CONTRACT_VERSION = 1
+
+COVERAGE_POLICY_VERSION = "coverage_policy_v1"
+
+
+def review_narration(work_dir, *, timeline="source", strict_evidence=False):
+    work_dir = Path(work_dir)
+    narration = _load(work_dir, "narration.json")
+    if narration is None:
+        raise SystemExit(f"缺少 {work_dir / 'narration.json'}；先写解说草稿再评审")
+    vlm_analysis, asr_result = _load_review_grounding(work_dir)
+    warnings = []
+    if timeline == "cut_output":
+        spans = _load_cut_clip_spans(work_dir)
+        if not spans:
+            msg = "cut_output review missing/stale clip_plan_validated.json; advisory fail-open, no strong OUTPUT-clock facts"
+            if strict_evidence:
+                raise SystemExit(msg)
+            warnings.append(msg)
+            vlm_analysis, asr_result = [], []
+        else:
+            vlm_analysis, asr_result = remap_grounding_to_output_timeline(
+                vlm_analysis, asr_result, spans
+            )
+    elif timeline != "source":
+        raise SystemExit(f"unknown review timeline: {timeline}")
+
+    bundle = build_evidence_bundle(
+        vlm_analysis,
+        asr_result,
+        narration,
+        timeline=timeline,
+        research=_load_review_research_context(work_dir),
+        warnings=warnings,
+    )
+    bundle_fp = _bundle_fingerprint(bundle)
+    fp_warning = _bundle_fingerprint_warning(bundle)
+    if fp_warning:
+        _append_warning_once(warnings, fp_warning)
+        _append_warning_once(bundle.setdefault("warnings", []), fp_warning)
+    chunk_reviews = []
+    chunks = _chunk_evidence_bundle(bundle)
+    for chunk in chunks:
+        messages = build_review_messages(
+            narration,
+            vlm_analysis,
+            asr_result,
+            work_dir=work_dir,
+            evidence_bundle=chunk,
+        )
+        resp = api_call(
+            {
+                "model": CONFIG.get("vlm_model", ""),
+                "messages": messages,
+                "max_tokens": 2000 if len(chunks) == 1 else 1600,
+                "temperature": 0,
+                "seed": 7 + int(chunk.get("chunk_index", 0)),
+            }
+        )
+        content = ""
+        try:
+            content = resp["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError):
+            log("评审 API 返回结构异常")
+        parsed = parse_review_response(content)
+        parsed["chunk_index"] = chunk.get("chunk_index", 0)
+        parsed["chunk_count"] = chunk.get("chunk_count", len(chunks))
+        chunk_reviews.append(parsed)
+    review = _merge_chunk_reviews(chunk_reviews)
+    if warnings:
+        review["warnings"] = list(warnings)
+    review["evidence_contract"] = {
+        "schema_version": EVIDENCE_CONTRACT_VERSION,
+        "timeline": timeline,
+        "clock": bundle.get("clock"),
+        "coverage_policy_version": COVERAGE_POLICY_VERSION,
+        "selected_ranges": bundle.get("coverage", {}).get("selected_ranges", []),
+        "evidence_bundle_fingerprint": bundle_fp,
+        "chunk_count": len(chunks),
+        "warnings": warnings,
+    }
+    _write_grounding_qc(work_dir, review, bundle, timeline=timeline)
+
+    (work_dir / "narration_review.json").write_text(
+        json.dumps(review, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    (work_dir / "narration_review.md").write_text(
+        format_review_md(review), encoding="utf-8"
+    )
+    n_err = sum(1 for f in review["findings"] if f["severity"] == "error")
+    log(
+        f"解说评审完成: {review['verdict']} | {len(review['findings'])} 条意见（error {n_err}）"
+    )
+    return review
+
+
+def _auto_timeline(work_dir):
+    """Default the grounding timeline so a manual `review.py --work-dir` matches what the
+    orchestrator does: cut_output when narration.json is in the cut OUTPUT timeline, else
+    source. Without this, reviewing a cut narration on the default 'source' timeline compares
+    OUTPUT-time narration against SOURCE-time evidence and floods false-positive 'hallucination'
+    findings (and the inverse flood for a legacy source-time narration mis-read as cut_output).
+
+    Detection is authoritative-first: the orchestrator records the run's edit_mode in
+    recap_run_manifest.json. In orchestrated cut mode narration.json is OUTPUT time; in full
+    mode it is SOURCE time. Trusting edit_mode is correct even when stale cut artifacts from a
+    prior run linger in a reused work_dir. Only when no manifest is present (standalone review
+    or a hand-built work_dir) do we fall back to artifact sniffing — and even then the legacy
+    legacy direct single-pass path writes a SOURCE-time narration.json alongside a separate
+    output-time narration_mapped.json, so its presence pins us back to source."""
+    work_dir = Path(work_dir)
+    manifest = work_dir / "recap_run_manifest.json"
+    if manifest.exists():
+        try:
+            mode = (
+                json.loads(manifest.read_text(encoding="utf-8"))
+                .get("settings", {})
+                .get("edit_mode")
+            )
+        except (ValueError, OSError):
+            mode = None
+        if mode == "cut":
+            return "cut_output"
+        if mode:  # "full" or any non-cut mode → narration.json is source time
+            return "source"
+    has_cut = (work_dir / "clip_plan_validated.json").exists() and (
+        work_dir / "edited_source.mp4"
+    ).exists()
+    if has_cut and not (work_dir / "narration_mapped.json").exists():
+        return "cut_output"
+    return "source"
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Review an agent-written narration.json for quality (LLM-as-judge)."
+    )
+    ap.add_argument("--work-dir", required=True)
+    ap.add_argument(
+        "--timeline",
+        choices=["source", "cut_output"],
+        default=None,
+        help="grounding timeline for narration.json; DEFAULT auto-detects cut_output when a "
+        "validated cut (clip_plan_validated.json + edited_source.mp4) is present, else source. "
+        "cut_output remaps source VLM/ASR to the cut output timeline via clip_plan_validated.json",
+    )
+    ap.add_argument(
+        "--strict-evidence",
+        action="store_true",
+        help="block instead of advisory fail-open when required cut-output evidence mapping is missing/stale",
+    )
+    args = ap.parse_args()
+    timeline = args.timeline or _auto_timeline(args.work_dir)
+    if args.timeline is None and timeline != "source":
+        log(f"评审 grounding 时间轴自动判定为 {timeline}（检测到已校验的剪辑产物）")
+    review = review_narration(
+        args.work_dir, timeline=timeline, strict_evidence=args.strict_evidence
+    )
+    print(
+        json.dumps(
+            {
+                "status": "reviewed",
+                "verdict": review["verdict"],
+                "findings": len(review["findings"]),
+                "review": str(Path(args.work_dir) / "narration_review.md"),
+            },
+            ensure_ascii=False,
+        )
+    )

package/lib/video-recap/skills/video-script/scripts/speech_ownership.py

@@ -0,0 +1,204 @@
+"""Load measured source-speech evidence and classify narration ownership."""
+
+import json
+import math
+from pathlib import Path
+
+from lib import CONFIG, stable_hash
+
+
+def _empty_evidence(mode):
+    return {
+        "anchors": [],
+        "speech_spans": [],
+        "quiet_windows": [],
+        "require_measured": mode == "cut_output",
+    }
+
+
+def _read_json(path):
+    try:
+        return json.loads(Path(path).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _timed_rows(payload, key):
+    rows = payload.get(key, []) if isinstance(payload, dict) else []
+    out = []
+    for row in rows if isinstance(rows, list) else []:
+        if not isinstance(row, dict):
+            continue
+        try:
+            start, end = float(row.get("start")), float(row.get("end"))
+        except (TypeError, ValueError):
+            continue
+        if math.isfinite(start) and math.isfinite(end) and end > start:
+            out.append({**row, "start": start, "end": end})
+    return out
+
+
+def _output_payload_is_current(payload, work_dir):
+    if not isinstance(payload, dict):
+        return False
+    if payload.get("schema_version") != 2 or payload.get("timeline") != "cut_output":
+        return False
+    plan = _read_json(Path(work_dir) / "clip_plan_validated.json")
+    return bool(
+        isinstance(plan, dict)
+        and payload.get("clip_plan_fingerprint") == stable_hash(plan)
+    )
+
+
+def load_source_sentence_evidence(work_dir, mode="full"):
+    """Load sentence boundaries plus speech/quiet spans on the narration clock."""
+    if work_dir is None:
+        return _empty_evidence(mode)
+    work_dir = Path(work_dir)
+    output_mode = mode in {"cut", "cut_output"}
+    path = work_dir / (
+        "speech_boundary_anchors_output.json"
+        if output_mode
+        else "speech_boundary_anchors.json"
+    )
+    payload = _read_json(path)
+    if mode == "cut_output" and not _output_payload_is_current(payload, work_dir):
+        return _empty_evidence(mode)
+    if not isinstance(payload, dict):
+        payload = {}
+
+    speech_spans = _timed_rows(payload, "speech_spans")
+    quiet_windows = _timed_rows(payload, "quiet_windows")
+    if not output_mode:
+        for name in ("asr_result.json", "asr_clean.json"):
+            raw = _read_json(work_dir / name)
+            if isinstance(raw, list):
+                candidate = {"speech_spans": raw}
+            elif isinstance(raw, dict):
+                candidate = {"speech_spans": raw.get("segments", [])}
+            else:
+                continue
+            speech_spans = _timed_rows(candidate, "speech_spans")
+            if speech_spans:
+                break
+        raw_quiet = _read_json(work_dir / "silence_periods.json")
+        candidate = {
+            "quiet_windows": [
+                row
+                for row in raw_quiet
+                if isinstance(row, dict) and not bool(row.get("has_speech", False))
+            ]
+        } if isinstance(raw_quiet, list) else {}
+        quiet_windows = _timed_rows(candidate, "quiet_windows")
+
+    anchors = []
+    for anchor in payload.get("sentence_anchors", []):
+        if not isinstance(anchor, dict) or anchor.get("confidence") not in {
+            "high",
+            "medium",
+        }:
+            continue
+        try:
+            when = float(anchor.get("time"))
+        except (TypeError, ValueError):
+            continue
+        if math.isfinite(when) and when >= 0:
+            anchors.append({**anchor, "time": round(when, 3)})
+    return {
+        "anchors": sorted(anchors, key=lambda item: item["time"]),
+        "speech_spans": speech_spans,
+        "quiet_windows": quiet_windows,
+        "require_measured": mode == "cut_output",
+    }
+
+
+def _merged_intervals(start, end, rows):
+    intervals = sorted(
+        (max(start, row["start"]), min(end, row["end"]))
+        for row in rows
+        if row["end"] > start and row["start"] < end
+    )
+    merged = []
+    for left, right in intervals:
+        if right <= left:
+            continue
+        if merged and left <= merged[-1][1]:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], right))
+        else:
+            merged.append((left, right))
+    return merged
+
+
+def _interval_overlap(start, end, rows):
+    return sum(right - left for left, right in _merged_intervals(start, end, rows))
+
+
+def _speech_overlap_excluding_quiet(start, end, speech, quiet):
+    speech_intervals = _merged_intervals(start, end, speech)
+    quiet_intervals = _merged_intervals(start, end, quiet)
+    overlap = sum(right - left for left, right in speech_intervals)
+    for speech_left, speech_right in speech_intervals:
+        overlap -= sum(
+            max(0.0, min(speech_right, quiet_right) - max(speech_left, quiet_left))
+            for quiet_left, quiet_right in quiet_intervals
+        )
+    return max(0.0, overlap)
+
+
+def segment_overlaps_source_speech(seg, evidence):
+    """Classify aggregate mix ownership across the complete narration interval."""
+    try:
+        start, end = float(seg.get("start")), float(seg.get("end"))
+    except (AttributeError, TypeError, ValueError):
+        return bool(getattr(seg, "get", lambda *_: True)("overlaps_speech", True))
+    duration = max(0.0, end - start)
+    quiet = evidence["quiet_windows"]
+    quiet_min = max(
+        0.3,
+        duration * float(CONFIG.get("quiet_overlap_min_ratio", 0.8) or 0.8),
+    )
+    speech = evidence["speech_spans"]
+    if speech:
+        return _speech_overlap_excluding_quiet(start, end, speech, quiet) > 0.05
+    if quiet and _interval_overlap(start, end, quiet) >= quiet_min:
+        return False
+    if evidence["anchors"] or evidence["require_measured"]:
+        return True
+    return bool(seg.get("overlaps_speech", True))
+
+
+def entry_overlaps_source_speech(seg, evidence, tolerance=0.05):
+    """Classify the entry instant; later quiet time cannot erase an unsafe start."""
+    try:
+        start = float(seg.get("start"))
+    except (AttributeError, TypeError, ValueError):
+        return True
+    if any(
+        row["start"] - tolerance <= start <= row["end"] + tolerance
+        for row in evidence["quiet_windows"]
+    ):
+        return False
+    if any(
+        row["start"] - tolerance <= start < row["end"] - tolerance
+        for row in evidence["speech_spans"]
+    ):
+        return True
+    if evidence["speech_spans"]:
+        return False
+    if evidence["anchors"] or evidence["require_measured"]:
+        return True
+    return bool(seg.get("overlaps_speech", True))
+
+
+def measure_narration_speech_ownership(narration, work_dir, mode="full"):
+    """Return narration copies with aggregate ownership derived from evidence."""
+    evidence = load_source_sentence_evidence(work_dir, mode=mode)
+    measured = []
+    for seg in narration if isinstance(narration, list) else []:
+        if not isinstance(seg, dict):
+            measured.append(seg)
+            continue
+        item = dict(seg)
+        item["overlaps_speech"] = segment_overlaps_source_speech(item, evidence)
+        measured.append(item)
+    return measured

package/lib/video-recap/skills/video-script/scripts/timeline_fusion.py

@@ -0,0 +1,199 @@
+"""Fuse scenes, ASR, and quiet windows for narration planning."""
+
+import importlib.util
+
+
+from pathlib import Path
+
+from lib import CONFIG
+
+
+from agent_text import _overlap_seconds, _recommended_char_budget
+from narration_lint import _validate_narration_budget
+
+try:
+    from deslop_qc import analyze_deslop_qc
+except ModuleNotFoundError:
+    _deslop_qc_path = Path(__file__).with_name("deslop_qc.py")
+    _deslop_qc_spec = importlib.util.spec_from_file_location(
+        "deslop_qc", _deslop_qc_path
+    )
+    if _deslop_qc_spec is None or _deslop_qc_spec.loader is None:
+        raise
+    _deslop_qc_module = importlib.util.module_from_spec(_deslop_qc_spec)
+    _deslop_qc_spec.loader.exec_module(_deslop_qc_module)
+    analyze_deslop_qc = _deslop_qc_module.analyze_deslop_qc
+
+
+def _align_narration_to_quiet(narration, scenes_analysis, silence_periods):
+    """Recompute overlaps_speech from real quiet windows; keep the agent's timing.
+
+    The dense continuous-bed design places narration ON the pictured beat over a
+    ducked original bed, so we no longer relocate segments into silence gaps. The
+    old shift moved voiceover up to 3s off the moment it was written for and could
+    silently blank a squeezed segment; both fought the design intent. We now only
+    correct the overlaps_speech flag that the ducking stage consumes, leaving the
+    agent's start/end (and text) intact.
+    """
+    if not silence_periods:
+        for n in narration:
+            n["overlaps_speech"] = True
+        return _validate_narration_budget(narration, scenes_analysis)
+
+    quiet_windows = [
+        qp for qp in silence_periods if _silence_window_is_usable_quiet(qp)
+    ]
+    quiet_ratio_min = float(CONFIG.get("quiet_overlap_min_ratio", 0.8) or 0.8)
+
+    # Run budget/dedup FIRST, then set the flag on the final (possibly merged) spans,
+    # so a dedup-merged beat's overlaps_speech reflects its extended timing, not its
+    # original shorter span (which the ducking stage in assemble.py would mis-duck).
+    aligned = _validate_narration_budget(narration, scenes_analysis)
+    for n in aligned:
+        try:
+            seg_start = float(n["start"])
+            seg_end = float(n["end"])
+        except (KeyError, TypeError, ValueError):
+            n["overlaps_speech"] = True
+            continue
+        seg_dur = max(0.0, seg_end - seg_start)
+        quiet_overlap = _quiet_overlap_seconds(seg_start, seg_end, quiet_windows)
+        n["overlaps_speech"] = quiet_overlap < max(0.3, seg_dur * quiet_ratio_min)
+
+    return aligned
+
+
+def _scene_asr_lines(asr_result, scene):
+    lines = []
+    for seg in asr_result or []:
+        try:
+            start = float(seg.get("start", 0))
+            end = float(seg.get("end", start))
+        except (TypeError, ValueError):
+            continue
+        if scene["start"] < end and scene["end"] > start:
+            text = str(seg.get("text", "")).strip()
+            if text:
+                lines.append(f"    [{start:.1f}-{end:.1f}] {text}")
+    return lines
+
+
+def _quiet_windows_for_scene(silence_periods, scene):
+    windows = []
+    for qp in silence_periods or []:
+        if not _silence_window_is_usable_quiet(qp):
+            continue
+        if qp["start"] < scene["end"] and qp["end"] > scene["start"]:
+            start = max(qp["start"], scene["start"])
+            end = min(qp["end"], scene["end"])
+            if end > start:
+                windows.append((start, end))
+    return windows
+
+
+def _silence_window_is_usable_quiet(qp):
+    if not isinstance(qp, dict):
+        return False
+    reason = str(qp.get("has_speech_reason", "")).lower()
+    granularity = str(qp.get("asr_granularity", "")).lower()
+    if reason in {
+        "coarse_asr_overlap_ignored",
+        "asr_overlap_low_confidence_quiet",
+        "coarse_asr_no_overlap",
+    }:
+        return True
+    if granularity == "coarse_grid" and qp.get("has_speech") is True:
+        return True
+    return not qp.get("has_speech", False)
+
+
+def _quiet_overlap_seconds(start, end, quiet_windows):
+    overlap_seconds = 0.0
+    for qw in quiet_windows:
+        try:
+            if isinstance(qw, dict):
+                q_start = float(qw.get("start", 0))
+                q_end = float(qw.get("end", q_start))
+            else:
+                q_start, q_end = qw
+                q_start = float(q_start)
+                q_end = float(q_end)
+        except (TypeError, ValueError):
+            continue
+        overlap_seconds += _overlap_seconds(start, end, q_start, q_end)
+    return overlap_seconds
+
+
+def _build_timeline_fusion(scenes, asr_segments, silence_periods):
+    """Fuse VLM scenes, ASR dialogue and quiet narration slots on one timeline."""
+    fusion = []
+    quiet_windows = [
+        w for w in silence_periods or [] if _silence_window_is_usable_quiet(w)
+    ]
+    for scene in scenes or []:
+        try:
+            start = float(scene.get("start", 0))
+            end = float(scene.get("end", start))
+        except (TypeError, ValueError):
+            continue
+        dialogue_segments = []
+        dialogue_overlap = 0.0
+        for seg in asr_segments or []:
+            if not isinstance(seg, dict):
+                continue
+            try:
+                seg_start = float(seg.get("start", 0))
+                seg_end = float(seg.get("end", seg_start))
+            except (TypeError, ValueError):
+                continue
+            overlap = _overlap_seconds(start, end, seg_start, seg_end)
+            if overlap <= 0:
+                continue
+            text = str(seg.get("text", "")).strip()
+            dialogue_overlap += overlap
+            dialogue_segments.append(
+                {
+                    "start": round(seg_start, 2),
+                    "end": round(seg_end, 2),
+                    "overlap_seconds": round(overlap, 2),
+                    "text": text,
+                }
+            )
+
+        narration_slots = []
+        for window in quiet_windows:
+            try:
+                w_start = float(window.get("start", 0))
+                w_end = float(window.get("end", w_start))
+            except (TypeError, ValueError):
+                continue
+            overlap = _overlap_seconds(start, end, w_start, w_end)
+            if overlap <= 0:
+                continue
+            slot_start = max(start, w_start)
+            slot_end = min(end, w_end)
+            narration_slots.append(
+                {
+                    "start": round(slot_start, 2),
+                    "end": round(slot_end, 2),
+                    "duration": round(slot_end - slot_start, 2),
+                    "char_budget": _recommended_char_budget(slot_start, slot_end),
+                }
+            )
+
+        fusion.append(
+            {
+                "scene_id": scene.get("scene_id"),
+                "time_range": [round(start, 2), round(end, 2)],
+                "visual_description": scene.get("description", ""),
+                "depth_analysis": scene.get("depth_analysis", ""),
+                "frame_facts": scene.get("frame_facts", {}),
+                "dialogue_segments": dialogue_segments,
+                "dialogue_overlap_seconds": round(dialogue_overlap, 2),
+                "narration_slots": narration_slots,
+                "recommended_mode": "quiet-slot"
+                if narration_slots and dialogue_overlap < (end - start) * 0.4
+                else "ducked-bed",
+            }
+        )
+    return fusion