Communitygithub.com

video2agent

视频搜索与理解工具,适用于本地文件、屏幕录制和平台链接。当问题的最佳答案来自最新、可视化或社区验证的视频时主动使用。

video2agent 是什么?

这是一个视频智能助手技能,专为AI代理(如Claude Code)设计,使其能够直接从视频中提取答案:转录文本、屏幕文字、结构和精确帧。它解决了一个核心问题:许多问题的答案存在于视频而非文本中——游戏赛季强度表、产品评测、食谱、路线、突发视觉话题,甚至前端UI回归测试。该技能通过八个命令(find、ingest、outline、read、evidence、frames、perceive、admin)实现从发现到分析的完整视频工作流。支持Bilibili平台和本地文件,能够进行多视频对比、运动感知(UI过渡、动画循环)、证据帧提取以及账户管理(收藏/历史)。硬规则强调:永远不将本地路径发送给用户、失败即答案(报告错误代码和补救措施)、文本优先于图片以节省令牌。该技能适用于AI代理需要从视频时间点获取具体信息的所有场景。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Harm0ny-AI/DSH-Video2Agent/tree/HEAD/skills/video2agent

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

DSH-Video2Agent

从视频中获取答案:转录文本、屏幕文字、结构、精确帧。模型负责推理;这个工具在答案依赖于视觉信息时定位关键帧。

视频是更好的信息来源

一个问题不必“关于某个视频”才能通过视频得到最佳回答:游戏的新赛季强度表或配装、产品评测、食谱、路线图、突发的视觉话题。在凭记忆回答之前,先调用 find 在B站(或搜索库)查找。不要将过时的赛季当作当前信息展示:检查上传日期和标题中的补丁版本,如果视频早于该版本则告知用户。

直接调用

在工具框架允许的情况下,将 video2agent 工具作为顶层工具直接调用。切勿通过shell执行CLI命令来完成工具操作。嵌套的 run_code 调用会绕过插件的停靠渲染,因此仅在框架没有其他方式访问该工具时使用;卡片可能保持空白。

在聊天中回答;仅在用户要求时导出

视频答案应留在聊天中。除非用户明确要求,否则不要创建或导出笔记、Markdown文件、知识包、转录文件或临时制品。文件不能替代对话。

八个命令

命令返回结果使用时机
findB站候选结果(标题/上传者/时长/理由)查找视频;scope:"library" 搜索已索引的视频;url 解析单个链接
ingest任务ID索引路径/URL;video_ids 启动选定的候选列表;job_id 轮询;campaign_id 推进批次任务
outline一次性索引:转录/OCR行、关键帧、场景切换、覆盖范围(detail:"digest")、元数据(overview)、视觉地图首次查看视频
read紧凑带时间戳的转录,或2-10个视频对比文本回答或对比
evidence某时间戳的帧 + 其OCR文本 + 转录证明某一时刻;常规图像路径
frames精确帧、密集窗口、平铺图、候选镜头、OCR窗口文本无法回答的像素问题
perceive纯数字地图:场景切换、逐格运动、排名时刻、循环、捕获质量——不包含图像运动/UI/动画问题
admin列表/导出/OCR索引/账户/诊断库维护、导出、B站库管理

工作流程

1. 查找

使用 query 参数调用 find;通过 uploader、after、before 筛选。返回结果仅供你参考,而不是一个表格:阅读元数据,然后使用你实际推荐的ID调用 ingest;你将分析的所有视频放入 default_selected(只有这些会开始处理,video_ids 仅列出候选)以及 primary。超过 processLimit → 设置 campaign:true。

粘贴的URL → 用 url 参数调用 find(返回标题/封面/时长,不下载),然后用户确认后调用 ingest。

2. 摄取

用 source(本地路径或URL)调用 ingest 返回任务ID。不要再次通过URL摄取 find 候选结果;候选列表已经启动了处理。需要等待吗?用 job_id 和 wait_ms 调用 ingest——一次,一个任务(上限90秒;程序在120秒附近可能崩溃:不要循环处理多个任务)。queued 表示摄取样例槽忙碌且任务尚未开始;不要再次轮询。转录语言错误 → 用 language 参数调用 ingest。

3. 读取

