最近一直在折腾 Agent 项目我发现一个特别容易被忽略的短板Agent 处理文本和图片已经挺顺手了但一碰到视频就哑火。你想让它看一段产品演示、总结一场会议录像、从教程视频里提取操作步骤它往往只能回你一句我无法直接处理视频文件。这个尴尬我遇到过很多次直到我把 claude-video 这个 Skill 装进项目里情况才彻底改观。简单说claude-video 就是一个让 Agent 真正具备看视频能力的 Skill它把视频内容拆解成模型能理解的信息再交给 Agent 去分析、总结、问答。这篇文章我会从原理、部署、实际使用到避坑完整聊一遍我自己的实践过程。1. 为什么 Agent 需要看视频的能力1.1 Agent 的多模态短板视频为什么这么难处理先明确一个事实目前主流的大语言模型在处理视频时并不会像人一样播放它。模型输入的是文本 token 和图像 token视频是一个带时间轴的多模态流模型原生状态下很难直接消费。即便某些模型号称支持视频输入实际调用时的成本、延迟和上下文占用也不是常规 Agent 项目能承受的。所以大多数 Agent 框架里视频文件传进去之后模型看到的只是一个文件名、一个路径或者一串没有语义的二进制字节。这个短板在真实项目里非常致命。我自己做过一个内部知识库 Agent用户经常上传培训录像、操作录屏期望 Agent 能直接回答视频里第几分钟讲到了某个配置这类问题。最开始只能让用户手动截图再传或者我们自己先用工具把视频转成文字稿再导入流程又碎又慢。问题本质在于Agent 缺少一条从视频文件到结构化理解的标准化通路。另一个容易忽略的点是时序语义。视频和图片最大的区别在于时间维度一段操作演示视频里先点了哪里、后点了哪里本身就构成完整的信息。如果只抽一两张静态图这个顺序信息就完全丢失了。所以视频理解必须同时解决内容和顺序两个问题这比单纯处理图片要复杂一个量级。1.2 claude-video 解决的三个核心问题claude-video 这个 Skill 做的事情就是补上这条通路。它把视频理解这个大问题拆成三个子问题分别解决视频内容怎么提取通过抽帧、音频转写等操作把视频转换成模型能够处理的图像序列和文字内容。上下文窗口怎么控制一部几十分钟的视频如果全部塞进上下文任何模型都会直接爆掉Skill 需要做采样、压缩和分段。时序信息怎么保留视频的关键在于时间顺序Skill 要保证 Agent 在分析时知道画面出现的先后顺序而不是拿到一堆打乱的帧。这三个问题听起来简单但在实际实现里环环相扣。抽帧密度决定了信息完整度也决定了 token 消耗音频转写的时间戳必须和画面准确对齐上下文分段策略要保证 Agent 既能看全貌又能定位细节。后面我会逐个展开讲。总之装上这个 Skill 之后Agent 面对视频不再是无能为力而是能把视频变成可查询、可分析、可总结的信息源。对于做 Agent 开发、自动化工作流、知识库问答的团队和个人来说这基本属于刚需。我个人的体会是这个 Skill 真正的价值不在能看视频这个噱头而在于它把视频处理变成了一种可以被 Agent 编排的标准化能力。以前你写死一段视频处理脚本只能干一件事现在通过 Skill 的机制Agent 可以自己在合适的时机调用视频理解能力和其他工具组合出更复杂的工作流。比如让 Agent 先看一遍视频再基于理解结果去写文档、提 bug、生成测试用例这种编排能力才是 Agent 项目里最稀缺的东西。2. 核心原理拆解视频是怎么被看懂的2.1 Skill 在 Agent 生态里的定位在展开原理之前先得说清楚 Skill 是什么。最近 Agent 生态里 Skill 这个概念很火通俗理解Skill 就是给 Agent 用的技能包——一个定义好的能力模块里面包含提示词模板、工具调用逻辑、处理流程描述有时候还带着独立脚本。Agent 在运行时看到某个 Skill 的描述就知道遇到这类任务时我可以调用这个技能来处理。Skill 和 Agent 框架本身是解耦的。你可以把它装进 Claude Code、Codex、OpenCode也可以集成到 Spring AI 这类框架里关键在于 Skill 的入口描述和脚本逻辑是否遵循统一的约定。claude-video 走的就是这个路子它定义了视频处理的完整流程Agent 只需要按约定调用不需要自己重新实现视频处理逻辑。这里补充一下 Skill 和 Plugin、Agent 的区别很多人容易混。Plugin 通常指的是外部工具的标准化接口比如一个天气查询插件、一个数据库连接插件它解决的是Agent 怎么调用外部能力的问题。Agent 则是一个完整的决策和执行单元它能理解任务、拆解步骤、调用工具、判断结果。Skill 介于两者之间它不只是工具接口还包含了一套处理特定领域任务的方法论——用什么工具、按什么顺序、怎么组织中间结果。用吃饭来类比Plugin 是给你一把刀Skill 是教你怎么把一条鱼完整处理好Agent 是那个根据今天想吃什么来决定怎么做鱼的人。claude-video 属于 Skill因为它不只是调用 ffmpeg 抽帧这个动作而是把整个视频理解流程封装成了一套可复用的方法论。2.2 抽帧、视觉理解与时序聚合的处理管线claude-video 的核心处理管线大概分四步。理解这条管线你就理解了这个 Skill 的大部分设计逻辑。第一步是抽帧。用 ffmpeg 按固定间隔从视频里抽取关键帧比如每秒抽一帧或者按场景切换抽帧。抽帧间隔直接影响信息密度和成本抽得太密token 消耗大抽得太疏关键画面容易漏掉。我一般建议先按每 5 秒一帧起步再根据视频内容和任务类型调整。如果是操作演示类视频画面变化频繁可以适当加密如果是讲座类视频画面基本不变抽帧间隔拉大反而更省资源。第二步是视觉理解。抽出来的帧会经过图像压缩和预处理然后贴上有序编号交给视觉模型逐张或者分批理解。每一帧都会被转化成文本描述画面里有什么人、什么物体、什么界面、什么动作、出现了什么文字等等。这一步的关键在于描述粒度。描述太粗比如只写屏幕上有一个窗口后面分析时信息不够用描述太细比如把每个像素颜色都写出来token 消耗又失控。实际使用中需要在提示词里明确要求模型关注与任务相关的视觉元素比如界面元素、人物动作、文字内容、数据图表而不是泛泛地描述场景。第三步是音频转写。视频里的信息有很大一部分在声音里尤其是讲解类视频。claude-video 会调用 Whisper 或其他语音识别工具把音轨转成带时间戳的文字稿。这一步和抽帧是并行的两路信息最后再合并。时间戳特别重要它是后面做时序对齐的锚点。如果没有时间戳视觉描述和语音内容就无法准确对应整个分析结果会变得混乱。第四步是时序聚合。把图像描述和音频文字稿按时间轴对齐生成一份结构化的视频内容摘要或者按时间段建立索引。这时候 Agent 拿到的就不再是一堆帧而是一份带时间线的视频文字版。聚合阶段还需要做一次去重和压缩因为相邻帧的描述往往高度重复直接拼接会造成大量 token 浪费。比如一个画面静止了 30 秒抽了 6 帧描述都差不多这时候只需要保留第一帧和最后一帧的描述中间标注画面持续 30 秒无变化即可。为什么非要用这条管线因为直接让模型看整个视频文件是不现实的。视频本质上是连续帧加连续音频的组合体积和 token 消耗都远超模型限制。抽帧加转写本质上是把连续信号离散化用尽量少的数据保留尽量多的语义信息。这个思路跟视频编码有点像——不是把每一帧都完整存下来而是只存关键帧和帧间差异解码时再还原。claude-video 做的事情在语义层面也是类似的丢掉冗余的连续信息保留关键语义节点。2.3 为什么听和看要双通道并行很多人第一次接触这种 Skill 都会有个疑问只做音频转写不就行了吗毕竟大模型对文本的理解能力最强把视频转成文字稿塞给 Agent 不就行了实际用下来你会发现纯转写会丢掉大量信息。产品演示视频里画面上高亮的按钮、报错弹窗、鼠标划过的路径这些在音频里根本不存在反过来教学视频里讲解员说的关键步骤光看画面也猜不准。举一个我实际遇到过的例子。有一次让 Agent 分析一个软件操作录屏视频里操作者没有说话只有键盘鼠标声音。如果只做音频转写得到的基本是空内容。但是通过抽帧加视觉理解Agent 能清楚看到操作者依次打开了哪些菜单、修改了哪些配置项、最终界面出现了什么结果。这就是看的价值。再举一个反向的例子。一段技术分享视频画面只有一个 PPT 在翻页但讲解员口述了大量背景知识和设计思路。这时候音频转写的信息密度远高于抽帧光看画面只能得到PPT 从第 3 页翻到第 15 页这种毫无营养的信息。两条通道单独拿出来都有缺陷合并起来才能互补。所以 claude-video 的设计逻辑是双通道输入视觉通道负责看到什么音频通道负责说了什么两条信息流在时间轴上对齐之后Agent 才有能力回答他在演示第几步的时候点了哪个按钮这种跨模态问题。这也是这个 Skill 比起简单视频转文字脚本的高级之处。双通道还有一个附带好处当其中一个通道信息缺失时比如视频没有音轨、或者画面是静止的系统能自动依赖另一个通道鲁棒性更高。3. 安装与部署实操3.1 环境准备与依赖安装在动手安装之前先把环境理清楚。claude-video 这样的 Skill 通常依赖三类组件一是 Agent 运行环境也就是你平时跑 Agent 的那个框架二是视频处理工具主要是 ffmpeg用来做抽帧和音轨提取三是语音识别工具比如 whisper.cpp 或 OpenAI 的 Whisper API用来做音频转写。以我常用的环境为例操作系统是 Ubuntu 22.04Agent 框架用的 Claude CodePython 版本 3.10 以上。ffmpeg 的安装很简单直接 apt 装就行sudo apt update sudo apt install -y ffmpeg装完之后验证一下ffmpeg -version只要能看到版本号输出这一步就算过了。语音识别这块我建议先直接调用 Whisper API部署最快、效果最稳缺点是有网络依赖和调用成本。如果对隐私有要求或者视频量大、成本敏感可以部署本地版 whisper.cpp模型用 base 或 small 级别就够用再大了转写速度会明显变慢。还有一个容易被忽略的依赖是图像预处理库。很多视频抽出来的帧分辨率很高直接送给视觉模型既费 token 又容易超出模型的图像尺寸限制。我习惯用 Python 的 Pillow 库统一做缩放和压缩pip install Pillow典型做法是把帧宽度缩到 1280 像素以内JPEG 质量压到 80 左右。这个体积下的图像视觉模型识别准确率基本不受影响但 token 消耗能省将近一半。3.2 将 claude-video 安装为 Skill环境准备好之后就可以把 claude-video 安装到 Agent 里了。Skill 的安装方式因框架而异但核心逻辑是一致的把 Skill 的目录放到 Agent 能找到的位置然后在 Skill 的配置文件里声明好入口描述和处理流程。以 Claude Code 为例它会扫描项目目录下的.claude/skills文件夹每个子目录对应一个 Skill。所以安装步骤就是mkdir -p .claude/skills git clone https://your-repo/claude-video.git .claude/skills/claude-video克隆下来之后检查目录结构。一个标准的 Skill 目录通常包含SKILL.md技能描述文件这是 Agent 最先读取的内容里面写清楚这个技能是干什么的、什么时候该用、怎么用。scripts/具体的处理脚本比如抽帧脚本、转写脚本、聚合脚本。assets/提示词模板、配置文件等辅助资源。SKILL.md 是整个 Skill 的灵魂Agent 通过它来判断是否调用这个技能。我之前自己写 Skill 的时候吃过亏描述写得太泛结果 Agent 在根本不需要视频理解的任务里也去调用它浪费了大量时间和 token。建议描述里写清楚触发条件比如当用户提供视频文件或视频链接且任务涉及视频内容分析、总结、问答时使用此技能。装完之后可以先用一个短视频做冒烟测试。找一个 10 秒左右的视频让 Agent 简单描述一下视频内容。如果 Agent 能准确说出画面里的主要元素和动作说明安装成功整个链路是通的。如果这一步就出问题后面基本不用继续了先排查链路。3.3 配置项详解帧率、分辨率和 token 预算安装只是第一步真正决定效果的是配置。claude-video 里几个关键配置项我把我的调参经验直接列出来。抽帧间隔是最重要的参数。我的经验值产品演示和操作录屏类视频每 2 到 3 秒抽一帧讲座和访谈类视频画面变化少每 10 到 15 秒抽一帧就够。新手最容易犯的错是怕漏信息所以猛抽帧结果一个 1 小时视频抽出上千帧视觉模型处理时间极长token 费用直接爆炸而且相邻帧之间信息高度冗余对分析结果没有实质帮助。记住一个原则抽帧密度只要保证关键画面不漏即可不需要还原每一个瞬间。分辨率方面视频帧统一缩放到 1280 宽度是性价比最高的选择。超过这个尺寸视觉模型对细节的识别能力提升非常有限但 token 消耗会成倍增长。如果有特别需要看清小字的地方可以在提示词里要求模型放大局部区域再看而不是整体提高分辨率。token 预算要分两级控制。第一级是单次视觉理解的 token 上限建议每批帧数控制在 10 到 20 张以内分批送给视觉模型避免单次请求过大被模型拒绝。第二级是最终聚合摘要的 token 上限这个要看 Agent 后续要拿这份摘要做什么。如果只是做总结3000 到 5000 token 足够如果要让 Agent 基于视频内容做逐步骤分析建议保留更多原始细节上限放宽到 8000 左右。我自己的配置经验整理成了一张表方便快速参考视频类型抽帧间隔分辨率宽度音频转写级别聚合摘要 token操作录屏2-3 秒1280高5000-8000产品演示3-5 秒1280高4000-6000讲座访谈10-15 秒960中3000-5000监控/会议录像5-8 秒1280中3000-5000这些参数不需要死记硬背关键是要理解每个参数影响什么运行时根据反馈动态调整。我现在的习惯是先按默认参数跑一遍看输出结果缺什么信息再针对性地调参。盲目照搬别人的参数不如理解自己的需求。4. 实际使用场景与效果4.1 场景一产品演示视频的深度分析第一个让我觉得这 Skill 真值的场景是分析产品演示视频。以前产品团队拿到竞品的演示录像只能人工拉片一帧一帧看对方的产品流程花大半天时间还不一定看得全。现在直接把录像丢给带 claude-video 的 Agent几分钟就能拿到一份结构化的分析报告。我实际跑过一次。视频是某 SaaS 产品的 15 分钟演示全程有英文配音画面上是密集的操作界面。我让 Agent 回答几个问题产品的主流程是什么、有哪些关键功能点、每一步操作后界面有什么变化、有哪些值得注意的设计细节。处理结果让我挺意外Agent 不仅准确列出了主流程的七个步骤还指出了演示者在第 9 分钟切换到了设置页修改了一个权限配置项这在有声轨全程讲解的情况下单纯靠音频转写是拿不到的信息。这个场景的关键在于看和听的对齐能力。演示视频里经常出现操作与讲解不完全同步的情况操作者先点击了一个按钮然后才解释这个按钮的作用。如果只有音频转写Agent 会误以为解释发生在点击之前。而 claude-video 的时序聚合能把画面和声音精确对位保证了因果关系的正确性。这一点在生成操作手册、用户引导文档这类下游任务里尤其重要因为步骤顺序错了整个文档就没法用。4.2 场景二会议录像的自动总结第二个场景是会议录像总结。团队每周都有例会动辄一两个小时不是每个人都能参加会后要补看又太费时间。以前我们会让人工把会议纪要整理出来发到群里效率低而且各人关注点不同纪要质量参差不齐。后来我试着用 claude-video 处理录屏的会议录像效果出乎意料地好。处理一次一小时会议录像总耗时大概在三到四分钟成本折算下来远低于人工整理的时间成本。输出的总结包含会议讨论的核心议题、每个议题的结论、待办事项及负责人、重要时间节点的讨论细节。这个信息密度已经超过大部分人工纪要了。特别是有屏幕共享的会议Agent 能同时看到共享的文档内容、代码片段和说话人的讲解把屏幕上讲了什么和嘴里说了什么对应起来输出质量非常扎实。会议场景还有一个显著优势数据是结构化的复用价值高。我让 Agent 把每次会议的总结按统一格式存成 Markdown 文件存档到知识库里。时间一长这份记录本身就是团队的项目文档资产。新成员加入时直接检索历史会议纪要就能快速了解项目演进过程省了大量 onboarding 成本。4.3 场景三教学视频的要点提取与索引第三个场景是教学视频处理。我平时收集了不少技术课程和行业分享视频数量多了之后管理起来很头疼内容在视频里不打开看就不知道讲了什么但每个都看完又没时间。claude-video 可以用作视频图书管理员先把视频内容结构化之后再按需取用。我处理过一个 40 分钟的技术分享视频。Agent 输出了一份分级结构的内容大纲主题、分节标题、每节的核心论点、提到的重要术语、时间戳索引。这个大纲就是一个高效的知识索引我想复习某个知识点直接按时间戳跳到对应位置就行不用从头再看一遍。更进阶的玩法是做跨视频的知识整合。把同一主题的多个视频都过一遍 claude-video让 Agent 汇总多个视频的观点找出共识和分歧。我试过把三个讲同一框架的视频放到一起分析Agent 最后输出了对比表列出了每个视频作者的侧重点和差异点这个内容单独看任何一个视频都得不出来只有跨视频对比才能发现。这就是把 Skill 能力叠加到工作流编排里的价值。5. 常见问题与排查技巧实录5.1 高频问题速查表用 claude-video 这段时间我陆陆续续踩了不少坑也帮同事排查过几次问题。把高频问题整理成了一张速查表建议大家先收藏遇到了直接对号入座问题现象可能原因处理办法Agent 无法识别视频文件Skill 没有正确安装或路径不对检查.claude/skills目录结构确认 SKILL.md 存在且有描述抽帧速度极慢视频分辨率过高或抽帧间隔过密先降低分辨率再拉大抽帧间隔必要时加 -ss 参数做随机抽样视觉模型报图片过大单帧分辨率超出模型限制用 Pillow 统一缩放到 1280 宽度内并压缩 JPEG 质量音频转写结果为空视频里静音或音轨格式不兼容先用 ffmpeg 把音轨转成 16kHz 单声道 WAV 后再转写总结内容时序混乱时间戳没对齐或聚合逻辑有 bug检查转写结果里每条是否带时间戳抽帧描述是否带帧号token 消耗异常大相邻帧描述过度冗余在聚合阶段做去重静止画面只保留首尾帧描述生成内容答非所问视觉描述的粒度与任务不匹配在提示词里明确要求关注任务相关的视觉元素而不是泛泛描述这张表里最容易被人忽视的是第一条。Skill 装好了但 Agent 压根不知道它存在这种问题最常见的原因是 SKILL.md 的描述写得不够明显。Agent 是在任务中途扫描可用技能的如果描述里没有明确提到视频分析总结等关键词它可能根本不会触发这个 Skill。我后来把所有视频相关的触发词都写进了描述开头的两行里问题直接消失。5.2 我踩过的几个坑从沉默到胡说排查问题过程中最有意思的是两类难搞的失败模式一类是 Agent 完全沉默另一类是 Agent 一本正经地胡说八道。沉默型失败通常出在 token 超限上。有一次我处理一个 2 小时的长视频没有做分段就直接整段丢给聚合模块结果单次请求的上下文直接爆了Agent 没有任何输出。后来我改成了滑动窗口策略先把视频按 10 分钟切成一段每段单独处理再把各段的结果汇总到最终聚合。这样每次请求的上下文都控制在合理范围内长视频也能稳定跑完。这个思路和数据库分页有点类似与其一次加载全部数据不如分页拉取再加总。胡说型失败更值得警惕。有一次处理监控视频画面清晰度不高视觉模型把一个人影误判成了某种设备Agent 基于这个错误信息得出了完全离谱的结论。排查时我发现自己犯了一个错误监控视频本来就模糊抽帧后又做了二次压缩细节进一步丢失模型的误判率大幅上升。解决方法有两个一是对这种低清晰度视频跳过压缩步骤保持原始分辨率二是在提示词里明确标注画面质量偏低要求模型在不确定时如实说不确定而不是强行编造。这个思路在 Agent 场景里特别重要——宁可让 Agent 承认自己看不清也不能让它自信地输出错误信息。5.3 性能优化与成本控制建议最后聊一下性能和成本。跑视频理解类任务比纯文本任务贵这是不可避免的但优化空间也很大。第一个优化点是缓存。同一个视频如果被多处引用重复抽帧和转写非常浪费。我的做法是处理完一个视频后把抽帧描述和音频转写结果缓存成 JSON 文件下次同样的视频直接读取缓存。视频内容不会变处理结果是可以复用的。在知识库场景里这个优化能把整体成本降到原来的三分之一甚至更低。第二个优化点是并发控制。处理几十个视频时串行跑要等很久。ffmpeg 抽帧和 Whisper 转写都是独立的可以多路并行。我一般用 Python 的 asyncio 或者任务队列来控制并发数一次跑 4 到 6 个任务既不会把 CPU 打满也能显著缩短总耗时。但如果用的是 Whisper API 这类外部服务注意并发限制超了会被限流反而更慢。第三个优化点是分级处理。不是所有视频都需要全量分析。我先让 Agent 快速抽少量帧和短音频片段生成一个粗略预览告诉用户这个视频大概讲什么。用户确认值得细看之后再跑完整管线。这个模式在视频库筛选场景里非常实用几分钟就能粗筛几十个视频找出真正需要精读的那几个。6. 扩展把 claude-video 融入更大的 Agent 工作流聊完基础使用再说说更进阶的玩法。claude-video 单独用已经很好用但它的威力真正释放是在和其他能力组合编排的时候。我目前已经在项目里把 claude-video 和几个下游任务接在了一起。第一个是视频驱动的文档生成。拿到视频分析结果之后让 Agent 自动生成操作手册、产品说明或培训讲义。以前写文档的人需要反复看视频确认细节现在 Agent 已经把细节提取好了文档生成只是基于结构化信息的再加工。我做过一个实验用同一段产品演示视频生成了一份完整的 FAQ 和一份新手教程两份文档风格和侧重点完全不同但核心信息都准确这个效率是人工完全没法比的。第二个是视频内容的自动化质检。把被测产品的操作录屏交给 Agent 分析让它核对每一步是否符合预期流程有没有出现异常弹窗和报错。本质上是用视频理解来自动化一部分测试验收工作。现在的 Agent 生态里测试工具很多但大多是针对代码和接口层面的UI 操作结果靠人眼看。claude-video 恰好补上了这一块让 Agent 能亲眼确认操作结果。第三个是视频知识库的问答系统。把历史培训视频、技术分享全部用 claude-video 处理成结构化索引再用一个检索问答 Agent 对接到这些索引上。用户提问之前有个视频讲过数据库迁移的注意事项具体是哪几点问答 Agent 能准确找到对应视频片段并给出答案。这相当于把原本只可看不可搜的视频资产变成了可检索的知识库对团队知识沉淀的价值非常大。最后再分享一个我个人觉得很有用的小技巧。在让 claude-video 处理视频之前先告诉 Agent 下游任务是什么这个上下文会影响整个处理管线的侧重。比如下游任务是生成操作手册提示词里就强调注意操作步骤和界面元素下游任务是写会议纪要就强调注意讨论结论和待办事项。同一个视频不同任务看重的信息点完全不同提前设定关注方向能从源头减少无效信息的提取既省钱又提升输出质量。这个技巧其实适用于所有 Skill 的使用——不要只把它当工具要把它当团队里一个可以沟通的协作者。