Video Vision 是一项让 Claude 具备观看和理解本地视频文件能力的技能。它将视频转化为 Claude 可直接推理的两路数据流：一是保存到磁盘的采样帧图片，通过 Read 工具按需读取（Claude 具备多模态能力）；二是由本地 Whisper 生成的带时间戳转录文本，首次下载模型后可完全离线运行。Claude 充当解释者，脚本只是确定性的感知层。
用途方面，凡用户指向一个视频文件并希望其被理解时均可触发，包括摘要、问答、生成字幕、查找某个瞬间、解释屏幕内容、转录对话或描述画面。用户在聊天中给出视频路径并带有任何隐含提问时也适用。不适用于流媒体 URL（如 YouTube，需先用 yt-dlp 下载）、实时摄像头画面或纯音频文件（应改用仅转录的工具）。
主要能力由两个子脚本承担：extract_frames.py 负责抽帧，transcribe_audio.py 负责转录；总控脚本 analyze_video.py 并行执行两者并向 stdout 输出 JSON 清单，包含视频路径、时长、帧目录、帧率、帧数量、各帧路径与时间点，以及转录模型、语言、全文和分段信息。
使用方式为运行总控脚本：python3 scripts/analyze_video.py --video /abs/path/to/file.mp4 [--fps 1] [--max-width 1024] [--whisper-model base] [--no-transcribe]。运行前需确保 ffmpeg 与 ffprobe 在 PATH 中、Python 3.9+，并安装 openai-whisper；若缺失，转录脚本会以退出码 2 结束并打印安装命令，应向用户说明并询问是否安装后继续。参数选择应依据用户意图：长讲座或会议摘要用 --fps 0.25、--max-width 768、base 模型；一般问答或短片段用 fps 1、宽 1024；需要细看画面或读取屏幕文字用 fps 2、宽 1280；音频嘈杂、口音重或多语言可换 small 或 medium 模型；纯音频问题可跳过抽帧；纯视觉问题可用 --no-transcribe。升级到 medium 约需下载 1.5 GB，large-v3 约 3 GB，升级前应提醒用户。
在清单基础上推理时：针对特定时间的视觉问题，查找 t 最接近目标时间戳的帧并只读取该帧；针对音频问题，检索 transcript.segments 中的文本并用 [MM:SS-MM:SS] 引用；做综合摘要时先浏览全文，再在时长范围内均匀采样 5 到 10 帧；需要交叉对照时，找到相关分段后读取落在该时间段内的帧。回答中始终以 [MM:SS] 标注时间戳以便用户核验。
边界情况包括：无音轨时转录分段为空，仅用帧继续；静默片段会导致转录出现空档，属正常现象；超过一小时的视频建议从低帧率和 base 模型开始，可先用 ffmpeg 预裁剪窄窗口再采样；帧时间戳是采样区间中点而非精确解码时间，不应声称帧级精确；帧目录位于临时目录且会被系统清理，隐私敏感时可手动删除；Whisper 模型缓存位于 ~/.cache/whisper，可删除以释放磁盘。若出现 ffmpeg 缺编解码器、Whisper 大模型内存不足或容器不受支持等故障，应读取 stderr 修复根因并记录，不要静默忽略失败。