如果你用过Claude这类多模态模型，大概都遇到过同一个尴尬场景：资料、文档、截图扔进去都能处理得明明白白，一旦丢过去一个视频文件，得到的回复往往是"我无法直接查看视频内容"。图片能看、文字能读，为什么视频就不行？其实不是模型本身不行，而是缺少一层把视频"翻译"成模型能理解的信息的中间件。claude-video这个Skill，就是干这件事的——它让Agent真正拥有"看视频"的能力，不需要换更大的模型，不需要给模型做微调，只靠一套Skill机制加几条自动化管线就能实现。

这篇文章我会从Agent视觉能力的底层限制讲起，拆解claude-video的设计思路、工程结构、核心实现，以及我在实测中踩过的坑和优化经验。如果你正在做Agent开发，或者想给自己的Agent扩展视频理解能力，这篇应该能帮你省下不少弯路。

1. Agent的"眼睛"为什么看不了视频：上下文窗口与信息密度的矛盾

1.1 模型有视觉能力，但视频不是"一张大图"

很多人误以为Claude这类多模态模型看不了视频，是因为模型不支持视觉输入。这个认知其实不对。Claude本身具备很强的图像理解能力，你给它一张复杂的架构图、一份手写笔记的照片，它都能准确识别。真正的问题在于： 视频不是一张图，而是几十张乃至几千张图的连续序列，外加一条音频轨 。

我们做一个简单的数学估算。一段30秒的视频，按常见的25帧/秒算，总共750帧画面。即便只取十分之一的帧率，也有75张图。按每张图压到vision模型接口需要的最低token来估算（通常一张图最少也要几百token），75张图就已经是几万token的开销，这还没算中间过程的注意力计算量。更不用提一段30分钟的视频——哪怕经过抽帧，也能轻松突破上下文窗口的承受上限。

所以，想让Agent处理视频，本质上不是"模型能不能看图"的问题，而是"怎么把视频的海量视觉信息压缩成模型能消化的有限token"的问题。这就是claude-video存在的根本价值。

1.2 视频文件是二进制格式，模型根本"读不到"

还有一个非常容易被忽略的技术细节：模型接口处理的是文本和图像URL，视频文件的二进制流不是模型能识别的输入格式。你可以把图片base64编码后传给模型，但把视频二进制丢进去，绝大多数模型API直接就会报错或忽略。

这意味着哪怕你想走"暴力投喂"路线，让模型直接看视频流，从接口层面就走不通。视频必须先经过解码，拆解成"图像帧 + 音频文本"这样的中间表示，模型才有机会接触其中的信息。

1.3 双轨信息结构：视觉与听觉必须分开处理

视频区别于图片的核心特征是信息双轨：画面传递视觉信息，音频传递语言/声音信息。这两者的重要性在不同场景下占比完全不同——一个教程录屏视频，音频轨可能承载了90%的信息；一个监控摄像头视频，画面信息才是全部。

claude-video这类Skill的巧妙之处，就是 把视频拆成两条独立的处理管线 ：

• 画面轨 → 抽帧 → 生成视觉描述
• 音频轨 → 转写 → 生成字幕文本

最后再把两条管线的输出在时间戳上对齐合并。这样既保留了视频的完整信息，又让模型只面对结构化的文本和少量图片，而不是面对一个它处理不了的二进制怪物。

2. claude-video的核心设计：抽帧、转写、对齐三段式管线

2.1 整体架构：视频如何变成模型能"看懂"的文本报告

claude-video的完整处理链路，一句话概括就是： 解码视频，分轨提取信息，按时间戳重组为结构化文档，把这个文档交给Agent阅读 。

整个流程可以拆成五个明确的步骤：

1. 视频解码与探查 ：读取视频文件，获取总时长、分辨率、音轨信息等元数据
2. 视觉轨处理 ：按策略抽帧，保留有代表性的关键画面
3. 听觉轨处理 ：提取音频，利用Whisper等语音识别模型转写为带时间戳的文本
4. 数据对齐 ：将视觉帧描述与音频转写文本按时间线合并，生成结构化JSON或Markdown
5. Agent消费 ：将结构化文档注入上下文，Agent基于文档进行问答、总结、分析

这样的管线设计，本质上是给Agent配了一个"视频助理"：助理负责把2小时的视频压缩成5000字左右的图文摘要，Agent只读摘要就能完成大部分任务。这比把视频原封不动塞给模型要聪明得多。

2.2 为什么Skill而非独立微调模型

