做 Agent 开发的人应该都有过这个念头：模型啥都好，就是好像有点“瞎”。文字、代码、图片都能处理，但你扔给它一个视频，它就愣住了。我最早遇到这个场景，是想让 Agent 帮我整理一套录播课的重点，结果它只能干瞪眼。后来我琢磨着，既然模型有视觉能力，那我能不能把视频拆开，喂给它“看”？这就是我折腾出 claude-video 这个 Skill 的起点。折腾完之后发现，这东西不只是能处理录播课，短视频、发布会回放、产品演示视频，甚至监控录像，都能派上用场。这篇文章就把我整个实现过程、踩过的坑、以及一些好用的技巧全部分享出来，希望对正在搞 Agent 开发或者想给自己的 Agent 加点“感知能力”的朋友有实际帮助。

1. 这个 Skill 解决的是什么问题

1.1 Agent 为什么天生看不了视频

先说清楚一个基础事实：目前主流的多模态大模型，确实能处理图像，但视频对它们来说是个很尴尬的输入格式。视频文件本身体积大、编码复杂，模型没法像读文本那样直接吞进去。即便某些 API 支持视频输入，要么有严格的时长限制，要么成本高得吓人，要么只抽取了极少的关键帧，信息丢失非常严重。

我实测过一些号称支持视频理解的接口，本质上也是后端帮你抽帧，但抽帧策略非常粗糙，经常是每隔几秒取一帧，遇到快速运动的画面，核心信息早就过去了，结果就是模型答非所问。而 Agent 本身是一个执行框架，它的强项是规划任务、调用工具、推理决策，而不是直接处理视频这种非结构化数据。所以你让 Agent“看视频”，它其实不知道该从何下手。

claude-video 的思路很简单，就是把“看视频”这件事，从模型能力问题，变成工程问题。用工具把视频拆解成模型擅长的模态，比如图像、文本、音频转写文本，然后再交给 Agent 去分析和总结。这样一来，Agent 不需要天生会处理视频，只要会调用 Skill，它就能完成“看视频”这个任务。

提示：核心思路就是“不做超能力，只做转换器”。把视频变成模型能理解的东西，Agent 自然就能处理了。

1.2 Skill 机制与“给 Agent 装技能”的底层逻辑

在深入之前，得先把 Skill 这个东西讲明白。在 Agent 的生态里，Skill 可以理解成一个可复用的能力模块，它不是一个独立的 Agent，而是给 Agent 用的“外挂工具箱”。一个 Skill 通常包含三个部分：触发条件说明、执行脚本或工具、输出格式约定。

为什么我建议用 Skill 封装，而不是直接写死在 Agent 代码里？因为 Skill 的设计哲学是职责单一和即插即用。你可以在一个 Agent 里挂多个 Skill，视频分析、文档总结、网页抓取各干各的，互不干扰。Agent 拿到任务后，会根据任务描述自动选择合适的 Skill 来执行。这个模式特别适合现在主流的 Agent 框架，比如 Claude Code、Codex、OpenCode 这类工具链里的 Skill 体系，原理都是相通的。

claude-video 这个 Skill 的设计目标非常聚焦：输入一个本地视频路径，输出一份结构化的视频分析报告。Agent 拿到这个报告之后，就能基于它做各种后续任务，比如写总结、提炼要点、回答具体问题。整个过程对 Agent 来说，就是“调一个函数，拿到一份文档”这么简单。

2. 核心实现原理：视频是怎么被“看懂”的

2.1 视频拆解：抽帧是最稳的起点

要让模型“看懂”视频，我试过好几条路子，最后验证下来，最稳的还是抽帧。视频本质上是一连串的静态图像按时间顺序播放，人眼看起来是连续的，但模型不需要这种连续性，它只需要足够多的关键画面就能理解内容。

抽帧的关键决策点是“怎么抽”。我初期试过均匀抽帧，直接指定数量，比如一个 10 分钟的视频抽 20 帧，每 30 秒取一帧。这种做法简单，但问题很大。如果视频里有快速变化的画面，比如产品演示中的操作步骤、教学视频里的板书切换，30 秒一帧完全不够用，关键信息直接漏掉。后来我改用基于场景切换的抽帧策略，通过检测画面的亮度、色彩、边缘特征变化，找到视频中画面发生剧烈变化的瞬间，在这些节点上抽帧。这样既能保证关键画面不丢，又能避免连续相似帧造成的信息冗余，效果好得多。