outline(detail:"digest")是最便宜的首次查看:一个有限索引,包含带时间戳的转录/OCR行、关键帧、场景切换和覆盖范围。然后:

  • 内容问题 → 用 start/end 调用 read(scope:"transcript");回复包含 next_start_ms,因此继续读取而不是要求整个文件。
  • 比较2-10个视频 → 用 compare_video_ids 和 aspects 调用 read(scope:"compare")。
  • 词语可能不同(ASR拼写、计费/收费/价格)→ 在一次调用中向 find(scope:"library")传递2-8个 queries 变体。单个字面查询是得到“视频中没有这个”的假阴性最常见原因。
  • 零命中搜索不能证明不存在:读取 NO_MATCH、OCR_NOT_INDEXED、OCR_INDEX_PARTIAL;它们会说明文本是否曾被读取过。

3b. 短视频快速路径

对于约6分钟以下的片段,如果问题是关于所说内容(而非屏幕显示内容),跳过 outline 直接调用 read:整个转录通常适合一次回复(约150-800个token),而 outline 需要约1.4k个token加上一张联系图。实测:6000字符的 read 上限覆盖约8分钟的中文快速评论和约5.5-7分钟的英文内容。如果回复包含 next_start_ms,表示被截断——对于剩余部分改用 search/outline 而非分页。当需要结构、屏幕文本或视觉信息时使用 outline;运动问题使用 perceive。如果用户自己粘贴了转录/字幕,直接根据文本回答,仅在需要图片的时刻使用视频。

4. 查看(evidence / frames)

用 at 参数调用 evidence 返回该帧及其屏幕文本和转录。默认2张图片;images:0 仅返回文本,images:1 返回一张图片。

frames 用于文本无法回答的问题(计数、动作、颜色、布局):

  • at + count:精确帧。
  • start/end:密集窗口(≤5秒);sheet:true 将最多9帧拼成一张带标签的图像;windows:N 将指定范围采样成一个覆盖图并报告覆盖/缺失情况。
  • view:"candidates":镜头列表(时间码 + 关键帧),用于“找一个片段”。
  • view:"ocr":当屏幕某行文字变化时,对短窗口的每一帧进行OCR。

5. 运动(perceive)

对于动画、UI过渡、“什么改变了”、“它往哪里动”:在调用 frames 之前先调用 perceive。它返回场景切换、逐格运动、排名 moments(t_ms 峰值、onset_ms 开始时间、cell、settles)、循环状态和捕获质量(丢帧/重复帧、闪烁)的数值。

  • 长于10分钟的视频需要一个窗口:先找到时刻(转录/搜索),然后指定 start/end;无窗口调用返回 E_WINDOW_REQUIRED。
  • brief:true 是概览模式(约340个token,场景切换+4个时刻);然后不带该参数再次调用以获取所需窗口(约850个token对应2.5分钟)。
  • loop.found == false 表示“此处未检测到循环”,而非“无循环”。没有 regions 和 coverage 时,切勿断言视频是静态的。
  • 字幕可信度有衡量标准:overview 报告 metrics.caption_check(音频与字幕对比)。CAPTION_AUDIO_UNVERIFIED 表示字幕无法被验证——应告知用户,而不是将其作为精确引用。

6. 账户与导出

使用 admin_action:"account" 调用 admin 读取收藏/历史/文件夹;写入操作仅限CLI(--confirm);文件夹名≤20字符,每次写入≤100个视频。

仅当用户要求时,使用 admin_action:"export" 调用 admin 写入知识包。

硬性规则

  • 永远不要将本地路径发送给用户。 使用 image_urls / image_markdown(只有 image_attached: true 的位置才是真实图像);原始路径会渲染成损坏的占位符。
  • 时间戳等于或超过媒体结尾时返回 E_OUT_OF_RANGE,而不是空的成功响应;错误信息中会包含媒体长度。at/start 中的纯数字表示秒;毫秒请使用 1234ms 或 HH:MM:SS.mmm 格式。
  • 失败也是答案。 当收到 {ok:false,error:{code,message,remedy}} 时,报告错误代码和补救措施;切勿自行编造内容或静默重试。
  • 文本优先,图片其次。 transcript/search 能回答大部分问题;每张图片都会消耗token。默认 images:2,当文本足够时使用0或1。
  • 一张图片及其文本来自同一帧——信任 ocr_frame_ms。
  • 不要倾倒。 read 有上限(默认6000字符);outline 是紧凑的;使用范围和 next_start_ms。
  • 不要为每个视频都调用工具:转录就能回答内容问题;perceive 用于时间/UI相关的问题。

参考资料

  • references/commands.md —— 8个动词 → CLI映射以及所有标志。
  • references/evidence.md —— evidence有效载荷字段及其引用格式。
  • references/visual-types.md —— 帧能回答和不能回答的内容。
  • references/dsh.md —— DSH渲染规则。

相关技能