1. 视频是Agent的盲区：这个Skill解决的问题

先说一个很多Agent开发者都会撞上的现状：文本、图片、网页、代码仓库，这些信息形态Claude已经处理得很顺手了，但只要丢过来一段视频，不管是本地MP4还是在线课程链接，绝大部分Agent都只会回一句“我无法直接观看视频”。我不是说视频理解这个方向没人做，而是说在当下主流的Agent工作流里，视频是一块被默认忽视的盲区。

这个盲区带来的问题很实际。很多用户手里最值钱的信息恰恰是以视频形式存在的：技术分享的录屏、内部培训的讲课录像、产品Demo演示、会议记录、短视频素材库。如果Agent读不了这些，那它在办公场景里的价值就要打个对折。claude-video这个Skill做的事情，就是给Agent装一双“能动的眼睛”，把一段视频从“打不开的文件”变成“可以阅读的文档”。

按照Agent Skills的惯例，这个Skill并不需要改造模型本身，而是通过工程手段在Claude和视频之间搭一座桥。核心工作模式可以概括成四句话：

1. 探测视频的元数据，搞清楚时长、分辨率、有无音轨。
2. 用ffmpeg抽帧，把画面转成静态图片序列。
3. 提取音轨并转写，把语音变成文字。
4. 对视频内嵌字幕做OCR，最后把所有信息按时间轴对齐，输出一份结构化文档。

Claude读这份文档，就能回答“这个视频讲了什么”“在第几分钟提到了某个关键词”“能不能把某段操作步骤整理出来”这类问题，等于间接拥有了视频理解能力。

适合看这篇文章的，一个是正在做Agent应用的开发者，另一个是在知识管理、内容生产、教育领域有视频处理需求的非技术用户。前者可以把它当一个现成的工具链参考，后者可以把部署好的Skill当成一个批量视频转写助手。后面我会把部署步骤、参数调优和踩坑记录全部摊开讲，尽量做到“照着做就能跑起来”。

2. 底层思路拆解：帧采样如何把“视频任务”变成“视觉任务”

要真正把这个Skill用明白，先得理解它底层的设计逻辑，否则你只能瞎调参数，出了问题也不知道从哪排查。

2.1 为什么不能直接把视频喂给视觉模型

Claude本身并不直接接受视频流输入，它处理的是静态图像。这不算什么秘密，而是当前多模态模型的普遍边界。视频本质上是时空数据，包含两个维度：时间维度（什么时候发生了什么）和空间维度（画面里有什么）。如果试图把全部帧都传给模型，token开销会瞬间爆炸，而且绝大多数帧之间高度重复，纯属浪费；如果只截取某一帧，又会丢失完整的时序信息。比如一段做菜教程，切菜动作从第10秒持续到第40秒，单看第10秒的静止帧，你根本不知道演示者是先切后炒还是先煮后切。

所以现实的做法是降维：把视频先拆成“若干关键帧 + 各种附加信号”，再交给模型去综合处理。这就像我们读书时不会逐字背诵，而是先看目录、找重点段落、再结合笔记去理解。claude-video走的正是这条路线。

2.2 Skill的典型数据管线

一个标准的数据管线大致分四段，每个Skill内部通常是四个可独立调用的子命令，也支持一条命令跑完整个流程。

第一段是探测元数据。用ffprobe读时长、分辨率、编码格式、是否有音轨。这一步决定后面采样策略怎么定。10秒的动图和3小时的会议录像显然不能用一个策略去处理，探测就是给后续流程提供判断依据。

第二段是抽帧。按时间均匀抽帧，或者用场景检测工具（比如PySceneDetect）按镜头边界抽关键帧。均匀抽帧对录屏和PPT讲解类视频很有效，因为这类画面变化慢，每隔30秒抽一帧也不会漏东西；场景检测对对话类、动作类视频更友好，它会在镜头切换的瞬间留下帧，例如说话人从A切到B，或者画面从主持人切到PPT。

第三段是提取附加信号。音轨转写用本地ASR模型，比如Whisper或Faster-Whisper；字幕处理则分两种情况，外挂字幕直接读文件，硬编码字幕只能靠OCR，把字幕出现那几帧的图像拿去做文字识别。