在具体实现上，我用的是 ffmpeg 的 select 滤镜配合 scene 参数。这个参数检测画面的变化程度，超过阈值就认为是场景切换，输出该帧。阈值调得太低会抽出大量相似帧，调得太高又会漏掉重要画面，我最终定在 0.3 左右，对大多数视频效果都不错。抽完帧之后，我会用 scale 把帧图统一缩放到模型能接受的尺寸，避免过大的图片拖慢处理速度，然后按时间顺序编号保存。

2.2 多模态识别的两条路线

抽帧只是第一步，拿到了图像序列后，需要让模型真正“看”这些图。这里有两条路线可选。

第一条路线，也是最直接的，就是把抽到的帧图直接交给多模态大模型，让模型针对每一帧输出文字描述。这种方式的好处是，模型能看到真实的画面信息，比如 PPT 上的文字、产品的实物外观、人物的表情动作，视觉还原度最高。缺点是逐帧调用成本较高，而且如果一帧图里信息量很大，模型的描述可能会漏掉细节。

第二条路线是结合 OCR 和视频中的字幕轨道。很多视频，尤其是教程类和会议类，都有清晰的字幕或讲解词，这些文本信息其实是理解视频内容的捷径。我通常的做法是：先用 OCR 工具识别视频画面中的文字，同时用 ffmpeg 提取视频的字幕轨，如果视频没有字幕轨，就用 ASR（自动语音识别）工具把音频转写成文本。文本信息非常密集，模型处理起来又快又准。

在实际的 Skill 设计里，我两条路线都会走。先提取文本级信息，让模型对整个视频的内容框架有个基本认知，再结合关键帧图像补充视觉细节，最后将两份信息合并输出。这样既保证了内容的完整性，又控制了成本，两条腿走路的稳定性远高于单条路线。

2.3 字幕与音频：被忽视的信息富矿

很多人在做视频理解的时候，会下意识地只关注图像，这其实是捡了芝麻丢了西瓜。我做了几个测试视频的分析对比，发现字幕和音频转写文本的信息密度，远远高于抽帧图片。原因很简单，视频里的语言信息往往是经过精心组织的，像录播课、讲解视频、会议录像，核心内容几乎全部在语言里，画面反而只是辅助。

所以我在 Skill 里把音频转写放在了一个非常靠前的位置。技术上用的是 ffmpeg 提取音频轨，然后调用 ASR 服务把音频转成带时间戳的文本。转写完成后，会生成一个类似“对话记录”的文本文件，每一条都包含开始时间、结束时间和说话内容。这份文本文件对 Agent 来说，就是一份结构清晰的视频内容索引，后续的所有分析都能基于它展开。

有个细节值得提一下，就是不同说话人的区分。如果视频是多人对话，转写工具通常能区分不同的说话人，生成类似“说话人 0”“说话人 1”这样的标签。有了这个标签，Agent 就能做更精细的分析，比如统计每个说话人的发言时长、提炼每个人的核心观点，这在会议纪要场景下非常有用。

2.4 整条流水线怎么串起来

理解了单点技术之后，整条流水线的设计就水到渠成了。我把 Skill 的内部流程设计成五个阶段：任务解析、媒体拆解、信息抽取、语义理解、报告生成。

任务解析阶段，Agent 会读取用户的输入，判断视频文件的路径、时长、以及用户希望分析的重点，比如“总结要点”还是“找某个片段”。媒体拆解阶段，调用 ffmpeg 完成抽帧、音频提取、字幕提取三个任务。信息抽取阶段，分别处理帧图和音频转写文本，生成多个中间文件。语义理解阶段，模型把中间文件聚合成一个整体的理解，这里通常会分几步走，先分别总结视觉信息和语言信息，再做信息融合。报告生成阶段，将理解结果按照预设的模板输出成结构化报告。

整个流程设计成一个链式结构，上一个步骤的输出是下一个步骤的输入。这样做的好处是每一步都可以单独替换或者优化，比如你有更好的抽帧算法，只替换媒体拆解这一层就行了，完全不需要动其他部分。

3. 实操过程与核心环节实现

3.1 工具选型与安装清单

