dsh-plugin-vision：DeepSeek Harness 視覺輔助插件

前言¶

DeepSeek Harness (DSH) 採用插件化架構，目前官方 API 僅提供文本模型，缺乏視覺能力。dsh-plugin-vision 通過註冊 vision_describe 工具，允許主模型調用任意 OpenAI 兼容的視覺 API 來描述圖片。這解決了在沒有原生視覺模型的主模型上處理圖片的需求。

安裝¶

使用官方提供的安裝腳本，將插件掛載到對應的 Profile。

git clone https://github.com/MoneShadow/dsh-plugin-vision && cd dsh-plugin-vision
./install.sh                 # 安裝到 web profile
./install.sh headless        # 安裝到其他 profile（如 headless 模式）

腳本會自動探測 DSH 安裝位置，將插件實體複製到全局依賴樹，並建立軟鏈。

注意：不要使用 dsh plugin add file: 命令安裝本插件。這會導致向 profile 注入 @deepseek-ai/dsh-tools 依賴副本，與全局依賴樹衝突，引發工具調用崩潰（Cannot read properties of undefined (reading 'prepare')）。請務必使用上述安裝腳本。

配置¶

編輯 ~/.dsh/settings.yaml，在文件末尾添加或修改 vision: 段。

vision:
  enabled: true
  autoPath: true                        # 桌面端粘貼圖片自動轉路徑（DSH Desktop 功能）
  baseURL: https://api.openai.com/v1   # 任意 OpenAI 兼容服務地址
  apiKey: ""                            # 視覺模型 API 密鑰
  model: gpt-4o-mini                    # 視覺模型名稱（如 qwen-vl-max）
  timeoutMs: 60000
  cache: true                           # 啓用答案緩存
  cacheTtlSeconds: 3600                 # 緩存有效期（秒）
  cacheMaxEntries: 200                  # 緩存條目上限（LRU 淘汰）

保存後，引擎會自動監視文件變化並熱更新配置，無需重啓。

核心功能與用法¶

1. 工具註冊與調用¶

插件運行在引擎側，會向全局 Agent 註冊 vision_describe 工具。
主模型在對話中可以直接調用該工具，傳入圖片參數：

vision_describe(image, prompt?)

支持的圖片源包括：
* 本地文件路徑
* file:// 協議路徑
* http(s) URL

2. 答案緩存¶

爲了減少 API 消耗，插件內置了答案緩存機制。
* 緩存鍵：圖片內容哈希 + 接口地址 + 模型 + 提問內容。
* 行爲：同一張圖、同一提問再次調用時，直接返回緩存結果，不重複請求視覺 API。
* 錯誤處理：請求失敗的描述不會緩存。
* 策略：基於 TTL（有效期）和 LRU（最少使用）淘汰策略。

3. 配置開關¶

當 enabled: false 時，vision_describe 工具依然會被註冊，但會返回明確的提示信息。主模型在接收到提示後，通常會引導用戶開啓該功能。

4. 密鑰安全¶

API 密鑰以 secret 角色存儲，在官方設置界面中不可見（write-only），避免明文泄露。

與 DSH Desktop 的配合¶

注意：“粘貼圖片自動轉路徑”功能由 DSH Desktop 實現，並非本插件的一部分。

DSH 插件運行在引擎（dsh 進程）側，無法感知瀏覽器的粘貼事件。DSH Desktop 通過向官方 UI iframe 注入補丁，監聽粘貼操作，將圖片存盤並自動插入 [圖片] /真實路徑，最終由主模型調用本插件的 vision_describe 工具查看。

配置中的 autoPath 字段由 DSH Desktop 讀取並控制該行爲。若未安裝 DSH Desktop，需手動將圖片路徑/URL 傳給工具。

注意事項與依賴¶

依賴項：本插件依賴 @deepseek-ai/dsh-tools 和 @deepseek-ai/schemastery（均爲 MIT 許可證）。
官方 API 限制：DeepSeek 官方 API 目前無視覺模型，必須接第三方 OpenAI 兼容服務（如通義千問、智譜、SiliconFlow 等）。
故障排查：如果安裝後任何工具調用（包括 bash）導致引擎崩潰，請檢查是否誤用了 dsh plugin add file: 安裝，並按照安裝腳本的說明重新安裝或卸載重裝。