video-understanding

## 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...