视频理解插件 dundunhan/dsh-video-lens

dsh-video-lens

为 DeepSeek Harness 提供视频理解能力——让纯文本智能体也能看懂、听懂视频。

这是一个 DeepSeek Harness（DSH）插件，让纯文本 LLM 智能体理解本地视频文件。它提供三个工具：

| 工具 | 作用 |
| video_probe | 通过 ffprobe 快速拿到轻量元数据：容器、时长、分辨率、帧率、编解码器、音轨、字幕。 |
| video_analyze | 理解内容：感知场景切换的抽帧（ffmpeg scdet）、可选的 ASR 转写（带时间戳的语音），再交给任意 OpenAI 兼容的视觉模型融合，输出结构化证据 JSON。 |
| video_ask | 按时间锚定的问答：解析明确的时间引用（「at 3:20」「第2分钟」），或通过转写关键词匹配定位相关语音，从命中的时间窗口重新抽帧，再给出有据可依的回答（答案 + 置信度 + 支撑时间戳）。 |

v0.3.2。插件不会把你绑死在某个服务商上：视觉和 ASR 都是 OpenAI 兼容端点，用 baseUrl + model + key 环境变量配置。

工作原理

video file ──► video_probe ──► ffprobe ──► compact metadata JSON
└─► video_analyze ──► scdet scene detection ──► shot boundaries
├─► ffmpeg frame sampling (one representative frame per shot, capped)
├─► ffmpeg audio extract ──► ASR transcript (timestamped) [optional]
└─► OpenAI-compatible vision API ──► evidence JSON

- 场景切换用 ffmpeg 的 scdet 滤镜检测（ffmpeg ≥ 6.0）。检测不到切点的视频，回退到均匀中点抽帧。
- ASR 是纯增量的：如果 asrApiKeyEnv 没设置，或者服务商调用失败，视觉分析照样跑完，transcript 为 null。
- 所有媒体处理都交给 PATH 上的 ffmpeg/ffprobe——智能体内部不做原生解码。

安装

前置条件：Node.js ≥ 20，ffmpeg ≥ 6.0（推荐），且 ffprobe 在 PATH 上（brew install ffmpeg / apt install ffmpeg）。

方式 A——npm（推荐）

in your DSH profile directory (the one containing package.json)
pnpm add dsh-video-lens

方式 B——从源码（开发）

克隆仓库，再通过本地链接挂载到你的 DSH 配置档：

git clone https://github.com/dundunhan/dsh-video-lens.git

无论用哪种方式，都要在配置档的 package.json 里注册这个 bundle——下面这一整块就是完整的配置档配置：

{
"dependencies": {
"dsh-video-lens": "^0.3"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-video-lens"
]
}
}
}

然后导出密钥并重启配置档：

export VIDEO_LENS_API_KEY=sk-... # vision
export VIDEO_LENS_ASR_KEY=sk-... # optional, ASR
不要自己安装宿主运行时。 @deepseek-ai/dsh-tools 声明为可选 peer：插件始终使用 DSH 安装 / DSH Desktop 自带的 dsh-tools。把它作为依赖加进你的配置档——或者像 0.3.1 那样锁定某个确切的 -rc 版本——会在宿主运行时旁边再装一个更旧的运行时，导致 Loader 条目导入失败，并连带整个插件树（以及应用）一起崩溃。

配置

所有选项都是 DSH 配置值：

| 键 | 默认值 | 含义 |
| visionBaseUrl | https://api.siliconflow.cn/v1 | 视觉端点（兼容 OpenAI） |
| visionModel | Qwen/Qwen3-VL-8B-Instruct | 视觉模型名称 |
| visionApiKeyEnv | VIDEO_LENS_API_KEY | 存放视觉密钥的环境变量 |
| asrBaseUrl | https://api.siliconflow.cn/v1 | ASR 端点（兼容 OpenAI 的 /audio/transcriptions） |
| asrModel | FunAudioLLM/SenseVoiceSmall | ASR 模型名称 |
| asrApiKeyEnv | VIDEO_LENS_ASR_KEY | 存放 ASR 密钥的环境变量 |
| maxFrames | 12 | 帧数上限（1–max）；实际数量随时长自适应（约每 30 秒 1 帧，短视频更密） |
| frameMaxWidth | 768 | 帧最大宽度；用来压小载荷 |
| frameQuality | 4 | JPEG 质量（ffmpeg -q:v） |
| sceneThreshold | 10 | scdet 阈值（0–100）；越高切点越少 |
| askPaddingSec | 2 | video_ask 在匹配到的转写片段前后留的窗口 |
| vlmMaxTokens | 1500 | 视觉模型最大输出 token 数 |
| vlmTimeoutMs | 90000 | 视觉调用超时 |
| asrTimeoutMs | 120000 | ASR 调用超时 |

用法

对智能体说：

"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": "…" }
}

权限与安全

