上个月我接到一个有点棘手的需求某培训团队攒了 200 多节录屏课程每节还配着一份 PPT他们想把这些内容全部整理成可检索的文字稿丢进知识库做二次编辑。人工看一遍视频再写稿子200 多节课够一个小团队忙一个月。他们问我能不能让 Agent 直接把视频和 PPT “读”了自动输出结构化内容我的第一反应是“能”但真正拆解下来发现这件事的难点不在 Agent 的“聪明程度”而在于缺一个专门干这活的Agent Skill。视频内容提取和 PPT 内容提取看起来都叫“提取”底层逻辑完全不一样。视频里有语音、有字幕、有画面文字、有时间轴PPT 里有占位符、有层级、有图表、还有动画状态。一个通用的“帮我总结一下这份资料”的 Prompt 根本覆盖不了这么多细节。这篇文章就记录我从设计、实现到踩坑的完整过程也把最终的 Skill 用法写清楚算是“诞生记 使用指南”二合一。1. 为什么要给 Agent 造一个“会看视频和 PPT”的能力真实场景里的三个难题1.1 通用做法为什么总是翻车一开始我没打算专门写一个 Skill先试了两种“暴力方案”。第一种是把视频丢给支持多模态的大模型让它直接看视频。效果怎么样几秒钟的短视频片段还凑合一旦视频超过 10 分钟输入端的 token 压力立刻爆炸响应慢、上下文碎片化提取出来的内容经常是“记流水账”式的描述——它能看到画面却抓不住课程里真正关键的技术术语。第二种方案是用现成的 OCR 工具把视频逐帧截图转文字再把 PPT 每页导出成图片后识别。这条路更快但产出是一堆没有结构的文字碎片既没时间轴也分不清哪些是画面里的注释、哪些是讲解者说的话知识库检索时根本没法用。这两次试错让我意识到一件事内容提取是一个需要专门工程手段的任务不能靠模型“硬看”。Agent 需要的是一个有边界的工具——输入端接收文件路径和参数输出端返回结构化文本中间每一步都人工设计好处理链路。这正是 Skill 的定位给它一个明确的工作描述和输入输出结构Agent 就知道在什么场景下该调用它、该传哪些参数。1.2 Skill 到底“聪明”在哪把模糊要求变成固定流水线一个标准的 Agent Skill 通常包含三个部分SKILL 描述文件用来告诉 Agent“这个能力是干什么的、什么时候用”参数 Schema用来约束输入格式处理逻辑代码真正干活的部分。用户只需要对 Agent 说“把这份录屏和配套 PPT 整理成带时间轴的文档”Agent 就会自动匹配到视频/PPT 提取 Skill然后解析出文件路径、输出格式这些关键参数交给处理逻辑去执行。这套设计最核心的价值是把模糊需求固化成了可复现的流水线。人工处理录屏时是有自己的套路的——先听语音转写再扫关键的 PPT 页面最后把两边对齐。Skill 干的就是同一件事只是把套路写成了代码。以后不管谁调用输出结构都是一致的不会今天给你一个 Markdown、明天给你一段纯文本。1.3 为什么不是“做一个全能转换工具”可能有人会问为什么不干脆把它做成一个独立运行的工具非要挂在 Agent 下面我自己的体会是独立工具的问题在于它没有“判断力”——给一份没有任何文字的纯图片版 PPT它也会硬着头皮跑一遍最后输出一堆占位符而挂在 Agent 下Skill 描述文件里就可以写明“若文件无法解析或无文本内容返回提示信息并建议用户补充素材”Agent 会根据返回内容决定下一步是重新调用还是询问用户。让识别不到的边界情况有人兜底这种交互逻辑只有 Skill 形态才能自然实现。2. Skill 的骨架设计描述文件、参数和输出结构先把边界钉死2.1 元信息描述让 Agent 知道“什么时候该想到我”我先建了一个 Skill 根目录里面放了一个元数据描述文件我用的是 YAML 格式。这份文件不写任何处理逻辑只做一件事给 Agent 建立“什么场景下该调这个 Skill”的映射。我当时写的描述看起来是这样的name: media_content_extractor description: 提取视频或演示文稿中的结构性内容支持语音转写、画面文字识别、 PPT 文本与图表数据解析。当用户要求整理录屏课程、会议录像、 演示文稿文字稿或需要把视频/PPT 转成带时间轴的文档时使用。 parameter_schema: file_path: { type: string, description: 待处理的视频或 PPT 文件绝对路径 } media_type: { type: string, enum: [video, ppt, auto], default: auto } lang: { type: string, default: zh, description: 内容语言zh/en/auto } with_timestamps: { type: boolean, default: true } need_images: { type: boolean, default: false }写描述文件时我吃亏过一次第一次我把 description 写得太窄只写了“提取视频字幕”结果用户说“帮我把这份课程录屏整理成文字稿”时Agent 宁可自己硬看视频也不调用 Skill。后来我把描述改成面向“用户意图”而不是“技术能力”加上了场景化的触发词和反例命中率才明显提上来。这个细节对任何 Skill 都适用。2.2 参数设计不是越多越好关键是“可推断”参数 Schema 看起来简单设计时最考验取舍。我最初的版本收了七八个参数包括抽帧间隔、ocr 引擎选择、并发线程数。结果发现 Agent 根本不知道怎么从用户的一句话里推断“并发线程数4”每次都要追问体验很差。后来我把暴露给 Agent 的参数收敛成 5 个文件路径、媒体类型、语言、是否需要时间戳、是否需要提取图片。凡是 Agent 能自己推断或处理代码能自动决定的一律不暴露。媒体类型我默认给了auto模式处理代码里通过文件扩展名和文件头判定。用户说“处理这个文件”时Agent 不需要额外追问“这是视频还是 PPT”。语言参数也做了同样的处理默认自动识别只有识别结果不理想时用户才会手动指定。参数设计的原则就一句话让调用方可以“少说也能做对”而不是逼他想清楚每一个细节。2.3 输出结构先定义“合格的成品长什么样”输出结构比输入参数更重要。我参考了人工整理课程笔记的习惯把输出设计成下面这种 Markdown 结构文档头源文件信息、总时长或总页数、提取时间内容主体按章节分组每个章节包含标题、正文、关键画面文字、对应时间戳/页码附录无法归类的备注、图表数据、人物高亮文本这样的结构有个好处它天然兼容“逐页/逐段落的保存位置”后续不管是喂给向量库还是人工校对都有抓手。我见过很多同类工具输出就是一整段“AI 总结”毫无结构检索和引用都很难受。输出定义这种事宁可一开始多花半小时设计也不要在拿到三个月的数据后再重新洗一遍。这里还要提一个容易被忽略的点一个 Skill 最好只输出一种主类型的内容但允许附带辅助文件。比如视频提取的主输出是 Markdown 文档但如果有用户要求need_imagestrue我就把关键帧图片按“页码/时间戳.png”的命名规则放进同级目录Markdown 里用相对路径引用。这样主输出保持轻量辅助资源按需生成Agent 也不需要解析一堆二进制内容。3. 视频提取的实现音频转写、关键帧抽帧和 OCR 三条线怎么拧成一股绳3.1 音频转写是主心骨字幕是白捡的惊喜视频内容提取我一开始以为画面识别是重点后来发现大部分有效信息都在人说的话里。培训类录屏尤其如此讲师讲解的内容覆盖了至少 80% 的知识点。所以我的处理流程第一步永远是“切音轨送转写”。这里用的是一套成熟的商用 ASR 服务支持中文、英文和中英混说返回每一句话的开始时间、结束时间和置信度。但有三种情况能让转写结果大幅偏离预期一是讲师口音重、专业术语多二是视频里插播了无语音的演示片段三是音轨里混着环境噪声。所以我没有把转写结果当成最终文本而是把它当作一个“带时间轴的内容骨架”。一个小的加分项是字幕轨道提取。如果视频本身带软字幕我优先解析视频内置的字幕流比如常见的 SRT/ASS 文本这个准确率高得惊人。我当时的实现是先探测视频有没有字幕轨有就提取出来和 ASR 结果做交叉比对——两者一致的内容直接采用 ASR 文本不一致的以字幕为准。没有字幕轨的视频就全依赖 ASR 输出。3.2 关键帧抽帧为什么“每 5 秒抽一帧”是最笨的做法画面文字的识别不能漫无目的地逐帧做视频一秒 25 帧到 30 帧全量 OCR 既不经济也没必要。我第一版确实用了固定间隔抽帧比如每 5 秒抽一帧结果画面里投屏 PPT 滚动时一帧卡片内容没拍全OCR 出来半句话毫无意义。后来我换成了场景检测抽帧通过比较相邻帧的画面差值检测到画面发生显著变化时才提取这一帧。录屏类型的视频画面切换的瞬间通常就是翻页或弹窗这些帧信息量最大。外加一个“静止帧合并”策略——如果连续 60 秒画面几乎没有变化只保留第一帧、中间帧和最后一帧。最终抽帧量大约是固定间隔方案的十分之一但覆盖的信息完整性没有下降。3.3 画面文字的 OCR关键帧里藏着讲解没说的信息有些关键信息讲师嘴上不一定会讲全都写在屏幕上了。比如代码示例里的函数名、PPT 角落里的参考链接、软件界面里的弹窗报错。这一部分必须靠 OCR 兜住。参数上我开了高精度模式语言设定跟随输入参数。为了让中文识别更稳我先把关键帧统一放大到宽度至少 1280 像素再做识别实践经验证明这能直接降低将近一半的漏字率。OCR 结果会带上它在画面里的坐标位置。我利用这一点做了“区域排除”——屏幕角落里常见的播放器进度条、音量图标、水印这些区域识别出来也没信息量直接过滤掉而画面中央或上方的文字保留并标记为“画面文字”。这样最后输出的文档里正文段落区分了“讲师讲解”和“屏幕内容”非常直观。3.4 时间轴对齐把三条线编成一张网有了 ASR 文本、字幕文本、OCR 画面文字之后我按时间戳做合并。每条原始记录都被打上标签[speech]或[frame]再按时间顺序排序。排序完成后我用一个简单规则做段落聚类同一主题下的内容时间间隔小于 20 秒的合并为同一段超过 20 秒就另起一段。每一段都包含这段时间内的讲话内容和画面文字。这样产出的文档天然就是“带时间轴的讲解稿”用户可以直接根据时间戳跳到对应的视频位置做音画核对知识库检索时也能按段落索引不用把整部视频看完才知道哪段讲了什么。这套三线合并的处理逻辑是我整个视频提取 Skill 里耗时最长、也最值得的部分。4. PPT 提取的实现解包、重绘和大纲重建不是“截图转文字”那么简单4.1 第一步是“解包”PPTX 本质上是个压缩文件PPT 提取我的实现路线和视频完全不一样。很多人处理 PPT 时的第一反应是“把每页截图出来再 OCR”这是我从一开始就想绕开的路因为 PPT 源文件本身就是结构化的只是结构被封装在二进制容器里。PPTX新版演示文稿格式本质上是一个 ZIP 压缩包我直接用解压缩工具把它打开里面会看到ppt/slides/slide1.xml这样的文件每张幻灯片对应一个 XML文本内容都在 XML 的特定标签里。绕过 OCR、直接读源文件里的文字准确率是 100%连标点符号都不会错。这比任何图像识别都靠谱。4.2 重绘渲染让文本和视觉互相印证只读 XML 文本是不够的因为 PPT 里大量信息通过排版、图形和空间位置关系表达——两个框上下排列可能表示流程一个框在页面的角落可能只是装饰。所以我同步采用了“重绘渲染”路线用开源办公转换引擎把 PPTX 转成 PDF再按页渲染成高清图片。这一步不是为了 OCR而是为了给后续的“视觉校验”提供素材也让 Agent 在需要时能够查看页面截图确认格式。重绘还有一层用途是处理图形化内容SmartArt 流程图、组合图形、文本框的相互位置关系这些信息在 XML 里东一块西一块但渲染成图片后一目了然。我的输出会保留页面图片并在 Markdown 中用“见页面示意图”之类的引用链接指过去。这样文档既有精确文本又能还原视觉。4.3 大纲层级重建怎么从“页面”还原出“目录”PPT 里最大的结构问题是一张页面的文本有层级但整个文档里没有显式的章节树。我需要从 XML 里的占位符类型推断。标准的演示文稿编辑软件会为每张幻灯片预设占位符类型标题占位符、副标题占位符、正文占位符。正文占位符里的条目还会通过文本缩进层级体现从属关系。我的实现分三步。第一步解析每张幻灯片的标题占位符作为文档章节标题第二步解析正文占位符通过每条文本的层级属性映射成无序列表或二级标题第三步把“章节标题—正文条目—页面编号”组装成一个树形结构。这个重建出的目录比我见过的很多“PPT 转文字”工具要细得多——它们通常只是按页输出纯文本而我是真正还原了一套大纲。4.4 图表数据内部幻灯片里最容易被忽略的部分PPT 里嵌入的图表通常以 OLE 对象形式存在不能直接读文字。我从 XML 里的图表数据缓存节点提取原始数据把横轴标签、系列名称和数值还原成 Markdown 表格。说实话这一步的适用范围有限有些图表没有内嵌数据缓存只能退回渲染后的图片但凡是能读出数据的情况我都会把表格放进输出因为表格比图片更适合做检索和二次分析。这个功能可以在 Skill 配置里用开关控制默认关闭——数据提取会显著增加处理时间不是每个项目都需要。5. 翻车复盘中文 OCR、黑帧、PPT 动画和长视频成本四个坑的真实修复过程5.1 中文 OCR 识别率由“卷积”变成“卷识”之后第一次跑通全流程我拿了一节讲卷积神经网络的视频做测试结果所有“卷积”都被识别成“卷识”“池化”变成“池他”。中文 OCR 在低分辨率下的笔画粘连问题比英文严重得多。排查过程里我先怀疑是抽帧分辨率太低把关键帧统一放大到 1280 像素后错误率下降了但仍有部分术语出错。真正解决问题是两个手段叠加第一把 OCR 引擎切到专门针对中文优化的深度学习模型并开启中英混合识别模式第二建立领域词表对识别结果做后处理纠错——把“卷识”这类高频错误映射回“卷积”。词表本身来自培训课程的大纲文件这是最省力的同义词来源。最终术语准确率从 91% 拉到了 98% 左右剩余错误属于人工核对时可以容忍的范围。5.2 黑帧和花屏帧抽帧逻辑加了一道“画质过滤闸门”场景检测抽帧上线后我发现提取出来的关键帧里有相当一部分是纯黑帧或严重花屏的帧。频闪的转场动画、播放器加载瞬间都可能触发画面差值检测导致废帧被当成关键帧。OCR 对这些废帧的处理结果是大量乱码文本严重干扰输出结构。修复方案是在 OCR 之前加一个“画质过滤”步骤对每张候选帧做亮度和清晰度统计平均亮度低于某阈值或清晰度过低的帧直接丢弃。我当时的直觉阈值是平均亮度大于 8、并且清晰度指标大于 0.2低于这两个值的帧直接跳过 OCR。加了这道闸门之后废帧占比大幅下降OCR 的输出文本也干净了很多。5.3 PPT 动画导致的内容缺失逐帧渲染才能挖出来的坑使用“重绘渲染”方案解析 PPT 时我遇到过一个非常隐蔽的问题某些页面的内容在转换后的渲染图里“消失了”。排查后发现这页 PPT 加了“单击后出现”的动画转换引擎默认渲染的是动画初始状态后置动画里的内容自然看不到。文本层提取不受影响因为 XML 里数据都在所以最初我没发现直到人工比对渲染图和源文件才意识到“视觉信息”和“文本信息”的产出不一致。我最终的取舍是文本部分以 XML 解析为准视觉部分用双状态渲染——先渲染初始帧再尝试触发所有动画后的终态帧两者合并取并集。这个方案增加了处理耗时但解决了动画内容丢失的问题。对于加了层层触发动画的复杂 PPT无法做到完全还原这一步目前我还没找到完美解法我在输出里会加一个“待人工复核”标记提示用户核对动画相关页面。5.4 长视频的时间成本1 小时视频处理近半小时的优化过程一开始把一节 1 小时的录屏走完全流程耗时接近 30 分钟这对批量处理 200 节课程是不可接受的。瓶颈很明确ASR 是串行等待OCR 对几百张关键帧逐张处理。我做了三件事把视频按静音段切分用多个并发任务同时转写时间缩短到原来的三分之一抽帧和 OCR 之间用生产者消费者模式并行处理关键帧刚抽出来就送去识别不等全部抽完引入内容缓存——同一文件二次处理时直接跳过已完成的中间结果。这三项优化组合下来1 小时视频的处理时间从 30 分钟降到大约 5 分钟。批量处理 200 节课的排队时间从“好几周”变成“一个通宵”这个提升对我来说是决定性的。成本方面也要注意并发任务是吃 CPU 和 GPU 的小规模部署时我限制并发线程数为 2避免处理少量视频时把整台机器拖垮。6. 使用指南Skill 接入配置、两种调用姿势和输出质量快速校验6.1 接入配置一个目录、一个配置文件、一段依赖清单Skill 的安装其实就是把一个目录放进 Agent 支持 Skill 加载的路径。目录结构保持清晰media_content_extractor/ SKILL.md # 元信息描述文件 extractor.py # 主处理逻辑 requirements.txt # 依赖清单extractor.py的主要入口接收一个参数字典内部按“视频/PPT”分支走不同流程最后返回统一封装的输出对象。依赖只有常见的数据处理、图像处理和视频处理库安装时一条命令拉完。配置完目录后在 Agent 的配置里声明 Skill 路径即可不需要改 Agent 本身。6.2 调用方法从自然语言到结构化参数接入完成后调用方式非常直观。用户对 Agent 说“帮我把 D 盘课程目录下的《网络基础-03-路由原理.mp4》和同目录的配套 PPT 整理成文档要带时间戳。”Agent 会根据 Skill 描述自动解析出file_path、media_typevideo、with_timestampstrue这些参数随后调用提取逻辑。处理完成返回 Markdown由 Agent 直接呈现给用户。整个过程用户不需要知道 Skill 存在他把这当成 Agent 的一次普通问答就行。第二种调用姿势是程序化调用——直接在代码里构造参数字典调用extractor.py处理。这种姿势适合把它嵌入批处理脚本比如维护一个课程清单每晚自动增量处理新增视频。我建议所有做知识库自动化的团队重点看这种用法配合文件监控可以做到“新课程一入库就自动产出文字稿”。6.3 质量校验三分钟判断提取结果能不能用输出之后怎么快速判断质量而不必把整篇文档从头看到尾我总结了一个三分钟校验法时长/页数核对视频总时长和 Markdown 末段的时间戳差距不应超过 2%PPT 页数和文档中标注的页码数应一致。术语抽查挑 5 个课程相关的专业术语在全文里搜索正确命中的至少有 4 个。如果低于这个比例多半是 OCR 或 ASR 的问题。画面文字抽样随机抽 3 个时间戳跳回原视频对应位置核对画面上的文字是否被正确提取。这是验证抽帧策略是否合理的最快方式。如果这三项都通过就可以放心把文档交给下一步了。我自己通常会再加一道自动化检查把输出里的时间戳序列拉成一张图看有没有明显的时间空洞有空洞说明那段视频里的内容没有被任何一条线覆盖需要回查。最后分享一个我在实际使用中总结的扩展方向整个 Skill 跑顺之后我又沿着这个思路扩展了两个方向一是把输出转成适合向量化的分段格式一个大段对应 L1 章节标题、L2 段落标题和正文知识库检索的命中率比整篇投喂高出不少二是针对“视频里没有配套 PPT”的纯对话类录屏额外增加说话人分离让输出里的每段话带上主讲人标签。如果你正在做 Agent 相关的知识库接入或者手上有一大批录屏和演示文稿等着被文字化我建议不要指望把文件直接丢给大模型。花点时间做一个专属 Skill把提取链路固化下来你会明显感觉到——Agent 不是一个“什么都能硬看”的黑盒而是需要一套好工具的熟练工。这套工具就是 Skill 存在的理由。