用途：把源视频转成 Agent 与下游阶段可读取的理解索引，角色是素材观察员/场记而非导演，先观察再解释，事实与推断分开，证据不足时保留不确定性。
主要能力与处理阶段：场景检测写 scenes.json（切点、时长、废片段过滤）；抽帧提取代表帧；ASR 通过 mimo-v2.5-asr 写粗分段对白 asr_result.json 与 asr_timing_evidence.json；静音检测写 silence_periods.json；VLM 观察写 vlm_analysis.json（场景描述、深层分析、frame_facts）；时间线融合与创作 brief 写 timeline_fusion.json、asr_writing_chunks.json、agent_narration_brief.md。各阶段产物与 provenance sidecar 匹配当前视频及设置时才复用，--force 强制重算。
环境与用法：需 ffmpeg（brew install ffmpeg | apt install ffmpeg | choco install ffmpeg）并设置 export MIMO_API_KEY=***。运行：python3 scripts/understand.py <video> --work-dir <work_dir> [选项]。常用选项包括 --context、--scene-threshold、--style、--edit-mode、--target-duration、--skip-asr、--mimo-video-overview、--force、--brief-only、--edited-storyboard-only、--consolidate/--no-consolidate、--consolidate-asr。若 work_dir/background_research.json 存在，会把剧情梗概和角色名折入 VLM 上下文。
输出契约：frames/、scenes.json、audio.wav、asr_result.json、asr_timing_evidence.json、silence_periods.json、speech_boundary_anchors.json、vlm_analysis.json、understanding_index.*、storyboard/、timeline_fusion.json、asr_writing_chunks.json、agent_narration_brief.md 等。
限制：不写解说词、不做解说评分；不编造信号无法支持的剧情，ASR/VLM 过薄时输出素材警告。MiMo ASR 的 start/end 是固定分片粗窗口，非词级对齐；空文本只表示原因未知，不能当作已证实静音。--skip-asr 会把现有转写替换成 []，不要用它绕过缓存问题。缓存对不上时用 cp -p / cp -Rp / rsync -t 保留时间重新复制，或设置 key 后重跑。参考资料见 references/research-guide.md 与 references/data-schema.md。