@oh-story/dsh 0.1.9 → 0.1.11

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

@@ -4,7 +4,8 @@ import json
 
 from pathlib import Path
 
-from lib import CONFIG, log
+from lib import CONFIG, log, load_background_research
+from asr_timing_evidence import asr_evidence_summary_for_brief
 
 
 from detect import detect_speech_boundary_anchors
@@ -35,14 +36,8 @@ def _research_context(work_dir):
     and read scenes with plot knowledge instead of labelling everyone "黑衣男子".
     Returns "" when no usable research file is present, so behaviour is unchanged.
     """
-    path = Path(work_dir) / "background_research.json"
-    if not path.exists():
-        return ""
-    try:
-        data = json.loads(path.read_text(encoding="utf-8"))
-    except (json.JSONDecodeError, OSError):
-        return ""
-    if not isinstance(data, dict):
+    data = load_background_research(work_dir)
+    if not data:
         return ""
     parts = []
     for key in ("synopsis", "episode_context", "worldbuilding"):
@@ -124,38 +119,16 @@ def _load_understanding_artifacts_for_brief(work_dir):
     Material-library restores are allowed to reuse expensive analysis artifacts,
     but cut pass 2 must still rebuild `agent_narration_brief.md` against the
     rendered OUTPUT timeline. This helper deliberately performs no extraction,
-    ASR, VLM, or external API calls; it only reads already-present JSON.
+    ASR, VLM, or external API calls; it only reads already-present JSON. An absent
+    artifact contributes [] (the brief documents the thin substrate); a corrupt one raises.
     """
     work_dir = Path(work_dir)
-    scenes = []
-    for name in ("vlm_analysis.json", "scenes.json"):
+
+    def _own(name):
         path = work_dir / name
-        if not path.exists():
-            continue
-        try:
-            data = _load_json(path)
-        except (OSError, ValueError, TypeError):
-            continue
-        if isinstance(data, list):
-            scenes = data
-            break
-    asr_result = []
-    if (work_dir / "asr_result.json").exists():
-        try:
-            data = _load_json(work_dir / "asr_result.json")
-        except (OSError, ValueError, TypeError):
-            data = []
-        if isinstance(data, list):
-            asr_result = data
-    silence_periods = []
-    if (work_dir / "silence_periods.json").exists():
-        try:
-            data = _load_json(work_dir / "silence_periods.json")
-        except (OSError, ValueError, TypeError):
-            data = []
-        if isinstance(data, list):
-            silence_periods = data
-    return scenes, asr_result, silence_periods
+        return _load_json(path) if path.exists() else []
+
+    return _own("vlm_analysis.json"), _own("asr_result.json"), _own("silence_periods.json")
 
 
 def _write_brief_from_existing_artifacts(video, work_dir, args, video_duration):
@@ -166,7 +139,7 @@ def _write_brief_from_existing_artifacts(video, work_dir, args, video_duration):
     if not (Path(work_dir) / "speech_boundary_anchors.json").exists():
         detect_speech_boundary_anchors(work_dir, asr_result)
     overview_path = Path(work_dir) / "mimo_video_overview.json"
-    if CONFIG.get("mimo_video_overview", False):
+    if CONFIG["mimo_video_overview"]:
         scenes = _merge_overview_into_scenes(scenes, overview_path)
 
     source_storyboard = None
@@ -193,8 +166,9 @@ def _write_brief_from_existing_artifacts(video, work_dir, args, video_duration):
         video_duration,
         work_dir,
         args.style,
-        mimo_overview_enabled=CONFIG.get("mimo_video_overview", False),
+        mimo_overview_enabled=CONFIG["mimo_video_overview"],
         mimo_overview_video_path=video,
