@oh-story/dsh 0.1.10 → 0.1.12

package/lib/video-recap/skills/video-script/scripts/brief_timeline.py

@@ -1,327 +0,0 @@
-"""Remap cut evidence and format output-timeline brief directives."""
-
-import json
-import math
-import re
-from pathlib import Path
-
-from lib import CONFIG, stable_hash
-
-
-def _parse_target_seconds(value):
-    """Parse a cut-mode target duration ("30m" / "600" / "1h5m" / "00:30:00") to seconds.
-
-    None or blank means the knob is unset (None). Any other value that does not parse to
-    a positive duration is a typo in user input and raises ValueError.
-    """
-    if value is None:
-        return None
-    if isinstance(value, (int, float)):
-        seconds = float(value)
-    else:
-        text = str(value).strip().lower()
-        if not text:
-            return None
-        if ":" in text:
-            parts = [float(p) for p in text.split(":")]
-            if len(parts) == 2:
-                seconds = parts[0] * 60 + parts[1]
-            elif len(parts) == 3:
-                seconds = parts[0] * 3600 + parts[1] * 60 + parts[2]
-            else:
-                raise ValueError(f"unparseable target duration: {value!r}")
-            if any(p < 0 for p in parts):
-                raise ValueError(f"unparseable target duration: {value!r}")
-        else:
-            factors = {"ms": 0.001, "s": 1, "m": 60, "h": 3600}
-            seconds = 0.0
-            pos = 0
-            for m in re.finditer(r"([0-9]+(?:\.[0-9]+)?)(ms|s|m|h)?", text):
-                if m.start() != pos:
-                    break
-                pos = m.end()
-                seconds += float(m.group(1)) * factors[m.group(2) or "s"]
-            if pos == 0 or pos != len(text):
-                raise ValueError(f"unparseable target duration: {value!r}")
-    if not seconds > 0:
-        raise ValueError(f"target duration must be positive: {value!r}")
-    return seconds
-
-
-def _format_research_directive(work_dir, substrate):
-    """A loud, actionable research-first directive — but ONLY when the substrate is too thin
-    for real commentary (no dialogue/story spine) and no background_research.json exists yet.
-
-    The narration's quality ceiling is how much story context the agent has: with only frame
-    descriptions it can only narrate pixels, so research the title FIRST (see
-    references/research-guide.md). Fires only for thin/empty substrate — NOT merely because a
-    title was given — so a dialogue-rich titled run is never nagged.
-    """
-    if (Path(work_dir) / "background_research.json").exists():
-        return []  # already researched; _format_background_research surfaces it
-    if substrate["level"] not in ("thin", "empty"):
-        return []  # rich enough to write from dialogue/spine; do not nag
-    context = CONFIG["context_info"].strip()
-    return [
-        "## ⚑ Research the story FIRST (do this before writing narration)",
-        "",
-        "Reason: the understanding substrate is thin — no dialogue/story spine, only frame",
-        "descriptions, so without research the narration can only describe pixels.",
-        "1. Pull the title/keywords from `--context`, the filename, or the user's description"
-        + (f" (context: {context})." if context else "."),
-        "2. Use any available web-search/browser tool to look up synopsis, characters, and",
-        "   relationships (see `references/research-guide.md`).",
-        "3. Write `work_dir/background_research.json`, then re-read this brief and write narration",
-        "   that names people and reads the picture through the plot.",
-        "4. If no tool/network or nothing found: skip — keep beats sparse and strictly grounded in",
-        "   the visible ASR/frame evidence rather than inventing drama.",
-        "",
-    ]
-
-
-def _load_cut_output_spans_for_brief(work_dir, *, required=False):
-    """Load fresh source→output spans for cut pass 2 brief evidence.
-
-    Pass 2 narration is authored against edited_source.mp4's OUTPUT timeline, so
-    ASR chunks and timeline_fusion must use the same OUTPUT clock. Before pass 2
-    (no edited_source.mp4 yet), callers may fall back to source-time evidence; once
-    pass 2 exists, missing/stale validated spans are a hard contract failure.
-    """
-
-    def fail(reason):
-        if required:
-            raise SystemExit(
-                "cut pass2 brief requires fresh clip_plan_validated.json with explicit "
-                f"source/output spans ({reason})"
-            )
-        return None
-
-    work_dir = Path(work_dir)
-    if not (work_dir / "edited_source.mp4").exists():
-        return None
-    validated_path = work_dir / "clip_plan_validated.json"
-    if not validated_path.exists():
-        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"))
-    ):
-        return fail("stale clip_plan_validated.json")
-    spans = []
-    for clip in plan["clips"]:
-        span = {
-            key: clip[key]
-            for key in ("source_start", "source_end", "output_start", "output_end")
-        }
-        if not all(math.isfinite(value) for value in span.values()):
-            return fail("non-finite clip span")
-        if span["source_end"] <= span["source_start"] or span["output_end"] <= span["output_start"]:
-            return fail("non-positive clip span")
-        spans.append(span)
-    return spans or fail("no clips")
-
-
-def _source_output_overlaps_for_brief(start, end, spans):
-    overlaps = []
-    for span in spans:
-        source_start = max(start, span["source_start"])
-        source_end = min(end, span["source_end"])
-        if source_end <= source_start:
-            continue
-        output_start = span["output_start"] + (source_start - span["source_start"])
-        output_end = span["output_start"] + (source_end - span["source_start"])
-        overlaps.append(
-            {
-                "source_start": source_start,
-                "source_end": source_end,
-                "output_start": output_start,
-                "output_end": output_end,
-            }
-        )
-    return overlaps
-
-
-def _remap_frame_facts_for_brief(frame_facts, overlap):
-    out = {}
-    for raw_ts, vals in frame_facts.items():
-        ts = float(raw_ts)
-        if not (overlap["source_start"] <= ts <= overlap["source_end"]):
-            continue
-        out_ts = overlap["output_start"] + (ts - overlap["source_start"])
-        out[f"{out_ts:.3f}"] = vals
-    return out
-
-
-def _remap_scenes_to_output_for_brief(scenes, spans):
-    out = []
-    for scene in scenes:
-        overlaps = _source_output_overlaps_for_brief(scene["start"], scene["end"], spans)
-        for part_idx, overlap in enumerate(overlaps):
-            item = dict(scene)
-            item["start"] = round(overlap["output_start"], 3)
-            item["end"] = round(overlap["output_end"], 3)
-            item["frame_facts"] = _remap_frame_facts_for_brief(
-                scene.get("frame_facts", {}), overlap
-            )
-            if len(overlaps) > 1:
-                item["scene_id"] = f"{scene['scene_id']}.{part_idx}"
-            out.append(item)
-    out.sort(key=lambda x: (x["start"], x["end"]))
-    return out
-
-
-def _remap_segments_to_output_for_brief(segments, spans):
-    out = []
-    for seg in segments:
-        for overlap in _source_output_overlaps_for_brief(seg["start"], seg["end"], spans):
-            item = dict(seg)
-            item["start"] = round(overlap["output_start"], 3)
-            item["end"] = round(overlap["output_end"], 3)
-            if "duration" in item:
-                item["duration"] = round(item["end"] - item["start"], 3)
-            out.append(item)
-    out.sort(key=lambda x: (x["start"], x["end"]))
-    return out
-
-
-def _remap_brief_evidence_to_output_timeline(
-    work_dir, scenes_analysis, asr_result, silence_periods, *, required=False
-):
-    spans = _load_cut_output_spans_for_brief(work_dir, required=required)
-    if not spans:
-        return scenes_analysis, asr_result, silence_periods
-    return (
-        _remap_scenes_to_output_for_brief(scenes_analysis, spans),
-        _remap_segments_to_output_for_brief(asr_result, spans),
-        _remap_segments_to_output_for_brief(silence_periods, spans),
-    )
-
-
-def _read_json(path, default):
-    """JSON artifact, or `default` when the optional file was never written."""
-    return json.loads(path.read_text(encoding="utf-8")) if path.exists() else default
-
-
-def _sentence_entry_anchors_for_brief(work_dir, edit_mode):
-    """Load sentence anchors and remap them to cut OUTPUT time when needed."""
-    work_dir = Path(work_dir)
-    anchors = [
-        dict(item)
-        for item in _read_json(
-            work_dir / "speech_boundary_anchors.json", {"sentence_anchors": []}
-        )["sentence_anchors"]
-    ]
-    if edit_mode != "cut" or not (work_dir / "edited_source.mp4").exists():
-        return anchors
-
-    spans = _load_cut_output_spans_for_brief(work_dir, required=True)
-    remapped = []
-    for anchor in anchors:
-        source_time = anchor["time"]
-        for span in spans:
-            if span["source_start"] - 0.05 <= source_time <= span["source_end"] + 0.05:
-                item = dict(anchor)
-                item["source_time"] = round(source_time, 3)
-                item["time"] = round(
-                    span["output_start"] + source_time - span["source_start"], 3
-                )
-                # Preserve the measured safe pause in OUTPUT time too, so cut-mode lint
-                # compares one clock.
-                source_pause_start = max(
-                    span["source_start"], min(anchor.get("pause_start", source_time - 0.12), source_time)
-                )
-                item["source_pause_start"] = round(source_pause_start, 3)
-                item["pause_start"] = round(
-                    span["output_start"] + source_pause_start - span["source_start"], 3
-                )
-                remapped.append(item)
-
-    speech_rows = [
-        row for row in _read_json(work_dir / "asr_result.json", []) if row["text"]
-    ]
-    quiet_rows = [
-        row
-        for row in _read_json(work_dir / "silence_periods.json", [])
-        if not row["has_speech"]
-    ]
-    out_payload = {
-        "schema_version": 2,
-        "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"))
-        ),
-        "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),
-    }
-    (work_dir / "speech_boundary_anchors_output.json").write_text(
-        json.dumps(out_payload, ensure_ascii=False, indent=2), encoding="utf-8"
-    )
-    return out_payload["sentence_anchors"]
-
-
-def _format_sentence_entry_anchors_for_brief(work_dir, edit_mode):
-    anchors = [
-        anchor
-        for anchor in _sentence_entry_anchors_for_brief(work_dir, edit_mode)
-        if anchor["confidence"] in {"high", "medium"}
-    ]
-    if not anchors:
-        return []
-    lines = [
-        "## 原声句末安全切入点",
-        "",
-        "这些时间是 ASR 句末标点与短声学停顿对齐后的旁白安全入口。旁白在原声已开始后切入时，"
-        "必须从其中一个点开始；否则会在 TTS 前被 `interrupts_source_sentence` 硬阻断。",
-        "- 调整方式：优先把 `start` 移到建议锚点；放不下时缩短文本、移动整块或删除该旁白，不能让脚本静默挪音频。",
-        '- 原声句子完整性是硬约束：切入块写 `"source_entry_policy": "sentence_boundary"`；'
-        "不存在 `intentional_interrupt` 绕过方式。没有后续可靠句末锚点时，移动、缩短或删除旁白块。",
-    ]
-    for anchor in anchors:
-        source_suffix = (
-            f" (SOURCE {anchor['source_time']:.2f}s)" if "source_time" in anchor else ""
-        )
-        text_tail = str(anchor.get("text_tail", "")).strip()
-        lines.append(
-            f"- {anchor['time']:.2f}s [{anchor['confidence']}]{source_suffix} {text_tail}".rstrip()
-        )
-    lines.append("")
-    return lines
-
-
-def _format_output_clip_list(work_dir):
-    """List the kept clips on the OUTPUT timeline (cut-first/narrate-second pass 2), so the
-    agent narrates against the real rendered cut instead of the source timeline."""
-    path = Path(work_dir) / "clip_plan_validated.json"
-    if not path.exists():
-        return []
-    plan = json.loads(path.read_text(encoding="utf-8"))
-    out = ["## Kept clips on the OUTPUT timeline", ""]
-    for c in plan["clips"]:
-        reason = c.get("reason", "")
-        out.append(
-            f"- OUTPUT {c['output_start']:.1f}–{c['output_end']:.1f}s ← SOURCE[{c.get('source_id', '0')}] "
-            f"{c['source_start']:.1f}–{c['source_end']:.1f}s (clip_id={c.get('clip_id', '?')})"
-            + (f" — {reason}" if reason else "")
-        )
-    out.append("")
-    return out if len(out) > 2 else []
-
-
-def _write_deslop_qc_requirements(work_dir):
-    """Write the stable deslop QC contract consumed by deslop_qc.py.
-
-    style_card_required defaults to False (advisory): a missing style_card.json is a
-    warning, not a render-blocking error. A future opt-in run can set it True to make
-    style_card.json a hard requirement — deslop_qc.py reads that field.
-    """
-    payload = {
-        "schema_version": 1,
-        "style_card_required": False,
-    }
-    path = Path(work_dir) / "deslop_qc_requirements.json"
-    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
-    return path

