理解索引里有哪些文件，各回答什么
video-understanding 是写稿前的分析阶段，角色是素材观察员（场记），不是导演：把源视频转成一组文件供写稿读取，自己不写解说词。
| 文件 | 回答什么，怎么用 |
|---|---|
scenes.json | 切点与每场起止，含废片段过滤结果；一场不等于一个剧情节拍 |
asr_result.json | 粗分段的对白文字；只用来找对白大致位置 |
asr_timing_evidence.json | 转写是否可用、精度边界、人名表修正前后的文字 |
silence_periods.json | 安静窗口与 has_speech；放旁白的候选位置 |
vlm_analysis.json | 逐场描述、深层分析和按时间点记录的 frame_facts |
timeline_fusion.json | 把画面、对白和安静窗口对齐到每一场 |
agent_narration_brief.md | 写稿前首先阅读的创作简报 |
另有原片联系表 storyboard/source_storyboard.jpg，以及默认生成、同样由模型汇总的全局故事索引 understanding_index.md。
运行前：素材权利、依赖和背景资料
- 素材权利：只处理你拥有或获准使用的视频。抽出的画面帧和音频会发给远程模型服务，发送前确认授权，并查看服务商的隐私与计费条款。
- 本地工具：用
python3运行scripts/understand.py，需要ffmpeg；中间文件写进--work-dir。 - 模型服务：转写用
mimo-v2.5-asr，画面观察用mimo-v2.5，都需要MIMO_API_KEY。--skip-asr只跳过转写，还会把已有转写覆盖成[]，不能用来绕过缺 key。 - 背景资料（可选）：
work_dir/background_research.json里的梗概和角色名会折进画面分析，--context可再补一条提示。这让描述能叫出人名，也可能把名字安错人，查法见影视解说写稿前怎么查资料。 - 缓存：已生成的文件只在与当前视频和相关设置一致时复用；需要全部重算时加
--force。
写旁白前，按这个顺序核对索引
- 先看状态。 简报会打印转写证据状态：
AVAILABLE_COARSE表示有粗转写；UNAVAILABLE_NO_KEY、FAILED_PROVIDER等表示这次没有可用对白；MISSING_OR_STALE表示证据缺失或与当前文件对不上。转写或画面观察过薄时会有素材警告，此时少下结论。 - 用联系表查场景切分。 漏切会把两场混成一条描述，多切会把一个动作拆散；被过滤掉的片段里也不能有你要用的镜头。不对就调整
--scene-threshold重跑。 - **逐场对照描述和
frame_facts。** 描述里的动作、物件去向和人名，都应在某条帧标签里找到。帧标签只记录抽到的帧，两帧之间发生了什么是模型补的。 - 把深层分析当假设。 提示模板要求依据可见证据分析情绪、关系和潜台词，信息不足时直说；它仍是模型的判断。
- 查会改变意思的字。 人名、否定词、数字先回听；被人名表修改过的窗口，对照前后两版。空文本不等于已证实的静音。
- 找跨文件矛盾。 融合时间线把每场画面和对白放在一起；后一场的对白否定前一场的描述，最该回看。
- 回原片看清每一拍。 结果写进自己的核对笔记并注明人工回看，不把手改的内容当成模型原始输出。
原创例子：三分钟早市短片里的一条错误观察
以下短片、人物和时间均为本文虚构，没有真实运行模型；JSON 为手写示意，只沿用 data-schema 的字段名并省略部分字段，不是该技能的实际输出。
素材：作者在早市自拍的三分钟短片《借来的秤》。鱼摊的秤坏了，摊主苗姨让侄女小禾去隔壁老钱摊借秤，老钱说中午前要还。约 2:06，小禾抱着秤走进两摊之间的过道；约 2:38，老钱过来问秤在哪；片尾，小禾从自家柜台下拿出秤递给他。
融合时间线节选（scene_id 从 0 数，简报显示为第 5 场）：
{
"scene_id": 4,
"time_range": [126.0, 152.0],
"visual_description": "小禾抱着秤走到老钱摊前，把秤还给老钱",
"depth_analysis": "她按约定在中午前归还",
"frame_facts": {
"128.0": ["小禾双手抱着秤走进过道"],
"136.0": ["小禾站在两摊之间，手里已经没有秤"]
},
"narration_slots": [{"start": 141.0, "end": 149.0, "duration": 8.0}]
}
下一场的一行转写（asr_result.json）：
{"start": 158.0, "end": 168.0, "text": "秤呢？说好中午前还我的。"}
照索引直接写，141—149 秒的安静窗口很容易填成“秤按时还了”。核对时，问题露在三处：
- 描述超出帧标签：帧标签只有“抱着秤”和“手里已经没有秤”，没有一帧拍到老钱接秤，“还给老钱”是模型补的。
- 跨文件矛盾：下一场有人问秤在哪。转写不标说话人，先记作“有人问秤”。
- 回到原片：126—140 秒里，小禾把秤放在自家柜台角，转身招呼客人，老钱不在画面中。
核对笔记：第 5 场改为“小禾把秤放在自家柜台角，没有交给老钱”（人工回看 126—140 秒）；删去“按约定归还”；158 秒附近的问话出自老钱，逐字回听后再引用。
故事因此变了：从“守约还秤”变成“说好中午前还，却忘了，片尾才补上”。那段安静要不要放旁白，由作者看过原片后决定；若放，只说画面能证明的：秤还在自家柜台上。
索引回答不了的问题
- 对白边界和说话人：转写的
start/end是固定分片形成的粗窗口，不是逐字对齐，也不标谁在说，见ASR时间戳不准怎么剪视频。 - 两帧之间的动作：交接、藏物、谁先动手，要看连续画面。
- 动机、镜头外的事和之后的结果：素材没拍到的就是未知，见AI分析视频乱编剧情怎么办。
- 安静该不该留：
has_speech为 false 只说明这段较安静、没有与检测到的转写语音重叠；沉默本身是不是表演，由你判断。 - 人名对不对：名字可能来自背景资料或人名表修正，长相、服装相近的人会被安错。
- 故事方向：简报里的解说风格只是
--style的值，默认“纪录片”；观众问题和主视角属于写稿阶段，见影视解说文案怎么写。 - 能不能用这段素材：索引不判断版权与授权。
常见误用与修法
| 误用 | 修法 |
|---|---|
只读 visual_description | 对照 frame_facts，多出的动作回原片看 |
把 depth_analysis 写成事实 | 改成可见动作，或找对白与连续行为支持 |
| 安静窗口一律填满旁白 | 先判断这段沉默是否在承担内容 |
| 素材换了版本仍用旧索引 | 对当前文件重跑；搬动工作目录用 cp -p 等保留文件时间 |
用 --brief-only 改正画面观察 | 它只用已有的分析文件重建简报，不重新看画面 |
常见问题
没有 MiMo API key，还能生成理解索引吗？
完整理解需要 MIMO_API_KEY：对白转写和画面观察都调用 MiMo 模型。没有 key 时重跑，只会复用已经缓存的转写、画面分析和故事索引，需要请求模型的汇总会记为跳过。不要用 --skip-asr 绕过：它会把已有转写替换成空列表，画面观察也仍然需要 key。
索引里出现了人名，可以直接写进解说吗？
先核对。人名可能来自 background_research.json 或 --context 折进画面分析的上下文，也可能来自转写的人名表修正；长相、服装相近的人容易被安错。用片中字幕、对白里的称呼或创作者提供的人物表确认后再写；确认不了，就用身份或动作来指代。
素材重新导出或剪过一版，旧索引还能用吗？
按新素材对待。各阶段只有在已生成的文件和来源记录都匹配当前视频与相关设置时才复用；转写证据记录了源视频、音频和转写文件的大小与修改时间，对不上时简报显示 MISSING_OR_STALE。旧索引里的时间和描述，只能当作旧版本的线索。
用 skill 来做
用 $video-recap 分析这段我有权使用的本地视频，只运行到视频理解阶段（video-understanding）写出创作简报后的暂停点：生成场景、转写、安静窗口、逐场观察、融合时间线和创作简报后停止，不写解说词。先报告转写证据状态和素材警告，再逐场列出描述里没有帧级事实支持的动作与人名，供我回原片核对。
更多方法依据： 逐场描述、帧标签与深层分析的提问模板 · 背景调研如何并入画面分析