前言¶

DeepSeek Harness（DSH）里的智能体默认只能处理文本。本地视频文件摆在面前，常见做法是手动抽帧、转写，再把结果塞进对话——步骤多，也难和具体时间点对齐。

下面介绍社区插件 dsh-video-lens（维护者 dundunhan）。它在 DSH Profile 里注册三个工具，用 ffprobe/ffmpeg 做元数据与抽帧，再对接 OpenAI 兼容的视觉模型和可选 ASR，把画面、转写和时间轴合成结构化证据 JSON，供纯文本模型后续推理。

这是什么¶

dsh-video-lens 是面向 DeepSeek Harness 的视频理解插件，当前版本 v0.3.1，MIT 许可证，源码在 GitHub（约 28 stars）。目录页：SkillHub。

它不内置解码器，媒体处理全部交给系统上的 ffmpeg/ffprobe；视觉与语音识别通过可配置的 baseUrl + model + 环境变量密钥调用，不绑定单一厂商。

核心功能¶

插件暴露三个工具，分工如下。

处理流程可以概括为：

video file ──► video_probe ──► ffprobe ──► 元数据 JSON
           └─► video_analyze ──► scdet 场景检测 ──► 镜头边界
                                 ├─► 每镜头代表帧抽样（有上限）
                                 ├─► 音频提取 ──► ASR 转写（可选）
                                 └─► OpenAI 兼容视觉 API ──► 证据 JSON

几点实现细节（来自 README）：

• 场景检测依赖 ffmpeg ≥ 6.0 的 scdet 滤镜；检测不到切镜时回退为均匀中点抽样。
• ASR 是附加能力：未配置 asrApiKeyEnv 或 ASR 失败时，视觉分析仍会完成，transcript 为 null。
• video_ask 在匹配到的转写片段两侧按 askPaddingSec（默认 2 秒）扩展窗口后再抽帧。

安装与启用¶

环境要求：Node.js ≥ 20；ffmpeg ≥ 6.0（推荐）且 ffprobe 在 PATH 中（如 brew install ffmpeg 或 apt install ffmpeg）。

在 DSH Profile 目录（含 package.json 的那一层）安装依赖：

pnpm add dsh-video-lens

在 Profile 的 package.json 里注册 bundle。README 给出的完整示例如下：

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

配置 API 密钥并重启 Profile：

export VIDEO_LENS_API_KEY=sk-...        # 视觉模型
export VIDEO_LENS_ASR_KEY=sk-...        # 可选，ASR

开发调试也可 clone 仓库后以本地 link 方式挂载，步骤见 GitHub README。

配置项¶

常用 DSH 配置键（默认值以 v0.3.1 README 为准）：

完整列表见仓库 README 的 Configuration 一节。

典型用法¶

向智能体描述本地视频路径即可，例如：

What’s in /tmp/demo.mp4?

智能体通常会先调 video_probe，再调 video_analyze。返回的证据 JSON 包含元数据、镜头列表、抽样帧、可选转写，以及视觉模型生成的 analysis（整体摘要、时间线、屏幕文字等），结构大致如下：

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

需要针对某一时间点或某段对白提问时，可走 video_ask，由插件解析时间或关键词后在该窗口内重新抽帧作答。

适用场景与注意¶

适合：需要在 DSH 对话里直接理解本地视频——审片纪要、会议录像摘要、教程片段定位、带时间戳的问答——且愿意自备 OpenAI 兼容视觉/ASR 端点的开发者。

兼容性（README 说明）：已在 @deepseek-ai/dsh-base + @deepseek-ai/dsh-web-app bundle 下测试；macOS / Linux 有测试记录，Windows 未测试。

权限与安全：DSH 插件在宿主进程内以受信任代码运行，社区目录与 DeepSeek / 幻方无官方从属关系，安装前请自行审阅源码与 SECURITY.md。该插件会读取智能体传入的本地路径（经 ffprobe/ffmpeg），执行 PATH 上的 ffmpeg/ffprobe（仅 argv 数组，不启 shell），并向配置的 visionBaseUrl 发送帧数据；若启用 ASR，还会向 asrBaseUrl 发送音频。密钥只会发往你配置的端点；单次分析的 payload 规模受 maxFrames 与 frameMaxWidth 约束。

卸载时从 dsh.profile.bundles 移除 dsh-video-lens，再执行 pnpm remove dsh-video-lens 并重装 Profile 即可。

小结¶

dsh-video-lens 把「探针 → 场景感知抽帧 → 可选转写 → 视觉理解」串成 DSH 可调用的工具链，让纯文本智能体也能基于本地视频做结构化分析与时间锚定问答。更多信息见 SkillHub 目录页与 GitHub 仓库。