第四段是汇总。把所有信息按时间轴对齐，生成一份结构化的叙事文档，包含以下几个字段：

字段	说明
time_code	时间码，格式是时:分:秒
shot_type	镜头类型，来自场景检测结果
frame_description	画面描述，由视觉模型生成
ocr_text	这一帧里识别到的字幕文本
asr_text	这段时间的语音转写文本
event_tags	事件标签，方便检索

这份文档就是Agent后续对话时主要“阅读”的对象。

2.3 关键决策：抽多少帧、什么时候抽

抽帧数和采样策略是这套管线里最值得花时间调的地方。抽少了漏信息，抽多了费token。我的经验公式是 target_frames = max(8, min(60, duration / 30)) ，意思是最少8帧，最多60帧，默认大约30秒抽1帧。

这个公式只适合匀速抽帧，实际使用中要按视频类型做策略修正。我整理了一张选型表，方便直接对号入座：

视频类型	推荐采样策略
录屏、PPT讲解	均匀抽帧，30秒1帧足够，画面变化慢
对话、综艺、访谈	场景检测按镜头边界抽帧，音轨转写作为主通道
体育、舞蹈、动作展示	运动检测高帧率采样，抓取动作拐点
课程、带字幕视频	均匀低帧率 + 字幕OCR，音轨转写做辅助

这里有个关键点：纯粹靠场景检测也未必完美。比如有人对着PPT讲两个小时，每翻一页PPT就是一个场景，场景检测会把每页都当成一个关键帧，最后抽出来几十帧全是PPT，这倒还行；但遇到一个人坐着不动讲30分钟、背景完全不变的情况，场景检测几乎抽不出几个帧，这时就必须依赖均匀采样兜底。所以比较稳的方法是“双轨采样”：用场景检测抓变化点，再用均匀采样保证底线覆盖，最后去重合并。

2.4 为什么这个设计对Agent友好

如果你用过Agent，会明白一个道理：Agent最擅长处理的是结构化、语义清晰的文本。claude-video最终输出的是一份“带时间码和事件标签的Markdown或JSON文档”，这正好落在Claude的优势区里。

更妙的是，这种文档型输出让Agent可以做跨视频检索。比如你给它10段培训视频生成的摘要文档，它就能回答“哪一段讲过权限配置”“哪一段提到了数据库连接池”，这种能力实际上是“把多个视频映射成了同一个语义空间”。相比把视频逐段喂给模型，文档化输出的可审计性也强得多——你能清楚看到Agent是基于哪一帧、哪一段转写得出的结论，方便追溯。

3. 部署与配置：把claude-video装进Agent的完整步骤

理解了原理之后，实操就没那么玄了。下面是我在本地环境里完整跑通的步骤，按顺序执行即可。

3.1 环境准备中最容易翻车的两个点

第一个坑是ffmpeg和ffprobe的安装问题。很多Python项目会通过imageio-ffmpeg间接引入ffmpeg，但它默认只给你一个ffmpeg二进制，不带ffprobe。而claude-video这种Skill的探测阶段依赖ffprobe读元数据，缺少它第一步就会报“command not found”。解决方法是直接用系统包管理器安装完整套件：

# macOS
brew install ffmpeg
# Ubuntu
sudo apt install ffmpeg

装完之后先验证路径：

which ffmpeg && which ffprobe
ffmpeg -version | head -n 1

第二个坑是ASR引擎的选择。如果转写用的是openai-whisper，在纯CPU环境上跑一个45分钟的视频可能要等20分钟以上，体验非常劝退。我实测下来Faster-Whisper在同样环境下能快3到5倍，因为它在CTranslate2上做了优化。模型大小方面，只处理英文用 base 够了，但要处理中文内容，至少上 small ，最好用 medium 。

这里补充一个我踩过的具体例子：同一段中文课程视频，用 base 模型转写会把“乐观锁”识别成“落官所”，几乎不可用；换 small 之后准确率明显改善，虽然偶尔还会把“缓存”写成“缓村”，但配合画面帧和OCR，Claude基本能推理出正确意思。

