最近一直在折腾Agent相关的东西，核心痛点是：文本知识好喂，但视频内容很难“消化”。市面上大部分Agent技能都是处理文档、网页、数据库，最多看一眼图片，遇到长视频或录屏基本就抓瞎。机缘巧合，我看到了一个叫claude-video的Skill，专门让Agent获得“看视频”的能力，而不是只读文件名。这个方向非常对我胃口，因为我自己有大量课程录屏、会议回放、Demo演示素材需要整理归档，光靠肉眼拉进度条实在是太痛苦了。这玩意恰好补上了Agent感知链路上最缺的一环。

这篇文章不打算做枯燥的代码逐行讲解，我更想以一个踩坑者的身份，把整个Skill从零到能用的过程拆开揉碎：为什么Agent需要视频理解能力、这个Skill内部的核心模块是怎么组织的、实操时参数怎么调、以及我实际跑通时遇到的一堆乱七八糟的问题。如果你也想让你的Agent从“只能看文字”进化到“能看会听”，这篇文章应该能帮你省掉不少试错时间。

1. 项目概述与设计思路拆解

1.1 为什么Agent必须拥有视频理解能力

先看一个扎心的场景：你手头有一个两小时的线下培训录屏，老板让你提炼出讲师提到的关键结论、客户提问、现场答疑，下班前要交。传统做法是什么？自己开着播放器二倍速刷，记笔记，再手工整理。Agent能干什么？如果只有文本接口，它连视频文件都打不开，最多帮你把文件名、大小、时长列出来，这跟“看视频”完全不搭边。

真正的视频理解，需要Agent能够完成三件事：看到画面、听懂语音、感知时序。看到画面意味着能从每一帧中提取物体、文字、场景、人物动作；听懂语音意味着能把口语内容转成文字并理解语义；感知时序意味着知道哪个结论出现在第几分钟、哪个问题在哪个环节被抛出。这三个能力合在一起，Agent才能像人一样“看完”一条视频，然后输出内容摘要、关键事件列表，甚至按时间轴生成结构化笔记。

claude-video这个Skill，本质上就是把“视频→多模态输入→结构化输出”这条链路做成一个可复用的能力包。你不需要每次都在Prompt里写一大段“请先抽帧、再调用外部工具、把结果整理成表格”这样的提示词，而是装一个技能，直接说“帮我看一下这段视频讲了什么”，Agent就会自动按预设流程执行。这种“Skill化”的思路，正是当前Agent工程里最实用的发展方向：把复杂流程封装成习惯动作，让Agent像肌肉记忆一样调用它们。

1.2 claude-video的方案选型逻辑

看一个Skill设计得好不好，先看它的输入处理策略。视频文件和文本最本质的区别在于：文本可以完整放进上下文，视频不行。一条十分钟的1080p视频，按25帧每秒算就是15000帧画面，哪个模型也吞不下这么大的数据量。所以视频理解的第一步一定是“降维”，把视频变成模型能消化的信息单元。

claude-video采用的核心策略是“多模态通道分离”——把视频从“一条连续的时间流”拆成三条平行的信息通道：视觉帧流、音频文本流、字幕文本流。视觉帧流通过抽帧获取，负责画面内容；音频通过语音识别转成文本，负责口语内容；字幕直接提取或OCR生成，负责屏幕上的文字信息。最后在Prompt里按时间戳把这三条通道对齐，让模型在同一时间点上同时看到“画面描述+说话内容+屏幕字幕”，这样它才能综合理解视频里到底发生了什么。

这个设计思路我觉得非常聪明，它没有追求把整个视频“塞”进上下文，而是理解模型的能力边界，把视频拆成它熟悉的模态再组合。对比一下其他方案：直接把视频转为Base64喂给视觉模型，现在上下文窗口虽然变大了，但成本极高，而且视频的所有帧并不是都对理解有用，纯属浪费token；只转文字听音频，又会丢掉画面上最关键的信息，比如PPT里的图表、代码、UI界面变化，这些恰恰是很多教学视频的核心内容。claude-video把这两者结合起来，而不是二选一，这是它能真正“看懂”视频的关键。

2. 核心模块拆解与配置要点

2.1 视觉帧通道：抽帧的算法与参数选择

视觉帧是整个视频理解里信息密度最高的一条通道。但抽帧不是均匀切时间点那么简单，这里的关键在于“该抽的帧必须抽到，不该抽的一帧都不要浪费”。我最初自己写脚本时踩过一个坑：每10秒抽一帧，结果遇到一个演示视频里PPT切换特别快，关键页面停留不到3秒，结果抽出来的全是过渡动画的模糊帧，模型完全看不出内容。

