@oh-story/dsh 0.1.12 → 0.1.13

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

@@ -6,12 +6,16 @@ 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_identity, load_prompt
+from lib import (
+    CONFIG,
+    file_identity,
+    is_usable_overview_chunk,
+    log,
+    offline_ignored_settings,
+)
 
 
-from vlm import (
-    _is_mimo_chunk_usable,
-)
+from vlm import vlm_prompt_payload
 
 
 def _fresh(out, *inputs):
@@ -45,9 +49,19 @@ def _artifact_identity(path):
     return file_identity(path) if path.exists() else None
 
 
-def _stage_cache_valid(artifact_path, expected_meta):
+def _without_settings(meta, keys):
+    settings = meta.get("settings")
+    if not keys or not isinstance(settings, dict):
+        return meta
+    return {**meta, "settings": {k: v for k, v in settings.items() if k not in keys}}
+
+
+def _stage_cache_valid(artifact_path, expected_meta, *, ignore_settings=()):
     """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."""
+    expected inputs/settings dict, and the output itself is the one the sidecar recorded.
+
+    `ignore_settings` names `settings` keys left out of the comparison on both sides (an
+    endpoint URL that only reflects which credential is set, or a retired legacy key)."""
     artifact_path = Path(artifact_path)
     if not artifact_path.exists() or artifact_path.stat().st_size == 0:
         return False
@@ -62,7 +76,9 @@ def _stage_cache_valid(artifact_path, expected_meta):
         return False
     expected = dict(expected_meta)
     expected["artifact"] = meta["artifact"]
-    return meta == expected
+    return _without_settings(meta, ignore_settings) == _without_settings(
+        expected, ignore_settings
+    )
 
 
 def _write_stage_meta(artifact_path, meta):
@@ -129,7 +145,7 @@ def _merge_overview_into_scenes(scenes, overview_path):
     by_scene = {}
     for chunk in overview["chunks"]:
         content = chunk["content"].strip()
-        if _is_mimo_chunk_usable(content):
+        if is_usable_overview_chunk(content):
             by_scene.setdefault(chunk["scene_id"], []).append(content)
     if not by_scene:
         return scenes
@@ -206,7 +222,6 @@ def _asr_cache_payload(video_path, *, skip_asr=False):
         "inputs": {"video": _video_input(video_path)},
         "settings": {
             "skip_asr": bool(skip_asr),
-            "mimo_asr_api_key_present": bool(CONFIG.get("mimo_asr_api_key")),
             "mimo_asr_api_url": CONFIG.get("mimo_asr_api_url"),
             "mimo_asr_model": CONFIG.get("mimo_asr_model"),
             "mimo_asr_language": CONFIG.get("mimo_asr_language"),
@@ -216,21 +231,29 @@ def _asr_cache_payload(video_path, *, skip_asr=False):
     }
 
 
+# Sidecars written before 0.6.1 recorded whether an ASR key was set. Key presence is not an
+# output setting: a missing key only meant the run wrote an UNAVAILABLE_NO_KEY placeholder,
+# which the evidence status below already refuses to reuse.
+_LEGACY_ASR_SETTINGS = ("mimo_asr_api_key_present",)
+
+
 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):
+    ignored = _LEGACY_ASR_SETTINGS + offline_ignored_settings(
+        CONFIG.get("mimo_asr_api_key"), "mimo_asr_api_url"
+    )
+    if not _stage_cache_valid(artifact_path, expected_meta, ignore_settings=ignored):
         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"}:
+        # as fresh would make one bad run a permanent cache hit. A key-less placeholder is
+        # retried too, so setting the key later transcribes for real.
+        if evidence.get("status") in {
+            "UNAVAILABLE_NO_DURATION", "EMPTY_UNKNOWN", "UNAVAILABLE_NO_KEY"
+        }:
             return "MISS"
         return "FRESH"
     return "MISS"
@@ -263,21 +286,6 @@ def _silence_cache_payload(video_path, asr_json):
     }
 
 
-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 = (
-            "仔细观察这些视频帧。分两部分输出：\n"
-            "【描述】不超过80字，描述画面中正在发生什么。\n"
-            "【深层分析】不超过120字，分析角色情绪、关系动态、潜台词。"
-        )
-    context = CONFIG.get("context_info", "")
-    if context:
-        prompt = f"已知信息：{context}\n\n{prompt}"
-    return {"prompt_text": prompt, "context_info": context}
-
-
 def _vlm_cache_payload(video_path, work_dir, scenes_json, frames):
     return {
         "schema_version": 1,
@@ -290,7 +298,7 @@ def _vlm_cache_payload(video_path, work_dir, scenes_json, frames):
             ),
         },
         "frames": _frame_cache_payload(video_path, CONFIG.get("fps"), frames),
-        "prompt": _vlm_prompt_payload(),
+        "prompt": vlm_prompt_payload(),
         "settings": {
             "fps": CONFIG.get("fps"),
             "vlm_model": CONFIG.get("vlm_model"),

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

@@ -7,14 +7,14 @@ import json
 
 from pathlib import Path
 
-from lib import CONFIG, log, get_video_duration, api_call
+from lib import CONFIG, log, get_video_duration, api_call, offline_ignored_settings
 
 from extract import extract_frames
 
-from detect import detect_scenes, detect_silence_periods, detect_speech_boundary_anchors
+from detect import detect_scenes, detect_silence_periods, ensure_speech_boundary_anchors
 
 from asr import transcribe_audio
-from asr_timing_evidence import write_asr_timing_evidence, asr_evidence_summary_for_brief
+from asr_timing_evidence import write_asr_timing_evidence
 
 from vlm import (
     analyze_scenes,
@@ -22,10 +22,12 @@ from vlm import (
     mimo_video_overview_cache_fresh,
 )
 
-from brief import build_agent_brief, assess_understanding_substrate
-
-
-from understanding_brief import _research_context, _write_brief_from_existing_artifacts
+from understanding_brief import (
+    _finish_brief,
+    _research_context,
+    _write_brief_from_existing_artifacts,
+)
+from understanding_storyboard import _write_edited_storyboard_only
 from understanding_cache import (
     _asr_cache_payload,
     _asr_cache_state,
@@ -43,11 +45,28 @@ from understanding_cache import (
     _write_mimo_overview_status,
     _write_stage_meta,
 )
-from understanding_storyboard import (
-    _generate_edited_storyboard,
-    _generate_source_storyboard,
-    _prepend_storyboard_brief_header,
-)
+
+
+def _refuse_keyless_overwrite(asr_json):
+    """Stop before a key-less ASR miss replaces a real transcript with the [] placeholder.
+
+    The cache can miss for reasons that say nothing about the transcript, e.g. a work_dir
+    copied without keeping mtimes changes the recorded artifact identity."""
+    if CONFIG["mimo_asr_api_key"] or not asr_json.exists():
+        return
+    try:
+        existing = json.loads(asr_json.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return
+    if isinstance(existing, list) and existing:
+        raise SystemExit(
+            "ASR 缓存与当前视频、设置或文件时间不匹配（常见原因：复制 work_dir 或视频时没保留"
+            "修改时间），且未设置 MIMO_ASR_API_KEY / MIMO_API_KEY，无法重新转写；"
+            f"已保留现有 asr_result.json（{len(existing)} 段），未覆盖。"
+            "请用保留时间的方式重新复制（cp -p / cp -Rp / rsync -t），"
+            "或设置 MIMO_ASR_API_KEY 或 MIMO_API_KEY 后重跑（会重新转写）。"
+            "不要用 --skip-asr 绕过：它会把现有转写替换成 []。"
+        )
 
 
 def main():
@@ -82,6 +101,14 @@ def main():
         action="store_true",
         help="rebuild agent_narration_brief.md from existing artifacts only; no extraction/API",
     )
+    ap.add_argument(
+        "--edited-storyboard-only",
+        action="store_true",
+        help=(
+            "write storyboard/edited_storyboard.* from clip_plan_validated.json (single- or "
+            "multi-source) and add its pointer to the existing brief; no extraction/API"
+        ),
+    )
     ap.add_argument(
         "--consolidate",
         action=argparse.BooleanOptionalAction,
@@ -94,6 +121,8 @@ def main():
         help="also clean the ASR transcript (Pass A)",
     )
     args = ap.parse_args()
+    if args.brief_only and args.edited_storyboard_only:
+        ap.error("--brief-only and --edited-storyboard-only are mutually exclusive")
 
     video = args.video
     work_dir = Path(args.work_dir)
@@ -125,6 +154,9 @@ def main():
     if args.brief_only:
         _write_brief_from_existing_artifacts(video, work_dir, args, video_duration)
         return
+    if args.edited_storyboard_only:
+        _write_edited_storyboard_only(video, work_dir)
+        return
 
     scenes_json = work_dir / "scenes.json"
     asr_json = work_dir / "asr_result.json"
@@ -149,6 +181,17 @@ def main():
         scenes = detect_scenes(video, work_dir, CONFIG["scene_threshold"])
         _write_stage_meta(scenes_json, scenes_meta)
 
+    # The VLM cache does not depend on ASR, so an offline run that would stop at Step 4 stops
+    # here instead, before Step 3 can rewrite the transcript or the silence windows.
+    vlm_meta = _vlm_cache_payload(video, work_dir, scenes_json, frames)
+    vlm_offline = offline_ignored_settings(CONFIG["api_key"], "api_url")
+    vlm_cached = not args.force and _stage_cache_valid(
+        vlm_json, vlm_meta, ignore_settings=vlm_offline
+    )
+    if not vlm_cached and not CONFIG["api_key"]:
+        key_name = CONFIG["api_env_var"]
+        raise SystemExit(f"请设置 {key_name} 环境变量（VLM 画面分析需要）")
+
     # Step 3: ASR
     asr_meta = _asr_cache_payload(video, skip_asr=args.skip_asr)
     cache_state = None
@@ -164,22 +207,11 @@ def main():
             work_dir, video, "EXPLICITLY_SKIPPED", final_segments=asr_result
         )
         log("跳过 ASR（--skip-asr）")
-    elif cache_state in {
-        "FRESH",
-        "LEGACY_UNVERIFIED",
-    }:
+    elif cache_state == "FRESH":
         asr_result = _load_json(asr_json)
-        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)} 段）")
+        log(f"跳过 ASR（证据匹配，已存在 {len(asr_result)} 段）")
     else:
+        _refuse_keyless_overwrite(asr_json)
         try:
             asr_result = transcribe_audio(video, work_dir)
         except Exception as e:
@@ -195,21 +227,16 @@ def main():
     if not args.force and _stage_cache_valid(silence_json, silence_meta):
         silence_periods = _load_json(silence_json)
         log(f"跳过静音检测（已存在 {len(silence_periods)} 个窗口）")
-        if not (work_dir / "speech_boundary_anchors.json").exists():
-            detect_speech_boundary_anchors(work_dir, asr_result)
+        ensure_speech_boundary_anchors(work_dir, asr_result)
     else:
         silence_periods = detect_silence_periods(video, work_dir, asr_result)
         _write_stage_meta(silence_json, silence_meta)
 
     # Step 4: VLM analysis (the only stage that requires the chat API key)
-    vlm_meta = _vlm_cache_payload(video, work_dir, scenes_json, frames)
-    if not args.force and _stage_cache_valid(vlm_json, vlm_meta):
+    if vlm_cached:
         vlm_analysis = _load_json(vlm_json)
         log(f"跳过 VLM 分析（已存在 {len(vlm_analysis)} 个场景）")
     else:
-        if not CONFIG["api_key"]:
-            key_name = CONFIG["api_env_var"]
-            raise SystemExit(f"请设置 {key_name} 环境变量（VLM 画面分析需要）")
         log("VLM API 连通性预检...")
         api_call(
             {
@@ -224,7 +251,14 @@ def main():
     # Step 4.1: optional MiMo scene-chunk video understanding
     overview_path = work_dir / "mimo_video_overview.json"
     if CONFIG["mimo_video_overview"]:
-        if not CONFIG["mimo_video_api_key"]:
+        if not CONFIG["mimo_video_api_key"] and mimo_video_overview_cache_fresh(
+            overview_path, video, scenes
+        ):
+            log("未设置 MIMO_API_KEY，复用已缓存的 MiMo 分片视频概览")
+            _write_mimo_overview_status(
+                work_dir, "cached", "未设置 MIMO_API_KEY，复用缓存", overview_path.name
+            )
+        elif not CONFIG["mimo_video_api_key"]:
             log("跳过 MiMo 分片视频概览：未设置 MIMO_API_KEY")
             overview_path.unlink(missing_ok=True)
             _write_mimo_overview_status(
@@ -265,123 +299,62 @@ def main():
     vlm_analysis = _merge_overview_into_scenes(vlm_analysis, overview_path)
 
     # optional consolidation (整理): build the understanding index before the brief folds it in
-    if args.consolidate or args.consolidate_asr:
+    enabled = bool(args.consolidate or args.consolidate_asr)
+    status, message, artifacts = "disabled", "consolidation 未启用", []
+    if enabled:
         from consolidate import consolidate
 
+        failure = None
+        result = {}
         try:
-            consolidate(
+            result = consolidate(
                 work_dir, do_asr=args.consolidate_asr, do_index=args.consolidate
             )
         except Exception as e:
             log(f"consolidate 跳过（忽略）: {e}")
-            _write_consolidation_status(
-                work_dir,
-                "failed",
-                e,
-                _present_consolidation_artifacts(work_dir),
-                do_asr=args.consolidate_asr,
-                do_index=args.consolidate,
-            )
+            failure = e
+        artifacts = _present_consolidation_artifacts(work_dir)
+        no_key = result.get("skipped_no_key") or []
+        if failure is not None:
+            status, message = "failed", failure
         else:
             expected = []
             skipped = []
-            if args.consolidate:
+            if args.consolidate and "index" not in no_key:
                 if vlm_analysis:
                     expected.append("understanding_index.json")
                 else:
                     skipped.append("无 vlm_analysis，跳过 index")
-            if args.consolidate_asr:
+            if args.consolidate_asr and "asr" not in no_key:
                 if asr_result:
                     expected.append("asr_clean.json")
                 else:
                     skipped.append("无 ASR 文本，跳过 ASR 清洗")
-            artifacts = _present_consolidation_artifacts(work_dir)
             missing = [name for name in expected if name not in artifacts]
             if missing:
-                _write_consolidation_status(
-                    work_dir,
-                    "failed",
-                    f"未产出预期 artifact: {', '.join(missing)}",
-                    artifacts,
-                    do_asr=args.consolidate_asr,
-                    do_index=args.consolidate,
+                status, message = "failed", f"未产出预期 artifact: {', '.join(missing)}"
+            elif no_key:
+                status, message = (
+                    "skipped_no_key",
+                    f"未设置 {CONFIG['api_env_var']}，consolidation（{', '.join(no_key)}）未发送请求",
                 )
             elif expected:
-                _write_consolidation_status(
-                    work_dir,
-                    "ok",
-                    "consolidation 完成",
-                    artifacts,
-                    do_asr=args.consolidate_asr,
-                    do_index=args.consolidate,
-                )
+                status, message = "ok", "consolidation 完成"
             else:
-                _write_consolidation_status(
-                    work_dir,
-                    "skipped",
-                    "；".join(skipped) or "无可整理输入",
-                    artifacts,
-                    do_asr=args.consolidate_asr,
-                    do_index=args.consolidate,
-                )
-    else:
-        _write_consolidation_status(
-            work_dir,
-            "disabled",
-            "consolidation 未启用",
-            [],
-            enabled=False,
-            do_asr=False,
-            do_index=False,
-        )
-
-    # Storyboard contact sheets (advisory, never blocking). Source uses scene anchors over the
-    # source timeline; edited is gated on clip_plan_validated.json file-presence (NOT edit_mode —
-    # recap.py forwards --edit-mode cut in BOTH passes, so the validated plan is the only reliable
-    # pass2 signal). Both cache via _write_stage_meta/_stage_cache_valid with fps + frame-set in the key.
-    source_storyboard = _generate_source_storyboard(
-        work_dir, Path(video), scenes, scenes_json, force=args.force
-    )
-    edited_storyboard = _generate_edited_storyboard(work_dir, video, force=args.force)
-    cut_mode = (work_dir / "clip_plan_validated.json").exists()
-
-    # understanding substrate warning + writing brief
-    substrate = assess_understanding_substrate(vlm_analysis, asr_result)
-    if substrate["level"] != "rich":
-        banner = "理解素材为空" if substrate["level"] == "empty" else "理解素材偏薄"
-        log(
-            f"⚠️  {banner}：ASR {substrate['asr_chars']} 字 | 场景 {substrate['scene_count']} | "
-            f"带 frame_facts 的场景 {substrate['scenes_with_frame_facts']} | 平均画面描述 {substrate['avg_description_len']} 字"
-        )
-    brief_path = build_agent_brief(
-        vlm_analysis,
-        asr_result,
-        silence_periods,
-        video_duration,
+                status, message = "skipped", "；".join(skipped) or "无可整理输入"
+    _write_consolidation_status(
         work_dir,
-        args.style,
-        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).
-    _prepend_storyboard_brief_header(
-        brief_path, source_storyboard, edited_storyboard, cut_mode=cut_mode
+        status,
+        message,
+        artifacts,
+        enabled=enabled,
+        do_asr=args.consolidate_asr,
+        do_index=args.consolidate,
     )
 
-    log("=" * 50)
-    log(f"理解完成。写作 brief: {brief_path}")
-    print(
-        json.dumps(
-            {
-                "status": "analyzed",
-                "work_dir": str(work_dir),
-                "brief": str(brief_path),
-                "substrate": substrate["level"],
-                "scenes": len(scenes),
-                "asr_segments": len(asr_result),
-            },
-            ensure_ascii=False,
-        )
+    _finish_brief(
+        video, work_dir, args, video_duration,
+        storyboard_scenes=scenes, brief_scenes=vlm_analysis,
+        asr_result=asr_result, silence_periods=silence_periods,
+        status="analyzed", done_label="理解完成", force=args.force,
     )