@qizhen2021/dsh-plugin-vision：DeepSeek Harness 的視覺分析工具

前言¶

DeepSeek Harness (DSH) 採用“一切皆插件”的架構。純文本模型（例如 deepseek-v4-flash）無法直接聲明 image 輸入，導致無法直接處理視覺任務。@qizhen2021/dsh-plugin-vision 插件註冊了一個 see 工具。它對任意圖片輸出純文本的三通道分析：離線 OCR（帶座標）、ASCII 佈局圖、以及視覺模型（VLM）的語義描述。這使得任何模型（包括純文本模型）都能通過該工具“看”圖。

核心功能¶

該插件提供三個處理通道：

1. OCR（離線）：使用 macOS Vision 框架，支持自動語言檢測。輸出格式爲 x y w h\|text，座標爲歸一化百分比 ×100，Y 軸原點在左下，已按行排序。
2. ASCII 佈局圖：使用 PIL 生成灰度圖，轉換爲 88 列寬的字符畫，梯度爲 ' .:-=+*#%@'。純文本模型可直接“看”佈局。
3. 語義描述：通過 opencode.ai 的 mimo-v2.5 模型（默認）進行結構化報告輸出。支持將 OCR 識別結果作爲 ground truth 注入，保證字符串逐字準確。

安裝與啓用¶

DSH 的 GUI 插件清單頁是隻讀的，不支持本地安裝。需通過 Profile Bundles 方式安裝。

1. 安裝包：

    cd ~/.dsh/profiles/web && pnpm add @qizhen2021/dsh-plugin-vision

2. 修改 ~/.dsh/profiles/web/package.json，在 dsh.profile.bundles 數組中追加：

    {
      "dsh": {
        "profile": {
          "bundles": [
            "@deepseek-ai/dsh-base",
            "@deepseek-ai/dsh-web-app",
            "@qizhen2021/dsh-plugin-vision"   // ← 追加這一行
          ]
        }
      }
    }

3. 重啓 dsh web 使插件生效。

配置¶

插件支持多種配置項，可在 ~/.dsh/profiles/web/cordis.patch.yml 中覆蓋默認值。

密鑰採用雙層讀取策略：優先從 ctx.credentials 服務讀取，未掛載時回退到 credentialPath YAML 直讀。密鑰不進代碼、不進日誌、不進 schema。

工具使用¶

調用 see 工具，參數如下：

• 參數：file_path（必填），ocr?/ascii?/vlm?（默認均爲 true），model?（默認使用配置的 defaultModel）。
• 返回值：JSON 格式的結構化報告，包含三個通道的結果。任一通道失敗不會導致整體失敗，僅標記爲 ok: false 並附帶錯誤信息。
• 錯誤處理：
  • 文件相關錯誤返回 FsError。
  • 視覺處理錯誤返回 VisionError。

注意事項與限制¶

• 平臺限制：OCR 功能僅支持 macOS（Vision 框架），ASCII 和 VLM 支持跨平臺。
• 性能開銷：swift 首次調用包含編譯過程，耗時約 1-2 秒，超時設置爲 90s。
• 無截圖模式：當前版本不支持截圖功能。
• 密鑰安全：密鑰處理完全在進程內進行，不暴露在代碼或日誌中。
• 圖像處理：大圖需通過 prep.py 縮至最長邊 ≤1600，否則可能導致網關或內存問題。