3.2 Skill文件结构与CLAUDE.md的关键写法

按Anthropic的Agent Skills惯例，一个Skill就是项目里的一个目录，claude-video的典型结构长这样：

skills/
  claude-video/
    CLAUDE.md
    bin/
      video_tool.py
    requirements.txt
    config.yaml

CLAUDE.md 是整个Skill的开关和说明书。Claude在对话过程中识别到“可能需要看视频”时，会读取这个文件，然后按里面的说明调用命令。所以它的第一段必须写清楚触发条件和调用方法。

我建议在CLAUDE.md里写得“斤斤计较”一点，明确什么时候不要用。例如：

# claude-video Skill

## 用途
当用户需要理解视频内容、从视频中提取信息、把视频转换成结构化文本时使用。
支持本地视频文件路径或可直接下载的URL。

## 不适用场景
- 用户只想要视频字幕文本，不需要画面信息时，请直接运行 `extract_subtitle` 命令，不要抽帧。
- 用户只是问“这个视频有没有版权/是否涉政”等主观评价，不要使用本Skill。
- 视频是DRM保护或直播流地址，直接告知无法处理。

## 核心命令
- `python bin/video_tool.py analyze <path> --output json`  
  执行完整分析，输出JSON格式的结构化结果。
- `python bin/video_tool.py extract-frames <path> --max-frames 40 --output-dir ./frames`  
  单独抽帧。
- `python bin/video_tool.py transcribe <path> --model small`  
  单独转写音轨。
- `python bin/video_tool.py ocr-frames <path>`  
  对抽出的帧做OCR，常见字库为中英文。

## 输出说明
命令输出采用JSON格式，包含 `time_code`、`frame_description`、`ocr_text`、`asr_text`、`event_tags` 等字段。Agent应优先阅读JSON中的 `summary` 字段，细节引用时再查具体条目。

别小看这段说明书。Agent Skills的机制决定了，CLAUDE.md写得越好，Claude调用你的工具时就越准确。尤其要写清楚“不适用场景”，否则Claude会在该干正事的时候想半天“我这个要不要用skill”，白白浪费对话轮次。

3.3 权限与运行方式

配置好环境后，给脚本执行权限：

chmod +x skills/claude-video/bin/video_tool.py

运行时强烈建议要求所有命令都支持 --output json 和 --output human 两种输出格式。JSON给Agent程序化解析，human格式给你自己调试时看。这是一个我在第一版里没做、后来补上的设计：所有CLI一开始只输出给人看的表格，Agent解析时经常出错；改成JSON输出之后，Claude的调用准确率直线上升，而且出错信息也更容易定位。

错误处理上也有一个经验：脚本要能向Agent传递“错误是什么”，而不只是报一个非零退出码。做法是最后一行stderr以 ERROR: 开头输出具体原因，比如：

ERROR: input file not found. 请检查路径是否正确，或是否缺少下载权限。

Claude读到这行会直接理解和反馈，而不是回一句无意义的“命令执行失败了”。

4. 实测使用：哪些任务表现好，哪些任务会翻车

装了不算本事，用起来才是。我分几个典型场景说说实测结果，这样你对它的能力边界会有直观判断。

4.1 效果好的场景

第一类，视频问答和内容总结。给一段约20分钟的技术分享录屏，我让Agent总结演讲者的主要观点和结论，它能给出结构清晰的要点，而且每个要点都带时间码。比如它回答“演讲者在第6分40秒提到高并发场景下的缓存策略”，我跳过去核对，基本准确。

第二类，教学视频转文字教程。因为管线里同时有OCR字幕、ASR转写和画面描述，Agent可以重构出带步骤的操作手册。我拿一段“用Python爬取公开表格数据”的演示视频试过，它生成的教程不仅有文字命令，还会顺带解释画面里高亮的部分是什么，这效果相当于把视频变成了一个可编辑、可检索的文档。

第三类，批量生成视频目录。把视频切片成10段，Agent能对照内容给每一段起名字生成带时间码的目录。我拿一套35集的课程视频做了批处理，生成的目录基本能直接当课表用，省掉大量手动打标签的时间。