先给出我实际使用的工具清单，都是开源或者免费的工具，没有特殊环境要求，普通开发机就能跑。

• ffmpeg：版本 4.4 以上，负责视频解码、抽帧、音频提取。安装方式不展开说了，Windows、macOS、Linux 都有现成的包。
• Python 3.9+：用于编写 Skill 的执行脚本，主要调用 ffmpeg 和后续的模型 API。
• faster-whisper：开源 ASR 工具，基于 Whisper 的优化版本，CPU 环境下速度还不错，准确率也能接受。
• 多模态模型 API：例如 Claude 或者支持视觉输入的模型接口，用于帧图分析和文本理解。
• Pillow：Python 图像处理库，用于帧图的尺寸调整和基础校验。

安装完毕之后，写一个环境检查脚本，确认 ffmpeg 是否在 PATH 里、模型 API 的 key 是否能正常调用。这个步骤很基础，但很多人会跳过，结果在运行 Skill 的时候卡在环境问题上，排查半天才发现是 ffmpeg 没装好。

3.2 Skill 的目录结构与配置说明

一个标准的 Skill 要能被 Agent 正确加载，目录结构必须符合框架约定。我的 claude-video Skill 结构是这样的：

claude-video/
├── SKILL.md          # Skill 的说明书，Agent 通过它了解这个 Skill 的用法
├── requirements.txt  # Python 依赖列表
├── scripts/
│   ├── preprocess.py # 视频拆解脚本：抽帧、提音频、转写
│   ├── analyze.py    # 图像语义理解脚本
│   └── report.py     # 报告生成脚本
└── config/
    └── settings.yaml # 模型 API 配置、抽帧参数、输出偏好

SKILL.md 是整个 Skill 的门面，Agent 每次执行任务之前都会先读它。里面需要写清楚这个 Skill 是干什么的、输入参数有哪些、输出格式是什么样的、有哪些限制。如果这份说明写得太模糊，Agent 可能会误调用或者不知道怎么调用，所以一定要写得详细具体。我自己的 SKILL.md 里甚至会写一个简短的示例用法，Agent 看了之后就能照着做。

config/settings.yaml 里放的是可调参数。抽帧的场景检测阈值、输出图片的尺寸、是否启用音频转写、ASR 的语言选项，都在这里配置。这样调参的时候不需要改代码，改配置文件就行，对非技术人员也友好。

3.3 核心脚本的工作流程解析

preprocess.py 是整个 Skill 的技术核心，我拆开讲讲它的逻辑。

脚本接收一个视频路径参数后，首先用 ffprobe 获取视频的基本信息，包括时长、分辨率、是否有音轨和字幕轨。这个信息的用途是动态调整后续参数。比如视频时长只有 30 秒，那抽帧数量就应该少一些；视频分辨率是 4K，帧图就得缩小，不然处理起来太慢。

接着抽取音频，用 ffmpeg 转成 16kHz 单声道的 WAV 格式，交给 faster-whisper 转写。这个采样率是语音识别里常用的配置，既能保证识别效果，又不会产生过大的文件。转写结果保存为带时间戳的 JSON 文件，每一段都记录起止时间和文本。

抽帧逻辑我前面提到过，就是用 scene 滤镜检测场景变化。这里有一个小优化，我会设定一个最长间隔，即使画面一直没有太大变化（比如一个静态的课堂画面持续了很久），也至少每 60 秒抽一帧。因为长时间的静态画面可能也隐含重要信息，比如黑板上的字、屏幕上的代码，给模型看一眼没有坏处。

analyze.py 负责把抽出来的帧图分批交给多模态模型理解。这里对并发和上下文窗口的管理比较讲究，一次性把几十张图全塞进去，输出质量会下降。我测试下来，一批处理 5 到 8 张图效果最平衡。每张图要求模型输出“画面描述 + 画面中的关键文字信息”，这样信息结构化程度高，后续融合时不容易乱。

report.py 将前两步的产物整合起来，配合预设的提示词模板，让模型生成最终的分析报告。报告输出为 Markdown 格式，内容包含视频概览、分段内容摘要、关键信息提取、以及按用户需求定制的重点分析。

3.4 从输入到输出的完整演示

拿一段 8 分钟的产品演示视频举例。用户对 Agent 说：“帮我看一下这个视频，然后告诉我这个产品的主要功能和使用流程。”

