---
name: movie-index
description: 将本地电影原片、字幕、技术切点、关键帧和视觉模型观察结果整理成经过验证的可搜索镜头数据库。开始新的电影解说项目、重建或检查索引、按对白或画面寻找素材、返回原片精确坐标与证据片段，或者为执笔人和编导提供共享证据时使用。
---

# 电影镜头索引

为执笔人和编导建立可复用的证据层。只把技术切点和模型描述当作坐标与检索辅助，不把它们当作剧情真相。

## 从当前现场开始

1. 先读取项目根目录的 `AGENTS.md`，以及影片目录中的 `project.json`、`production/state.json` 和最新索引报告。
2. 核对原片、字幕是否仍与记录的指纹和媒体时长一致。
3. 如果现有索引完整且有效，直接复用。只继续缺失或失败的单元；除非原片或提示词版本发生变化，不得重跑已经成功的视觉批次。
4. 创建或修改数据库结构前，读取 [references/index-contract.md](references/index-contract.md)。
5. 接受检索质量或向其他角色交付素材前，读取 [references/retrieval-and-validation.md](references/retrieval-and-validation.md)。

## 建立证据层

1. 使用 `ffprobe` 探测原片，记录绝对路径、来源、时长、媒体流、帧率、分辨率、编码、声道数和采样率。
2. 读取字幕但不修改源文件。保留字幕编号、文本、语言和毫秒级起止时间。
3. 使用 PySceneDetect 或同类工具取得技术切点，并记录检测器名称、版本和完整参数。
4. 每个技术镜头至少提取一张代表图，计算基础画质信息，并保证可续跑时镜头编号保持稳定。
5. 将所有与镜头时间重叠的字幕关联到该镜头。
6. 只有视觉模型传输确实需要时，才把异常长镜头拆成有上限的视觉单元；必须保留父技术镜头及原片精确区间。
7. 要求视觉模型只记录画面中直接可见的人物、地点、动作顺序、物体、检索词和不确定项。不得推测剧情、动机、台词、画外事件或证据不足的人物身份。
8. 保存原始响应、规范化事实、失败信息、模型名称、提示词版本、用量和处理时间。
9. 为字幕和规范化视觉事实建立全文检索。人工纠错必须单独保存在覆盖层中。

## 搜索并返回证据

1. 将自然语言需求拆成人物、地点、动作、物体、对白和大致剧情位置等线索。
2. 联合搜索字幕索引与视觉索引，再应用经过确认的人工纠错。
3. 返回排序后的候选项，包括镜头或视觉单元编号、精确起止时间、字幕、视觉事实、不确定项和代表图。
4. 对第一候选项至少提取三张连续证据图，并导出带合理前后余量、保留原声的原片片段。
5. 交由执笔人或编导查看连续原片。不得仅凭模型描述就断言剧情事实。

## 守住职责边界

- 不得把技术镜头强制聚合成预先规定数量的剧情场景。
- 不得代替执笔人或编导对镜头评分、合并并决定故事结构。
- 不得把 8～12 分钟叙事卷当作正式剧情分段；它只是看片时的上下文包装。
- 纠正人物或含义时，不得覆盖原始模型结果；必须添加带证据和来源的纠错记录。
- 结构检查和代表性检索测试没有通过前，不得标记 `INDEX_VERIFIED`。

## 交付

交付索引合同规定的全部产物，并生成 `INDEX_REPORT.md`，记录来源指纹、数量、视觉覆盖率、失败项、模型与提示词版本、可用时的费用，以及检索测试结果。只有验证通过后，才能把 `production/state.json` 更新为 `INDEX_VERIFIED`。