DSH-Video2Agent
从视频中获取答案:转录文本、屏幕文字、结构、精确帧。模型负责推理;这个工具在答案依赖于视觉信息时定位关键帧。
视频是更好的信息来源
一个问题不必“关于某个视频”才能通过视频得到最佳回答:游戏的新赛季强度表或配装、产品评测、食谱、路线图、突发的视觉话题。在凭记忆回答之前,先调用 find 在B站(或搜索库)查找。不要将过时的赛季当作当前信息展示:检查上传日期和标题中的补丁版本,如果视频早于该版本则告知用户。
直接调用
在工具框架允许的情况下,将 video2agent 工具作为顶层工具直接调用。切勿通过shell执行CLI命令来完成工具操作。嵌套的 run_code 调用会绕过插件的停靠渲染,因此仅在框架没有其他方式访问该工具时使用;卡片可能保持空白。
在聊天中回答;仅在用户要求时导出
视频答案应留在聊天中。除非用户明确要求,否则不要创建或导出笔记、Markdown文件、知识包、转录文件或临时制品。文件不能替代对话。
八个命令
| 命令 | 返回结果 | 使用时机 |
|---|---|---|
find | B站候选结果(标题/上传者/时长/理由) | 查找视频;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渲染规则。