@oh-story/dsh 0.1.12 → 0.1.13

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

@@ -19,7 +19,6 @@ VALID_STATUSES = {
     "FAILED_AUDIO_EXTRACTION",
     "FAILED_PROVIDER",
     "EMPTY_UNKNOWN",
-    "LEGACY_UNVERIFIED",
 }
 _TOP_KEYS = {
     "schema_version", "status", "source_video", "audio", "asr_result",
@@ -63,10 +62,8 @@ def load_glossary_names(work_dir):
     )
 
 
-def _glossary_binding(work_dir, *, legacy=False):
-    """The glossary names that could have corrected this transcription (legacy: unknown)."""
-    if legacy:
-        return {"names": None, "name_count": None}
+def _glossary_binding(work_dir):
+    """The glossary names that could have corrected this transcription."""
     names = load_glossary_names(work_dir)
     return {"names": names, "name_count": len(names)}
 
@@ -87,12 +84,12 @@ def _atomic_json_write(path, payload):
             pass
 
 
-def _window_evidence(observed_segments, final_segments, legacy):
+def _window_evidence(observed_segments, final_segments):
     observed_segments = observed_segments or []
     windows = []
     for index, final in enumerate(final_segments or []):
         observed = observed_segments[index] if index < len(observed_segments) else None