使用或再分发之前请先读这段。DSH 插件以受信任代码的身份运行在宿主进程里，而且没有官方插件审查——自查由作者负责。见 SECURITY.md。

这个插件做什么

- 读取：智能体传给其工具的任何本地文件路径（通过 ffprobe/ffmpeg）。
- 执行：从 PATH 调用 ffprobe 和 ffmpeg（绝不经过 shell——只用 argv 数组）。
- 网络：每次 video_analyze 向配置的 visionBaseUrl 发出一次出站调用（帧 + 视觉密钥），另外可选向 asrBaseUrl 发出一次（音频 + ASR 密钥）。
- 不做：执行 shell、eval 代码、回传数据、自动更新，或自行读取文件。

运维方职责

- 密钥的安全性取决于它被发往的端点——只配置你信任的端点。
- 真正的访问边界是 DSH 宿主沙箱；插件的可读性检查只是 UX 防护，不是安全边界。
- 载荷大小有上限：每次分析调用 maxFrames × 约 100–300 KB（768px JPEG）。

兼容性

- 已在 DSH 配置档组合 @deepseek-ai/dsh-base + @deepseek-ai/dsh-web-app 上测试。
- 宿主运行时不锁定版本：@deepseek-ai/dsh-tools 是可选 peer，从宿主安装中解析，因此插件跟随加载它的核心（已针对核心 0.1.0-rc.7 和 0.1.5-rc.2 验证，后者是 DSH Desktop 2.0.5 锁定的上游版本）。
- Node ≥ 20（用到 AbortSignal.any / 内置 fetch / FormData）。
- scdet 需要 ffmpeg ≥ 6.0；更旧的版本会退化为均匀采样。
- macOS 已验证。Windows：0.3.1 在 Windows 上报告的启动失败并非平台特有——那是锁定的旧 dsh-tools 运行时导致的（见故障排查）；代码路径本身与操作系统无关（ffmpeg/ffprobe 通过 argv 启动，不走 shell）。

故障排查

dsh-plugin-desktop: plugin tree failed to load: failed to apply loader entry include (cordis:include): AggregateError: loader entries failed to apply——客户端不再启动。

0.3.1 在 DSH Desktop 2.0.5 上撞到了这个问题。底下完整的错误是插件（或宿主的 tools 条目）导入失败：

failed to import loader entry video-lens (dsh-video-lens): The requested module '@deepseek-ai/dsh-llm' does not provide an export named 'CallId'
[cause]: profiles/<name>/node_modules/@deepseek-ai/dsh-tools/lib/index.js:4

原因：0.3.1 锁定了 @deepseek-ai/dsh-tools@0.1.0-rc.7，于是配置档里多了一份更旧的 dsh-tools，而宿主跑的是更新的核心（0.1.5-rc.2）。任何 Loader 条目失败都会拖垮整棵树，所以在移除插件之前应用无法启动。

恢复（已安装 0.3.1 且应用无法启动）：

1. 用客户端的 Recovery 页面回到上一个健康配置档，或者从配置档中移除插件：dsh plugin --profile <name> remove dsh-video-lens（Desktop：在其终端里运行该命令）。
2. 安装 dsh-video-lens@^0.3.2，该版本把宿主运行时作为可选 peer，不会往配置档里装任何东西。

测试

npm test # packaging + unit + network + e2e (needs ffmpeg)
node test/host-boot.test.mjs latest # boot a real host with the plugin mounted
node test/host-boot.test.mjs 0.1.0-rc.7 # exactly one core version
node test/host-boot.test.mjs desktop-stable # the upstream core DSH Desktop currently pins

- test/packaging.test.mjs——manifest 契约：官方宿主运行时包（@deepseek-ai/dsh-*）必须保持为可选 peer，绝不能成为已安装依赖，并且发布的 bundle patch / entry 必须能解析。
- test/host-boot.test.mjs —— 端到端防护：打包插件，按 DSH Desktop 的配置档约定（nodeLinker: hoisted、autoInstallPeers: false）装进一个一次性配置档，然后用真实的 DSH 宿主启动该配置档，并要求 Web 界面能起来 —— 同时断言配置档没有安装任何宿主运行时包。需要 pnpm 在 PATH 上（或设置 PNPM_BIN），并且需要网络访问；不需要 API key，也不需要 ffmpeg。CI 会针对 latest、0.1.0-rc.7，以及 DSH Desktop 当前锁定的核心版本运行它。

卸载

1. 在配置档 package.json 的 dsh.profile.bundles 里移除 dsh-video-lens。
2. 移除依赖：pnpm remove dsh-video-lens（npm install）—— 如果你是从源码安装的，就删掉 link: 条目 —— 然后重新安装配置档。

路线图

- v1.0：按文件哈希缓存帧，在 README 里给出评测表（5 种视频类型 × 指标），发布到 npm（进行中）。
- 更远的未来：当配置的 VLM 支持时，把原生视频输入模型作为可选的快速路径。

许可证

MIT —— 见 LICENSE。