package/lib/video-recap/skills/video-script/scripts/narration.py

@@ -1,12 +0,0 @@
-"""Public narration-brief API for this self-contained skill."""
-
-from agent_brief import build_agent_brief
-from brief_context import assess_understanding_substrate
-from narration_lint import lint_narration, validate_narration_or_raise
-
-__all__ = [
-    "assess_understanding_substrate",
-    "build_agent_brief",
-    "lint_narration",
-    "validate_narration_or_raise",
-]

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

@@ -1,348 +0,0 @@
-"""Load and format research, consolidation, and substrate context."""
-
-import hashlib
-import json
-import re
-from pathlib import Path
-
-from lib import CONFIG
-
-
-def _load_background_research(work_dir):
-    """Load the agent-authored background_research.json ({} when absent)."""
-    path = Path(work_dir) / "background_research.json"
-    if not path.exists():
-        return {}
-    return json.loads(path.read_text(encoding="utf-8"))
-
-
-def _clip_text(text, limit):
-    """Collapse whitespace and clip. Research fields are optional, so None clips to ""."""
-    return re.sub(r"\s+", " ", str(text or "")).strip()[:limit]
-
-
-def _format_background_research(research, limit=1800):
-    """Render background_research.json into a bounded Story-context brief section."""
-    if not research:
-        return []
-    lines = [
-        "## Story context (from background_research.json)",
-        "",
-        "Research is context_only: use it for aliases/names/world terms and weak background only; do NOT reveal future plot or upgrade research-only relationships/causes into current on-screen facts without visual/ASR support.",
-        "",
-    ]
-    for key, label in (
-        ("synopsis", "Synopsis"),
-        ("worldbuilding", "Worldbuilding"),
-        ("episode_context", "Episode context"),
-    ):
-        value = _clip_text(research.get(key), 500)
-        if value:
-            lines.append(f"- {label}: {value}")
-
-    characters = research.get("characters", {})
-    if characters:
-        lines.append("- Characters:")
-        for name, desc in list(characters.items())[:12]:
-            lines.append(f"    - {_clip_text(name, 60)}: {_clip_text(desc, 160)}")
-
-    details = research.get("character_details", {})
-    if details:
-        lines.append("- Character details:")
-        for name, info in list(details.items())[:8]:
-            bits = []
-            aliases = [_clip_text(alias, 40) for alias in info.get("aliases", [])[:4]]
-            if aliases:
-                bits.append("别名 " + "/".join(aliases))
-            role = _clip_text(info.get("role"), 80)
-            if role:
-                bits.append(role)
-            rels = [_clip_text(rel, 80) for rel in info.get("relationships", [])[:4]]
-            if rels:
-                bits.append("；".join(rels))
-            if bits:
-                lines.append(f"    - {_clip_text(name, 60)}: {'; '.join(bits)}")
-
-    arcs = research.get("plot_arcs", [])
-    if arcs:
-        lines.append("- Plot arcs:")
-        for arc in arcs[:8]:
-            name = _clip_text(arc.get("name"), 80)
-            desc = _clip_text(arc.get("description"), 180)
-            status = _clip_text(arc.get("status"), 40)
-            if name or desc:
-                tail = f" [{status}]" if status else ""
-                lines.append(f"    - {name}: {desc}{tail}".rstrip())
-
-    notes = research.get("cultural_notes", [])
-    if notes:
-        lines.append("- Cultural notes:")
-        for note in notes[:6]:
-            item = _clip_text(note.get("item"), 80)
-            expl = _clip_text(note.get("explanation"), 160)
-            if item and expl:
-                lines.append(f"    - {item}: {expl}")
-            elif item or expl:
-                lines.append(f"    - {item or expl}")
-
-    lines.extend(
-        [
-            "",
-            'Use these names, relationships, and stakes in the narration instead of generic labels like "男子"/"白发女子".',
-            "",
-        ]
-    )
-    text = "\n".join(lines)
-    if len(text) <= limit:
-        return lines
-    clipped = text[:limit].rsplit("\n", 1)[0].rstrip()
-    return [
-        *clipped.splitlines(),
-        "",
-        "[Story context clipped to keep ASR/visual evidence in context]",
-        "",
-    ]
-
-
-def assess_understanding_substrate(
-    scenes_analysis, asr_result, *, has_story_context=False
-):
-    """Measure how much real signal the writing agent has to work with.
-
-    Recap quality collapses to generic 看图说话 when the agent has no story spine and
-    only literal frame descriptions to paraphrase. A spine is substantial dialogue
-    (ASR) OR researched/given story context — frame-fact VOLUME alone (a visually busy
-    but storyless clip, e.g. an anime whose dialogue ASR could not read) is NOT a spine,
-    so it must not grade as "rich"; otherwise the sparse-substrate warning, the research
-    directive, and the density relief never fire for exactly that cold-narration case.
-    """
-    asr_chars = sum(len(seg["text"]) for seg in asr_result)
-    scenes_with_facts = sum(1 for s in scenes_analysis if s.get("frame_facts"))
-    desc_lens = [len(s["description"]) for s in scenes_analysis]
-    avg_desc = sum(desc_lens) // len(desc_lens) if desc_lens else 0
-
-    has_asr = asr_chars >= 20
-    has_facts = scenes_with_facts > 0
-    has_story_spine = asr_chars >= 200 or bool(has_story_context)
-    if not has_asr and not has_facts and avg_desc < 25:
-        level = "empty"
-    elif (has_asr or has_facts) and has_story_spine:
-        level = "rich"
-    else:
-        level = "thin"
-    return {
-        "level": level,
-        "asr_chars": asr_chars,
-        "scene_count": len(scenes_analysis),
-        "scenes_with_frame_facts": scenes_with_facts,
-        "avg_description_len": avg_desc,
-        "has_story_context": bool(has_story_context),
-    }
-
-
-def _format_substrate_warning(assessment):
-    """Render a loud brief banner when the understanding substrate is weak."""
-    if assessment["level"] == "rich":
-        return []
-    if assessment["level"] == "empty":
-        head = "⚠️ UNDERSTANDING SUBSTRATE IS EMPTY — narration will be generic guesswork unless you fix this first."
-    else:
-        head = '⚠️ Understanding substrate is THIN — narration risks generic "看图说话" without more grounding.'
-    return [
-        head,
-        f"  ASR chars: {assessment['asr_chars']} | scenes: {assessment['scene_count']} | "
-        f"scenes with frame_facts: {assessment['scenes_with_frame_facts']} | avg description: {assessment['avg_description_len']} chars",
-        "  Before writing: do background research (write background_research.json with names/relationships/plot),",
-        "  lean on any --context provided, and use ASR dialogue + frame_facts as the factual spine.",
-        "  Do NOT invent plot. If you truly have nothing, keep beats sparse and factual rather than fabricating drama.",
-        "",
-    ]
-
-
-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")
-    return path
-
-
-def _format_asr_chunks_for_brief(chunks, max_chunks=24):
-    if not chunks:
-        return []
-    lines = [
-        "## ASR writing chunks (semantic windows)",
-        "",
-        "Use these chunks as the dialogue spine instead of swallowing the full transcript at once.",
-        "Full data: `asr_writing_chunks.json`.",
-        "",
-    ]
-    for chunk in chunks[:max_chunks]:
-        scene_ids = ",".join(str(sid) for sid in chunk["scene_ids"]) or "n/a"
-        text = chunk["text"]
-        if len(text) > 900:
-            text = text[:897] + "..."
-        lines.extend(
-            [
-                f"### ASR chunk {chunk['chunk_id'] + 1}: {chunk['start']:.1f}-{chunk['end']:.1f}s | scenes {scene_ids} | {chunk['char_count']} units",
-                text or "(empty transcript chunk)",
-                "",
-            ]
-        )
-    if len(chunks) > max_chunks:
-        lines.append(
-            f"... {len(chunks) - max_chunks} more chunks in `asr_writing_chunks.json`."
-        )
-        lines.append("")
-    return lines
-
-
-def _format_timeline_fusion_for_brief(fusion, max_items=40):
-    if not fusion:
-        return []
-    lines = [
-        "## Timeline fusion (VLM + ASR + quiet slots)",
-        "",
-        "This is the pre-aligned multimodal view. Use `narration_slots` when available; otherwise write ducked-bed beats around dialogue.",
-        "Full data: `timeline_fusion.json`.",
-        "",
-    ]
-    for item in fusion[:max_items]:
-        start, end = item["time_range"]
-        slot_text = (
-            ", ".join(
-                f"{slot['start']:.1f}-{slot['end']:.1f}s/{slot['char_budget']}字"
-                for slot in item["narration_slots"][:4]
-            )
-            or "none"
-        )
-        dialogue_text = (
-            "; ".join(
-                f"{seg['start']:.1f}-{seg['end']:.1f}s {seg['text'][:80]}"
-                for seg in item["dialogue_segments"][:3]
-                if seg["text"]
-            )
-            or "none"
-        )
-        lines.extend(
-            [
-                f"### Fusion scene {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}",
-                "",
-            ]
-        )
-    if len(fusion) > max_items:
-        lines.append(
-            f"... {len(fusion) - max_items} more fused scenes in `timeline_fusion.json`."
-        )
-        lines.append("")
-    return lines
-
-
-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)."""
-    work_dir = Path(work_dir)
-    path = work_dir / "understanding_index.json"
-    meta_path = work_dir / "understanding_index.json.meta.json"
-    if not path.exists() or not meta_path.exists():
-        return {}
-    try:
-        meta = json.loads(meta_path.read_text(encoding="utf-8"))
-        source_md5 = hashlib.md5(
-            (work_dir / "vlm_analysis.json").read_bytes()
-        ).hexdigest()
-    except (OSError, json.JSONDecodeError):
-        return {}
-    if not isinstance(meta, dict):
-        return {}
-    expected = {
-        "source_md5": source_md5,
-        "model": _consolidation_model(),
-        "prompt_md5": _index_prompt_fingerprint(),
-    }
-    if scenes_analysis:
-        expected["scene_count"] = len(scenes_analysis)
-    if not meta.items() >= expected.items():
-        return {}
-    try:
-        index = json.loads(path.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return {}
-    if not isinstance(index, dict) or not all(
-        isinstance(index.get(key), list)
-        for key in ("characters", "relationships", "plot_points", "entities")
-    ):
-        return {}
-    if not all(isinstance(item, dict) for item in index["characters"]):
-        return {}
-    if not all(isinstance(item, dict) for item in index["relationships"]):
-        return {}
-    return index
-
-
-def _format_consolidation(index):
-    """Render consolidate.py's understanding_index.json into a compact brief section.
-
-    plot_points/entities items are model output and may be bare strings or objects."""
-    if not index:
-        return []
-    lines = ["## Understanding index (from consolidate.py)", ""]
-    chars = index["characters"]
-    if chars:
-        lines.append("- Characters:")
-        for c in chars:
-            lines.append(
-                f"    - {c.get('name', '?')}: {str(c.get('description', '')).strip()}"
-            )
-    rels = index["relationships"]
-    if rels:
-        lines.append("- Relationships:")
-        for r in rels:
-            lines.append(
-                f"    - {r.get('a', '?')} — {r.get('relation', '?')} — {r.get('b', '?')}"
-            )
-    plot = index["plot_points"]
-    if plot:
-        lines.append("- Plot spine:")
-        lines.extend(
-            f"    {i + 1}. {p.get('text', p) if isinstance(p, dict) else p}"
-            for i, p in enumerate(plot)
-        )
-    ents = index["entities"]
-    if ents:
-        ent_names = [str(e.get("name", e) if isinstance(e, dict) else e) for e in ents]
-        lines.append(f"- Entities: {', '.join(ent_names)}")
-    lines.append("")
-    return lines