@lemoncat7/dsh-partner 2.8.1 → 2.8.3

package/resources/skills/video-recap-production/upstream/skills/video-script/scripts/review_runner.py

@@ -0,0 +1,186 @@
+"""Run narration review and write its advisory artifacts."""
+
+import argparse
+
+import json
+
+
+from pathlib import Path
+
+from lib import CONFIG, log, api_call
+
+from evidence_bundle import build_evidence_bundle
+from review_grounding import (
+    _load_cut_clip_spans,
+    _load_required,
+    _load_review_grounding,
+    remap_grounding_to_output_timeline,
+)
+from review_response import (
+    _chunk_evidence_bundle,
+    _load_review_research_context,
+    _merge_chunk_reviews,
+    _write_grounding_qc,
+    build_review_messages,
+    format_review_md,
+    parse_review_response,
+)
+
+EVIDENCE_CONTRACT_VERSION = 1
+
+COVERAGE_POLICY_VERSION = "coverage_policy_v1"
+
+
+def review_narration(work_dir, *, timeline="source", strict_evidence=False):
+    work_dir = Path(work_dir)
+    narration = _load_required(work_dir, "narration.json", "先写解说草稿再评审")
+    vlm_analysis, asr_result = _load_review_grounding(work_dir)
+    warnings = []
+    if timeline == "cut_output":
+        spans = _load_cut_clip_spans(work_dir)
+        if not spans:
+            msg = "cut_output review missing/stale clip_plan_validated.json; advisory fail-open, no strong OUTPUT-clock facts"
+            if strict_evidence:
+                raise SystemExit(msg)
+            warnings.append(msg)
+            vlm_analysis, asr_result = [], []
+        else:
+            vlm_analysis, asr_result = remap_grounding_to_output_timeline(
+                vlm_analysis, asr_result, spans
+            )
+    elif timeline != "source":
+        raise SystemExit(f"unknown review timeline: {timeline}")
+
+    bundle = build_evidence_bundle(
+        vlm_analysis,
+        asr_result,
+        narration,
+        timeline=timeline,
+        research=_load_review_research_context(work_dir),
+        warnings=warnings,
+    )
+    chunk_reviews = []
+    chunks = _chunk_evidence_bundle(bundle)
+    for chunk in chunks:
+        messages = build_review_messages(
+            narration,
+            vlm_analysis,
+            asr_result,
+            work_dir=work_dir,
+            evidence_bundle=chunk,
+        )
+        resp = api_call(
+            {
+                "model": CONFIG["vlm_model"],
+                "messages": messages,
+                "max_tokens": 2000 if len(chunks) == 1 else 1600,
+                "temperature": 0,
+                "seed": 7 + chunk["chunk_index"],
+            }
+        )
+        content = ""
+        try:
+            content = resp["choices"][0]["message"]["content"]
+        except (KeyError, IndexError, TypeError):
+            log("评审 API 返回结构异常")
+        parsed = parse_review_response(content)
+        parsed["chunk_index"] = chunk["chunk_index"]
+        parsed["chunk_count"] = chunk["chunk_count"]
+        chunk_reviews.append(parsed)
+    review = _merge_chunk_reviews(chunk_reviews)
+    if warnings:
+        review["warnings"] = list(warnings)
+    review["evidence_contract"] = {
+        "schema_version": EVIDENCE_CONTRACT_VERSION,
+        "timeline": timeline,
+        "clock": bundle["clock"],
+        "coverage_policy_version": COVERAGE_POLICY_VERSION,
+        "selected_ranges": bundle["coverage"]["selected_ranges"],
+        "chunk_count": len(chunks),
+        "warnings": warnings,
+    }
+    _write_grounding_qc(work_dir, review, bundle, timeline=timeline)
+
+    (work_dir / "narration_review.json").write_text(
+        json.dumps(review, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    (work_dir / "narration_review.md").write_text(
+        format_review_md(review), encoding="utf-8"
+    )
+    n_err = sum(1 for f in review["findings"] if f["severity"] == "error")
+    log(
+        f"解说评审完成: {review['verdict']} | {len(review['findings'])} 条意见（error {n_err}）"
+    )
+    return review
+
+
+def _auto_timeline(work_dir):
+    """Default the grounding timeline so a manual `review.py --work-dir` matches what the
+    orchestrator does: cut_output when narration.json is in the cut OUTPUT timeline, else
+    source. Without this, reviewing a cut narration on the default 'source' timeline compares
+    OUTPUT-time narration against SOURCE-time evidence and floods false-positive 'hallucination'
+    findings.
+
+    Detection is authoritative-first: the orchestrator records the run's edit_mode in
+    recap_run_manifest.json. In orchestrated cut mode narration.json is OUTPUT time; in full
+    mode it is SOURCE time. Trusting edit_mode is correct even when stale cut artifacts from a
+    prior run linger in a reused work_dir. Only when no manifest is present (standalone review
+    or a hand-built work_dir) do we fall back to artifact sniffing: a rendered cut
+    (clip_plan_validated.json + edited_source.mp4) means narration.json is OUTPUT time."""
+    work_dir = Path(work_dir)
+    manifest = work_dir / "recap_run_manifest.json"
+    if manifest.exists():
+        try:
+            mode = (
+                json.loads(manifest.read_text(encoding="utf-8"))
+                .get("settings", {})
+                .get("edit_mode")
+            )
+        except (ValueError, OSError):
+            mode = None
+        if mode == "cut":
+            return "cut_output"
+        if mode:  # "full" or any non-cut mode → narration.json is source time
+            return "source"
+    has_cut = (work_dir / "clip_plan_validated.json").exists() and (
+        work_dir / "edited_source.mp4"
+    ).exists()
+    return "cut_output" if has_cut else "source"
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Review an agent-written narration.json for quality (LLM-as-judge)."
+    )
+    ap.add_argument("--work-dir", required=True)
+    ap.add_argument(
+        "--timeline",
+        choices=["source", "cut_output"],
+        default=None,
+        help="grounding timeline for narration.json; DEFAULT auto-detects cut_output when a "
+        "validated cut (clip_plan_validated.json + edited_source.mp4) is present, else source. "
+        "cut_output remaps source VLM/ASR to the cut output timeline via clip_plan_validated.json",
+    )
+    ap.add_argument(
+        "--strict-evidence",
+        action="store_true",
+        help="block instead of advisory fail-open when required cut-output evidence mapping is missing/stale",
+    )
+    args = ap.parse_args()
+    timeline = args.timeline or _auto_timeline(args.work_dir)
+    if args.timeline is None and timeline != "source":
+        log(f"评审 grounding 时间轴自动判定为 {timeline}（检测到已校验的剪辑产物）")
+    review = review_narration(
+        args.work_dir, timeline=timeline, strict_evidence=args.strict_evidence
+    )
+    print(
+        json.dumps(
+            {
+                "status": "reviewed",
+                "verdict": review["verdict"],
+                "findings": len(review["findings"]),
+                "review": str(Path(args.work_dir) / "narration_review.md"),
+            },
+            ensure_ascii=False,
+        )
+    )

package/resources/skills/video-recap-production/upstream/skills/video-script/scripts/speech_ownership.py

@@ -0,0 +1,143 @@
+"""Load measured source-speech evidence and classify narration ownership."""
+
+import json
+from pathlib import Path
+
+from lib import CONFIG, file_identity
+
+
+def _empty_evidence(mode):
+    return {
+        "anchors": [],
+        "speech_spans": [],
+        "quiet_windows": [],
+        "require_measured": mode == "cut_output",
+    }
+
+
+def _read_json(path):
+    """JSON artifact, or None when the optional file was never written."""
+    return json.loads(path.read_text(encoding="utf-8")) if path.exists() else None
+
+
+def _output_payload_is_current(payload, work_dir):
+    plan_path = Path(work_dir) / "clip_plan_validated.json"
+    return (
+        payload is not None
+        and plan_path.exists()
+        and payload["clip_plan_identity"] == file_identity(plan_path)
+    )
+
+
+def load_source_sentence_evidence(work_dir, mode="full"):
+    """Load sentence boundaries plus speech/quiet spans on the narration clock."""
+    if work_dir is None:
+        return _empty_evidence(mode)
+    work_dir = Path(work_dir)
+    if mode == "full":
+        payload = _read_json(work_dir / "speech_boundary_anchors.json") or {
+            "sentence_anchors": []
+        }
+        speech_spans = [
+            row for row in _read_json(work_dir / "asr_result.json") or [] if row["text"]
+        ]
+        quiet_windows = [
+            row
+            for row in _read_json(work_dir / "silence_periods.json") or []
+            if not row["has_speech"]
+        ]
+    else:
+        payload = _read_json(work_dir / "speech_boundary_anchors_output.json")
+        if mode == "cut_output" and not _output_payload_is_current(payload, work_dir):
+            return _empty_evidence(mode)
+        if payload is None:
+            payload = {"sentence_anchors": [], "speech_spans": [], "quiet_windows": []}
+        speech_spans = payload["speech_spans"]
+        quiet_windows = payload["quiet_windows"]
+    anchors = [
+        anchor
+        for anchor in payload["sentence_anchors"]
+        if anchor["confidence"] in {"high", "medium"}
+    ]
+    return {
+        "anchors": sorted(anchors, key=lambda item: item["time"]),
+        "speech_spans": speech_spans,
+        "quiet_windows": quiet_windows,
+        "require_measured": mode == "cut_output",
+    }
+
+
+def _merged_intervals(start, end, rows):
+    intervals = sorted(
+        (max(start, row["start"]), min(end, row["end"]))
+        for row in rows
+        if row["end"] > start and row["start"] < end
+    )
+    merged = []
+    for left, right in intervals:
+        if right <= left:
+            continue
+        if merged and left <= merged[-1][1]:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], right))
+        else:
+            merged.append((left, right))
+    return merged
+
+
+def _interval_overlap(start, end, rows):
+    return sum(right - left for left, right in _merged_intervals(start, end, rows))
+
+
+def _speech_overlap_excluding_quiet(start, end, speech, quiet):
+    speech_intervals = _merged_intervals(start, end, speech)
+    quiet_intervals = _merged_intervals(start, end, quiet)
+    overlap = sum(right - left for left, right in speech_intervals)
+    for speech_left, speech_right in speech_intervals:
+        overlap -= sum(
+            max(0.0, min(speech_right, quiet_right) - max(speech_left, quiet_left))
+            for quiet_left, quiet_right in quiet_intervals
+        )
+    return max(0.0, overlap)
+
+
+def segment_overlaps_source_speech(seg, evidence):
+    """Classify aggregate mix ownership across the complete narration interval."""
+    start, end = seg["start"], seg["end"]
+    quiet = evidence["quiet_windows"]
+    quiet_min = max(0.3, (end - start) * CONFIG["quiet_overlap_min_ratio"])
+    speech = evidence["speech_spans"]
+    if speech:
+        return _speech_overlap_excluding_quiet(start, end, speech, quiet) > 0.05
+    if quiet and _interval_overlap(start, end, quiet) >= quiet_min:
+        return False
+    if evidence["anchors"] or evidence["require_measured"]:
+        return True
+    return bool(seg.get("overlaps_speech", True))
+
+
+def entry_overlaps_source_speech(start, evidence, *, authored_overlap=True, tolerance=0.05):
+    """Classify the entry instant; later quiet time cannot erase an unsafe start."""
+    if any(
+        row["start"] - tolerance <= start <= row["end"] + tolerance
+        for row in evidence["quiet_windows"]
+    ):
+        return False
+    if any(
+        row["start"] - tolerance <= start < row["end"] - tolerance
+        for row in evidence["speech_spans"]
+    ):
+        return True
+    if evidence["speech_spans"]:
+        return False
+    if evidence["anchors"] or evidence["require_measured"]:
+        return True
+    return bool(authored_overlap)
+
+
+def measure_narration_speech_ownership(narration, work_dir, mode="full"):
+    """Return narration copies with aggregate ownership derived from evidence."""
+    evidence = load_source_sentence_evidence(work_dir, mode=mode)
+    return [
+        {**seg, "overlaps_speech": segment_overlaps_source_speech(seg, evidence)}
+        for seg in narration
+    ]

