你把一段 YouTube 链接丢给 Claude Code，问它视频里演示了什么。Claude 回复了一段看起来很有道理的分析，但你隐约觉得不对劲。仔细一看，它分析的是标题和简介，根本没看到画面里那个关键的操作步骤。这种事发生一次是烦恼，发生五次你就开始怀疑：号称多模态的模型，为什么连个视频都看不了。
Brad Bonanno 比你先烦透了。这位澳大利亚独立开发者每天泡在视频内容里——分析竞品演示、看屏幕录制找 Bug、从讲座里提炼笔记。每次他都要手动描述视频内容给 Claude，效率低到愤怒。他的解决方案没有等 Anthropic 加原生视频支持，而是自己写了条管线，把这件看似复杂的事拆成了四步。
整个项目只有 7 个 Python 脚本、不到 2800 行代码，却能在 50 多个 Agent 宿主上跑。更让人意外的是，很多公共视频根本不需要 API 密钥——字幕免费的，帧提取用的 ffmpeg 也是免费的。Whisper 只在字幕不可用时才介入，而 Groq 的 whisper-large-v3 处理五分钟视频大约只要半分钱。
我不打算把它吹成改变世界的神器。它做的事本质上就是下载、抽帧、转录、塞进上下文——全是已有工具的胶水代码。但你仔细看帧去重算法和动态帧预算的设计，会发现这个胶水粘得比大多数同类东西聪明得多。
这条管线的核心设计哲学很简单：先省钱再干活。优先用免费字幕，帧去重避免重复画面占用 Token，只在必须时才调用 Whisper。这个成本控制的思路贯穿了整个项目的每一层。
管线整体结构说清楚了，但几个具体的设计决定才是真正让这条管线好用的地方。
值得关注的地方
帧预算系统是整条管线里最容易被忽视的精巧之处。它不是简单地把视频切成固定帧数，而是按视频时长动态调整：30 秒以内的短视频给约 30 帧，基本覆盖每个关键时刻；1 到 3 分钟的视频给约 60 帧，密度仍然可观；超过 10 分钟的长视频封顶在 100 帧，同时会给你一个”稀疏扫描”的警告。这意味着你不会在一条 2 小时的讲座上烧掉几万个图像 Token，系统自己就知道什么时候该收手。
帧去重算法更值得拿出来聊。它没有引入 OpenCV 或 Pillow 这些重量级依赖，而是用纯 ffmpeg 把每帧缩成 16×16 的灰度缩略图，然后计算与上一个保留帧的平均绝对差异。差异低于 2.0 阈值的帧直接丢掉。更聪明的是，去重之后再应用帧预算上限——确保那 100 帧全都花在不同画面上，而不是浪费在静态讲台场景的重复帧上。腾讯云开发者社区的一篇分析文章把这个称为”零依赖视频 RAG 管线”，不算夸张。
四种细节模式本质上是一个时间换视觉精度的拨盘。在一条 49 分钟的 YouTube 视频上实测的数据很能说明问题：transcript 模式只拉字幕，零点零几秒完事，不产生任何图像 Token。efficient 模式只解关键帧，大概半秒搞定 50 帧，约 9800 个图像 Token。balanced 模式做场景切换检测，20 秒提取 100 帧，约 19700 个 Token。token-burner 模式不打帧数上限，全量提取所有场景切换帧，同样 20 秒但出 116 帧。讲白了就是让你自己决定是想省钱还是想看全貌。没有哪个模式是”最好”的，全看你对这条视频有多在意。
跨平台分发这件事上，claude-video 也比看上去想得更远。它不是给 Claude Code 定制的，而是基于 Agent Skills 协议写的——SKILL.md 里用相对路径解析脚本位置，同一份 skill 装在 Claude Code、Codex、Cursor、Copilot、Gemini CLI 甚至 Windsurf 里都能跑。这对一个只有一个人维护的项目来说，等于用最小的分发成本撬动了最大的用户覆盖面。不过这也带来一个问题：32 个 open PR 堆在那里没人处理，社区贡献的节奏显然没跟上 Star 增长的速度。
首次运行时会自动检测 yt-dlp 和 ffmpeg 是否存在，macOS 上直接走 brew 安装，其他平台打印精确的安装指令。这个体验细节很小，但它意味着你不需要在看视频之前先花半小时配环境。一个”装上就能用”的开源项目，跟一个”README 写了一千字配置说明”的项目，在实际使用时是两种完全不同的东西。
四种模式的选择不只是参数的区别。它反映了一个设计判断：有些视频你只想快速扫一眼，有些你愿意花时间深挖。把选择权交给用户而不是替用户决定，这个做法在 AI 工具里并不多见。
跑起来看看
安装路径按你的 Agent 宿主不同分两条。Claude Code 用户最方便，只需两行命令：
/plugin marketplace add bradautomates/claude-video
/plugin install watch@claude-video
如果你用 Codex、Cursor、Copilot 或其他 50 多个 Agent Skills 兼容平台：
npx skills add bradautomates/claude-video -g
装好之后直接用，基本就是一条 /watch 命令跟一个 URL 和问题：
/watch https://youtu.be/dQw4w9WgXcQ 这视频讲什么？
/watch ~/Movies/screen-recording.mp4 UI 在哪一秒崩的？
如果你想只盯着某一段看，加上 --start 和 --end，工具只会下载和提取这段时间的内容，不浪费 Token：
/watch https://youtu.be/abc --start 2:15 --end 2:45
/watch video.mp4 --start 50 --end 60
有几个坑值得提前知道。如果视频没有原生字幕，工具会自动走 Whisper 转录，但你需要提前配置 Groq 或 OpenAI 的 API Key 放在 ~/.config/watch/.env 里。不想走 Whisper 的话加 --no-whisper，纯靠帧内容分析也能用，只是准确度会打折扣。另外超过 10 分钟的视频在默认模式下帧密度会显著下降，识别效果不好，建议分段处理或者切换到 token-burner 模式，但要做好 Token 消耗翻倍的准备。
还有一个隐藏的细节：默认帧宽是 512px，高度被限制在 1998px 以内。这个数字不是随便选的，而是 Anthropic Read 工具能直接渲染图像的最大边界。如果你需要阅读屏幕上的文字，用 --resolution 1024 可以把帧宽提升到 1024px，代价是图像 Token 消耗也跟着涨。
什么时候用，什么时候别用
知道它能做什么之后，更关键的问题是搞清楚什么时候该用它，什么时候不该用。适合的场景和它处理不了的场景，我分开说。
| 场景 | 典型用户 | 优势 | 局限 |
|---|---|---|---|
| 视频内容分析 | 市场/内容运营 | 直接看画面，不是靠标题猜 | 长视频准确度随帧密度下降 |
| Bug 复现诊断 | 开发者 | 屏幕录制丢进去就能定位帧 | 需要录制质量过关 |
| 会议记录整理 | 远程协作团队 | 自动转录加帧分析，会议结束笔记已出 | Whisper 准确性取决于音频质量 |
| 学习笔记提炼 | 学生/自学者 | 讲座视频直接转结构化笔记 | token-burner 模式下成本不低 |
不适用的情况也有三类。你只是想快速知道视频大概讲了什么，直接看 YouTube 的 AI 摘要就够了，不需要起一条管线。你的视频超过 2 小时且内容高度重复（比如安防监控），帧去重会丢掉大部分画面但可能恰好丢掉了关键帧。你的工作流里根本没有 Claude Code 或任何 Agent 宿主，那这个工具对你来说就是一个用不了的 Python 脚本。
但体验上的坑说清楚了，更底层的问题是这个项目的维护节奏能不能撑住它的热度。先看关键数据。
社区怎么样了
但体验上的坑说清楚了，更底层的问题是这个项目的维护节奏能不能撑住它的热度。先看关键数据。
| 指标 | 数据 | 说明 |
|---|---|---|
| Stars | ~7000（截至 2026 年 7 月） | 2.5 个月爆发增长，单日峰值 953 |
| Forks | ~720 | Star/Fork 比约 10:1，健康 |
| 核心维护者 | 1 人 | Bus Factor = 1，是硬伤 |
| 提交数 | 11 个 commit | 项目极简，但 release tag 规则发布 |
| Open PRs | 32 个 | 远超 commit 数，社区贡献未形成闭环 |
| 协议 | MIT | 完全开放，无商业限制 |
7 月初在 GitHub Trending 上冲得很猛的那几天，HackerNews 和 Reddit 上都有讨论串。比较有代表性的评价来自开发者 Andrew Oooo，他在 dev.to 上写了一篇详细评测，核心判断是：”token costs on long videos are real, and the frame-budget dial is not optional if you care about your bill.”这话说到点子上了——Token 消耗是这道管线不可回避的成本，帧预算拨盘不是锦上添花的功能，而是控制成本的生命线。
但有一个数据比 Stars 更有说服力：32 个 open PR 没人处理。这表明项目目前处于”写完了放着”的状态，bradautomates 自己在 README 里也标注项目是低维护模式。短期用没问题，长期依赖的话需要考虑到这个 Bus Factor = 1 的风险。
我的真实看法
我对这个项目的评价不是”好”或”不好”，而是”它把对的事做对了，把难的事留给了你”。
对的事包括哪些。零依赖的帧去重算法、按视频时长动态调整的帧预算、四种细节模式让你自己选成本与精度的平衡。这些设计决定都是对的——它们不需要最新的大模型，不需要最复杂的架构，只是把已有工具线的胶水粘在了正确的位置上。7 个 Python 脚本做出一款 7000 Stars 的项目，这在传统开源世界几乎不可想象，但在 Agent Skills 的时代，prompt + pipeline 本身就是产品。
难的事留给了你。长视频的准确度问题没有简单的解法，目前只能靠分段处理或者接受 token-burner 的成本。Bus Factor = 1 的维护风险在你决定把这条管线集成到工作流之前，需要认真掂量。更根本的一个问题是：Anthropic 迟早会加原生视频输入支持，到那一天 /watch 的位置在哪里？如果你的答案只是”在那之前先这么用”，那没问题。如果你在考虑围绕它建一套工作流，这个时间窗口值得先算清楚。
跟同类项目比，claude-video 的独特位置很清楚。jordanrendric 的 claude-video-vision 走的是 MCP 服务路线，需要 Node.js 环境，但支持本地 Whisper 离线跑。thoughtpunch 的 claudetube 提供了 40 多个 MCP 工具，功能更全但有缓存依赖和更复杂的安装步骤。claude-video 选择了最轻的路径：一个 slash 命令、7 个 stdlib Python 脚本、跨 50 多个宿主的分发协议。三条路没有绝对的对错，只是面向不同的使用习惯。
三者代表了同一个问题的三种解法。claude-video 的路线最接近”less is more”——它没有试图构建平台，只是缝了一条效率足够高的数据管线。这种克制在一个 11 个 commit 的项目里既是优势也是天花板。
资源地址
| 资源 | 地址 |
|---|---|
| GitHub | https://github.com/bradautomates/claude-video |
| 作者 YouTube | https://www.youtube.com/@bradbonanno |
聊完了数据和位置，该聊点真的了。如果你准备动手试试，下面是我的建议。
先装上，别急着建工作流
如果你已经在用 Claude Code 或者其他 Agent 宿主，两分钟装上，把手头最常看的视频类型丢进去试一圈。从 5 分钟以内的短视频开始，balanced 模式是默认的不出错选择。
如果你还在观望，关注两个指标：PR 合并速度有没有恢复，以及 bradautomates 会不会引入第二个核心维护者。这两个信号决定了 claude-video 能否从”一个爆款个人项目”变成”一个可以长期依赖的工具”。Star 数不用看了，7024 还是 7530 不重要。
这个工具不需要你重新理解什么。它只是把你一直在做的事——手动描述视频内容给 AI——自动化了。仅此而已，也足够了。