claude-video的做法是两层策略结合。第一层是按固定间隔采样，给整个视频建立一个基础时间轴，比如默认每5秒一帧或每10秒一帧，这个值取决于视频类型和你的Token预算。第二层是“高变化场景插帧”，对相邻帧之间做像素差异检测，如果画面变化幅度超过设定阈值，说明这里可能发生了重要内容切换，比如PPT翻页、界面跳转、人物入场，就在这两帧之间额外补抽一帧，确保不遗漏关键瞬间。

在实际使用中，参数怎么选？需要说清楚你的业务场景。录屏教程、PPT讲解类视频，重点在画面文字和界面操作，5秒一帧就够，配合OCR效果极好；体育比赛、动物行为、安防监控这类画面高速变化的视频，2秒甚至1秒一帧才能捕捉到动作细节；但抽帧越密，Token消耗越大，一张画面按标准视觉模型计费可能要几百上千个Token，一小时视频光是视觉帧就可能吃掉几百万Token，成本需要提前估算。所以最稳妥的方式是“先粗后细”：先用10秒间隔跑一遍，让Agent产出粗粒度摘要，你看一眼覆盖度，再针对关键区段加密抽帧，二次精读。

2.2 音频转写通道：让Agent“听见”口述内容

听觉通道在视频理解里占了语义的半壁江山。对大多数视频来说，镜头画面可能平平无奇，但解说词、讲师口语、采访对白承载了绝大部分意图和信息。把音频转成文字，最常用的方案就是Whisper，它支持几十种语言，中文识别的准确率在清晰录音环境下可圈可点，对付日常语速、带口音的普通话也基本够用。

不过这里有一个需要特别处理的细节：时间戳对齐。Whisper虽然能输出每个分句的开始和结束时间，但如果你直接拿它的输出文本去对接帧的时间轴，你会发现句子的边界和画面的切换天然存在偏移，口语说“我们来看这个界面”时，画面往往在半秒后才切到那个界面。所以在claude-video的实现里，转写结果不是直接拼进Prompt，而是先做一次“对齐校准”：用VAD（语音活动检测）切分语音段，再把每段语音的文本对齐到对应的帧区间，尽量让模型看到“第3分钟讲师说的话”和“第3分钟画面里显示的内容”是匹配的。

如果你处理的是多人对话视频，比如访谈、圆桌讨论，还需要额外接一个说话人分离模块，也就是把“哪位发言人说了这段话”标出来。这一步可做可不做，取决于你后续要不要按发言人维度整理摘要。我的建议是：单人讲解视频不需要，直接转文字就行；多人会议视频建议加上，否则整理出来的摘要像是所有人都混在一起说话，信息归属完全错乱。

2.3 字幕提取通道：画面文字的OCR与字幕轨解析

这条通道往往容易被忽略，但它恰恰是录屏类视频理解的胜负手。录屏内容里，代码编辑器的报错信息、PPT上的要点、网页里的数据表格、弹出的对话框提示，这些信息只存在于画面中，语音可能压根没提到。如果没有OCR能力，Agent看完视频就等于“看到了但没看懂文字”。

claude-video用了双路字幕提取方案：第一路是先检查视频容器里有没有内嵌字幕轨，像MKV、MP4文件经常自带CC字幕，直接解析出来最准；第二路是如果没有字幕轨，就启用OCR对视觉帧跑文字识别，把画面上出现的文字按时间戳提取出来。这两路结果都会进入最终Prompt，但要注意合并去重，避免同一句话在语音转写和OCR字幕里重复出现，浪费上下文空间。

OCR这块我强烈建议你对中文字符做针对性处理。英语OCR成熟的引擎很多，但中文识别率受字体、背景干扰、文字大小影响很大。如果视频里PPT是深色背景白字，识别率较高；但代码编辑器里的彩色关键字、浅色注释在小字号下经常被识别成乱码。实操时我通常会把OCR结果里置信度低的文本过滤掉，或者把它们作为“疑似内容”附在帧描述后边，让模型自己判断是否有用。

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

3.1 Skill的整体目录结构与入口配置

装这个Skill之前，先看它长什么样。一个标准的Claude Skill目录大概是这样组织的：

claude-video/
├── SKILL.md                 # Skill的元信息与主指令
├── src/
│   ├── frame_extractor.py   # 抽帧模块
│   ├── audio_transcriber.py # 音频转写模块
│   ├── subtitle_ocr.py      # 字幕OCR模块
│   └── timeline_builder.py  # 时间轴对齐与Prompt组装
├── scripts/
│   ├── extract_audio.sh     # 音频提取脚本
│   └── video_probe.sh       # 视频信息探测脚本
├── prompts/
│   ├── summary_prompt.txt   # 摘要生成的Prompt模板
│   └── qa_prompt.txt        # 问答模式的Prompt模板
└── config.yaml              # 全局配置：采样率、模型参数等

SKILL.md是技能入口，里面描述了“这个技能什么时候被触发、先执行什么、后执行什么、用什么工具处理什么输入”。如果你打算照抄思路做一个自己的视频理解技能，核心就是把SKILL.md里的执行流程写清楚，让Agent看到“视频文件”这一输入类型时，自动按流程开工：先探测视频基本信息（时长、分辨率、是否有音频轨），再决定抽帧间隔和转写策略，然后并行执行抽帧和音频提取，最后汇总到时间轴组装模块生成结构化报告。

拿config.yaml举例，我通常会把它调成下面这样：

frame_interval_sec: 5            # 抽帧间隔，单位秒
frame_change_threshold: 0.35     # 画面变化阈值，超过则插帧
max_frames_per_call: 50          # 每次调用模型的最大帧数
whisper_model: "medium"          # 转写模型档位
ocr_language: "chinese_simplified"
output_format: "markdown"

这套配置不是死的，需要按实际输入调整。比如你只要一个两分钟的短视频，5秒一帧只有24帧，完全可以直接丢给模型；但如果是两小时长视频，50帧一轮，循环调用模型几十次，中间还需要做分段摘要再合并，这就是另一个复杂度的工程了。

3.2 核心代码逻辑：抽帧、转写与时间轴组装

先说抽帧端。用ffmpeg逐帧导出再筛选，效率太低；正确做法是先生成关键帧时间点列表，再按时间点精准截取。伪代码如下：

import json
import subprocess


def get_keyframe_timestamps(video_path, interval_sec=5, change_threshold=0.35):
    # 第一步：获取视频总时长
    probe = subprocess.run(
        ["ffprobe", "-v", "quiet", "-print_format", "json", "-show_format", video_path],
        capture_output=True, text=True
    )
    duration = float(json.loads(probe.stdout)["format"]["duration"])

    timestamps = []
    prev_frame = None
    t = 0.0
    while t < duration:
        frame = extract_frame_at(video_path, t)
        if prev_frame is not None:
            diff = frame_diff(prev_frame, frame)
            if diff > change_threshold:
                # 画面剧变，往前退 1 秒补抽前一个时间点的帧
                timestamps.append(max(0, t - 1))
        timestamps.append(t)
        prev_frame = frame
        t += interval_sec
    return timestamps

注意画面对比那一步， frame_diff 可以简单用像素差均方差，也可以用感知哈希；我实测下来，对PPT切换、界面跳转这类画面变化，像素差均方差就够了，追求更高精度再上感知哈希也没问题。这个“剧变补帧”策略，能有效弥补固定间隔采样对快速场景切换的漏检。

再看音频转写端。先用ffmpeg把音轨抽成16kHz单声道WAV，这个采样率对Whisper足够，还能减少文件体积加快推理：

ffmpeg -i input.mp4 -vn -ac 1 -ar 16000 -f wav audio.wav

然后调用Whisper模型转文字，并输出带时间戳的JSON格式：

import whisper

model = whisper.load_model("medium")
result = model.transcribe("audio.wav", language="zh", verbose=False)

segments = []
for seg in result["segments"]:
    segments.append({
        "start": seg["start"],
        "end": seg["end"],
        "text": seg["text"].strip()
    })

最后是时间轴组装。这里需要把三个通道的信息汇聚成一个按时间排序的“事件流”。我的一段输出样例大概长这样：

[
  {
    "time": "00:00:00",
    "frame_desc": "标题页：如何提升Agent的视频理解能力",
    "ocr_text": "如何提升Agent的视频理解能力",
    "audio_text": "大家好，今天我们来聊一聊……",
    "scene_type": "intro"
  },
  {
    "time": "00:05:12",
    "frame_desc": "代码编辑器界面，函数定义与调用窗口",
    "ocr_text": "def get_keyframe_timestamps():",
    "audio_text": "抽帧这一步，最重要的是平衡覆盖率和成本。"
  }
]