package/resources/skills/video-recap-production/upstream/skills/video-script/scripts/timeline_fusion.py

@@ -0,0 +1,108 @@
+"""Fuse scenes, ASR, and quiet windows for narration planning."""
+
+from lib import CONFIG
+from agent_text import _overlap_seconds, _recommended_char_budget
+from narration_lint import _validate_narration_budget
+
+
+def _quiet_windows(silence_periods):
+    return [qp for qp in silence_periods if not qp["has_speech"]]
+
+
+def _align_narration_to_quiet(narration, scenes_analysis, silence_periods):
+    """Recompute overlaps_speech from real quiet windows; keep the agent's timing.
+
+    The dense continuous-bed design places narration ON the pictured beat over a
+    ducked original bed, so segments are never relocated into silence gaps. Only
+    the overlaps_speech flag that the ducking stage consumes is corrected, leaving
+    the agent's start/end (and text) intact.
+
+    Budget/dedup runs FIRST so a dedup-merged beat's overlaps_speech reflects its
+    extended timing, not its original shorter span.
+    """
+    aligned = _validate_narration_budget(narration, scenes_analysis)
+    quiet_windows = _quiet_windows(silence_periods)
+    quiet_ratio_min = CONFIG["quiet_overlap_min_ratio"]
+    for n in aligned:
+        seg_dur = n["end"] - n["start"]
+        quiet_overlap = sum(
+            _overlap_seconds(n["start"], n["end"], qw["start"], qw["end"])
+            for qw in quiet_windows
+        )
+        n["overlaps_speech"] = quiet_overlap < max(0.3, seg_dur * quiet_ratio_min)
+    return aligned
+
+
+def _scene_asr_lines(asr_result, scene):
+    lines = []
+    for seg in asr_result:
+        if scene["start"] < seg["end"] and scene["end"] > seg["start"] and seg["text"]:
+            lines.append(f"    [{seg['start']:.1f}-{seg['end']:.1f}] {seg['text']}")
+    return lines
+
+
+def _quiet_windows_for_scene(silence_periods, scene):
+    windows = []
+    for qp in _quiet_windows(silence_periods):
+        if qp["start"] < scene["end"] and qp["end"] > scene["start"]:
+            start = max(qp["start"], scene["start"])
+            end = min(qp["end"], scene["end"])
+            if end > start:
+                windows.append((start, end))
+    return windows
+
+
+def _build_timeline_fusion(scenes, asr_segments, silence_periods):
+    """Fuse VLM scenes, ASR dialogue and quiet narration slots on one timeline."""
+    fusion = []
+    quiet_windows = _quiet_windows(silence_periods)
+    for scene in scenes:
+        start, end = scene["start"], scene["end"]
+        dialogue_segments = []
+        dialogue_overlap = 0.0
+        for seg in asr_segments:
+            overlap = _overlap_seconds(start, end, seg["start"], seg["end"])
+            if overlap <= 0:
+                continue
+            dialogue_overlap += overlap
+            dialogue_segments.append(
+                {
+                    "start": round(seg["start"], 2),
+                    "end": round(seg["end"], 2),
+                    "overlap_seconds": round(overlap, 2),
+                    "text": seg["text"],
+                }
+            )
+
+        narration_slots = []
+        for window in quiet_windows:
+            overlap = _overlap_seconds(start, end, window["start"], window["end"])
+            if overlap <= 0:
+                continue
+            slot_start = max(start, window["start"])
+            slot_end = min(end, window["end"])
+            narration_slots.append(
+                {
+                    "start": round(slot_start, 2),
+                    "end": round(slot_end, 2),
+                    "duration": round(slot_end - slot_start, 2),
+                    "char_budget": _recommended_char_budget(slot_start, slot_end),
+                }
+            )
+
+        fusion.append(
+            {
+                "scene_id": scene["scene_id"],
+                "time_range": [round(start, 2), round(end, 2)],
+                "visual_description": scene["description"],
+                "depth_analysis": scene.get("depth_analysis", ""),
+                "frame_facts": scene.get("frame_facts", {}),
+                "dialogue_segments": dialogue_segments,
+                "dialogue_overlap_seconds": round(dialogue_overlap, 2),
+                "narration_slots": narration_slots,
+                "recommended_mode": "quiet-slot"
+                if narration_slots and dialogue_overlap < (end - start) * 0.4
+                else "ducked-bed",
+            }
+        )
+    return fusion