这里有一个很值得聊的设计抉择：为什么用Skill机制，而不是去微调一个视频理解模型？

首先，微调一个能理解视频的大模型，成本和难度根本不是个人开发者能承受的。那意味着需要海量的视频-文本配对数据，需要大规模算力训练，而且效果还未必好。其次，Skill机制的优势在于 可组合、可替换、可维护 ——底层模型升级了，Skill不用改；抽帧策略想调整，改一个脚本参数就行。

更关键的是，视频理解场景的差异化极大：有人想分析网课内容，有人想审阅监控录像，有人想总结B站测评视频。如果每个需求都去微调模型，完全不可行；但用Skill去适配不同场景，只需要改提示词和抽帧策略。

2.3 与其他视频处理方案的对比

方案	原理	视频长度限制	成本	效果
直接丢视频给模型	模型原生支持视频输入	极短（秒级）	极高	有但不可持续
字幕文件直接喂模型	仅提取音轨	长	低	丢失画面信息
逐帧截图让模型看	仅提取画面	短	中	丢失音频信息
claude-video三段式	音画分离再对齐	长	低	双轨信息完整，效果最好

从表格里能看出，其他方案都在"信息完整性"或"处理时长"上有明显短板，claude-video的三段式管线是兼顾成本和效果的最佳实践。

3. Skill的工程结构：Manifest文件、脚本与提示词的协同机制

3.1 Skill的目录结构长什么样

基于我所了解的Skill标准结构，一个完整的claude-video Skill应该包含这样几个核心文件：

claude-video/
├── SKILL.md              # Skill清单文件，向Agent声明能力
├── scripts/
│   ├── extract_frames.sh # 抽帧脚本（基于ffmpeg）
│   ├── transcribe.py     # 音频转写脚本（基于whisper）
│   └── build_context.py  # 时间轴对齐与结构化输出脚本
└── assets/
    └── video_summary_prompt.txt  # 注入给Agent的视频分析提示词

3.2 SKILL.md：Agent如何知道自己在"看视频"

在Skill机制下， SKILL.md 是Agent识别技能存在与调用边界的关键文件。manifest里会写清楚：该Skill在什么条件下被触发、需要调用哪些外部工具、有哪些已知限制。

比如claude-video的SKILL.md核心逻辑大概是：

---
name: claude-video
description: 为Agent提供视频理解能力。当用户提供视频文件路径或URL时触发。
triggers:
  - 用户上传/指定视频文件
  - 用户要求分析视频内容
steps:
  - 检查视频文件是否存在及格式
  - 调用scripts/extract_frames.sh抽取关键帧
  - 调用scripts/transcribe.py转写音频轨
  - 调用scripts/build_context.py生成结构化报告
tools:
  - ffmpeg
  - whisper

这里面的关键在于 触发机制 。Agent本身不会主动去"看"视频，它需要按照manifest中的描述，依次调用外部脚本来完成视频信息的提取。这一步做得好不好，直接决定了Agent在多轮对话中的稳定性——如果Agent不知道什么时候该调用视频分析管线，这个Skill就形同虚设。

3.3 为什么这样分层：让Agent做判断，让脚本做执行

Skill设计的一个重要原则是： Agent负责判断与推理，脚本负责精确执行 。

抽帧需要精确的ffmpeg参数，转写需要稳定的模型推理，这些都不适合让Agent在对话过程中临场发挥。相反，Agent擅长的是理解用户意图、决定调用哪条管线、对最终报告进行语义分析。

这种分层还有一个好处：测试时可以单独调脚本验证输出质量，不必每次都走整个Agent对话流程，debug效率高很多。

4. 抽帧与转写的工程实现：我采用的策略和可复用脚本

4.1 抽帧策略：固定间隔还是动态抽帧？

这是整个Skill设计里我调整最多次的参数。最初的版本做过固定间隔抽帧，每5秒抽一帧，结果遇到两小时的课程视频时，光帧就抽了1440张，后续处理直接卡死。

后来改成动态抽帧策略，根据视频总时长自适应调整抽帧间隔：

视频时长	抽帧间隔	预计帧数	适用场景
< 1分钟	0.5秒	~120	短视频、广告
1-10分钟	1秒	60-600	操作演示、新闻
10-60分钟	3秒	200-1200	网课、会议录像
> 60分钟	5秒	720+	讲座、直播回放

这样能控制总帧数在一个合理区间。如果视频时长远超1小时，还需要配合"分段抽帧"策略——把视频切成5–10分钟的小段，分别处理后再合并，避免一次处理的帧数太多。