Agent 解析任务之后，调用 claude-video Skill。preprocess.py 开始工作，ffmpeg 抽取了约 120 张场景帧，提取了音频并转写成约 2000 字的文本。analyze.py 分批处理了这些帧图，生成了画面描述和关键文字信息。report.py 综合所有信息，最终输出如下报告：

• 视频概览：这是一个名为 XX 的 SaaS 产品的 8 分钟演示视频，主讲人从头到尾演示了产品的主要操作路径。
• 产品功能点：报告列出登录、项目创建、成员协作、权限管理、报表导出等 8 个功能点，每个功能点都附上了对应的视频时间戳和画面描述。
• 使用流程：报告梳理出从注册到导出报表的完整使用链路，标注了每个步骤中操作的关键位置。
• 补充信息：报告额外指出演示中提到了产品的定价页面和试用限制，这些信息隐藏在画面的角落文字里，如果只看转写文本很容易漏掉。

整个过程大约耗时 3 分钟，其中大部分时间花费在音频转写上，抽帧和图像理解相对较快。将这个过程与手动看视频做笔记相比，效率和信息完整度都有了质的提升。

4. 常见问题与排查技巧实录

4.1 问题速查表

我把自己在实际使用中遇到的典型问题整理成了一张表，这些问题几乎每个人都会碰到。

问题	现象	根本原因	排查与解决办法
抽帧数量过多或过少	报告信息冗余或关键信息缺失	scene 阈值设得不合适	调节 config 里的 scene 阈值，同时检查是否设置了最长间隔，两者配合使用
视频无音频轨	音频转写为空	视频本身是无声的	启动 Skill 时先检测音轨，无音轨则直接跳过 ASR，靠把帧图分析作为主要信息源
ASR 转写准确率低	出现大量同音错字	背景音乐干扰或专业术语未识别	尝试用 ffmpeg 做简单降噪或人声增强，或在 ASR 参数里指定领域或语言模型
帧图尺寸过大	API 调用超时或费用暴涨	原视频分辨率过高	在 preprocess.py 里统一缩放帧图，长边限定为 1024 像素
报告出现幻觉	模型描述了视频中不存在的画面	多模态模型对模糊帧图脑补	在提示词中严格要求模型“仅根据提供的画面和文本作答，不确定的部分明确标注”；同时对模糊帧图直接丢弃，不送入模型

4.2 几个容易踩坑的细节

除了表格里的问题，还有几个隐蔽的坑值得单独拿出来说。

第一个坑：直接把视频文件作为 API 输入。即便某些模型接口宣称支持视频输入，我也强烈建议不要这么做，除非你的视频非常短。视频文件本身包含大量冗余信息，直接送进去，不仅费用高，处理时间也长，而且模型内部的实际处理逻辑对你不可见，你很难判断它是否真的“看”到了关键内容。用自己控制的抽帧管线，每一步都可控、可审计，这是工程上更稳妥的做法。

第二个坑：忽视视频的音频信息。我见过很多初版的视频理解 Skill，只抽帧不做音频转写，效果差得惊人。视频里的人物对话、讲解、旁白，承载了大量语义信息，不经过 ASR 提取就是巨大的浪费。如果有条件，音频转写这块千万别省。

第三个坑：提示词写得太随意。不少人在调用多模态模型分析帧图时，只写一句“描述这张图片”，这样得到的描述质量通常很一般。我后期会在提示词里明确指出分析重点，例如“这是一段产品演示视频的某一帧，请提取画面中所有可见的文字信息，并描述当前界面所展示的功能模块”。提示词越具体，输出越可控。

4.3 提升识别质量的三条心得

第一，善用“过采样 + 后筛选”的组合策略。抽帧宁可多抽，也先别担心成本。我把每批图片送入模型后，都会要求模型标注每张图的信息价值（高、中、低）。最终生成报告的时候，信息价值高的图会被重点描述，信息价值低的图就直接略过。这样既不会漏信息，也不会让输出变得冗长。

第二，区分场景，采用不同的 ASR 参数。如果视频是多人会议，开启说话人分离；如果视频带有明显的专业术语，比如医疗、法律、编程，尽量在 ASR 工具里指定对应领域的语言模型或提示词，准确率能提升不少。