package/resources/skills/video-recap-production/upstream/skills/video-script/scripts/validate.py

@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""video-script validation entrypoint.
+
+Validate an agent-written narration.json against the local understanding index.
+Legacy full mode performs budget cleanup/deduplication and derives speech ownership.
+Protected mode keeps the approved timeline and metadata exact except for measured
+``overlaps_speech`` ownership.
+"""
+
+import argparse
+import json
+import math
+from pathlib import Path
+
+from lib import CONFIG, log
+from narration_lint import (
+    _validate_narration_budget,
+    validate_narration_or_raise,
+)
+from speech_ownership import measure_narration_speech_ownership
+from timeline_fusion import _align_narration_to_quiet
+
+
+def _load(path):
+    path = Path(path)
+    return json.loads(path.read_text(encoding="utf-8")) if path.exists() else None
+
+
+def _load_cut_clip_plan(work_dir):
+    raw_plan = Path(work_dir) / "clip_plan.json"
+    validated_plan = Path(work_dir) / "clip_plan_validated.json"
+    if not validated_plan.exists():
+        return _load(raw_plan)
+    if not raw_plan.exists():
+        return _load(validated_plan)
+
+    # Validation may run before the cut stage refreshes clip_plan_validated.json;
+    # a validated plan older than the raw plan is stale, so lint against the raw plan.
+    if validated_plan.stat().st_mtime_ns >= raw_plan.stat().st_mtime_ns:
+        return _load(validated_plan)
+    return _load(raw_plan)
+
+
+def _validate_output_timeline_bounds(narration, duration, tolerance=0.05):
+    """Hard-gate lint-validated cut_output narration against the rendered output timeline.
+
+    cut_output narration is authored in edited_source.mp4 time. If any segment falls outside
+    that media duration, fail before TTS/render instead of spending time on unusable audio.
+    """
+    if not math.isfinite(duration) or duration <= 0:
+        raise SystemExit(
+            f"output_duration must be finite and positive, got output_duration={duration:.3f}"
+        )
+
+    problems = []
+    for idx, seg in enumerate(narration):
+        start, end = seg["start"], seg["end"]
+        if end <= -tolerance or start >= duration + tolerance:
+            problems.append(
+                f"segment {idx} [{start:.3f},{end:.3f}] fully outside output_duration={duration:.3f}"
+            )
+            continue
+        if start < -tolerance:
+            problems.append(
+                f"segment {idx} start={start:.3f} before output timeline (output_duration={duration:.3f})"
+            )
+        if end > duration + tolerance:
+            problems.append(
+                f"segment {idx} end={end:.3f} exceeds output_duration={duration:.3f}"
+            )
+    if problems:
+        raise SystemExit(
+            "cut_output narration exceeds rendered output timeline: "
+            + "; ".join(problems)
+        )
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Validate + align agent-written narration.json."
+    )
+    ap.add_argument("--work-dir", required=True)
+    ap.add_argument("--mode", default="full", choices=["full", "cut", "cut_output"])
+    ap.add_argument(
+        "--output-duration",
+        type=float,
+        default=None,
+        help="cut_output: rendered edited_source.mp4 duration in seconds",
+    )
+    ap.add_argument(
+        "--preserve-approved-text",
+        action="store_true",
+        help="validate approved narration without rewriting, truncating, merging, or reordering it",
+    )
+    args = ap.parse_args()
+
+    work_dir = Path(args.work_dir)
+    CONFIG["edit_mode"] = args.mode
+    narration_path = work_dir / "narration.json"
+    narration = _load(narration_path)
+    if narration is None:
+        raise SystemExit(f"缺少 {narration_path}；请先按 video-script 规则写解说词")
+    vlm_analysis = _load(work_dir / "vlm_analysis.json")
+    silence_periods = _load(work_dir / "silence_periods.json") or []
+    if args.mode == "cut_output":
+        # Two-pass cut: narration is authored in OUTPUT time against edited_source.mp4 — there is
+        # no source-time clip membership check. Lint the authored shape first, then derive speech
+        # ownership from the mapped output evidence and persist that measured flag for
+        # voiceover/assemble instead of trusting JSON.
+        report = validate_narration_or_raise(
+            narration, None, clip_plan=None, mode="cut_output", work_dir=work_dir,
+            require_chronological=args.preserve_approved_text,
+        )
+        narration = measure_narration_speech_ownership(
+            narration, work_dir, mode="cut_output"
+        )
+        try:
+            if args.output_duration is None:
+                raise SystemExit("--output-duration is required when --mode cut_output")
+            _validate_output_timeline_bounds(narration, args.output_duration)
+        except SystemExit as exc:
+            report["errors"].append({
+                "level": "error",
+                "index": None,
+                "code": "invalid_output_timeline",
+                "message": str(exc),
+            })
+            report["ok"] = False
+            report["error_count"] = len(report["errors"])
+            (work_dir / "narration_lint.json").write_text(
+                json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8"
+            )
+            raise
+        narration_path.write_text(
+            json.dumps(narration, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+    elif args.mode == "cut":
+        clip_plan = _load_cut_clip_plan(work_dir)
+        validate_narration_or_raise(
+            narration, vlm_analysis, clip_plan=clip_plan, mode="cut", work_dir=work_dir
+        )
+        if not args.preserve_approved_text:
+            narration = _validate_narration_budget(narration, vlm_analysis)
+    else:
+        validate_narration_or_raise(
+            narration, vlm_analysis, clip_plan=None, mode="full", work_dir=work_dir,
+            require_chronological=args.preserve_approved_text,
+        )
+        if args.preserve_approved_text:
+            narration = measure_narration_speech_ownership(
+                narration, work_dir, mode="full"
+            )
+        else:
+            narration = _align_narration_to_quiet(
+                narration, vlm_analysis, silence_periods
+            )
+        narration_path.write_text(
+            json.dumps(narration, ensure_ascii=False, indent=2), encoding="utf-8"
+        )
+
+    log(f"解说词验证完成: {len(narration)} 段")
+    print(
+        json.dumps(
+            {
+                "status": "validated",
+                "segments": len(narration),
+                "lint": str(work_dir / "narration_lint.json"),
+            },
+            ensure_ascii=False,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

package/resources/skills/video-recap-production/upstream/skills/video-understanding/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: video-understanding
+user-invocable: false
+description: >
+ 把视频分析为结构化理解索引：场景检测、ASR 转写、逐场景 VLM 观察、静音窗口、融合时间线和写作 brief。
+ 用于理解、索引或总结视频，也作为后续创作前的分析阶段。输入视频文件；输出 scenes.json、
+ asr_result.json、vlm_analysis.json、silence_periods.json、timeline_fusion.json、agent_narration_brief.md。
+ 触发词：视频理解、视频分析、视频索引、video understanding、analyze video、看懂视频。
+---
+
+## 1. 定位
+
+本技能把源视频转成 Agent 与下游阶段可读取的理解索引。它的创作角色是**素材观察员 / 场记**，不是导演：
+
+- 先观察，再解释；事实与推断分开。
+- 除了“发生了什么”，还要让下游看见知识、权力、目标、关系或情绪在哪一刻变化。
+- 标出由谁的 POV 承载变化、哪个反应或表演不可替代，以及哪里存在完整台词/动作的自然剪辑边界。
+- 证据不足时保留不确定性，不制造戏剧结论。
+
+## 2. 处理阶段
+
+1. **场景检测**：写 `scenes.json`，包含切点、时长和废片段过滤结果。
+2. **抽帧**：为视觉分析提取代表帧。
+3. **ASR**：通过 `mimo-v2.5-asr` 写粗分段对白 `asr_result.json`，并写
+   `asr_timing_evidence.json` 说明可用性、有限时间精度与文本修正来源。
+4. **静音检测**：写 `silence_periods.json`，标注安静窗口与 `has_speech`。
+5. **VLM 观察**：写 `vlm_analysis.json`，包含场景描述、深层分析和 `frame_facts`。
+6. **时间线融合与创作 brief**：写 `timeline_fusion.json`、`asr_writing_chunks.json` 和 `agent_narration_brief.md`。
+
+各阶段只有在输出产物与 provenance sidecar 同时匹配当前视频及影响结果的设置时才会复用；`--force` 强制重算。
+
+## 3. 环境要求
+
+```bash
+# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
+export MIMO_API_KEY=***
+```
+
+ASR 使用 `mimo-v2.5-asr`；VLM 使用 `mimo-v2.5`。`--skip-asr` 可跳过对白转写，但完整理解仍需要 `MIMO_API_KEY` 运行 VLM。`--mimo-video-overview` 可开启按场景块的视频概览。
+
+若 `work_dir/background_research.json` 存在，本技能会把剧情梗概和角色名折入 VLM 上下文；`--context` 可补充一条简短提示。
+
+下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。
+
+## 4. 运行命令
+
+```bash
+python3 scripts/understand.py <video> --work-dir <work_dir> \
+  [--context "节目名/角色名"] [--scene-threshold 0.1] [--skip-asr] [--mimo-video-overview] [--force]
+```
+
+## 5. 输出契约
+
+| 文件 | 内容 |
+|------|------|
+| `scenes.json` | 场景切点、起止时间与时长 |
+| `asr_result.json` | `[{start, end, text}]` 时间戳对白 |
+| `asr_timing_evidence.json` | ASR 可用性状态、粗窗口精度、glossary 前后文本，以及它所描述的源视频/音频/结果文件（路径存在性 + size/mtime） |
+| `vlm_analysis.json` | 逐场景描述、深层分析与 `frame_facts` |
+| `silence_periods.json` | `[{start, end, duration, has_speech}]` 安静窗口 |
+| `timeline_fusion.json` | VLM、ASR 与静音信息的统一时间线 |
+| `asr_writing_chunks.json` | 按句界和场景切分的 ASR 写作块 |
+| `agent_narration_brief.md` | Agent 首先阅读的创作简报 |
+
+后续写作阶段根据创作简报与索引制定方案并写 `narration.json`。
+
+## 6. 参考资料
+
+- 背景调研：`references/research-guide.md`，产出 `background_research.json`。
+- JSON 结构：`references/data-schema.md`。
+
+## 7. 能力边界
+
+- 不写解说词，也不做解说评分；只负责生成理解索引与创作简报。
+- 不编造信号无法支持的剧情；当 ASR / VLM 过薄时输出素材警告。
+- MiMo ASR 的 `start/end` 是固定分片形成的**粗窗口**，不是词级对齐；空文本只表示原因未知，
+  不能当作已证实静音。`asr_timing_evidence.json` 的状态字段见 `references/data-schema.md`。