ffmpeg的抽帧命令很简单，核心参数就是 -vf fps 指定帧率：

ffmpeg -i input.mp4 -vf fps=1 frame_%04d.jpg

不过我实际使用的是更能控制总帧数的方案——按总时长和间隔计算抽取数量：

# 提取视频总时长（秒）
DURATION=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 input.mp4 | cut -d. -f1)
# 动态间隔：时长除以目标帧数
INTERVAL=$(echo "$DURATION / 120" | bc)
# 按间隔抽帧
ffmpeg -i input.mp4 -vf "select='not(mod(n\,$INTERVAL))'" -vsync vfr frame_%04d.jpg

这样无论视频多长，总帧数都稳定在120张左右，后续结合视觉模型的批量处理能力，token开销就在可控范围内。

4.2 音频转写：Whisper模型的接入与参数调优

音频轨转写我选择集成Whisper模型，稳定性好，而且落地部署成本低。调用时有一个非常值得注意的参数： word_timestamps=True ，开启词级时间戳。这个看起来不起眼的参数，在后面做音画对齐时能省掉很多麻烦。

import whisper

model = whisper.load_model("base")
result = model.transcribe(
    "audio.mp3",
    word_timestamps=True,
    verbose=False
)

for segment in result["segments"]:
    start = segment["start"]
    end = segment["end"]
    text = segment["text"].strip()
    print(f"[{start:.1f}-{end:.1f}] {text}")

用吐司时间戳而不是单纯整段字幕，是因为只有拿到每个时间点的文本，才能和抽帧的时间戳做精准关联。比如12.3秒处的转写文本提到"登录界面"，而同一时间戳的抽帧正好是登录页面截图，这样Agent在总结时，就能以时间点为锚把画面和语音对齐。

4.3 合并对齐：结构化JSON的设计

最终生成给Agent的结构化文档，我采用的格式是分段JSON，以时间戳为索引：

{
  "video_meta": {
    "duration_seconds": 1435,
    "resolution": "1920x1080",
    "num_frames": 120
  },
  "segments": [
    {
      "start": 0.0,
      "end": 30.2,
      "audio": "大家好，欢迎收看本期视频，今天我们来讲Agent开发的核心概念",
      "frames": [
        {"timestamp": 10.0, "path": "frame_0010.jpg", "description": "主持人出镜，背景为PPT封面"},
        {"timestamp": 25.0, "path": "frame_0025.jpg", "description": "PPT翻页，显示章节标题"}
      ]
    }
  ]
}

这个结构的关键在于： 音频文本和画面描述按时间段组织在一起 ，并且所有帧都保留了文件路径，方便Agent在需要细看某帧时二次调阅。相较让Agent读一坨纯文本字幕，这种结构化数据能显著提升它对视频内容的时间感知能力。

5. 让模型"看懂"视频：提示词注入与事实性约束

5.1 什么才叫"看懂"视频

管线跑完后，拿到了结构化的帧描述和转写文本，但这些都只是中间产物。真正让Agent表现出"看懂了视频"，还需要一个精心设计的提示词，告诉Agent怎么利用这些结构化信息。

我踩过一个很深的坑：第一次跑通整个管线后，测试"这个视频讲了什么"，Agent的回答居然开始脑补画面细节，把很多根本没有在抽帧里出现过的场景描述得绘声绘色。这就是典型的 模型幻觉问题 ——它看到一些音频转写文字后，就根据自己对世界的预设编造了可能的内容。

5.2 基于事实的提示词模板

解决幻觉的做法，是在提示词里建立严格的 事实边界 ：

你在分析一个视频。以下是视频的元数据和内容片段信息：
[插入以上JSON]

请基于信息回答用户问题。严格遵守以下规则：
1. 只能引用JSON中出现的内容：包括转写文本和画面描述。
2. 当信息不足时，明确说"视频内容中未明确提及"。
3. 回答时标注信息的时间点，格式如[MM:SS]。
4. 当用户询问画面细节时，优先参考对应的frames描述。
5. 不得自行推断或想象JSON中不存在的画面或台词。

加了这个约束之后，幻觉问题大幅减少，回答中还会主动标注时间戳，不说完全消除，但效果已经从"编故事"变成了"有据可查的回忆"。

5.3 时间戳能力：让Agent能"回溯"到具体位置