-        observed_text = None if legacy or observed is None else str(observed.get("text") or "")
+        observed_text = None if observed is None else str(observed.get("text") or "")
         final_text = str(final.get("text") or "")
         windows.append({
             "index": index,
@@ -111,20 +108,19 @@ def write_asr_timing_evidence(
     audio_path=None,
 ):
     """Write a sidecar recording which source/audio/result files it describes, without
-    changing the legacy result."""
+    changing the result itself."""
     if status not in VALID_STATUSES:
         raise ValueError(f"unknown ASR timing evidence status: {status}")
     work_dir = Path(work_dir)
-    legacy = status == "LEGACY_UNVERIFIED"
     payload = {
         "schema_version": SCHEMA_VERSION,
         "status": status,
         "source_video": _identity(video_path),
         "audio": _identity(audio_path) if audio_path else None,
         "asr_result": _identity(work_dir / "asr_result.json"),
-        "glossary": _glossary_binding(work_dir, legacy=legacy),
+        "glossary": _glossary_binding(work_dir),
         "precision": dict(_PRECISION),
-        "windows": _window_evidence(observed_segments, final_segments, legacy),
+        "windows": _window_evidence(observed_segments, final_segments),
     }
     path = work_dir / EVIDENCE_FILENAME
     _atomic_json_write(path, payload)
@@ -146,11 +142,9 @@ def _is_identity(value):
     )
 
 
-def _valid_glossary(payload, work_dir, legacy):
+def _valid_glossary(payload, work_dir):
     if not isinstance(payload, dict) or set(payload) != _GLOSSARY_KEYS:
         return False
-    if legacy:
-        return payload == _glossary_binding(work_dir, legacy=True)
     return payload == _glossary_binding(work_dir) and _is_int(payload.get("name_count"))
 
 
@@ -162,8 +156,8 @@ def _valid_status_relationships(status, result, audio):
         return bool(result) and not any(texts) and _is_identity(audio)
     if status == "UNAVAILABLE_NO_DURATION":
         return result == [] and _is_identity(audio)
-    if status in {"EXPLICITLY_SKIPPED", "UNAVAILABLE_NO_KEY", "LEGACY_UNVERIFIED"}:
-        return audio is None and (status == "LEGACY_UNVERIFIED" or result == [])
+    if status in {"EXPLICITLY_SKIPPED", "UNAVAILABLE_NO_KEY"}:
+        return audio is None and result == []
     return False
 
 
@@ -199,8 +193,7 @@ def validate_asr_timing_evidence(evidence_path, video_path, asr_result_path):
         return False
     if not _valid_status_relationships(status, result, audio):
         return False
-    legacy = status == "LEGACY_UNVERIFIED"
-    if not _valid_glossary(evidence.get("glossary"), evidence_path.parent, legacy):
+    if not _valid_glossary(evidence.get("glossary"), evidence_path.parent):
         return False
 
     if audio is not None:
@@ -240,10 +233,7 @@ def validate_asr_timing_evidence(evidence_path, video_path, asr_result_path):
             or window.get("text_availability") != ("AVAILABLE" if text else "UNAVAILABLE_UNKNOWN")
         ):
             return False
-        if legacy:
-            if observed is not None or modified is not None:
-                return False
-        elif (
+        if (
             not isinstance(observed, str) or not isinstance(modified, bool)
             or modified != (observed != text)
         ):
@@ -265,6 +255,7 @@ def asr_evidence_summary_for_brief(work_dir, video_path):
     if valid:
         payload = json.loads(evidence_path.read_text(encoding="utf-8"))
         return {"status": payload["status"],
-                "glossary_modifications": None if payload["status"] == "LEGACY_UNVERIFIED"
-                else sum(w["glossary_modified"] is True for w in payload["windows"])}
+                "glossary_modifications": sum(
+                    w["glossary_modified"] is True for w in payload["windows"]
+                )}
     return {"status": "MISSING_OR_STALE", "glossary_modifications": None}

package/lib/video-recap/skills/video-understanding/scripts/briefing/builder.py

@@ -9,10 +9,12 @@ from briefing.context import (
     _format_asr_chunks_for_brief,
     _format_background_research,
     _format_consolidation,
+    _format_moderation_refusals,
     _format_substrate_warning,
     _format_timeline_fusion_for_brief,
     _load_background_research,
     _load_consolidation,
+    _scene_number,
     _write_json_artifact,
     assess_understanding_substrate,
 )
@@ -28,7 +30,6 @@ from briefing.timeline import (
     _load_cut_output_spans_for_brief,
     _parse_target_seconds,
     _remap_brief_evidence_to_output_timeline,
-    _write_deslop_qc_requirements,
 )
 from timeline_fusion import (
     _build_timeline_fusion,
@@ -36,6 +37,24 @@ from timeline_fusion import (
     _scene_asr_lines,
 )
 
+
+def _duration_label(seconds):
+    """'45s' / '2min' / '1m42s' / '2h' / '2h01m' / '2h01m05s', rounded to whole seconds;
+    a unit is dropped only when it and everything below it are zero.
+
+    A minute-rounded label hid the real length: a 90 s target read '~2min'."""
+    whole = int(seconds + 0.5)
+    if whole < 60:
+        return f"{whole}s"
+    minutes, secs = divmod(whole, 60)
+    if minutes < 60:
+        return f"{minutes}min" if secs == 0 else f"{minutes}m{secs:02d}s"
+    hours, minutes = divmod(minutes, 60)
+    if minutes == 0 and secs == 0:
+        return f"{hours}h"
+    return f"{hours}h{minutes:02d}m" if secs == 0 else f"{hours}h{minutes:02d}m{secs:02d}s"
+
+
 def build_agent_brief(
     scenes_analysis,
     asr_result,
@@ -87,16 +106,8 @@ def build_agent_brief(
     beat_count_phrase = (
         f"at most ~{target_count}" if thin_substrate else f"roughly {target_count}"
     )
-    output_label = (
-        f"{output_seconds / 60:.0f}min"
-        if output_seconds >= 60
-        else f"{output_seconds:.0f}s"
-    )
-    source_label = (
-        f"{video_duration / 60:.0f}min"
-        if video_duration >= 60
-        else f"{video_duration:.0f}s"
-    )
+    output_label = _duration_label(output_seconds)
+    source_label = _duration_label(video_duration)
 
     lines = [
         "# Agent Narration Brief",
@@ -111,8 +122,7 @@ 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.
+    # A caller that passes no ASR evidence must not get an invented available status.
     if asr_evidence is None:
         asr_evidence = {"status": "MISSING_OR_STALE", "glossary_modifications": None}
 
@@ -173,7 +183,7 @@ def build_agent_brief(
             "- `visual_audio_board.json` owns the exact picture/performance/reaction, entry/exit reason, original-audio anchor, `audio_owner`, and `narration_job` for each beat.",
             "- Only after the story/edit decisions are coherent, author `style_card.json` from `--style`, evidence, and user preference. It owns voice and pacing, not story structure, and is not a preset enum, fixed taxonomy, title plan, or packaging promise.",
             "- `packaging_plan.json` is optional and deferred until content lock unless the user explicitly asks for packaging. It must express the story's truthful promise, never drive or distort it.",
-            "- `deslop_qc.json` is deterministic report-only tool QC: do not hand-author it, do not treat it as an AIGC detector, and do not auto-rewrite from it. Corrections remain human/agent rewrite work guided by objective blockers and advisory readability signals.",
+            "- `narration_lint.json.deslop_qc` is deterministic report-only tool QC written by validation: do not treat it as an AIGC detector, and do not auto-rewrite from it. Corrections remain human/agent rewrite work guided by objective blockers and advisory readability signals.",
             "",
         ]
     )
@@ -194,6 +204,7 @@ def build_agent_brief(
         )
     )
     lines.extend(_format_substrate_warning(substrate))
+    lines.extend(_format_moderation_refusals(scenes_analysis))
     lines.extend(_format_research_directive(work_dir, substrate))
     lines.extend(_format_background_research(_load_background_research(work_dir)))
     lines.extend(_format_consolidation(consolidation_index))
@@ -205,7 +216,8 @@ def build_agent_brief(
         asr_result,
         silence_periods,
     )
-    if edit_mode == "cut" and (Path(work_dir) / "edited_source.mp4").exists():
+    cut_pass2 = edit_mode == "cut" and (Path(work_dir) / "edited_source.mp4").exists()
+    if cut_pass2:
         chunk_scenes, chunk_asr, _ = _remap_brief_evidence_to_output_timeline(
             work_dir, scenes_analysis, asr_for_chunks, [], required=True
         )
@@ -237,7 +249,7 @@ def build_agent_brief(
         cut_target_example = (
             target_duration if target_duration != "(not set)" else "30m"
         )
-        if not (Path(work_dir) / "edited_source.mp4").exists():
+        if not cut_pass2:
             # PASS 1 of 2 (cut-first): pick the footage. Narration comes AFTER the cut is
             # rendered, so it can be written against the real OUTPUT timeline — no source->output
             # mapping, no silent drop/clamp, no desync.
@@ -259,7 +271,7 @@ def build_agent_brief(
                     "- 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.",
                     "- 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.",
+                    "- Advisory does not mean absent: the cut CLI still snaps clip ends to sentence boundaries by default and blocks a cut inside ASR-detected speech unless it lands in a quiet window or a sentence-end pause estimate, using `silence_periods.json` and `speech_boundary_anchors.json` as the executable safety net under your listening.",
                     "",
                     "### clip_plan.json shape (original source timestamps)",
                     "",
@@ -366,22 +378,45 @@ def build_agent_brief(
             '- ✗ "一个蒙眼的男人抱着一个篮子走在雨里。"  (just describes the frame)',
             '- ✓ "护送者本可以独自离开，却为了保护那个孩子，主动把追兵引向自己。"  (who, why, stakes)',
             "",
-            "## Scene timing guide",
-            "",
         ]
     )
+    # Cut pass 2 narrates edited_source.mp4, so its guide lists only the kept footage on the
+    # OUTPUT clock; the source-time guide (cut-away scenes, credits) belongs to pass 1.
+    if cut_pass2:
+        guide_scenes, guide_asr, guide_silence = fusion_scenes, fusion_asr, fusion_silence
+        lines.extend(
+            [
+                "## Scene timing guide (OUTPUT time)",
+                "",
+                "Only footage kept in `edited_source.mp4`, timed on its OUTPUT timeline (0 .. total); "
+                "scenes the cut left out are not listed.",
+                "",
+            ]
+        )
+    else:
+        guide_scenes, guide_asr, guide_silence = scenes_analysis, asr_result, silence_periods
+        lines.extend(["## Scene timing guide", ""])
 
-    for scene in scenes_analysis:
+    for scene in guide_scenes:
         duration = scene["end"] - scene["start"]
         max_chars = max(5, int(max(1.0, duration - breath_sec) * effective_rate))
-        quiets = _quiet_windows_for_scene(silence_periods, scene)
+        quiets = _quiet_windows_for_scene(guide_silence, scene)
         quiet_text = ", ".join(f"{s:.1f}-{e:.1f}s" for s, e in quiets) or "none"
+        span = f"{scene['start']:.1f}-{scene['end']:.1f}s"
         lines.extend(
             [
-                f"### Scene {scene['scene_id'] + 1}: {scene['start']:.1f}-{scene['end']:.1f}s",
+                f"### OUTPUT {span} (source scene {_scene_number(scene['scene_id'])})"
+                if cut_pass2
+                else f"### Scene {_scene_number(scene['scene_id'])}: {span}",
                 f"- Duration: {duration:.1f}s; max budget if fully narrated: {max_chars} chars",
                 f"- Quiet windows: {quiet_text}",
-                f"- Description: {scene.get('description', '')}",
+                f"- Description: {scene.get('description', '')}"
+                + (
+                    " [moderation_refused]"
+                    if scene.get("analysis_status") == "moderation_refused"
+                    and scene.get("description_source") != "mimo_video_overview"
+                    else ""
+                ),
             ]
         )
         if scene.get("depth_analysis"):
@@ -389,7 +424,7 @@ def build_agent_brief(
         facts = _format_frame_facts(scene)
         if facts:
             lines.append(facts.rstrip())
-        asr_lines = _scene_asr_lines(asr_result, scene)
+        asr_lines = _scene_asr_lines(guide_asr, scene)
         if asr_lines:
             lines.append("- ASR overlap:")
             lines.extend(asr_lines[:8])
@@ -397,6 +432,5 @@ def build_agent_brief(
 
     brief_path = Path(work_dir) / "agent_narration_brief.md"
     brief_path.write_text("\n".join(lines), encoding="utf-8")
-    _write_deslop_qc_requirements(work_dir)
     log(f"已写入 Agent 解说写作 brief: {brief_path}")
     return brief_path

package/lib/video-recap/skills/video-understanding/scripts/briefing/context.py

@@ -4,9 +4,17 @@ import json
 import re
 from pathlib import Path
 
+from index_normalize import normalize_index
 from lib import CONFIG, file_identity
 
 
+def _scene_number(scene_id):
+    """1-based scene number for every human-facing label in the brief (JSON keeps the
+    0-based `scene_id`); a scene split across kept clips ("3.1") reads "4 part 2"."""
+    base, _, part = str(scene_id).partition(".")
+    return f"{int(base) + 1} part {int(part) + 1}" if part else str(int(base) + 1)
+
+
 def _load_background_research(work_dir):
     """Load the agent-authored background_research.json ({} when absent)."""
     path = Path(work_dir) / "background_research.json"
@@ -158,6 +166,31 @@ def _format_substrate_warning(assessment):
     ]
 
 
+def _format_moderation_refusals(scenes_analysis):
+    """One brief line naming the scenes MiMo moderation refused, so blank descriptions read as
+    refusals (vlm.analyze_scenes sets analysis_status), not as empty footage."""
+    refused = [
+        scene for scene in scenes_analysis or []
+        if isinstance(scene, dict) and scene.get("analysis_status") == "moderation_refused"
+    ]
+    if not refused:
+        return []
+    labels = ", ".join(_scene_number(scene["scene_id"]) for scene in refused[:12])
+    more = f" …(+{len(refused) - 12})" if len(refused) > 12 else ""
+    covered = sum(
+        1 for scene in refused if scene.get("description_source") == "mimo_video_overview"
+    )
+    overview_note = f"; {covered} of them are described by the MiMo overview instead" if covered else ""
+    return [
+        f"- Moderation-refused scenes: {len(refused)}/{len(scenes_analysis)} "
+        f"(Scene {labels}{more}) — MiMo refused the frame VLM request, so their frame "
+        f"description is blank and they carry no frame_facts{overview_note}. This is a "
+        "content-moderation refusal, not empty footage: ground them in ASR, burned-in "
+        "subtitles, or background research, or skip them in cut mode.",
+        "",
+    ]
+
+
 def _write_json_artifact(work_dir, name, payload):
     path = Path(work_dir) / name
     path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
@@ -175,7 +208,7 @@ def _format_asr_chunks_for_brief(chunks, max_chunks=24):
         "",
     ]
     for chunk in chunks[:max_chunks]:
-        scene_ids = ",".join(str(sid) for sid in chunk["scene_ids"]) or "n/a"
+        scene_ids = ", ".join(_scene_number(sid) for sid in chunk["scene_ids"]) or "n/a"
         text = chunk["text"]
         if len(text) > 900:
             text = text[:897] + "..."
@@ -223,7 +256,7 @@ def _format_timeline_fusion_for_brief(fusion, max_items=40):
         )
         lines.extend(
             [
-                f"### Fusion scene {item['scene_id']}: {start:.1f}-{end:.1f}s ({item['recommended_mode']})",
+                f"### Fusion scene {_scene_number(item['scene_id'])}: {start:.1f}-{end:.1f}s ({item['recommended_mode']})",
                 f"- Visual: {item['visual_description']}",
                 f"- Dialogue overlap: {item['dialogue_overlap_seconds']:.1f}s | {dialogue_text}",
                 f"- Narration slots: {slot_text}",
@@ -278,7 +311,10 @@ def _load_consolidation(work_dir, scenes_analysis):
         return {}
     if not all(isinstance(item, dict) for item in index["relationships"]):
         return {}
-    return index
+    # An index written before the deterministic repairs existed is repaired here too, so a
+    # --brief-only run does not wait for the next full understand.py run (pure, no model call).
+    # No duration cap: the brief's scenes may be an edited timeline, plot times are source times.
+    return normalize_index(index)[0]
 
 
 def _format_consolidation(index):

package/lib/video-recap/skills/video-understanding/scripts/briefing/inputs.py

@@ -3,24 +3,18 @@
 import json
 from pathlib import Path
 
-from lib import CONFIG, file_identity
+from lib import (
+    CONFIG,
+    file_identity,
+    is_usable_overview_chunk,
+    offline_ignored_settings,
+    settings_match,
+)
 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.
+# Same literal as consolidate._ASR_SPAN_TOL; test_asr_span_tol_matches_across_files pins them.
 _ASR_SPAN_TOL = 0.05
 
-_MIMO_REJECTION_MARKERS = (
-    "request was rejected",
-    "considered high risk",
-    "high risk",
-    "content policy",
-    "cannot process",
-    "无法处理",
-    "内容审核",
-    "违规",
-)
-
 
 def _load_clean_asr(work_dir, asr_result):
     """Return consolidate.py's cleaned ASR segments, or None to fall back to raw asr_result.
@@ -70,15 +64,6 @@ def _load_clean_asr(work_dir, asr_result):
     return segments
 
 
-def _is_mimo_chunk_usable(content):
-    """A chunk is usable only if MiMo returned real analysis (not empty / a moderation refusal)."""
-    text = (content or "").strip()
-    if not text:
-        return False
-    low = text.lower()
-    return not any(marker in low for marker in _MIMO_REJECTION_MARKERS)
-
-
 def _mimo_video_settings():
     """Non-secret MiMo video-overview settings that affect generated content."""
     return {
@@ -139,7 +124,7 @@ def _mimo_overview_matches_current_inputs(overview, scenes, video_path=None):
     if not isinstance(chunks, list) or not all(
         isinstance(chunk, dict)
         and isinstance(chunk.get("content"), str)
-        and _is_mimo_chunk_usable(chunk["content"])
+        and is_usable_overview_chunk(chunk["content"])
         for chunk in chunks
     ):
         return False
@@ -153,7 +138,8 @@ 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 cached_keys == expected_keys
+    ignored = offline_ignored_settings(CONFIG["mimo_video_api_key"], "mimo_video_api_url")
+    return settings_match(overview.get("settings"), settings, ignored) and cached_keys == expected_keys
 
 
 def _load_mimo_overview_for_brief(work_dir, scenes, enabled=None, video_path=None):
@@ -242,10 +228,12 @@ def _format_optional_stage_warnings(
         work_dir, "consolidation.status.json"
     )
     if consolidation_status is not None and consolidation_status["enabled"]:
-        if consolidation_status["status"] == "failed":
+        if consolidation_status["status"] in {"failed", "skipped_no_key"}:
             warnings.append(
                 _optional_stage_warning(
-                    "consolidation", "failed", consolidation_status["message"]
+                    "consolidation",
+                    consolidation_status["status"],
+                    consolidation_status["message"],
                 )
             )
         elif consolidation_status.get("do_index") is True and not consolidation_index: