卡住的不是模型，是"喂什么给它"
大模型能读文本、能看图，但你把一段本地 mp4 的路径丢给纯文本 Agent，它只能确认"这里有个文件"。视频是带时间轴的连续信号，而模型一次只能消化一屏静态内容。所以「让 Agent 看懂视频」本质不是模型能力问题，而是怎么把视频切成模型能消化的证据。
dsh-video-lens（显示名「视频理解插件」，仓库 dundunhan/dsh-video-lens，MIT，npm 最新版 0.3.2）补的就是这一段。它是 DeepSeek Harness 的原生插件，定位很窄：给纯文本智能体补上"看"和"听"。
按站点记录，它的信任档位是已验证（L4 · 真实安装）——本站已于 3 天前在 dsh 0.2.0-rc.2 下真实安装成功。安全扫描结论是 🔵 含敏感能力 · 8 处证据 · 尚无人工评估，能力项为读写 / 递归删除本地文件与发起外部网络请求；站点另挂 ⚠️「需要额外安装运行时依赖（如 Python 包 / 系统命令）」的风险提示，真实含义就是 ffmpeg / ffprobe 前置。维护方面，最近一次提交在 26 天前（2026-09-19）。
三个工具，各管一段
| 工具 | 干什么 | 代价 |
|---|---|---|
| video_probe | 用 ffprobe 快速拿轻量元数据：容器、时长、分辨率、帧率、编解码器、音轨、字幕 | 极低，不解析画面 |
| video_analyze | 感知场景切换的抽帧（ffmpeg scdet）+ 可选 ASR 转写，交给视觉模型融合，输出结构化证据 JSON | 一次视觉调用，可选再加一次 ASR |
| video_ask | 按时间锚定的问答：解析「at 3:20」「第2分钟」这类时间引用，或按转写关键词定位语音，从命中时间窗重新抽帧，给出答案 + 置信度 + 支撑时间戳 | 按需，比全片分析便宜 |
实践用法是"粗筛 → 通读 → 精读"：video_probe 判断值不值得深看，video_analyze 拿全局理解，video_ask 追问细节。
一次 video_analyze 内部跑了什么
video file ──► video_probe ──► ffprobe ──► compact metadata JSON
└─► video_analyze ──► scdet ──► frame sampling ──► ASR [optional] ──► vision API ──► evidence JSON1. 场景检测：用 ffmpeg 的 scdet 滤镜找镜头切换点，每个镜头构成一段时间区间。
2. 代表帧抽取：每个镜头抽一帧代表画面，总量被上限卡住；检测不到切点时会回退到均匀中点抽帧。
3. 可选转写：抽出音轨送 ASR，得到带时间戳的语音片段。
4. 融合：把帧和转写一起发给视觉模型，产出结构化证据 JSON。
一条设计边界值得记住：所有媒体处理都交给 PATH 上的 ffmpeg / ffprobe，插件内部不做原生解码——它只是当"调度员"。
一次提问的输入与输出
对智能体说 What's in /tmp/demo.mp4?，它会先 video_probe 再 video_analyze，回来的证据大致是：
{
"metadata": { "container": "mov,mp4,m4a,3gp,3g2,mj2", "durationSec": 268.4 },
"shots": [{ "timeSec": 12.3, "score": 45.2 }],
"framesSampled": [{ "timestampSec": 5.5, "jpegBytes": 12345 }],
"transcript": { "text": "…", "segments": [{ "start": 0.0, "end": 2.4, "text": "…" }], "language": "zh" },
"visionModel": "Qwen/Qwen3-VL-8B-Instruct",
"analysis": { "overall_summary": "…", "timeline": [{"timestamp_sec": 5.5, "description": "…"}], "on_screen_text": "…", "visual_style": "…", "notable_moments": "…" }
}shots 是切点及得分，framesSampled 记录每个送进模型的帧落在第几秒，analysis.timeline 是带时间戳的描述列表——结论可回指，你能顺着时间戳回看那一帧。video_ask 的返回更多一层：答案 + 置信度 + 支撑时间戳，只重抽命中的那一段帧。
关键默认值
| 键 | 默认值 | 含义 |
|---|---|---|
| maxFrames | 12 | 帧数上限；实际数量随时长自适应（约每 30 秒 1 帧，短视频更密） |
| frameMaxWidth | 768 | 帧最大宽度，用于压小载荷 |
| frameQuality | 4 | JPEG 质量（ffmpeg -q:v） |
| sceneThreshold | 10 | scdet 阈值（0–100），越高切点越少 |
| vlmTimeoutMs | 90000 | 视觉调用超时 |
| asrTimeoutMs | 120000 | ASR 调用超时 |
默认端点也要留意：visionBaseUrl 与 asrBaseUrl 都是 https://api.siliconflow.cn/v1，默认视觉模型 Qwen/Qwen3-VL-8B-Instruct。插件不把你绑死在某个服务商上——两者都是 OpenAI 兼容端点，用 baseUrl + model + key 环境变量配即可，但默认值确实指向硅基流动。
装之前要知道的两件事
第一，别自己往配置档里装宿主运行时。 插件把 @deepseek-ai/dsh-tools 声明为可选 peer，始终从 DSH 安装 / DSH Desktop 自带的运行时解析。一旦把它当依赖加进配置档，或像 0.3.1 那样锁死某个确切的 -rc 版本，宿主运行时旁边就会多出一份更旧的 dsh-tools，Loader 条目导入失败会连带整棵插件树和客户端一起崩溃。遇到这种情况，用客户端 Recovery 页面回到上一个健康配置档，再改装 dsh-video-lens@^0.3.2——该版本已把宿主运行时收回为可选 peer，不再往配置档装任何东西。
第二，ASR 是纯增量的，transcript 为 null 不是坏了。 只设了 VIDEO_LENS_API_KEY 却没配 VIDEO_LENS_ASR_KEY 时，transcript 会一直是 null。这是设计行为：密钥没设置、或服务商调用失败时，视觉分析照样跑完，转写字段记为 null。需要带时间戳的语音就补上密钥，不需要就忽略该字段。
最后是前置条件：Node.js ≥ 20，ffmpeg ≥ 6.0（推荐），ffprobe 在 PATH 上（brew install ffmpeg / apt install ffmpeg）。缺一样，插件基本不可用。
总结
它把"看视频"拆成可审计的几步——ffprobe 拿元数据、scdet 找切点、抽帧、可选转写、视觉模型融合、输出带时间戳的证据 JSON，成本与精度都能靠几个参数调；想对照同类插件的中文清单与安装形态，见 DeepSeek Harness Hub 插件清单。
适合与不适合
适合：快速摸清一段本地录屏或会议录像讲了什么；需要把结论落到具体时间点、便于回溯的证据型问答；已有 OpenAI 兼容视觉或 ASR 端点、想复用自家额度的团队。
不适合：机器上装不了 ffmpeg ≥ 6.0、或 ffprobe 不在 PATH 的环境——插件完全不可用，请先解决前置；需要视频剪辑、转码、字幕烧录的需求，它只做理解与问答；对密钥流向敏感又不愿改默认端点（默认 https://api.siliconflow.cn/v1 会把密钥发往该端点），或指望上游持续追新（最近一次提交在 26 天前，路线图 v1.0 仍在进行中）。
标签：视频理解插件、DeepSeek Harness、抽帧与语音转写、按时间锚问答
本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。