@oh-story/dsh 0.1.9 → 0.1.11

package/lib/video-recap/skills/{video-script/scripts/agent_brief.py → video-understanding/scripts/briefing/builder.py}

@@ -1,16 +1,11 @@
 """Build the agent narration brief from validated local evidence."""
 
-import importlib.util
-
-
 from pathlib import Path
 
-from lib import CONFIG
-
-from lib import log
+from lib import CONFIG, log
 
 from agent_text import _chunk_asr_for_writing, _format_frame_facts
-from brief_context import (
+from briefing.context import (
     _format_asr_chunks_for_brief,
     _format_background_research,
     _format_consolidation,
@@ -21,12 +16,12 @@ from brief_context import (
     _write_json_artifact,
     assess_understanding_substrate,
 )
-from brief_inputs import (
+from briefing.inputs import (
     _format_optional_stage_warnings,
     _load_clean_asr,
     _load_mimo_overview_for_brief,
 )
-from brief_timeline import (
+from briefing.timeline import (
     _format_output_clip_list,
     _format_research_directive,
     _format_sentence_entry_anchors_for_brief,
@@ -41,20 +36,6 @@ from timeline_fusion import (
     _scene_asr_lines,
 )
 
-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 build_agent_brief(
     scenes_analysis,
     asr_result,
@@ -65,6 +46,7 @@ def build_agent_brief(
     *,
     mimo_overview_enabled=None,
     mimo_overview_video_path=None,
+    asr_evidence=None,
 ):
     """Write a compact brief that tells the agent exactly how to author recap artifacts."""
     # account for the global narration atempo (CONFIG['narration_speed']) so a beat's text
@@ -73,12 +55,12 @@ def build_agent_brief(
     effective_rate = (
         CONFIG["speech_rate"]
         * CONFIG["speech_safety_margin"]
-        * float(CONFIG.get("narration_speed", 1.0) or 1.0)
+        * CONFIG["narration_speed"]
     )
-    breath_sec = CONFIG.get("breath_ms", 250) / 1000
-    target_pause_ms = CONFIG.get("breath_ms", 250)
-    edit_mode = CONFIG.get("edit_mode", "full")
-    target_duration = CONFIG.get("target_duration") or "(not set)"
+    breath_sec = CONFIG["breath_ms"] / 1000
+    target_pause_ms = CONFIG["breath_ms"]
+    edit_mode = CONFIG["edit_mode"]
+    target_duration = CONFIG["target_duration"] or "(not set)"
     # Cut mode sizes narration to the OUTPUT (the kept clips), not the full source.
     # In pass 2, prefer the actual validated edited_source duration; target_duration is
     # only a planning goal and can differ after clip snapping or under/over-selection.
@@ -88,20 +70,20 @@ def build_agent_brief(
         if spans:
             output_seconds = max(span["output_end"] for span in spans)
         else:
-            target_seconds = _parse_target_seconds(CONFIG.get("target_duration"))
+            target_seconds = _parse_target_seconds(CONFIG["target_duration"])
             if target_seconds:
                 output_seconds = min(video_duration, target_seconds)
     # A loose first-draft timing fallback, not a creative quota. The Agent's beat map and audio-owner
     # decisions determine the real count; this only prevents accidental per-sentence fragmentation.
-    cov_target = CONFIG.get("narration_coverage_target", 0.7)
-    block_seconds = CONFIG.get("narration_block_seconds", 9.0)
+    cov_target = CONFIG["narration_coverage_target"]
+    block_seconds = CONFIG["narration_block_seconds"]
     target_count = max(1, round(output_seconds * cov_target / block_seconds))
 
     has_story_context = (Path(work_dir) / "background_research.json").exists()
     substrate = assess_understanding_substrate(
         scenes_analysis, asr_result, has_story_context=has_story_context
     )
-    thin_substrate = substrate.get("level") in ("thin", "empty")
+    thin_substrate = substrate["level"] in ("thin", "empty")
     beat_count_phrase = (
         f"at most ~{target_count}" if thin_substrate else f"roughly {target_count}"
     )
@@ -129,6 +111,26 @@ def build_agent_brief(
         f"- Target duration (cut mode): {target_duration}",
         f"- Effective speech budget: {effective_rate:.2f} Chinese chars/sec after {breath_sec:.2f}s pause allowance",
     ]
+    # Understanding validates evidence before calling; the standalone script skill
+    # has no producer dependency and must not invent an available ASR status.
+    if asr_evidence is None:
+        asr_evidence = {"status": "MISSING_OR_STALE", "glossary_modifications": None}
+
+    lines.extend(
+        [
+            "",
+            "## ASR timing evidence",
+            "",
+            f"- Status: {asr_evidence['status']}",
+            f"- Glossary modifications: {asr_evidence.get('glossary_modifications') or '(unverified)'}; details: asr_timing_evidence.json",
+            "- Empty text: UNKNOWN_NOT_PROVEN_SILENCE; these windows locate a search region, not subtitle onsets.",
+            "- Timing: coarse provider windows; word alignment: NOT_PERFORMED; dialogue boundaries: NOT_VERIFIED.",
+            "- ASR window ends and timeline-fusion/quiet-window recommendations are advisory only. "
+            "They must not be treated as verified dialogue boundaries or safe cut points; use direct listening "
+            "and picture review before preserving or cutting original dialogue.",
+            "",
+        ]
+    )
     if thin_substrate:
         lines.append(
             f"- Narration density: substrate is {substrate['level']} — do NOT chase a beat count. "
@@ -159,7 +161,7 @@ def build_agent_brief(
     lines.extend(
         [
             f"- Default pause between beats: {target_pause_ms}ms",
-            f"- Context: {CONFIG.get('context_info') or '(none)'}",
+            f"- Context: {CONFIG['context_info'] or '(none)'}",
             "",
             "## Creative decisions before expression / packaging",
             "",
@@ -256,7 +258,8 @@ def build_agent_brief(
                     "- Use `reason` to preserve the actual edit decision: `beat_id | function | change | POV | preferred moment | 入点 | 出点`, not merely 'important plot'. Function is `cold_open`, `setup`, `turn`, `escalation`, or `payoff`.",
                     "- Clip length follows the moment. Vary pace; after any cold-open, order clips by causality so the cut reads as one coherent story, not a flat highlights reel.",
                     "- Inspect dense scene-change candidates before locking boundaries. For source-authored cuts, delete irrelevant short shots and extend relevant shots to a complete action/reaction; for edit-created joins, move boundaries, restore same-source motion, or merge clips so the artificial cut disappears where possible. Do not hide a bad join with a transition.",
-                    "- End a clip on a COMPLETE spoken line — set the clip end at or just after an ASR line-end (or inside the quiet window that follows it), never mid-sentence, so the original dialogue is never chopped off. Use the ASR [start–end] times + Quiet windows below as safe cut points; the CLI also snaps clip ends to the nearest line-end as a safety net.",
+                    "- Preserve complete spoken lines, but do not infer completeness from ASR window ends or quiet-window suggestions. Directly listen and inspect picture around each proposed boundary, then place the cut after the verified utterance/reaction; automatic snapping is only an advisory candidate.",
+                    "- Advisory does not mean absent: the cut CLI still snaps clip ends to sentence boundaries by default and blocks a cut that lands mid-sentence, using `silence_periods.json` and `speech_boundary_anchors.json` as the executable safety net under your listening.",
                     "",
                     "### clip_plan.json shape (original source timestamps)",
                     "",
@@ -318,7 +321,7 @@ def build_agent_brief(
             "1. Assign `audio_owner` and `narration_job` before prose. No clear narration job means no narration for that beat.",
             "2. When narration owns a beat, write one fluent BLOCK that completes a continuous thought (often premise -> trigger/action -> change/meaning) for one TTS call. Sentence count is not a target: use one or a few complete connected sentences, and never split TTS merely because captions need shorter cues.",
             "3. 7:3 is a rough fallback, never a coverage quota. A strong dialogue/performance/action/silence beat may contain no narration; an exposition bridge may be narration-led.",
-            "4. Default `overlaps_speech` to true only for authored narration windows. If source speech has already started, begin at an `原声句末安全切入点`; never enter mid-sentence. Do not cover a must-hear original-audio anchor; leave that beat un-narrated or place narration around it.",
+            "4. Default `overlaps_speech` to true only for authored narration windows. If source speech has already started, use a sentence end confirmed by direct listening and picture review; ASR coarse ends are not proof. Do not cover a must-hear original-audio anchor; leave that beat un-narrated or place narration around it.",
             "5. Do not describe what the viewer can already see; narration may add context, causal links, foreshadowing, evidence-grounded interpretation, or transitions.",
             "6. Keep timing visually local: anchor each block to the planned beat and exact footage it covers; don't let prose run past the change it explains.",
             "7. Preserve performance: consider the listener/reaction instead of the speaker/action, and leave enough time for an irreplaceable look, pause, mistake, or action sound to land.",

package/lib/video-recap/skills/video-understanding/scripts/{brief_context.py → briefing/context.py}

@@ -1,11 +1,10 @@
 """Load and format research, consolidation, and substrate context."""
 
-import hashlib
 import json
 import re
 from pathlib import Path
 
-from lib import CONFIG
+from lib import CONFIG, file_identity
 
 
 def _load_background_research(work_dir):
@@ -243,36 +242,9 @@ def _consolidation_model():
     return CONFIG["vlm_model"]
 
 
-def _clean_asr_prompt_fingerprint():
-    # Keep this literal in sync with consolidate.CLEAN_PROMPT without importing it;
-    # brief.py and narration.py must remain byte-identical cross-skill copies.
-    prompt = """你在清洗中文视频的 ASR 逐段转写。对【每一段】做：补标点、修明显同音/错别字、（能判断时）在句首轻标说话人，让长段连读文本变成清晰可读的句子。
-铁律：
-- 不要合并或拆分段落，输出段数必须与输入完全一致，顺序一致。
-- 不要改时间，不要输出 start/end（时间由程序保留）。
-- 只清洗 text，不要增删事实、不要脑补画面。
-只返回 JSON：{"segments":[{"i":0,"text":"清洗后的文本","speaker":"可选说话人"}, ...]}，i 为输入段的下标。"""
-    return hashlib.md5(prompt.encode("utf-8")).hexdigest()
-
-
-def _index_prompt_fingerprint():
-    prompt = """你在根据逐场景画面分析、ASR对白、background_research术语表，为一个视频建立【全局理解索引】，供后续写解说词时保持人物/关系/主线一致。
-规则：
-- visual/asr 是当前视频事实证据；每个人物、关系、剧情节点、物件尽量给 evidence_ids。
-- background_research 只能用于人名/别名/术语/身份消歧，默认 support=context_only；不能把后续剧情或未出现关系升级为当前画面事实。
-- ASR 中出现但画面描述未命名的人名，应进入 characters[*].asr_mentions。
-只返回 JSON：
-{"characters":[{"name":"角色名或外观指代","description":"身份/特征","aliases":[],"visual_descriptions":[],"asr_mentions":[],"research_role":"","evidence_ids":[],"confidence":"high|medium|low"}],
- "relationships":[{"a":"角色","b":"角色","relation":"关系","evidence_ids":[],"support":"direct|indirect|context_only"}],
- "plot_points":[{"time":"00:00","text":"按时间顺序的关键剧情节点","evidence_ids":[]}],
- "entities":[{"name":"重要物件/地点/线索","evidence_ids":[]}],
- "research_glossary":[{"name":"名字/术语","aliases":[],"role":"说明","support":"context_only"}]}"""
-    return hashlib.md5(prompt.encode("utf-8")).hexdigest()
-
-
 def _load_consolidation(work_dir, scenes_analysis):
     """Load consolidate.py's understanding_index.json only when its provenance matches
-    the current vlm_analysis.json, model and index prompt ({} otherwise)."""
+    the current vlm_analysis.json and model ({} otherwise)."""
     work_dir = Path(work_dir)
     path = work_dir / "understanding_index.json"
     meta_path = work_dir / "understanding_index.json.meta.json"
@@ -280,17 +252,14 @@ def _load_consolidation(work_dir, scenes_analysis):
         return {}
     try:
         meta = json.loads(meta_path.read_text(encoding="utf-8"))
-        source_md5 = hashlib.md5(
-            (work_dir / "vlm_analysis.json").read_bytes()
-        ).hexdigest()
+        source = file_identity(work_dir / "vlm_analysis.json")
     except (OSError, json.JSONDecodeError):
         return {}
     if not isinstance(meta, dict):
         return {}
     expected = {
-        "source_md5": source_md5,
+        "source": source,
         "model": _consolidation_model(),
-        "prompt_md5": _index_prompt_fingerprint(),
     }
     if scenes_analysis:
         expected["scene_count"] = len(scenes_analysis)

package/lib/video-recap/skills/{video-script/scripts/brief_inputs.py → video-understanding/scripts/briefing/inputs.py}

@@ -1,11 +1,10 @@
 """Validate optional ASR, MiMo, and stage-status inputs for the brief."""
 
-import hashlib
 import json
 from pathlib import Path
 
-from lib import CONFIG, file_fingerprint, stable_hash
-from brief_context import _clean_asr_prompt_fingerprint, _consolidation_model
+from lib import CONFIG, file_identity
+from briefing.context import _consolidation_model
 
 # Shared with consolidate.py, which this byte-identical copy cannot import (the sibling
 # skill ships no consolidate.py). Keep both literals in sync.
@@ -27,7 +26,7 @@ def _load_clean_asr(work_dir, asr_result):
     """Return consolidate.py's cleaned ASR segments, or None to fall back to raw asr_result.
 
     Accepted only when the file is at least as fresh as asr_result.json, its provenance
-    (source_md5 / model / prompt_md5) matches, and every segment keeps its original span
+    (source identity / model) matches, and every segment keeps its original span
     within _ASR_SPAN_TOL."""
     if not asr_result:
         return None
@@ -45,16 +44,12 @@ def _load_clean_asr(work_dir, asr_result):
         return None
     try:
         payload = json.loads(clean_path.read_text(encoding="utf-8"))
-        source_md5 = hashlib.md5(src_path.read_bytes()).hexdigest()
+        source = file_identity(src_path)
     except (OSError, json.JSONDecodeError):
         return None
     if not isinstance(payload, dict):
         return None
-    provenance = {
-        "source_md5": source_md5,
-        "model": _consolidation_model(),
-        "prompt_md5": _clean_asr_prompt_fingerprint(),
-    }
+    provenance = {"source": source, "model": _consolidation_model()}
     if not payload.items() >= provenance.items():
         return None
     segments = payload.get("segments")
@@ -84,7 +79,7 @@ def _is_mimo_chunk_usable(content):
     return not any(marker in low for marker in _MIMO_REJECTION_MARKERS)
 
 
-def _mimo_video_settings_fingerprint():
+def _mimo_video_settings():
     """Non-secret MiMo video-overview settings that affect generated content."""
     return {
         "model": CONFIG["mimo_video_model"],
@@ -104,16 +99,6 @@ def _mimo_chunk_cache_key(chunk):
     return f"{chunk['chunk_id']}|{chunk['scene_id']}|{chunk['start']:.3f}-{chunk['end']:.3f}"
 
 
-def _mimo_cached_chunks_fingerprint(done):
-    return stable_hash(done)
-
-
-def _mimo_overview_payload_fingerprint(overview):
-    payload = dict(overview)
-    payload.pop("overview_fingerprint", None)
-    return stable_hash(payload)
-
-
 def _mimo_video_chunks(scenes):
     """Split scene spans into MiMo video chunks. scenes.json rows carry no scene_id, so the
     row index stands in for it there."""
@@ -146,7 +131,7 @@ def _mimo_overview_matches_current_inputs(overview, scenes, video_path=None):
     Provenance keys are read with .get: a stale or partial file simply does not match."""
     if not isinstance(overview, dict) or overview.get("input") != "scene_chunks":
         return False
-    settings = _mimo_video_settings_fingerprint()
+    settings = _mimo_video_settings()
     expected_keys = [
         _mimo_chunk_cache_key(chunk) for chunk in _mimo_video_chunks(scenes)
     ]
@@ -160,7 +145,7 @@ def _mimo_overview_matches_current_inputs(overview, scenes, video_path=None):
         return False
     if video_path is not None:
         try:
-            if overview.get("source_video_fingerprint") != file_fingerprint(video_path):
+            if overview.get("source_video_identity") != file_identity(video_path):
                 return False
         except OSError:
             return False
@@ -168,14 +153,7 @@ def _mimo_overview_matches_current_inputs(overview, scenes, video_path=None):
         cached_keys = [_mimo_chunk_cache_key(chunk) for chunk in chunks]
     except (KeyError, TypeError, ValueError):
         return False
-    return (
-        overview.get("settings") == settings
-        and overview.get("overview_fingerprint")
-        == _mimo_overview_payload_fingerprint(overview)
-        and overview.get("chunks_fingerprint")
-        == _mimo_cached_chunks_fingerprint(chunks)
-        and cached_keys == expected_keys
-    )
+    return overview.get("settings") == settings and cached_keys == expected_keys
 
 
 def _load_mimo_overview_for_brief(work_dir, scenes, enabled=None, video_path=None):

package/lib/video-recap/skills/{video-script/scripts/brief_timeline.py → video-understanding/scripts/briefing/timeline.py}

@@ -5,7 +5,7 @@ import math
 import re
 from pathlib import Path
 
-from lib import CONFIG, stable_hash
+from lib import CONFIG, file_identity
 
 
 def _parse_target_seconds(value):
@@ -104,8 +104,9 @@ def _load_cut_output_spans_for_brief(work_dir, *, required=False):
         return fail("missing clip_plan_validated.json")
     plan = json.loads(validated_path.read_text(encoding="utf-8"))
     raw_path = work_dir / "clip_plan.json"
-    if raw_path.exists() and plan["raw_plan_fingerprint"] != stable_hash(
-        json.loads(raw_path.read_text(encoding="utf-8"))
+    if (
+        raw_path.exists()
+        and validated_path.stat().st_mtime_ns < raw_path.stat().st_mtime_ns
     ):
         return fail("stale clip_plan_validated.json")
     spans = []
@@ -250,9 +251,7 @@ def _sentence_entry_anchors_for_brief(work_dir, edit_mode):
         "artifact": "speech_boundary_anchors_output.json",
         "timeline": "cut_output",
         "source_artifact": "speech_boundary_anchors.json",
-        "clip_plan_fingerprint": stable_hash(
-            json.loads((work_dir / "clip_plan_validated.json").read_text(encoding="utf-8"))
-        ),
+        "clip_plan_identity": file_identity(work_dir / "clip_plan_validated.json"),
         "sentence_anchors": sorted(remapped, key=lambda item: item["time"]),
         "speech_spans": _remap_segments_to_output_for_brief(speech_rows, spans),
         "quiet_windows": _remap_segments_to_output_for_brief(quiet_rows, spans),