第三，时间一致性很关键。在抽取帧图和转写文本时，所有产物都必须保留绝对时间戳。这样在报告生成阶段，模型可以准确地说出“在 02:35 处，画面上出现了 xx”，而不是模糊的描述“在视频中段”。时间戳是后续用户按图索骥、回看视频的关键锚点，不能丢。

5. 应用场景、效果边界与扩展方向

5.1 什么场景下效果最好

根据不同视频类型的实测，我总结出一张效果对照表。

视频类型	推荐分析策略	效果评价与说明
录播教程、网课	音频转写为主 + 关键帧为辅	效果极好。课程内容基本全在语言里，转写文本可准确提炼知识点，帧图补充课件的公式和图表
产品演示视频	帧图分析为主 + 音频转写为辅	效果优秀。画面操作路径是核心信息，帧图的界面文字识别很有价值
多人会议录像	音频转写 + 说话人分离	效果良好。能自动生成会议纪要，按说话人提炼观点，但需要讲话人声音清晰
短视频（弹幕版）	音频转写 + 字幕提取	效果一般。短视频信息密度低，有时画面创意比语言内容更重要，纯文本模式容易漏掉重点
长时间监控录像	帧图分析为主，按时间间隔采样	效果普通。监控画面通常静态内容多，抽帧信息量低，如果要做异常检测，建议用专门的行为识别模型，这类通用分析 Skill 并不擅长

5.2 这个 Skill 做不了的

这里想很诚实地讲一讲边界，免得有人拿去用之后觉得不靠谱。

最明显的问题：复杂场景的行为理解。比如“视频里这个人是在鼓掌还是在挥手”这种问题，这类 Skill 是无法有效处理的。因为帧图是离散的，行为是连续的变化过程，从几帧静态图推断行为，准确率很低。真要处理这类需求，得用专门的行为识别模型或者视频理解的专项模型，不是一个用抽帧 + 多模态 API 的 Skill 能覆盖的。

另一个问题是长视频的上下文管理。如果视频超过 1 小时，抽出来的帧图很容易超过几百张，转写文本也动辄上万字。把这么多内容一次性放进上下文窗口里，再让模型做综合提炼，效果会明显下降。我的处理方式是把视频按语义切成多个片段，分别生成片段级摘要，再在更高层级把摘要合并成整体报告。这种方式能缓解长距离信息关联的问题，但比真正端到端的视频理解模型还是差一些。

5.3 后续可以怎么扩展

如果你用这个 Skill 跑通了基础流程，又想让它的能力更进一步，有几个方向值得探索。

第一个方向：把生成的报告反过来用于下游任务。比如把视频分析报告喂给 RAG 知识库，用户之后就可以用自然语言向 Agent 提问“视频里 XX 功能的具体操作步骤是什么”，Agent 会从报告库中检索相关片段，并带上时间戳返回给用户。这就相当于把不可搜索的视频，变成了可检索的知识资产。

第二个方向：做成多 Agent 协作的流水线。视频分析本身可以拆成多个子任务，一个 Agent 专门做帧图分析，一个专门做文本理解，还有一个负责最终的信息融合。通过编排层把多个 Agent 串起来，处理效率和并行度能得到明显提升，特别是对批量处理大量视频的场景很有用。

第三个方向：增加人机交互校验。目前整个流程是全自动的，但有些高风险场景，比如医疗手术教学视频的分析，输出的准确性要求极高。可以考虑在流水线中加入一个人工确认节点，让人类对模糊画面或关键片段做二次确认，再生成最终报告。

6. 一点实际体会

我做完这个 Skill 之后，最大的感受是：Agent 的能力边界往往取决于你给它配了什么工具，而不是模型本身有多聪明。模型的能力在那摆着，但如果没有合适的介质去连接视频这种非结构化数据，再强的模型也使不上劲。claude-video 这个项目本质上就是在做这种连接，把视频“翻译”成模型能读懂的语言，剩下的推理和总结就交给模型发挥即可。

如果你也想在自己项目里试试，我的建议是别一上来就想着做得多完善，先把最简版本跑通：抽帧、转写、分析、出报告，四步走通之后，再根据你的具体场景逐步优化。我一开始甚至没有用场景检测抽帧，只是简单均匀抽样，效果也能接受，后续才慢慢加上各种优化。工具这东西，先跑起来比什么都重要。