Video Understand 是一个视频理解技能，定位是“共享证据层”，用于在剪辑等后续操作之前，把素材的事实信息一次性提取、整理并校验，避免下游技能各自重复分析。它只做客观观察与语义理解，保留源时间，不替下游做剪辑、卡片或视觉风格的决策。
用途：当一个视频项目需要可复用的媒体元数据、词级转录、客观语音分析，或有证据支持的语义理解时使用。它是 /video-cut、/video-to-shorts、/video-add-captions、/video-add-content-cards、/video-add-motion-graphics 等技能的前置条件，需要先运行它，让这些技能消费同一份已验证的证据与时间线。
主要能力：
- 项目初始化：从原始源视频创建项目结构，包括 input/、review/00-video-understanding/、final/、面向机器的最小 work/ 树、身份时间线、project.json、媒体事实和 START-HERE.md。它不会为未选定的编辑操作创建文件夹。
- 媒体探测：仅在源需要显式刷新元数据时，再次运行 probe.py。
- 音频提取与转录：用 ffmpeg 提取 16 kHz 单声道音频，再用 transcribe.py 配合 faster-whisper 转录，支持词级时间戳。
- 客观指标与语义候选：用 analyze.py 从转录生成客观指标和语义候选。
- 语义理解撰写：阅读源、转录和分析后，撰写 understanding.json，包含事实性摘要、源时间范围、置信度和转录证据，但不规定剪辑、卡片或外观。
- 校验：用 validate.py 在使用前校验 understanding 与 transcript。
- 审阅产物：在 review/00-video-understanding/ 下只创建三种有用产物：video-summary.md、transcript.srt、contact-sheet.jpg，并核对元数据、时间戳、证据引用和可见帧。不得用 PNG 或其他临时文件名代替协议规定的名称。
使用方式：
- 依赖：需要 ffmpeg/ffprobe、Python 和 faster-whisper 用于转录，处理媒体前先检查这些依赖。
- 初始化项目： python scripts/init_project.py path/to/source.mp4 path/to/my-video-project
- 需要时刷新元数据： python scripts/probe.py input/original-video.mp4 work/understand/media.json
- 提取音频并转录： ffmpeg -y -i input/original-video.mp4 -ac 1 -ar 16000 work/cache/audio16k.wav python scripts/transcribe.py work/cache/audio16k.wav work/understand/transcript medium --lang auto --cache-dir work/cache/faster-whisper
- 生成客观指标与语义候选： python scripts/analyze.py work/understand/transcript.json work/understand/analysis.json
- 撰写 understanding.json 后校验： python scripts/validate.py understanding work/understand/understanding.json work/understand/transcript.json
适用场景：需要在视频编辑之前统一提取媒体事实、词级转录、语音客观分析和有证据的语义理解的视频项目；尤其是要与 /video-cut、/video-to-shorts、/video-add-captions、/video-add-content-cards、/video-add-motion-graphics 等下游技能共享同一份证据和时间线的场景。
限制与注意事项：
- 该技能不产出剪辑决策，不规定 cut、cards 或 looks，只做证据与理解层。
- 使用 --lang auto 处理未知或混合语言语音；绝不能从用户提示的语言推断口播语言。只有当音频本身或用户显式元数据确定语言时，才传固定语言，如 --lang zh。
- 模型下载保存在项目本地的 work/cache/faster-whisper/ 缓存中。
- faster-whisper 偶尔会输出起止值相等的点时间词，共享时间线映射器会将其保留为 1 ms 区间，避免字幕和衍生结果静默丢字。
- 只有在审阅产物和语义证据都通过校验后，才把 understanding 操作的 check.status 标记为 pass。操作生命周期状态与检查结果是分开的；永远不要往 check.status 写 verified。
- 创建或校验 project.json 时阅读 project-schema.md；映射源时间与节目时间时阅读 timeline-schema.md；撰写语义理解前阅读 understanding-schema.md；可参考 understanding.example.json 作为紧凑示例。
- 所有持久机器文件位于 work/understand/；work/cache/ 视为一次性缓存。