@oh-story/dsh 0.1.9 → 0.1.11

package/lib/video-recap/skills/video-understanding/scripts/consolidate.py

@@ -9,18 +9,17 @@ Optional, synchronous, in-pipeline. Two independent LLM passes over the video's
     TEXT per segment index only; each segment's original start/end is re-attached here, so a
     cleanup pass can never shift the timing-bearing spans downstream chunking depends on.
 
-Both passes degrade gracefully (a chat-API failure logs and is skipped) and are idempotent
-(a fresh artifact is reused). Mirrors review.py's pure-seam + thin-driver shape so it is
+Both passes are idempotent (a fresh artifact is reused); a failure raises and the runner
+records it in consolidation.status.json. Mirrors review.py's pure-seam + thin-driver shape so it is
 unit-testable with a mocked api_call. NON-required: the pipeline runs unchanged without it.
 """
 
 import argparse
-import hashlib
 import json
 import re
 from pathlib import Path
 
-from lib import CONFIG, log, api_call
+from lib import CONFIG, log, api_call, file_identity, load_background_research
 from understanding_cache import _fresh
 
 # Shared tolerance for the per-segment span check. The brief-side gate inlines the SAME
@@ -59,9 +58,7 @@ INDEX_PROMPT = """你在根据逐场景画面分析、ASR对白、background_res
 def build_clean_messages(asr_result):
     lines = []
     for i, seg in enumerate(asr_result or []):
-        if not isinstance(seg, dict):
-            continue
-        lines.append(f"{i}. {str(seg.get('text', '')).strip()}")
+        lines.append(f"{i}. {seg['text'].strip()}")
     user = f"{CLEAN_PROMPT}\n\n## 逐段转写（共 {len(lines)} 段）\n" + "\n".join(lines)
     return [{"role": "user", "content": user}]
 
@@ -69,7 +66,7 @@ def build_clean_messages(asr_result):
 def parse_clean_response(text, asr_result):
     """Zip cleaned TEXT onto the original segments (start/end preserved by construction).
     Returns the original asr_result UNCHANGED on any parse / shape / count problem."""
-    base = [s for s in (asr_result or []) if isinstance(s, dict)]
+    base = list(asr_result or [])
     if not base:
         return asr_result
     data = _extract_json(text)
@@ -87,8 +84,8 @@ def parse_clean_response(text, asr_result):
     out = []
     for i, seg in enumerate(base):
         cleaned = by_index.get(i, {})
-        new_text = str(cleaned.get("text", "")).strip() or str(seg.get("text", ""))
-        merged = {"start": seg.get("start"), "end": seg.get("end"), "text": new_text}
+        new_text = str(cleaned.get("text", "")).strip() or seg["text"]
+        merged = {"start": seg["start"], "end": seg["end"], "text": new_text}
         speaker = str(cleaned.get("speaker", "")).strip()
         if speaker:
             merged["speaker"] = speaker
@@ -96,17 +93,10 @@ def parse_clean_response(text, asr_result):
     return out
 
 
-def _json_md5_file(work_dir, name):
+def _input_identity(work_dir, name):
+    """{size, mtime_ns} of one input artifact, or None when it is absent."""
     path = Path(work_dir) / name
-    return hashlib.md5(path.read_bytes()).hexdigest() if path.exists() else ""
-
-
-def _asr_clean_source_md5(work_dir):
-    return _json_md5_file(work_dir, "asr_clean.json")
-
-
-def _research_source_md5(work_dir):
-    return _json_md5_file(work_dir, "background_research.json")
+    return file_identity(path) if path.exists() else None
 
 
 def _research_glossary_from_context(background_research):
@@ -148,23 +138,22 @@ def _research_glossary_from_context(background_research):
     return glossary
 
 
+def _dialogue_source(asr_result, asr_clean):
+    """asr_clean.json segments when present (consolidate's own output), else raw asr_result rows."""
+    return asr_clean["segments"] if asr_clean else (asr_result or [])
+
+
 def _dialogue_segments_for_index(asr_result=None, asr_clean=None):
-    clean_segments = (
-        (asr_clean or {}).get("segments") if isinstance(asr_clean, dict) else None
-    )
-    source = clean_segments if isinstance(clean_segments, list) else (asr_result or [])
     out = []
