@oh-story/dsh 0.1.3 → 0.1.5

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

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""video-script validation entrypoint.
+
+Validate an agent-written narration.json against the local understanding index.
+Writes narration_lint.json and, in full mode, rewrites only normalized fields plus
+the measured overlaps_speech flag; authored start/end timing is preserved exactly.
+"""
+
+import argparse
+import json
+import math
+from pathlib import Path
+
+from lib import CONFIG, log, stable_hash
+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)
+
+    raw = _load(raw_plan)
+    validated = _load(validated_plan)
+    if isinstance(validated, dict) and validated.get(
+        "raw_plan_fingerprint"
+    ) == stable_hash(raw):
+        return validated
+    # Validation may run before the cut stage refreshes clip_plan_validated.json.
+    # Without a matching raw-plan provenance fingerprint, lint against the current
+    # raw plan even when mtimes are equal or misleading.
+    return raw
+
+
+def _validate_output_timeline_bounds(narration, output_duration, tolerance=0.05):
+    """Hard-gate 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.
+    """
+    try:
+        duration = float(output_duration)
+    except (TypeError, ValueError):
+        raise SystemExit(f"output_duration must be numeric, got {output_duration!r}")
+    if not math.isfinite(duration) or duration <= 0:
+        raise SystemExit(
+            f"output_duration must be finite and positive, got output_duration={duration:.3f}"
+        )
+    if not isinstance(narration, list):
+        return
+
+    problems = []
+    for idx, seg in enumerate(narration):
+        if not isinstance(seg, dict):
+            continue
+        try:
+            start = float(seg.get("start"))
+            end = float(seg.get("end"))
+        except (TypeError, ValueError):
+            continue
+        if not math.isfinite(start) or not math.isfinite(end):
+            problems.append(f"segment {idx} has non-finite time [{start!r},{end!r}]")
+            continue
+        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",
+    )
+    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. Derive speech ownership from the mapped output
+        # evidence, then persist that measured flag for voiceover/assemble instead of trusting JSON.
+        narration = measure_narration_speech_ownership(
+            narration, work_dir, mode="cut_output"
+        )
+        validate_narration_or_raise(
+            narration, None, clip_plan=None, mode="cut_output", work_dir=work_dir
+        )
+        if args.output_duration is None:
+            raise SystemExit("--output-duration is required when --mode cut_output")
+        _validate_output_timeline_bounds(narration, args.output_duration)
+        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
+        )
+        narration = _validate_narration_budget(narration, vlm_analysis)
+    else:
+        validate_narration_or_raise(
+            narration, vlm_analysis, clip_plan=None, mode="full", work_dir=work_dir
+        )
+        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/lib/video-recap/skills/video-understanding/SKILL.md

@@ -0,0 +1,75 @@
+---
+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`。
+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/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本不从其他技能目录读取文件；外部输入仅限命令显式传入的视频、参数与 `work_dir` 产物。
+
+## 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}]` 时间戳对白 |
+| `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 过薄时输出素材警告。
+- 不发布、不调度，只向 `work_dir` 写产物并停止。

package/lib/video-recap/skills/video-understanding/references/data-schema.md

@@ -0,0 +1,299 @@
+# 数据格式（中间 JSON）
+
+所有中间文件均在 pipeline 工作目录（work_dir/）下。
+
+## vlm_analysis.json
+
+每场景的 VLM 分析结果，数组格式：
+
+```json
+[
+  {
+    "scene_id": 1,
+    "start": 5.0,
+    "end": 15.0,
+    "description": "男子闯入房间",
+    "depth_analysis": "角色情绪分析...",
+    "frame_facts": {
+      "5.0": ["男子闯入房间, 头发蓬乱表情紧张"],
+      "10.0": ["男子俯身盯着床上男孩, 男孩睁眼惊醒"]
+    }
+  }
+]
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `scene_id` | int | 场景编号 |
+| `start` | float | 开始时间（秒） |
+| `end` | float | 结束时间（秒） |
+| `description` | string | 画面简述（≤80字） |
+| `depth_analysis` | string | 深层分析（情绪/关系/潜台词） |
+| `frame_facts` | object | 帧级事实，key 为时间戳字符串 |
+
+## asr_result.json
+
+语音转文字结果：
+
+```json
+[
+  {"start": 0.0, "end": 3.5, "text": "What are you doing here?"}
+]
+```
+
+## asr_writing_chunks.json
+
+由 CLI 在生成 `agent_narration_brief.md` 时自动写出。它把长 ASR 按句子边界拆成适合 Agent 消化的语义块；中文按字符计数，非 CJK 文本按词数计数，并尽量保留 scene 对齐。
+
+```json
+[
+  {
+    "chunk_id": 0,
+    "start": 0.0,
+    "end": 28.5,
+    "scene_ids": [0, 1],
+    "char_count": 642,
+    "text": "第一段对白……",
+    "segments": [
+      {"start": 0.0, "end": 3.5, "text": "第一句。", "char_count": 4}
+    ]
+  }
+]
+```
+
+## silence_periods.json
+
+静音窗口列表（适合放解说）：
+
+```json
+[
+  {"start": 2.0, "end": 8.5, "duration": 6.5, "has_speech": false}
+]
+```
+
+`has_speech` 标记该窗口是否与检测到的 ASR 语音重叠；下游（pipeline / narration）只把 `has_speech=false` 的窗口当作可放解说的安静窗口。
+
+## timeline_fusion.json
+
+由 CLI 在生成 brief 时自动写出。它把 VLM 场景、ASR 对白和静音窗口按时间轴 overlap 合并，减少写稿时手工推断“这一幕有没有对白/能不能插解说”的成本。
+
+```json
+[
+  {
+    "scene_id": 0,
+    "time_range": [0.0, 10.0],
+    "visual_description": "两人在门口对峙",
+    "depth_analysis": "关系紧张",
+    "frame_facts": {"1.0": ["女子回头"]},
+    "dialogue_segments": [
+      {"start": 2.0, "end": 4.0, "overlap_seconds": 2.0, "text": "你到底是谁"}
+    ],
+    "dialogue_overlap_seconds": 2.0,
+    "narration_slots": [
+      {"start": 5.0, "end": 7.0, "duration": 2.0, "char_budget": 5}
+    ],
+    "recommended_mode": "ducked-bed"
+  }
+]
+```
+
+## narration.json
+
+Agent 撰写的解说词。full 模式下使用原视频时间；**两阶段 cut 编排流程**在第二次暂停前已经剪出 `edited_source.mp4`，因此 `narration.json` 必须直接使用剪后成片的 OUTPUT 时间轴（0..成片总时长），不会再生成或消费 `narration_mapped.json`。只有旧版直接单阶段剪辑路径才会把原视频时间的 narration remap 成 `narration_mapped.json`：
+
+```json
+[
+  {"start": 2.5, "end": 7.0, "narration": "解说文本", "pause_after_ms": 250, "overlaps_speech": true}
+]
+```
+
+## narration_lint.json
+
+续跑验证 `narration.json` 时生成的预检结果。它检查写稿、时间安全和解说覆盖。`metrics` 为 full 模式下的诊断指标（cut 模式为空对象），不是要求命中某个旁白比例的创作配额；低覆盖 warning 应检查是否为有意的原声/沉默选择。
+
+```json
+{
+  "ok": false,
+  "error_count": 1,
+  "warning_count": 1,
+  "metrics": {
+    "segment_count": 12,
+    "narration_coverage": 0.68,
+    "narration_seconds": 61.2,
+    "timeline_seconds": 90.0,
+    "avg_block_chars": 48,
+    "original_block_count": 4
+  },
+  "errors": [
+    {"level": "error", "index": 2, "code": "time_overlap", "message": "Segment overlaps the previous narration segment"}
+  ],
+  "warnings": [
+    {"level": "warning", "index": 0, "code": "over_budget", "budget_chars": 28, "actual_chars": 42}
+  ]
+}
+```
+
+常见 code：`invalid_time`、`empty_narration`、`time_overlap`、`outside_clip_plan`、`over_budget`、`incomplete_sentence`、`slot_too_short`、`under_narrated`、`over_narrated`、`fragmented_beats`、`no_original_blocks`。
+
+## style_card.json（Agent 撰写，可选/按 brief 要求）
+
+`style_card.json` 是表达层契约：由 Agent 根据 `--style`、`--context`、素材证据、ASR 和用户偏好信号综合撰写。`--style` 是 freeform verbatim guidance（原样自由文本指导），不是枚举、preset、switch，也不是一组可穷举风格名；不要把它翻译成固定档位。它是当前版本的活动契约：用户对声音、节奏、字幕阅读或禁忌提出新反馈后，更新原文件并移除过期偏好，不要只改 `narration.json`。
+
+这个文件记录声音、节奏、回收意图和证据支撑的表达判断；字段可以随项目增减，下游只把它当 JSON object 读取，不要求固定键名。它不负责标题、封面、首句承诺或卖点包装。
+
+```json
+{
+  "voice": "冷静但有压迫感，少讲大道理，多用人物动作和台词里的证据推进",
+  "pacing": "前 15 秒紧凑建立冲突，每个 beat 连续说完一个思路；中段留原声喘息，结尾回收开头疑问",
+  "payoff_intent": "让观众先看到误会，再看到人物选择的代价",
+  "subtitle_read_posture": "TTS 保持连续口语，字幕按阅读宽度拆 cue，不用字幕换行切碎朗读",
+  "evidence_intent": ["优先引用画面动作", "关键转折保留原声"]
+}
+```
+
+## packaging_plan.json（Agent 撰写，可选）
+
+`packaging_plan.json` 是内容锁定后的可选包装层契约：标题、封面帧/视觉钩子、首句、观众承诺、卖点和发布包装信息。它帮助 review 判断“包装承诺”和正文前 15 秒是否对齐；不应反过来驱动故事取舍。
+
+它不是文风策略，不覆盖 `style_card.json` 的声音、节奏或表达规则；如果包装需要某个承诺，正文仍要用素材证据兑现。
+
+```json
+{
+  "title": "一句能对外展示的标题",
+  "cover_frame": {"time": 12.4, "reason": "人物第一次正面做出关键选择"},
+  "first_line": "开场第一句解说",
+  "viewer_promise": "观众看完会明白的冲突/反转/信息增量",
+  "selling_points": ["强冲突", "原声高光"],
+  "packaging_notes": "发布侧备注，不写文风规则"
+}
+```
+
+## deslop_qc_requirements.json（工具/brief 生成的运行契约）
+
+`deslop_qc_requirements.json` 是 tool/brief generated run contract：工具或 brief 生成本次运行的 QC 要求，供 `deslop_qc` 读取，不由 Agent 手写。字段为 `schema_version` 与 `style_card_required`。
+
+`style_card_required` 默认 `false`（advisory）：缺少 `style_card.json` 只是 warning，不阻断出片。将来的 opt-in 运行可把它设为 `true`，让 `style_card.json` 成为硬性要求——`deslop_qc` 只读这个字段判断缺少 `style_card.json` 是否是 blocker，不扫描 `agent_narration_brief.md` 的 prompt wording 来推断。如果 requirements 文件缺失或损坏，按 legacy/migration advisory 处理，不作为 hard failure。
+
+该契约不改变 `--style`：`--style` 仍是 freeform verbatim guidance，不增加固定风格档位。它也不改变 `deslop_qc` 边界：仍然是 report-only，不是 AIGC detector，不自动改写。
+
+最小示例：
+
+```json
+{
+  "schema_version": 1,
+  "style_card_required": false
+}
+```
+
+## deslop_qc.json（CLI 生成，报告型 QC）
+
+`deslop_qc.json` 由本地 deterministic scanner 生成，Agent 不手写。它只是 report-only QC：不是 AIGC detector，不判断文本是不是 AI 写的，不会自动改写。修改仍由 Agent/人工根据报告回到 `narration.json`、`style_card.json` 或字幕源里处理。
+
+报告分两层：
+
+- `blockers`：客观阻断项，会并入 `narration_lint.json` 的 error，例如 requirements 要求但缺少/损坏 `style_card.json`、破折号、占位符泄漏。
+- `advisories`：建议项，只提示可读性/口语化风险，例如模板化“不是……而是……”转折、套话密度、抽象总结词、解释链、比喻标记、过长段落；它们不自动阻断，也不自动改写。
+
+```json
+{
+  "ok": false,
+  "contract": "Local readability/QC report only: this is not an AIGC detector, does not claim AI-generation accuracy, and never rewrites text. Corrections remain human/agent rewrite work.",
+  "scanner": "deslop_qc.py",
+  "style_card_required": true,
+  "blocker_count": 1,
+  "advisory_count": 1,
+  "blockers": [
+    {"severity": "blocker", "code": "missing_style_card", "source": "style_card", "index": null, "message": "style_card.json is required by this expression/packaging run but is missing"}
+  ],
+  "advisories": [
+    {"severity": "advisory", "code": "cliche_density", "source": "narration", "index": null, "message": "套话/高频抽象词偏密，建议换成具体行动、选择和后果"}
+  ],
+  "metrics": {"segments_scanned": 12, "text_units": 860, "sentence_count": 38}
+}
+```
+
+## clip_plan.json
+
+cut 模式下 Agent 选择要保留的原片片段，数组或 `{ "clips": [...] }` 都可接受。默认片段不能重叠，避免同一原片时间映射到多个输出位置：
+
+```json
+{
+  "target_duration": "10m",
+  "clips": [
+    {"start": 12.0, "end": 38.0, "reason": "b01 | hook | knowledge: unknown→threat | POV=主角 | 保留倾听反应 | 入点=问题已问出 | 出点=沉默落地"}
+  ]
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `start` | float | 原视频片段开始秒数 |
+| `end` | float | 原视频片段结束秒数 |
+| `reason` | string | 选择该片段的剧情/信息原因 |
+
+## clip_plan_validated.json
+
+CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
+
+```json
+{
+  "clips": [
+    {
+      "clip_id": 0,
+      "source_start": 12.0,
+      "source_end": 38.0,
+      "output_start": 0.0,
+      "output_end": 26.0,
+      "duration": 26.0,
+      "reason": "b01 | hook | knowledge: unknown→threat | POV=主角 | 保留倾听反应 | 入点=问题已问出 | 出点=沉默落地"
+    }
+  ],
+  "total_duration": 26.0,
+  "target_duration": 600.0
+}
+```
+
+## narration_mapped.json
+
+仅旧版直接单阶段剪辑路径会生成。两阶段 cut 编排流程不使用它：Agent 在第二阶段直接按剪后成片 OUTPUT 时间轴写 `narration.json`。启用旧版路径时，`start/end` 已变成短视频输出时间，`source_start/source_end` 保留原视频时间：
+
+```json
+[
+  {
+    "start": 2.0,
+    "end": 7.0,
+    "source_start": 14.0,
+    "source_end": 19.0,
+    "source_clip_id": 0,
+    "narration": "解说文本"
+  }
+]
+```
+
+## background_research.json
+
+可选的背景调研结果（由 Agent 使用任意可用搜索/浏览方式整理）：
+
+```json
+{
+  "synopsis": "剧情概要",
+  "characters": {"角色名": "角色简介"},
+  "worldbuilding": "世界观设定",
+  "episode_context": "集数上下文",
+  "character_details": {
+    "角色名": {
+      "aliases": ["别名/昵称"],
+      "role": "主角|配角|反派|次要角色",
+      "relationships": ["与XX是夫妻", "与YY是师徒"]
+    }
+  },
+  "plot_arcs": [
+    {"name": "线索名称", "description": "简要描述", "status": "进行中|已解决|伏笔"}
+  ],
+  "cultural_notes": [
+    {"item": "文化梗/典故/时代背景", "explanation": "解释"}
+  ]
+}
+```
+
+> `character_details`、`plot_arcs`、`cultural_notes` 为（可选，新增）字段。仅含 `synopsis`、`characters`、`worldbuilding`、`episode_context` 四个原始字段的旧 JSON 仍然有效。

package/lib/video-recap/skills/video-understanding/references/prompt-templates.md

@@ -0,0 +1,37 @@
+# Prompt 模板
+
+> 本文件被 `load_prompt()` 按 `### NAME` 切片读取。当前 CLI 只读取 VLM 模板；解说词由 Agent 根据 `agent_narration_brief.md` 撰写。
+
+## 目录
+
+| 模板名 | 用途 | 使用阶段 |
+|--------|------|----------|
+| VLM_DEPTH_PROMPT | 场景画面深度分析 | VLM 分析 |
+
+### VLM_DEPTH_PROMPT
+仔细观察这些视频帧，分析这个场景。分三部分输出：
+
+【描述】
+不超过80字，描述画面中正在发生什么（场景、人物、动作、表情、文字、事件）。
+
+【帧标签】
+逐帧列出每帧可见的人物动作和物品关系。每帧一行，格式：
+时间点 | 该帧可见的关键动作（1-2个完整短句，包含谁在做什么、物品如何被使用，如有字幕/文字也一并列出）
+示例：
+5.0s | 男子闯入房间, 头发蓬乱表情紧张
+10.0s | 男子俯身盯着床上男孩, 男孩睁眼惊醒
+15.0s | 男孩从床上坐起双手抱住头上的瓷枕准备防御
+
+【深层分析】
+不超过180字，分析：
+1. 角色的真实情绪或心理状态（通过表情、肢体语言、眼神判断）
+2. 人物之间的关系动态（亲密、紧张、疏离、试探等）
+3. 从场景开头到结尾发生了什么变化（知识、权力、目标、关系或情绪）
+4. 谁的视角最能承载这次变化；说话者、倾听者或旁观者中，谁的反应最值得保留
+5. 对话背后的潜台词（他们没说出口但由可见证据支持的东西）
+
+要求：
+- 必须基于画面可见的证据推断，不做无根据的猜测
+- 不要用"象征""隐喻"等文学词汇
+- 用口语化表达："他明显是在试探她的反应"
+- 如果画面信息不足，直接说"信息不足"

package/lib/video-recap/skills/video-understanding/references/research-guide.md

@@ -0,0 +1,74 @@
+# 背景调研指南（可选）
+
+Agent 在跑视频理解（video-understanding）**之前**先做背景调研，确认作品名、角色关系、剧情背景或科普概念，写入 `work_dir/background_research.json`。理解阶段会把它并入 VLM 的画面分析上下文，让场景描述能直接叫出人物名字、带着剧情读画面，而不是把人都标成「黑衣男子」。**调研不是必需步骤**；没有浏览器工具、网络不可用或用户未提供明确片名时，直接跳过，不阻塞视频生成。
+
+## 工具选择
+
+使用当前环境里可用的任意检索方式即可，例如：
+
+- Codex / Claude 自带的联网搜索或网页浏览工具
+- 用户已经配置好的浏览器自动化或页面读取工具
+- 普通浏览器手动查找后把结果整理进 JSON
+- 已知资料、用户给的剧情背景或项目内已有文档
+
+## 通用流程
+
+1. 从 `--context`、文件名或用户描述里提取可搜索关键词。
+2. 搜索 1-3 个高价值问题，不要过度调研。
+3. 只记录对解说有帮助的事实：人物关系、剧情前提、世界观、当前集上下文、术语解释。
+4. 写入 `work_dir/background_research.json`。
+5. 如果查不到可靠信息，跳过并继续写 `narration.json`。
+
+## 按视频类型搜索策略
+
+### 短剧 / 电视剧
+
+| 搜索关键词 | 目标字段 |
+|-----------|---------|
+| `{作品名} 剧情 介绍 人物` | synopsis, characters |
+| `{作品名} 人物 关系` | characters |
+| `{作品名} 第{N}集 剧情` | episode_context |
+
+### 电影
+
+| 搜索关键词 | 目标字段 |
+|-----------|---------|
+| `{电影名} 剧情 简介` | synopsis |
+| `{电影名} 影评 解读` | cultural_notes |
+
+### 纪录片 / 科普视频
+
+| 搜索关键词 | 目标字段 |
+|-----------|---------|
+| `{主题} 背景 知识` | worldbuilding |
+| `{核心概念} 解释` | synopsis |
+| `{主题} 最新 进展` | cultural_notes |
+
+## 写入格式
+
+写入 `work_dir/background_research.json`，只填搜到的字段，未搜到的字段省略，不要写 `null` 或空字符串。
+
+```json
+{
+  "synopsis": "...",
+  "characters": {
+    "角色名": "简介或关系"
+  },
+  "worldbuilding": "...",
+  "episode_context": "...",
+  "cultural_notes": [
+    {"item": "...", "explanation": "..."}
+  ]
+}
+```
+
+## 错误处理
+
+| 场景 | 处理 |
+|------|------|
+| 没有浏览器 / 搜索工具 | 跳过调研，直接写解说词 |
+| 搜索无结果 | 换一组关键词重试一次，仍无结果则跳过 |
+| 结果互相矛盾 | 只使用用户提供的上下文或画面/ASR 可验证的信息 |
+| 信息可能剧透后续 | 只用于理解人物关系，不在解说里剧透用户没要求的后续剧情 |
+
+**原则**：背景资料只能补上下文，不能替代 `vlm_analysis.json` / `asr_result.json` 里的画面和对白证据。