前言¶

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 倉庫。