-    for i, seg in enumerate(source or []):
-        if not isinstance(seg, dict):
-            continue
-        text = str(seg.get("text", "")).strip()
+    for i, seg in enumerate(_dialogue_source(asr_result, asr_clean)):
+        text = seg["text"].strip()
         if not text:
             continue
         out.append(
             {
                 "id": f"asr:{i}",
-                "start": seg.get("start"),
-                "end": seg.get("end"),
+                "start": seg["start"],
+                "end": seg["end"],
                 "text": text,
             }
         )
@@ -280,44 +269,34 @@ def build_index_messages(
 ):
     lines = []
     for i, scene in enumerate(vlm_analysis or []):
-        if not isinstance(scene, dict):
-            continue
-        sid = scene.get("scene_id", i)
-        start = float(scene.get("start", 0) or 0)
-        end = float(scene.get("end", 0) or 0)
-        desc = str(scene.get("description", "")).strip().replace("\n", " ")
-        facts = scene.get("frame_facts")
+        sid = scene["scene_id"]
+        start = float(scene["start"])
+        end = float(scene["end"])
+        desc = scene["description"].strip().replace("\n", " ")
+        facts = scene.get("frame_facts")  # vlm.py only writes the key when non-empty
         fact_txt = ""
-        if isinstance(facts, dict) and facts:
+        if facts:
             actions = []
 
             def fact_key(x):
+                # timestamps are regex-captured from the VLM reply ("[\d.]+"), so "1.2.3" is possible
                 try:
                     return (0, float(x))
-                except (TypeError, ValueError):
+                except ValueError:
                     return (1, str(x))
 
             for ts in sorted(facts.keys(), key=fact_key):
-                vals = facts[ts]
-                actions.extend(vals if isinstance(vals, list) else [str(vals)])
+                actions.extend(facts[ts])
             if actions:
                 fact_txt = " | 帧实: " + "；".join(a for a in actions[:6] if a)
         lines.append(f"[visual:{i} 场景{sid} {start:.0f}-{end:.0f}s] {desc}{fact_txt}")
     asr_lines = []
-    clean_segments = (
-        (asr_clean or {}).get("segments") if isinstance(asr_clean, dict) else None
-    )
-    source_asr = (
-        clean_segments if isinstance(clean_segments, list) else (asr_result or [])
-    )
-    for i, seg in enumerate(source_asr or []):
-        if not isinstance(seg, dict):
-            continue
-        text = str(seg.get("text", "")).strip()
+    for i, seg in enumerate(_dialogue_source(asr_result, asr_clean)):
+        text = seg["text"].strip()
         if not text:
             continue
         asr_lines.append(
-            f"[asr:{i} {float(seg.get('start', 0) or 0):.0f}-{float(seg.get('end', 0) or 0):.0f}s] {text}"
+            f"[asr:{i} {float(seg['start']):.0f}-{float(seg['end']):.0f}s] {text}"
         )
     glossary = _research_glossary_from_context(background_research)
     glossary_lines = []
@@ -432,44 +411,31 @@ def _extract_json(text):
         return None
 
 
-def _asr_source_md5(work_dir):
-    """Provenance: md5 of the on-disk asr_result.json BYTES (writer + reader hash the same thing)."""
-    path = Path(work_dir) / "asr_result.json"
-    return hashlib.md5(path.read_bytes()).hexdigest() if path.exists() else ""
-
-
-def _vlm_source_md5(work_dir):
-    """Provenance: md5 of the on-disk vlm_analysis.json bytes."""
-    path = Path(work_dir) / "vlm_analysis.json"
-    return hashlib.md5(path.read_bytes()).hexdigest() if path.exists() else ""
-
-
 def _index_meta_path(work_dir):
     return Path(work_dir) / "understanding_index.json.meta.json"
 
 