第四类，内容初筛和合规检查。比如检查一批短视频里是否出现某个特定物体或文字，约束好关键词后，Agent可以把可疑的时间点标记出来，人工再去复核。这虽然不是终审判断，但作为一轮粗筛已经足够好用。

4.2 会翻车的场景

先说动作语义理解。判断一个太极拳动作是否“到位”、或者一段复杂手势操作是否“连贯”，静态帧很难给你满意答案。Vision模型从两三帧画面里推断动态过程，本质上是在猜，准确率无法保证。所以涉及“正确姿势指导”“动作技巧评级”这类需求，当前技术栈并没有根本解决。

其次，纯背景音视频会少一个信息通道。没有语音，ASR输出空白；如果画面也单调，帧描述也拿不到太多信息。音乐类、氛围类视频处理效果很差。

再有就是长视频的token成本问题。两个小时会议视频，假如全部采样，视觉token动辄几千上万。要压成本就得少抽帧，但少抽又可能导致关键信息丢失。这里我后面会重点讲怎么平衡。

最后，在线视频和DRM是绕不过去的限制。Skill能处理的是本地文件或可匿名下载的URL，像某些平台会员加密的、动态密钥的播放地址都没法处理。这不是Skill的问题，是底层抓取和版权边界决定的。

4.3 和原生视频模型相比，它的位置在哪里

现在业内已经有一些原生支持视频输入的模型的进展，但claude-video这类Skill和它们不是替代关系，而是互补关系。原生视频模型是“黑盒看视频”，直接从视频流里理解意图，链路短但不可审计，调参空间有限；Skill方案是“分阶段抽帧 + 多渠道信息融合”，输出结果透明，可以溯源，可以随时介入调整。

我在实际产线上经常把两者组合使用：先用claude-video抽帧生成索引，把长视频变成可检索的结构化文档，等需要深挖某段时，再把那几秒的片段交给原生视频模型做定向理解。这样成本低，精度也能满足需求。

5. 参数调整与成本控制：帧率、分辨率、token数量的三重平衡

用好claude-video，最核心的功课就是学会控制“看”多少、怎么“看”。这里没有绝对正确的参数，但有可复用的方法。

5.1 控制视觉token的三个关键变量

第一个变量是抽帧数，这是我们最大的成本杠杆。从8帧到60帧，视觉token差距可以达到好几倍。

第二个变量是分辨率。抽出来的帧不要直接全尺寸喂给模型，先缩到短边720像素，视觉token能显著下降，信息损失却很小。视频画面本身有大量冗余细节，720px足够让模型看懂内容。

第三个变量是JPEG压缩质量。设成80的压缩质量，肉眼几乎分辨不出区别，但文件体积会小很多，视觉模型处理时开销也更低。

这三件事组合起来，效果很可观。给你一个我常用的ffmpeg命令，里面同时体现了场景检测和分辨率控制：

ffmpeg -i input.mp4 -vf "select='gt(scene,0.3)',scale=720:-2" -vsync vfr frames/%04d.jpg

这里的 scene 阈值是0.3。0到1之间，阈值越高，抽帧越挑剔。0.3适合节奏较快的视频；慢速课程可以调到0.4到0.5，减少重复帧。 scale=720:-2 表示缩放宽度不超过720，高度按比例自动计算且保证偶数，避免编码器报错。

如果视频是PPT录屏这一类，即使调高了阈值，每翻一页PPT仍然会触发扬景变化导致抽帧过多。我再加一层过滤：对抽出来的帧计算相似度，如果相邻两帧过于相似就丢弃只保留一张，这个去重动作能再砍掉不少冗余帧。

5.2 实测token消耗参考

以下数据来自我本地跑过的几个样本，建议当作数量级参考，不要当成精确值：

视频类型	采样方式	视觉token估算	音频转写token约	成本档位
10分钟录屏	均匀20帧 + 缩放720px	1万到2万	约2000	低
45分钟中文课程	场景检测40帧 + 缩放720px	2万到4万	约8000	中
2小时会议录像	混匀 + 场景检测最多60帧	4万以上	约1.5万	高

