claude-video 评测：给 Claude 装上眼睛和耳朵的 /watch 插件

它解决的是 Claude 的视觉盲区

Claude 能读网页、跑脚本、浏览仓库，但拿一个视频链接给它，它只能从标题猜内容，或者拉一份缺少画面信息的字幕。claude-video 的 /watch 命令补上了这个缺口：你给它一个 URL 或本地路径，它下载视频、提取帧、生成带时间戳的转录，然后把这些材料全部塞进 Claude 的上下文。它针对的是那些需要同时理解画面和声音的场景，比如分析一个广告的开头钩子，或者从屏幕录制里找出 bug 的根源。这个项目不是给普通观众用的，而是给那些已经依赖 Claude 做内容分析的人，让他们把视频也纳入这条工作流。

从 URL 到答案的六步流程

整个流程在 README 里写得很清楚。第一步，你粘贴视频链接或本地文件路径，yt-dlp 会先检查有没有字幕。如果有字幕，它就不下载视频本体，直接返回字幕。如果没有，或者需要 Whisper 处理音频，它才下载所需的片段。第二步，ffmpeg 按你选的 detail 模式提取帧，efficient 模式只解码关键帧，速度接近即时，balanced 和 token-burner 模式则优先选场景切换帧，不够时用均匀采样补足。第三步，转录来源有两个，优先用 yt-dlp 拉原生字幕，免费且快，但准确性一般，备选方案是提取 16 kHz 单声道 64 kbps 的 mp3 音频，约每分钟 480 kB，然后发给 Whisper，Groq 的 whisper-large-v3 是首选，OpenAI 的 whisper-1 是备选。第四步，脚本把帧路径和时间戳标记打印出来，Claude 并行读取每一帧图片。最后，Claude 基于这些实际看到的和听到的内容回答问题，而不是基于标题或描述。任务结束后，脚本会打印工作目录，如果不需要追问，Claude 会清理掉它。

帧预算：为什么它决定你的费用

帧是 token 消耗的大头，每一帧都是一张图片，图片 token 累积得很快。脚本的自动 fps 逻辑就是为了防止你把上下文预算浪费在一个 30 分钟视频的稀疏扫描上，而更好的做法是聚焦到 30 秒的关键窗口。默认帧预算随视频时长递增，30 秒以内约 30 帧，1 到 3 分钟约 60 帧，超过 10 分钟封顶 100 帧，并且会给出“稀疏扫描”警告，建议你重跑一次聚焦模式，或者用 --detail token-burner 获得无上限的完整覆盖。如果你指定了时间范围，比如“大约 2:30”或“最后 30 秒”，就用 --start 和 --end 参数，聚焦模式会获得更密集的每帧预算，最高每秒 2 帧。这个设计很务实，它承认了一个现实：长视频的全面分析成本太高，不如让用户先定位到关键片段。

去重逻辑：避免为重复帧付费

即使选择了场景切换帧，屏幕录制里一个幻灯片停留 90 秒也会产生十几张几乎一样的帧，每一张都会被当作独立的图片计费。脚本默认开启去重，可以用 --no-dedup 关闭。去重过程分三步，先用 ffmpeg 把每张 JPEG 缩成 16×16 的灰度缩略图，然后计算当前帧与上一张被保留帧的平均绝对亮度差，阈值是 2.0，低于或等于就丢弃，否则保留并成为新的参考。比较对象是上一张被保留的帧，而不是前一张，这样能捕捉到缓慢的淡入淡出，那种变化不会触发逐帧阈值。阈值故意设得很低，而且衡量的是绝对亮度而非结构，所以一行代码的差异、终端滚动一行、两个不同颜色的纯色幻灯片都能保留下来。帧预算上限在去重之后才应用，所以预算花在真正不同的帧上。运行时会报告类似“6 selected from 14 candidates (… 8 near-duplicates dropped …)”的信息，让你知道发生了什么。

安装与配置：零配置开始，但有前提