-def _prompt_fingerprint(prompt):
-    return hashlib.md5(str(prompt or "").encode("utf-8")).hexdigest()
+def _index_meta(work_dir, vlm_analysis):
+    """Provenance of understanding_index.json: `source` (vlm_analysis.json identity) + `model`
+    are what brief consumers check; the other inputs and the prompt text are the producer's
+    own rebuild gate."""
+    return {
+        "schema_version": INDEX_SCHEMA_VERSION,
+        "source": _input_identity(work_dir, "vlm_analysis.json"),
+        "inputs": {
+            "asr_result": _input_identity(work_dir, "asr_result.json"),
+            "asr_clean": _input_identity(work_dir, "asr_clean.json"),
+            "background_research": _input_identity(work_dir, "background_research.json"),
+        },
+        "scene_count": len([s for s in (vlm_analysis or []) if isinstance(s, dict)]),
+        "model": CONFIG["vlm_model"],
+        "prompt": INDEX_PROMPT,
+    }
 
 
 def _write_index_meta(work_dir, vlm_analysis):
     _index_meta_path(work_dir).write_text(
-        json.dumps(
-            {
-                "schema_version": INDEX_SCHEMA_VERSION,
-                "source_md5": _vlm_source_md5(work_dir),
-                "asr_md5": _asr_source_md5(work_dir),
-                "asr_clean_md5": _asr_clean_source_md5(work_dir),
-                "research_md5": _research_source_md5(work_dir),
-                "scene_count": len(
-                    [s for s in (vlm_analysis or []) if isinstance(s, dict)]
-                ),
-                "model": CONFIG.get("vlm_model", ""),
-                "prompt_md5": _prompt_fingerprint(INDEX_PROMPT),
-            },
-            ensure_ascii=False,
-            indent=2,
-        ),
+        json.dumps(_index_meta(work_dir, vlm_analysis), ensure_ascii=False, indent=2),
         encoding="utf-8",
     )
 
@@ -482,31 +448,18 @@ def _index_cache_matches(work_dir, vlm_analysis):
         meta = json.loads(meta_path.read_text(encoding="utf-8"))
     except (json.JSONDecodeError, OSError):
         return False
-    return (
-        isinstance(meta, dict)
-        and meta.get("schema_version") == INDEX_SCHEMA_VERSION
-        and meta.get("source_md5") == _vlm_source_md5(work_dir)
-        and meta.get("asr_md5", "") == _asr_source_md5(work_dir)
-        and meta.get("asr_clean_md5", "") == _asr_clean_source_md5(work_dir)
-        and meta.get("research_md5", "") == _research_source_md5(work_dir)
-        and meta.get("scene_count")
-        == len([s for s in (vlm_analysis or []) if isinstance(s, dict)])
-        and meta.get("model") == CONFIG.get("vlm_model", "")
-        and meta.get("prompt_md5") == _prompt_fingerprint(INDEX_PROMPT)
-    )
+    return meta == _index_meta(work_dir, vlm_analysis)
 
 
 # ── thin drivers (I/O + api_call) ─────────────────────────────────────────────
 
 
 def _load(work_dir, name):
+    """Read one of this skill's own JSON artifacts: absent → None, corrupt → raise."""
     path = Path(work_dir) / name
     if not path.exists():
         return None
-    try:
-        return json.loads(path.read_text(encoding="utf-8"))
-    except (ValueError, OSError):
-        return None
+    return json.loads(path.read_text(encoding="utf-8"))
 
 
 def consolidate_transcript(work_dir):
