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

dsh-video-lens

为 DeepSeek Harness 提供的视频理解能力——让纯文本 agent 拥有观看和聆听视频的眼睛和耳朵。

一个 DeepSeek Harness（DSH）插件，让纯文本 LLM agent 能够理解本地视频文件。它提供两个工具：

| 工具 | 功能 |
|---|---|
| video_probe | 通过 ffprobe 获取廉价、即时的元数据：容器格式、时长、分辨率、帧率、编解码器、音轨、字幕。 |
| video_analyze | 内容理解：场景变化感知的帧采样（ffmpeg scdet）、可选的 ASR 转录（带时间戳的语音），并与任意 OpenAI 兼容的视觉模型融合，生成结构化证据 JSON。 |
| video_ask | 时间锚定的问答：解析明确的时间引用（"at 3:20"、"第2分钟"）或通过转录关键词匹配定位相关语音，从匹配的时间窗口中重新采样帧，并基于有据可依的证据作答（答案 + 置信度 + 支撑时间戳）。 |

v0.3.2。该插件绝不将你锁定到某个提供商：视觉和 ASR 均为 OpenAI 兼容端点，通过 baseUrl + model + 密钥环境变量进行配置。

工作原理

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——agent 内部不做原生解码。

安装

前置条件：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 profile 中：

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

无论采用哪种方式，都要在你的 profile 的 package.json 中注册该 bundle——下面这个完整的代码块就是完整的 profile 配置：

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

然后导出密钥并重启 profile：

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。将其作为依赖添加到你的 profile 中——或固定一个确切的 -rc 版本（这正是 0.3.1 所做的）——会在宿主运行时旁边安装第二个、更旧的运行时，导致 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 调用超时 |

用法

向 agent 提问：

“/tmp/demo.mp4 里有什么？”

agent 会先调用 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。

此插件会做什么

- 读取：agent 传给其工具的任何本地文件路径（通过 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）。
- ffmpeg ≥ 6.0 以支持 scdet；更旧版本会降级为均匀采样。
- 已验证 macOS。Windows：在 Windows 上报告的 0.3.1 启动失败并非平台特定问题——而是固定的旧版 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//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  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——清单契约：官方主机运行时包（@deepseek-ai/dsh-*）必须保持为可选 peer，绝不能作为已安装依赖，且发布的 bundle patch / entry 必须能够解析。
- test/host-boot.test.mjs — 端到端防护：打包插件，将其安装到 DSH Desktop 配置文件契约（nodeLinker: hoisted、autoInstallPeers: false）下的临时配置文件中，然后用真实的 DSH 宿主启动该配置文件，并要求 Web 界面能够启动——同时断言该配置文件未安装任何宿主运行时包。需要 PATH 上有 pnpm（或 PNPM_BIN）以及网络访问；无需 API 密钥，也无需 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。