组装完成后，这份事件流就作为一个结构化文档交给你指定的下游模型，让它根据你的需求生成摘要、问答、思维导图或者看一下是否符合某个主题的检索条件。

3.3 Prompt模板设计：如何引导模型“带着任务看视频”

Skill真正产出质量的上限，其实取决于Prompt模板设计得有多好。同样是给模型一份事件流，有人让它输出高质量摘要，有人只能得到流水账，区别就在于你让它“怎么看”和“看完做什么”。

我在设计summary_prompt.txt时，会明确要求模型不逐帧复述，而是先建立一个“视频到底是什么、目标受众是谁、讲解节奏如何”的整体认知，再按信息层级输出：核心结论、关键证据、行动建议。对QA场景，则会让模型对每个问题标注它在视频中的时间戳出处，这样用户看完答案还能快速跳到原片核对。

这里提供一个我调试过的基础模板思路：

你是一个视频分析助手。下面是视频的多通道事件流，包含时间戳、画面描述、OCR文字和语音转写。
请完成以下任务：
1. 概括视频的主题、目标受众、讲解结构；
2. 提取3-5条核心结论，每条结论必须引用对应的时间戳和画面证据；
3. 列出所有出现在视频中的URL、文件名、数字指标等关键实体；
4. 如果存在多个讲者，按讲者维度分别整理其观点。
要求：不要复述视频内容，以结构化清单输出；不确定的信息必须标注“未确认”。

这套模板在我实测里效果不错，核心经验是“给模型明确的输出维度，而不是一句大而全的‘总结一下’”。你越清楚地说明你要什么维度的信息，模型越能在视频事件流里筛选关键内容。

4. 工具选型、常见问题与避坑实录

4.1 工具链选型：为什么选ffmpeg、Whisper和OCR组合

这个Skill的能力栈，第一印象可能觉得“技术门槛高”，但你拆开看，每一块都能找到成熟的开源工具：抽帧用ffmpeg，音频转写用Whisper，字幕OCR可以选PaddleOCR也可以选Tesseract。关键是不要让每项能力都从零开始造轮子，而是把成熟工具串成一条流水线。

ffmpeg是雷打不动的第一选择，整个视频生态的视频处理基本都绕不开它，优点在于跨平台、命令行友好、处理速度快，抽帧、转码、音轨提取一条命令搞定。Whisper目前是语音转写准确率第一梯队，尤其对中文和混合中英文内容表现优秀，而且OpenAI开源了权重，你可以本地跑，不涉及任何数据外传。OCR方面，中英文混合场景我更推荐PaddleOCR，它对中文的识别精度明显优于Tesseract，但对于纯英文录屏，Tesseract也够用，看你的场景取舍。

如果你预算充足，也可以考虑把Whisper替换成云端语音识别API，识别速度和稳定性更优，但中文新词、术语的识别率有时反而不如本地微调过的Whisper做得好。我个人的建议是：本地优先，数据安全可控，长期成本更低；只有当你需要海量并发转写时才考虑上云。

4.2 踩坑实录：时间戳偏移、OCR误读与长视频分片

先说时间戳偏移这个坑，几乎每个做视频理解的人都会被坑一次。Whisper输出的句子时间戳是独立的，但它只会告诉你“这句语音从第几秒开始”，不会告诉你“这句话对应的画面在哪一帧”。我最初直接把语音文本和帧时间点强制对齐，结果整理出来的摘要经常出现“解说在讲A，画面却是B”的错乱现象。后来我在时间轴上加了“语音活动检测”这一步，用VAD先切出语音段，再以语音段为锚点关联帧时间，错位问题大幅减少。具体的方案是：先跑Whisper拿到分句时间戳，然后把每个句子的时间戳映射到最近的抽帧点上，尽量保证文本跟画面对应。

OCR误读是另一个高频问题。PPT背景图复杂、代码字体小、光线反光，OCR都会给出错误文本。我最初踩过一个大坑：某次视频里PPT有一行“准确率提升至95%”，OCR硬是识别成了“准确率提升至9%”，最终摘要引用了这个错误数据，后续核对原片才发现问题。从那以后，我在OCR模块里加了置信度过滤，低于0.8的结果默认不纳入摘要，同时会在Prompt模板里加一句“OCR结果可能不精确，如与语音内容矛盾请优先采用语音内容”。这个方法简单，但真的能救命。