安装方式有两种。在 Claude Code 里推荐用插件市场命令，/plugin marketplace add bradautomates/claude-video，然后 /plugin install watch@claude-video，这样能自动更新。其他 50 多个 Agent Skills 宿主，比如 Codex、Cursor、Copilot、Gemini CLI，用 npx skills add bradautomates/claude-video -g，-g 表示全局安装，去掉则只对当前项目生效。启动时零配置，yt-dlp 和 ffmpeg 会在首次运行时自动安装，macOS 用 brew，Linux 和 Windows 会打印具体命令。字幕覆盖大部分公开视频，免费。只有视频没有字幕时才需要 Whisper API 密钥。这个设计降低了上手门槛，但也意味着如果视频没有字幕，你必须有 Whisper 的 API 密钥，否则只能依赖 yt-dlp 的字幕，而自动生成的字幕质量参差不齐。

局限与误用场景

这个工具不是万能的。首先，帧预算上限 100 帧意味着超过 10 分钟的视频只能得到稀疏的扫描，如果你需要分析整个视频的每一个细节，默认模式会遗漏大量内容，必须使用 token-burner 模式，但那会迅速烧掉你的上下文预算。其次，去重逻辑虽然聪明，但阈值是固定的 2.0，对于画面快速变化但内容重复的视频，比如一个不断滚动但本质相同的终端输出，可能会保留过多或过少的帧，这取决于实际亮度变化。第三，转录依赖字幕或 Whisper，如果视频没有字幕且你没有配置 Whisper API，整个流程会卡住。最后，这个项目依赖 Claude 的 Read 功能，如果宿主环境不支持图片输入，帧就毫无意义。对于需要精确时间点分析的场景，比如逐帧检查动画，这个工具会显得粗糙，因为帧提取是均匀采样或场景切换，不是逐帧。

替代方案：为什么不用现成的视频摘要工具

市面上有很多视频摘要服务，比如 YouTube 自带的摘要、或者各种 AI 笔记工具，它们通常只处理转录文本，忽略画面内容。claude-video 的差异在于它把帧和转录一起交给 Claude，让回答能引用画面上的具体元素，比如“在 0:45 的帧里，错误对话框显示的是权限问题”。另一个替代方案是自己写脚本，用 yt-dlp 下载视频，用 ffmpeg 抽帧，然后手动调用 Claude API，但那样你得自己处理字幕抓取、去重、预算控制这些细节，而这个插件把这些封装成了 /watch 命令。如果你只需要文字摘要，不关心画面，那么直接用 Whisper 转录然后丢给 Claude 会更简单，成本也更低。但如果你需要分析视觉内容，比如广告的构图、屏幕录制的 UI 状态，claude-video 的帧提取是不可替代的。

维护与许可证：MIT 下的活跃项目

项目采用 MIT 许可证，这意味着你可以自由使用、修改和分发，只要保留版权声明。仓库最近一次推送是 2026 年 7 月 1 日，发布了 v0.2.0，之前有 v0.1.3 和 v0.1.2，版本迭代算比较活跃。维护成本方面，它依赖 yt-dlp 和 ffmpeg 这两个外部工具，它们更新频繁，如果上游接口变化，插件可能需要跟进。通过 Claude Code 的插件市场安装可以自动更新，但如果你用 npx 方式，可能需要手动检查更新。没有看到详细的升级指南，所以版本跳跃时可能需要自己看 changelog。对于个人使用，MIT 许可证没有太多限制，但如果你要集成到商业产品里，最好检查一下依赖库的许可证，尤其是 Whisper API 的调用是外部服务，有额外费用。

编辑结论

claude-video 适合那些需要让 Claude 分析屏幕录制、广告创意或长视频内容的人，尤其是当字幕可用时，它能以极低成本获得带时间戳的转录和关键帧。不建议在视频没有字幕且你不想配置 Whisper API 的情况下使用，因为免费路径会失效。也不适合需要逐帧精确分析的场景，因为默认 100 帧上限和去重逻辑会丢弃细节。在采用前，先确认你的 Claude Code 版本支持 Read 图像输入，并检查 ffmpeg 和 yt-dlp 的安装方式是否匹配你的系统。对于超过 10 分钟的视频，先想清楚是全局概览还是局部聚焦，否则会得到一次稀疏扫描的结果，而不是你想要的答案。

官方来源

1. Official README
2. Project repository
3. Release notes