同一段视频，如果你不缩放，直接喂原始1920×1080的帧，视觉token会多出好几倍，成本直接翻上去。这也是控制成本时第一个要检查的地方。

5.3 怎么科学地调整采样参数

在Skill的配置文件里，我建议把这些参数做成可调项，每次修改不用改代码：

sample_mode: hybrid   # uniform | scene | motion | hybrid
max_frames: 60
scale_width: 720
jpeg_quality: 80
with_ocr: true
with_asr: true
scene_threshold: 0.3
motion_score_threshold: 0.15

一套我认为靠谱的调试流程是“先粗后细做增量”：

1. 用低分辨率、低抽帧数先跑一遍，快速得到初步结果。
2. 让Agent阅读结果，把不确定或遗漏的内容点列出来。
3. 针对模糊时间段，只对那几秒做增量抽帧，定向补充。

这个思路好比先看地图全貌，再放大某个街区。整体成本控制效果很好，因为你只在必要的地方花钱。

6. 从Demo到落地：与现有Agent工作流的结合方式

能跑通只是第一步，怎么融合进实际工作流，才是真正影响生产力的问题。这里分享几个我实践过的落地场景。

6.1 作为知识管理工具链的入口

最简单的落地方式，是把视频变成结构化文档后导入知识库。专门做开发的人可以把JSON输出导入向量数据库，实现语义检索。个人的知识管理场景反而更简单：每个视频生成一个Markdown文件，按日期和主题归档，放到Obsidian或Notion里，就能全局搜索。

我用一个实际案例说明：手上有100多个技术分享视频，过去想找“哪一次分享聊过分布式事务”只能靠记忆或一个个打开。现在我用claude-video批量生成文档，再丢进本地知识库，搜“分布式事务”直接能定位到那期视频第几分钟，完全摆脱了“视频内容等于不存在”的尴尬。

6.2 在多Agent架构里扮演感知器官

在更复杂的Agent系统里，claude-video是可以作为“感知环节”存在的。比如做一个新闻短视频分析集群，整个流程可以这样设计：

1. 采集Agent负责下载视频。
2. claude-video输出结构化“脚本 + 字幕 + 画面描述”。
3. 事实核查Agent把转写文本与公开资料比对，标注存疑点。
4. 摘要Agent把多个视频的结果合并生成日报。

这个流程里每个环节之间通过统一的JSON接口衔接，Agent之间不需要互相知道对方内部实现，只要认准数据结构就行。单独把claude-video拎出来当一个微服务，也不会和别的环节冲突。

6.3 和其他Skill的组合玩法

Agent生态最有意思的地方是Skill之间可以拼装。claude-video的输出格式是标准文档，所以它可以很自然地接在别的工具后面。

比如，claude-video生成带时间轴的描述文档后，你可以让一个“流程拆解Skill”把这个文档改写成操作手册、培训讲义或问题排查步骤。反过来，其他工具产生的章节信息也可以传给claude-video，作为抽帧时的时间范围提示，让采样更有针对性。本质上你是在搭一套Lego，claude-video是其中一个成色不错的积木块。

6.4 我在落地时踩过的坑

最后照例说说踩坑经验，这几条基本是绕不过去的。

第一，文件路径约定要统一。批量处理多个视频时，如果输入参数有时给绝对路径、有时给相对路径，脚本很容易在拼接时出错。建议在Skill内部约一个统一的工作区，所有中间帧、临时文件都放这里，循环每个视频时清空上一次的产物，避免串数据。

第二，并发处理要限制。多个视频同时跑ffmpeg多路解码，很容易把CPU打满，机器直接卡死。我的做法是加并发上限，或者干脆串行队列执行，牺牲一点速度换稳定。

第三，ASR模型首次运行要下载权重文件，有些网络环境下会卡在下载那一步。我后来改成先把需要的模型用脚本预下载到缓存目录，再进入正式流程，从根上避免了这个问题。

第四，临时文件要勤清理。一个两小时的视频，hybrid模式可能会生成上百张JPG，占几百MB磁盘空间。所以Skill脚本一定要在运行结束前清理临时帧目录，只保留最终的结构化输出文档，否则磁盘很快就会被塞满。