长视频分片是性能问题的核心。一小时以上的视频，一次性把全部事件流丢给模型，上下文窗口撑不住，而且会触发模型“注意力稀释”，就是开头看得到、中间信息全被忽略。我的经验是把长视频切成15-20分钟的片段，逐片生成局部摘要，再把全部局部摘要合并，生成总摘要。这个“分段-局部摘要-汇总”的流程，虽然会损失少量跨片段的关联信息，但换来的是每段信息密度和准确率的显著提升。

4.3 常见问题速查表

问题现象	原因分析	解决方案
摘要画面描述和语音内容对不上	时间戳未对齐	引入VAD切分语音段，再与抽帧时间映射
OCR识别出的关键数字错误	帧中文字小、背景杂乱	加置信度阈值，低置信度不作为证据
长视频摘要信息遗漏严重	上下文过长信息稀释	切段生成局部摘要，再合并总摘要
抽帧画面全是过渡动画	均匀采样未捕捉关键切换	增加画面变化检测，剧变时补帧
Whisper对专业术语识别差	模型词表里没有领域专有名词	可尝试微调模型，或在Prompt里提供术语词典
视频处理非常慢	转写模型档位过高、抽帧过密	降低whisper模型档位，适当放宽抽帧间隔

很多问题并不是某一个模块坏了，而是整体流程缺乏反馈和校验机制。比如OCR置信度低时，你可以选择不信任它，但最好在输出里保留“疑似内容”标记，让后续模型自行判断。长远来看，给Skill加一个“自检”环节非常有必要：在处理完视频后，生成摘要之前，让模型自己对照事件流检查一遍逻辑是否连贯、关键实体是否遗漏。哪怕只是多花一轮调用，输出质量的提升也非常明显。

5. 经验心得与扩展方向

5.1 我实测下来的几个关键建议

如果你也是第一次动手做Agent的视频理解能力，我先给几条最实在的建议。

第一，别一上来就追求“全自动”。先拿一条5分钟以内的短视频手动跑通全流程：抽帧、转写、OCR、组装事件流、生成摘要。每一步都手动执行一遍，确认每个模块的输出质量，再考虑怎么把它们串起来。视频理解是一个链条，链条上任何一环质量差，最终结果都会拉胯。先稳定再提效，这句话在AI工程里从来没有过时。

第二，发挥Agent的优势，多轮对话才是善用方式。我在实际应用中很少要求Agent只看一遍视频就给出完整报告，更多是让它先“看一遍”然后我问：“这段视频里提到的那三个方案具体在屏幕上出现过吗？帮我截个图。”Agent基于已经构建的事件流，可以快速定位到对应时间戳，再针对该区间抽帧放大识别，准确率比一次性全量输出要好得多。视频理解不是“看完交卷”，而是“看完待命”。

第三，Skill的Prompt要因人而异性。不同场景下“理解”的含义完全不同：课程场景需要逻辑结构和重点提炼；会议场景需要决策、待办、责任人；产品演示场景需要功能清单和交互流程。这些差异不要在Skill内部写死，而是在SKILL.md中预留“任务类型”参数，由用户每次调用时指定。一个过分僵化的Skill，用一两次就会觉得“不对味”。

5.2 这个Skill后续还能怎么扩展

视频理解这个方向，一旦打通“视频→多模态事件流→下游模型”的链路，能做的事情远超“生成摘要”。

一个很自然的扩展是“视频问答系统”。把视频处理成事件流后，存入向量数据库，用户用自然语言提问，检索出相关时间片段再送给模型回答。这等于把一个视频库变成一个可对话的知识库，输入任何一段培训视频或历史会议，团队成员都能直接问“去年那场会关于预算的结论是什么”。目前我和一些朋友在试点这个方向，效果在我看来是很有潜力的。

还有一个方向是把事件流进一步结构化，构建“视频知识图谱”。比如提取视频中出现的人物、产品、项目、地点、指标，以及它们之间的关系和时间线。这个图可以用来做视频推荐、知识检索、甚至跨视频的内容关联分析。做这块需要额外的实体识别和关系抽取模块，工程量大不少，但如果你的视频库规模够大，这笔投入是完全值得的。

最后，如果你把claude-video和现有 Agent 的工作流打通，会发现它的价值不止于看懂单条视频。举个我最近在做的例子：给Agent加一个“每日自动看行业录屏并输出简报”的定时任务，Agent晚上自动拉取新的视频文件，按流程处理后生成简报，第二天早上推送到群里。这本质上就是把“人肉拉进度条”的工作自动化，让Agent真正变成团队里的“视频信息处理专员”。有人说Agent只能处理文本，这个Skill的存在说明，给Agent接上合适的输入管道，它就能看见世界。