@@ -519,16 +472,16 @@ def consolidate_transcript(work_dir):
     if _fresh(out_path, work_dir / "asr_result.json"):
         existing = _load(work_dir, "asr_clean.json") or {}
         if (
-            existing.get("source_md5") == _asr_source_md5(work_dir)
-            and existing.get("model") == CONFIG.get("vlm_model", "")
-            and existing.get("prompt_md5") == _prompt_fingerprint(CLEAN_PROMPT)
+            existing.get("source") == _input_identity(work_dir, "asr_result.json")
+            and existing.get("model") == CONFIG["vlm_model"]
+            and existing.get("prompt") == CLEAN_PROMPT
             and existing.get("postprocess_version") == ASR_CLEAN_POSTPROCESS_VERSION
         ):
             log("consolidate(asr): asr_clean.json 已最新，跳过")
             return existing
     resp = api_call(
         {
-            "model": CONFIG.get("vlm_model", ""),
+            "model": CONFIG["vlm_model"],
             "messages": build_clean_messages(asr_result),
             "max_tokens": 4000,
             "temperature": 0.2,
@@ -537,9 +490,9 @@ def consolidate_transcript(work_dir):
     content = _response_text(resp)
     segments = parse_clean_response(content, asr_result)
     payload = {
-        "source_md5": _asr_source_md5(work_dir),
-        "model": CONFIG.get("vlm_model", ""),
-        "prompt_md5": _prompt_fingerprint(CLEAN_PROMPT),
+        "source": _input_identity(work_dir, "asr_result.json"),
+        "model": CONFIG["vlm_model"],
+        "prompt": CLEAN_PROMPT,
         "postprocess_version": ASR_CLEAN_POSTPROCESS_VERSION,
         "segments": segments,
     }
@@ -564,10 +517,10 @@ def consolidate_index(work_dir):
         return _load(work_dir, "understanding_index.json")
     asr_result = _load(work_dir, "asr_result.json") or []
     asr_clean = _load(work_dir, "asr_clean.json") or {}
-    background_research = _load(work_dir, "background_research.json") or {}
+    background_research = load_background_research(work_dir)
     resp = api_call(
         {
-            "model": CONFIG.get("vlm_model", ""),
+            "model": CONFIG["vlm_model"],
             "messages": build_index_messages(
                 vlm_analysis,
                 asr_result=asr_result,
@@ -599,18 +552,14 @@ def consolidate_index(work_dir):
 
 
 def consolidate(work_dir, do_asr=False, do_index=True):
-    """Default = index-only (Pass B, zero timing risk). Pass A (asr) is opt-in."""
+    """Default = index-only (Pass B, zero timing risk). Pass A (asr) is opt-in.
+
+    Failures propagate; understanding_runner catches them and writes the "failed" status."""
     result = {}
     if do_asr:
-        try:
-            result["asr_clean"] = consolidate_transcript(work_dir)
-        except Exception as e:
-            log(f"consolidate(asr) 跳过（忽略）: {e}")
+        result["asr_clean"] = consolidate_transcript(work_dir)
     if do_index:
-        try:
-            result["index"] = consolidate_index(work_dir)
-        except Exception as e:
-            log(f"consolidate(index) 跳过（忽略）: {e}")
+        result["index"] = consolidate_index(work_dir)
     return result
 
 

package/lib/video-recap/skills/video-understanding/scripts/detect.py

@@ -6,7 +6,7 @@ from concurrent.futures import ThreadPoolExecutor
 from pathlib import Path
 
 from lib import CONFIG
-from lib import log, run_cmd, get_video_duration, file_fingerprint
+from lib import log, run_cmd, get_video_duration, file_identity
 
 # ── Step 2: 场景检测 ──────────────────────────────────────────────────
 
@@ -48,10 +48,10 @@ def detect_scenes(video_path, work_dir, threshold=None):
 
     # 先过滤黑/白帧过渡场景，再合并短场景
     # （合并会保留短场景的 start，若黑场被并入长场景，单点采样会误删整段，故顺序在前）
-    if CONFIG.get("scene_junk_filter", True):
+    if CONFIG["scene_junk_filter"]:
         scenes = _filter_junk_scenes(scenes, video_path)
     # 合并短场景（< 3s 合并到相邻场景）
-    scenes = _merge_short_scenes(scenes, min_duration=CONFIG.get("scene_merge_min", 4.0))
+    scenes = _merge_short_scenes(scenes, min_duration=CONFIG["scene_merge_min"])
 
     # 保存
     scenes_file = work_dir / "scenes.json"
@@ -115,9 +115,9 @@ def _sample_frame_luma(video_path, timestamp, sample_size=64):
 
 def _is_junk_scene(video_path, timestamp, threshold_dark=None, threshold_bright=None):
     """Return True for near-black or near-white scene-start frames."""
-    threshold_dark = CONFIG.get("scene_junk_dark_luma", 8.0) if threshold_dark is None else threshold_dark
-    threshold_bright = CONFIG.get("scene_junk_bright_luma", 245.0) if threshold_bright is None else threshold_bright
-    pixel_ratio = min(1.0, max(0.0, float(CONFIG.get("scene_junk_pixel_ratio", 0.995))))
+    threshold_dark = CONFIG["scene_junk_dark_luma"] if threshold_dark is None else threshold_dark
+    threshold_bright = CONFIG["scene_junk_bright_luma"] if threshold_bright is None else threshold_bright
+    pixel_ratio = min(1.0, float(CONFIG["scene_junk_pixel_ratio"]))
     try:
         lumas = _sample_frame_luma(video_path, timestamp)
     except Exception as exc:
@@ -157,7 +157,7 @@ def _filter_junk_scenes(scenes, video_path):
     # 每个探点都是一次 ffmpeg 进程（seek + 解一帧），一部 30 分钟片有几百个场景，串行下来
     # 光进程启动就要几十秒。按场景并行：每个 worker 内部仍然短路，所以既保留了「多数场景只
     # 探一次」，又把进程启动开销摊平。判定逻辑与探点完全不变。
-    workers = max(1, int(CONFIG.get("scene_junk_workers", 8) or 8))
+    workers = int(CONFIG["scene_junk_workers"])
     with ThreadPoolExecutor(max_workers=min(workers, len(scenes))) as executor:
         verdicts = list(executor.map(lambda s: _scene_is_junk(s, video_path), scenes))
     filtered = []
@@ -203,7 +203,7 @@ def annotate_quiet_windows_with_asr(periods, asr_result=None, *, video_duration=
     Coarse grid ASR (large synthetic windows from chunking) must not turn every quiet
     window into speech. The return value is (annotated_periods, qc). Inputs are copied.
     """
-    out = [dict(p) for p in (periods or []) if isinstance(p, dict)]
+    out = [dict(p) for p in (periods or [])]
     qc = {"coarse_asr_windows": 0, "low_confidence_speech_flags": 0, "asr_granularity": "none"}
     for qp in out:
         qp.setdefault("speech_overlap_ratio", 0.0)
@@ -216,20 +216,15 @@ def annotate_quiet_windows_with_asr(periods, asr_result=None, *, video_duration=
 
     valid_segments = []
     for seg in asr_result:
-        if not isinstance(seg, dict):
-            continue
-        try:
-            ss, se = float(seg.get("start", 0)), float(seg.get("end", 0))
-        except (TypeError, ValueError):
-            continue
+        ss, se = float(seg["start"]), float(seg["end"])
         if se > ss:
             valid_segments.append((ss, se))
     asr_coverage = sum(se - ss for ss, se in valid_segments)
     avg_seg_dur = asr_coverage / len(valid_segments) if valid_segments else 0
     if video_duration is None:
-        ends = [float(p.get("end", 0) or 0) for p in out] + [se for _, se in valid_segments]
+        ends = [float(p["end"]) for p in out] + [se for _, se in valid_segments]
         video_duration = max(ends or [0.0])
-    configured = float(configured_segment_seconds if configured_segment_seconds is not None else (CONFIG.get("asr_segment_seconds", 30) or 30))
+    configured = float(configured_segment_seconds if configured_segment_seconds is not None else CONFIG["asr_segment_seconds"])
     coarse_asr = (
         (len(valid_segments) <= 5 and asr_coverage > float(video_duration) * 0.8) or
         asr_coverage > float(video_duration) * 1.5 or
@@ -243,7 +238,7 @@ def annotate_quiet_windows_with_asr(periods, asr_result=None, *, video_duration=
         overlap_seconds = 0.0
         for ss, se in valid_segments:
             overlap_seconds += max(0.0, min(float(qp["end"]), se) - max(float(qp["start"]), ss))
-        ratio = overlap_seconds / max(0.001, float(qp.get("duration", 0.0) or 0.0))
+        ratio = overlap_seconds / max(0.001, float(qp["duration"]))
         qp["asr_overlap_seconds"] = round(overlap_seconds, 3)
         qp["speech_overlap_ratio"] = round(ratio, 4)
         qp["asr_granularity"] = granularity
@@ -333,7 +328,7 @@ def detect_silence_periods(video_path, work_dir, asr_result=None):
                             "duration": round(total_dur - dur_start, 2)})
 
     # 合并相邻静音段（间隔 < merge_gap 的合并为一个大窗口）
-    merge_gap = CONFIG.get("silence_merge_gap", 0.5)
+    merge_gap = CONFIG["silence_merge_gap"]
     merged = []
     for rp in sorted(raw_periods, key=lambda x: x["start"]):
         if merged and rp["start"] - merged[-1]["end"] < merge_gap:
@@ -352,7 +347,7 @@ def detect_silence_periods(video_path, work_dir, asr_result=None):
         periods,
         asr_result,
         video_duration=get_video_duration(str(audio_path)) if asr_result else None,
-        configured_segment_seconds=CONFIG.get("asr_segment_seconds", 30),
+        configured_segment_seconds=CONFIG["asr_segment_seconds"],
     )
 
     (work_dir / "silence_periods.qc.json").write_text(
@@ -368,12 +363,6 @@ def detect_silence_periods(video_path, work_dir, asr_result=None):
     return periods
 
 
-def _asr_segments(asr_result):
-    if isinstance(asr_result, dict):
-        asr_result = asr_result.get("segments", [])
-    return [item for item in (asr_result or []) if isinstance(item, dict)]
-
-
 def detect_speech_boundary_anchors(work_dir, asr_result):
     """Write sentence-end entry anchors by aligning ASR punctuation to short pauses.
 
@@ -385,14 +374,14 @@ def detect_speech_boundary_anchors(work_dir, asr_result):
     work_dir = Path(work_dir)
     audio_path = work_dir / "audio.wav"
     out_path = work_dir / "speech_boundary_anchors.json"
-    segments = _asr_segments(asr_result)
+    segments = list(asr_result or [])
     report = {
         "schema_version": 1,
         "artifact": "speech_boundary_anchors.json",
         "status": "completed",
         "detector": {
-            "noise_threshold": CONFIG.get("source_boundary_noise_threshold", "-18dB"),
-            "min_pause_seconds": float(CONFIG.get("source_boundary_min_pause", 0.12)),
+            "noise_threshold": CONFIG["source_boundary_noise_threshold"],
+            "min_pause_seconds": float(CONFIG["source_boundary_min_pause"]),
             "alignment": "terminal_punctuation_to_nearest_acoustic_pause",
         },
         "sentence_anchors": [],
@@ -408,8 +397,8 @@ def detect_speech_boundary_anchors(work_dir, asr_result):
         "ffmpeg", "-hide_banner", "-nostats", "-i", str(audio_path),
         "-af", (
             "silencedetect="
-            f"noise={CONFIG.get('source_boundary_noise_threshold', '-18dB')}:"
-            f"d={float(CONFIG.get('source_boundary_min_pause', 0.12))}"
+            f"noise={CONFIG['source_boundary_noise_threshold']}:"
+            f"d={float(CONFIG['source_boundary_min_pause'])}"
         ),
         "-f", "null", "-",
     ], timeout=120)
@@ -434,16 +423,13 @@ def detect_speech_boundary_anchors(work_dir, asr_result):
         })
     report["acoustic_pauses"] = pauses
 
-    max_error = float(CONFIG.get("source_boundary_max_alignment_error", 2.1))
+    max_error = float(CONFIG["source_boundary_max_alignment_error"])
     used = set()
     anchors = []
     for asr_index, segment in enumerate(segments):
-        try:
-            seg_start = float(segment.get("start"))
-            seg_end = float(segment.get("end"))
-        except (TypeError, ValueError):
-            continue
-        text = str(segment.get("text") or "").strip()
+        seg_start = float(segment["start"])
+        seg_end = float(segment["end"])
+        text = segment["text"].strip()
         if seg_end <= seg_start or not text:
             continue
         last_midpoint = seg_start - 1e-6
@@ -496,17 +482,22 @@ def _audio_cache_matches(audio_path, video_path):
     except (OSError, ValueError, TypeError):
         return False
     try:
-        expected = file_fingerprint(video_path)
+        expected = file_identity(video_path)
     except OSError:
         return False
-    return meta.get("source_video_fingerprint") == expected
+    return (
+        isinstance(meta, dict)
+        and meta.get("source_video") == str(Path(video_path).resolve())
+        and meta.get("source_video_identity") == expected
+    )
 
 
 def _write_audio_meta(work_dir, video_path):
     _audio_meta_path(work_dir).write_text(
         json.dumps({
             "schema_version": 1,
-            "source_video_fingerprint": file_fingerprint(video_path),
+            "source_video": str(Path(video_path).resolve()),
+            "source_video_identity": file_identity(video_path),
             "audio": "audio.wav",
         }, ensure_ascii=False, indent=2),
         encoding="utf-8",