这版提示词里还包含了一个非常好用的设计——时间戳回溯。既然JSON里存储了每个片段的时间边界，Agent的回答就能带上具体时间点。比如用户问"视频里讲Agent记忆的部分在哪"，Agent可以直接答"在[04:23]到[06:10]之间，核心观点是..."。

这个能力在实际使用中特别受用，尤其是做内容审阅和课程学习时，用户可以根据时间戳直接跳到视频对应位置验证，形成"AI摘要-人工复核"的闭环。让Agent不只给结论，还能给原始出处，实用性提升了一大截。

6. 实测效果与容易踩的坑：从参数调优到边界场景

6.1 实测效果数据

我把这套Skill跑在一段23分钟的Agent开发讲座视频上，输入是纯视频文件，输出是3000字左右的带时间戳摘要，完整处理链路耗时约2分钟（其中转写占了大头，抽帧很快），token开销约1.8万。

作为对比，同样这段视频如果直接丢字幕文件给Agent，token只要几千，但回答缺少画面信息的支持，比如"讲师在PPT上画了一个架构图"这种信息就完全提取不到。所以多出来的token开销，买的是 双轨信息的完整性 ，在需要分析画面内容的场景下这钱花得值。

6.2 踩坑记录一：抽帧密度与token爆炸的权衡

第一版把所有帧的base64全部传给模型，结果一个5分钟的视频就烧掉了接近10万token，直接把上下文干爆了。后来我加入了帧描述前置压缩步骤——先把抽帧的图片交给视觉模型批量生成一行描述文字，再把描述文字注入最终文档。一张图几百token就变成二三十个字的文本，成本瞬间降了几个量级。

这也是一个在设计上容易被忽略的细节： 不要裸传图片，要传图片的描述 。除非Agent需要细看某一帧，否则绝大多数场景下一行准确度够高的画面描述，就足以支撑理解。

6.3 踩坑记录二：音频转写的"人多人杂"问题

网课、会议这类视频往往不止一个人在说话，Whisper默认输出是不区分说话人的，导致最后生成的文本是一锅粥。实测中发现这个问题对总结的影响还不算大，但一旦需要按发言人区分内容，就必须在管线里加入声纹分离（Speaker Diarization）。这个功能目前需要额外依赖，而且模型较大，对本地部署的机器有要求。我的经验是：默认版本不做说话人分离，有需求时再加，避免让Skill的安装门槛变高。

6.4 边界场景：什么视频不适合这套方案

做了这么多实测后，我觉得还是得诚实地说一下这套方案的边界。claude-video对以下场景的适配度有限：

• 纯音乐视频或无声画面视频 ：音频转写管线直接闲置，只能靠画面描述，效果打折
• 动效密集的短视频 （比如几十个快切镜头的电影预告片）：抽帧间隔过大容易漏掉关键画面，间隔过小token又撑不住
• 打满字幕的视频 ：字幕信息和音频转写会重复，多花token同时输出两份相似文本

针对这些场景，我现在的建议是保持默认配置作为基线，再根据实际遇到的视频类型微调参数。比如电影预告片就把抽帧间隔调到0.5秒；纯画面视频就直接关掉Whisper转写，节省处理时间。

7. 从claude-video出发：Skill化思路在其他媒介上的扩展

做完这个项目后我最大的体会是， "让模型获得某种感知能力"并不一定需要换模型，大多数情况下是缺一个把原始信息翻译成模型友好格式的中间层 。视频如此，音频如此，一些专有格式的文档也是如此。

顺着这个思路，我给自己的Agent又陆续补了几个类似的"感官组件"：一个处理扫描版PDF的Skill（思路是把PDF先转成大图，再走图像识别管线）、一个处理本地数据库文件的Skill（用SQLite查询代替直接读二进制文件）。本质上和claude-video是同一个套路—— 把模型不擅长的原始输入，转化为模型擅长的结构化文本输入 。

这套方法论其实比某一个具体Skill更能复用。当你下次遇到"模型能力不够"的时刻，先别急着换更大更贵的模型，想想能否通过外挂一条预处理管线来解决问题。往往一个写好脚本、一套好提示词，就能补上能力缺口。

最后分享一个小技巧：如果哪天你也做了一个自己的Skill，记得把处理过程中的中间产物保留下来，别急着清理。这些帧文件、转写文本、结构化JSON在后面调试提示词时都是极好的测试样本——我自己就是靠着一套缓存好的中间数据，反复调整提示词和参数，数据来源稳定，才能分清楚Agent表现变化到底是哪个环节引起的。