+        asr_evidence=asr_evidence_summary_for_brief(work_dir, video),
     )
     _prepend_storyboard_brief_header(
         brief_path, source_storyboard, edited_storyboard, cut_mode=cut_mode

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

@@ -1,13 +1,12 @@
 """Own understanding-stage cache keys, provenance, and statuses."""
 
-import hashlib
-
 import json
 
 from pathlib import Path
 
+from asr_timing_evidence import EVIDENCE_FILENAME, validate_asr_timing_evidence
 from extract import FRAME_TIME_CONVENTION_VERSION
-from lib import CONFIG, log, file_fingerprint, load_prompt
+from lib import CONFIG, log, file_identity, load_prompt
 
 
 from vlm import (
@@ -34,14 +33,23 @@ def _load_json(path):
     return json.loads(Path(path).read_text(encoding="utf-8"))
 
 
-def _artifact_fingerprint(path):
+def _video_input(video_path):
+    """The source video as a cache input: resolved path plus {size, mtime_ns}, so two
+    different files written in the same timestamp tick never share a stage output."""
+    return {"path": str(Path(video_path).resolve()), **file_identity(video_path)}
+
+
+def _artifact_identity(path):
+    """{size, mtime_ns} of an input artifact, or None when it does not exist."""
     path = Path(path)
-    return file_fingerprint(path) if path.exists() else None
+    return file_identity(path) if path.exists() else None
 
 
 def _stage_cache_valid(artifact_path, expected_meta):
+    """A stage output is reusable when it exists, is non-empty, its sidecar equals the
+    expected inputs/settings dict, and the output itself is the one the sidecar recorded."""
     artifact_path = Path(artifact_path)
-    if not artifact_path.exists():
+    if not artifact_path.exists() or artifact_path.stat().st_size == 0:
         return False
     meta_path = _artifact_meta_path(artifact_path)
     if not meta_path.exists():
@@ -50,18 +58,17 @@ def _stage_cache_valid(artifact_path, expected_meta):
         meta = _load_json(meta_path)
     except (OSError, ValueError, TypeError):
         return False
-    recorded = meta.get("artifact_fingerprint") if isinstance(meta, dict) else None
-    if not recorded or recorded != _artifact_fingerprint(artifact_path):
+    if not isinstance(meta, dict) or meta.get("artifact") != file_identity(artifact_path):
         return False
     expected = dict(expected_meta)
-    expected["artifact_fingerprint"] = recorded
+    expected["artifact"] = meta["artifact"]
     return meta == expected
 
 
 def _write_stage_meta(artifact_path, meta):
     meta_path = _artifact_meta_path(artifact_path)
     payload = dict(meta)
-    payload["artifact_fingerprint"] = _artifact_fingerprint(artifact_path)
+    payload["artifact"] = _artifact_identity(artifact_path)
     meta_path.write_text(
         json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8"
     )
@@ -93,7 +100,7 @@ def _write_mimo_overview_status(
         "mimo_video_overview.status.json",
         {
             "stage": "mimo_video_overview",
-            "enabled": bool(CONFIG.get("mimo_video_overview", False))
+            "enabled": bool(CONFIG["mimo_video_overview"])
             if enabled is None
             else bool(enabled),
             "status": status,
@@ -116,23 +123,19 @@ def _merge_overview_into_scenes(scenes, overview_path):
     `frame_facts` is untouched, `assess_understanding_substrate` (which grades on frame_facts +
     ASR) cannot regress; richer descriptions can only help.
     """
-    overview = _load_json(overview_path) if Path(overview_path).exists() else None
-    if not isinstance(overview, dict):
+    if not Path(overview_path).exists():
         return scenes
+    overview = _load_json(overview_path)
     by_scene = {}
-    for chunk in overview.get("chunks") or []:
-        if not isinstance(chunk, dict):
-            continue
-        content = str(chunk.get("content", "")).strip()
-        if content and _is_mimo_chunk_usable(content):
-            by_scene.setdefault(chunk.get("scene_id"), []).append(content)
+    for chunk in overview["chunks"]:
+        content = chunk["content"].strip()
+        if _is_mimo_chunk_usable(content):
+            by_scene.setdefault(chunk["scene_id"], []).append(content)
     if not by_scene:
         return scenes
     enriched = 0
-    for scene in scenes or []:
-        if not isinstance(scene, dict):
-            continue
-        contents = by_scene.get(scene.get("scene_id"))
+    for scene in scenes:
+        contents = by_scene.get(scene["scene_id"])
         if not contents:
             continue
         scene.setdefault("frame_description", scene.get("description", ""))
@@ -184,7 +187,7 @@ def _scene_cache_payload(video_path):
     return {
         "schema_version": 1,
         "stage": "scenes",
-        "source_video_fingerprint": file_fingerprint(video_path),
+        "inputs": {"video": _video_input(video_path)},
         "settings": {
             "scene_threshold": CONFIG.get("scene_threshold"),
             "scene_junk_filter": CONFIG.get("scene_junk_filter"),
@@ -200,7 +203,7 @@ def _asr_cache_payload(video_path, *, skip_asr=False):
     return {
         "schema_version": 1,
         "stage": "asr",
-        "source_video_fingerprint": file_fingerprint(video_path),
+        "inputs": {"video": _video_input(video_path)},
         "settings": {
             "skip_asr": bool(skip_asr),
             "mimo_asr_api_key_present": bool(CONFIG.get("mimo_asr_api_key")),
@@ -213,12 +216,34 @@ def _asr_cache_payload(video_path, *, skip_asr=False):
     }
 
 
+def _asr_cache_state(artifact_path, expected_meta, video_path):
+    """Classify an ASR cache without upgrading stale evidence into new authority."""
+    artifact_path = Path(artifact_path)
+    if not _stage_cache_valid(artifact_path, expected_meta):
+        return "MISS"
+    evidence_path = artifact_path.parent / EVIDENCE_FILENAME
+    if not evidence_path.exists():
+        return "LEGACY_UNVERIFIED"
+    if validate_asr_timing_evidence(evidence_path, video_path, artifact_path):
+        evidence = _load_json(evidence_path)
+        if evidence.get("status") == "LEGACY_UNVERIFIED":
+            return "LEGACY_UNVERIFIED"
+        # An all-empty transcription is an unexplained outcome, not proven silence; treating it
+        # as fresh would make one bad run a permanent cache hit.
+        if evidence.get("status") in {"UNAVAILABLE_NO_DURATION", "EMPTY_UNKNOWN"}:
+            return "MISS"
+        return "FRESH"
+    return "MISS"
+
+
 def _silence_cache_payload(video_path, asr_json):
     return {
         "schema_version": 1,
         "stage": "silence",
-        "source_video_fingerprint": file_fingerprint(video_path),
-        "asr_result_fingerprint": _artifact_fingerprint(asr_json),
+        "inputs": {
+            "video": _video_input(video_path),
+            "asr_result": _artifact_identity(asr_json),
+        },
         "asr_meta": _load_json(_artifact_meta_path(asr_json))
         if _artifact_meta_path(asr_json).exists()
         else None,
@@ -238,7 +263,8 @@ def _silence_cache_payload(video_path, asr_json):
     }
 
 
-def _vlm_prompt_fingerprint():
+def _vlm_prompt_payload():
+    """The exact prompt/context text the VLM stage sends; compared by equality."""
     prompt = load_prompt("VLM_DEPTH_PROMPT")
     if not prompt:
         prompt = (
@@ -249,33 +275,28 @@ def _vlm_prompt_fingerprint():
     context = CONFIG.get("context_info", "")
     if context:
         prompt = f"已知信息：{context}\n\n{prompt}"
-    return {
-        "prompt_text_fingerprint": _text_fingerprint(prompt),
-        "context_info_fingerprint": _text_fingerprint(context),
-    }
-
-
-def _text_fingerprint(value):
-    return hashlib.md5(str(value or "").encode("utf-8")).hexdigest()
+    return {"prompt_text": prompt, "context_info": context}
 
 
 def _vlm_cache_payload(video_path, work_dir, scenes_json, frames):
     return {
         "schema_version": 1,
         "stage": "vlm",
-        "source_video_fingerprint": file_fingerprint(video_path),
-        "scenes_fingerprint": _artifact_fingerprint(scenes_json),
+        "inputs": {
+            "video": _video_input(video_path),
+            "scenes": _artifact_identity(scenes_json),
+            "background_research": _artifact_identity(
+                Path(work_dir) / "background_research.json"
+            ),
+        },
         "frames": _frame_cache_payload(video_path, CONFIG.get("fps"), frames),
-        "prompt": _vlm_prompt_fingerprint(),
+        "prompt": _vlm_prompt_payload(),
         "settings": {
             "fps": CONFIG.get("fps"),
             "vlm_model": CONFIG.get("vlm_model"),
             "api_url": CONFIG.get("api_url"),
             "mimo_disable_thinking": CONFIG.get("mimo_disable_thinking", True),
             "mimo_media_resolution": CONFIG.get("mimo_media_resolution"),
-            "background_research_fingerprint": _artifact_fingerprint(
-                Path(work_dir) / "background_research.json"
-            ),
         },
     }
 
@@ -290,13 +311,10 @@ def _frame_cache_payload(video_path, fps, frames):
         # v2: frame number→time is (n-1)/fps, not n/fps. Bumping invalidates frames/VLM
         # artifacts produced under the old off-by-one so they are recomputed, not reused.
         "schema_version": FRAME_TIME_CONVENTION_VERSION,
-        "source_video_fingerprint": file_fingerprint(video_path),
+        "inputs": {"video": _video_input(video_path)},
         "fps": float(fps),
         "frame_count": len(frames),
         "frames": frame_names,
-        "frame_fingerprints": {
-            name: file_fingerprint(frame) for name, frame in zip(frame_names, frames)
-        },
     }
 
 

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

@@ -14,6 +14,7 @@ from extract import extract_frames
 from detect import detect_scenes, detect_silence_periods, detect_speech_boundary_anchors
 
 from asr import transcribe_audio
+from asr_timing_evidence import write_asr_timing_evidence, asr_evidence_summary_for_brief
 
 from vlm import (
     analyze_scenes,
@@ -27,6 +28,7 @@ from brief import build_agent_brief, assess_understanding_substrate
 from understanding_brief import _research_context, _write_brief_from_existing_artifacts
 from understanding_cache import (
     _asr_cache_payload,
+    _asr_cache_state,
     _frames_cache_valid,
     _load_json,
     _merge_overview_into_scenes,
@@ -112,7 +114,6 @@ def main():
         CONFIG["target_duration"] = args.target_duration
     if args.mimo_video_overview:
         CONFIG["mimo_video_overview"] = True
-    scene_threshold = CONFIG.get("scene_threshold")
 
     video_duration = get_video_duration(video)
     if CONFIG["fps"] <= 0:
@@ -145,21 +146,39 @@ def main():
         scenes = _load_json(scenes_json)
         log(f"跳过场景检测（已存在 {len(scenes)} 个场景）")
     else:
-        scenes = detect_scenes(video, work_dir, scene_threshold)
+        scenes = detect_scenes(video, work_dir, CONFIG["scene_threshold"])
         _write_stage_meta(scenes_json, scenes_meta)
 
     # Step 3: ASR
     asr_meta = _asr_cache_payload(video, skip_asr=args.skip_asr)
+    cache_state = None
+    if not args.skip_asr and not args.force:
+        cache_state = _asr_cache_state(asr_json, asr_meta, video)
     if args.skip_asr:
         asr_result = []
         asr_json.write_text(
             json.dumps(asr_result, ensure_ascii=False, indent=2), encoding="utf-8"
         )
         _write_stage_meta(asr_json, asr_meta)
+        write_asr_timing_evidence(
+            work_dir, video, "EXPLICITLY_SKIPPED", final_segments=asr_result
+        )
         log("跳过 ASR（--skip-asr）")
-    elif not args.force and _stage_cache_valid(asr_json, asr_meta):
+    elif cache_state in {
+        "FRESH",
+        "LEGACY_UNVERIFIED",
+    }:
         asr_result = _load_json(asr_json)
-        log(f"跳过 ASR（已存在 {len(asr_result)} 段）")
+        if cache_state == "LEGACY_UNVERIFIED":
+            write_asr_timing_evidence(
+                work_dir,
+                video,
+                "LEGACY_UNVERIFIED",
+                final_segments=asr_result,
+            )
+            log(f"复用旧 ASR（{len(asr_result)} 段；时间/声学证据未经验证）")
+        else:
+            log(f"跳过 ASR（证据匹配，已存在 {len(asr_result)} 段）")
     else:
         try:
             asr_result = transcribe_audio(video, work_dir)
@@ -188,13 +207,13 @@ def main():
         vlm_analysis = _load_json(vlm_json)
         log(f"跳过 VLM 分析（已存在 {len(vlm_analysis)} 个场景）")
     else:
-        if not CONFIG.get("api_key"):
-            key_name = CONFIG.get("api_key_source", "MIMO_API_KEY")
+        if not CONFIG["api_key"]:
+            key_name = CONFIG["api_env_var"]
             raise SystemExit(f"请设置 {key_name} 环境变量（VLM 画面分析需要）")
         log("VLM API 连通性预检...")
         api_call(
             {
-                "model": CONFIG.get("vlm_model", ""),
+                "model": CONFIG["vlm_model"],
                 "messages": [{"role": "user", "content": "hi"}],
                 "max_tokens": 5,
             }
@@ -204,8 +223,8 @@ def main():
 
     # Step 4.1: optional MiMo scene-chunk video understanding
     overview_path = work_dir / "mimo_video_overview.json"
-    if CONFIG.get("mimo_video_overview", False):
-        if not CONFIG.get("mimo_video_api_key"):
+    if CONFIG["mimo_video_overview"]:
+        if not CONFIG["mimo_video_api_key"]:
             log("跳过 MiMo 分片视频概览：未设置 MIMO_API_KEY")
             overview_path.unlink(missing_ok=True)
             _write_mimo_overview_status(
@@ -227,7 +246,7 @@ def main():
                 log(f"MiMo 分片视频概览失败（忽略）: {e}")
                 _write_mimo_overview_status(work_dir, "failed", e, None)
             else:
-                if overview_path.exists() and overview:
+                if overview:
                     _write_mimo_overview_status(
                         work_dir, "ok", "MiMo 分片视频概览完成", overview_path.name
                     )
@@ -341,8 +360,9 @@ def main():
         video_duration,
         work_dir,
         args.style,
-        mimo_overview_enabled=CONFIG.get("mimo_video_overview", False),
+        mimo_overview_enabled=CONFIG["mimo_video_overview"],
         mimo_overview_video_path=video,
+        asr_evidence=asr_evidence_summary_for_brief(work_dir, video),
     )
     # C1: post-process the RETURNED brief FILE (not brief.py) so the brief⇄narration twin stays
     # byte-identical. Prepends a storyboard header pointing the agent at the sheet(s).

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

@@ -2,14 +2,15 @@
 
 from pathlib import Path
 
-from lib import CONFIG, log, file_fingerprint
+from lib import CONFIG, log
 
 
 from storyboard import build_source_storyboard, build_edited_storyboard
 
 
 from understanding_cache import (
-    _artifact_fingerprint,
+    _artifact_identity,
+    _video_input,
     _frames_manifest_path,
     _load_json,
     _stage_cache_valid,
@@ -19,8 +20,8 @@ from understanding_cache import (
 
 def _storyboard_sample_policy():
     return {
-        "max_tiles": CONFIG.get("storyboard_max_tiles", 30),
-        "columns": CONFIG.get("storyboard_columns", 6),
+        "max_tiles": CONFIG["storyboard_max_tiles"],
+        "columns": CONFIG["storyboard_columns"],
     }
 
 
@@ -31,9 +32,11 @@ def _edited_storyboard_meta(clip_plan_validated_json, frames_manifest_path):
     return {
         "schema_version": 1,
         "stage": "edited_storyboard",
-        "clip_plan_validated_fp": _artifact_fingerprint(clip_plan_validated_json),
+        "inputs": {
+            "clip_plan_validated": _artifact_identity(clip_plan_validated_json),
+            "frames_manifest": _artifact_identity(frames_manifest_path),
+        },
         "fps": float(CONFIG.get("fps") or 0),
-        "frames_manifest_fp": _artifact_fingerprint(frames_manifest_path),
         "sample_policy": _storyboard_sample_policy(),
     }
 
@@ -44,10 +47,10 @@ def _generate_source_storyboard(
     """Generate (or reuse cached) the source storyboard. Advisory: returns dict|None, never raises.
 
     Cached via _write_stage_meta/_stage_cache_valid on storyboard/source_storyboard.json; the
-    meta includes fps + the frames-manifest fp so an fps-change resume rebuilds (Principle 5).
+    meta includes fps + the frames-manifest identity so an fps-change resume rebuilds (Principle 5).
     If frames/ is absent (cache hit skipped extraction / cleaned) → skip + log; pipeline continues.
     """
-    if not CONFIG.get("storyboard", True):
+    if not CONFIG["storyboard"]:
         return None
     frames_dir = Path(work_dir) / "frames"
     if not frames_dir.is_dir() or not any(frames_dir.glob("frame_*.jpg")):
@@ -57,10 +60,12 @@ def _generate_source_storyboard(
     meta = {
         "schema_version": 1,
         "stage": "source_storyboard",
-        "video_fp": file_fingerprint(video_path),
+        "inputs": {
+            "video": _video_input(video_path),
+            "scenes": _artifact_identity(scenes_json),
+            "frames_manifest": _artifact_identity(_frames_manifest_path(work_dir)),
+        },
         "fps": float(CONFIG.get("fps") or 0),
-        "scenes_fp": _artifact_fingerprint(scenes_json),
-        "frames_manifest_fp": _artifact_fingerprint(_frames_manifest_path(work_dir)),
         "sample_policy": _storyboard_sample_policy(),
     }
     if not force and _stage_cache_valid(json_path, meta):
@@ -73,7 +78,7 @@ def _generate_source_storyboard(
         else:
             log("storyboard 跳过 source（缓存匹配）")
             return cached
-    result = build_source_storyboard(work_dir, video_path, scenes, CONFIG.get("fps"))
+    result = build_source_storyboard(work_dir, video_path, scenes, CONFIG["fps"])
     if result is not None and json_path.exists():
         _write_stage_meta(json_path, meta)
     return result
@@ -84,7 +89,7 @@ def _generate_edited_storyboard(work_dir, source_video_path, *, force=False):
     file-presence (NOT on edit_mode — recap.py forwards --edit-mode cut in BOTH passes, so the
     validated plan presence is the only reliable pass2 signal). Advisory: returns dict|None.
     """
-    if not CONFIG.get("storyboard", True):
+    if not CONFIG["storyboard"]:
         return None
     clip_plan_validated_json = Path(work_dir) / "clip_plan_validated.json"
     if not clip_plan_validated_json.exists():
@@ -113,7 +118,7 @@ def _generate_edited_storyboard(work_dir, source_video_path, *, force=False):
         log("storyboard 跳过 edited：clip_plan_validated.json 无法解析")
         return None
     result = build_edited_storyboard(
-        work_dir, source_video_path, clip_plan_validated, CONFIG.get("fps")
+        work_dir, source_video_path, clip_plan_validated, CONFIG["fps"]
     )
     if result is not None and json_path.exists():
         _write_stage_meta(json_path, meta)