deepseek-visual-plugin

前言¶

DeepSeek Harness 的理念是“一切皆插件”。在構建智能體時，純文本模型無法直接處理圖片輸入。本插件解決了這個問題：它攔截含圖片的消息，判斷當前模型是否原生支持 image。多模態模型直接放行，純文本模型則調用視覺模型生成描述，再把圖片塊替換爲文字。這樣，純文本模型也能“看懂”圖片。

安裝與啓用¶

本插件以單文件 ESM 插件形式部署到 Harness 家目錄，通過 home 級補丁啓用，對所有 profile（web / headless 及未來新建的 profile）生效。

Windows（PowerShell）

# 1. 部署插件代碼
$dest = "$env:USERPROFILE\.dsh\profiles\node_modules\deepseek-visual-plugin"
New-Item -ItemType Directory -Path $dest -Force | Out-Null
Copy-Item index.js, package.json, cordis.patch.yml -Destination $dest -Force

# 2. 在 $DSH_HOME/cordis.patch.yml 中加入（不存在則創建）
# - insert:
#     - id: deepseek-visual
#       name: deepseek-visual-plugin
#       config:
#         model: <視覺模型名>
#         baseUrl: <OpenAI 兼容端點>
#         apiKeyEnv: <憑證引用名>

Linux / macOS（Bash / Zsh）

# 1. 部署插件代碼
dest="$HOME/.dsh/profiles/node_modules/deepseek-visual-plugin"
mkdir -p "$dest"
cp index.js package.json cordis.patch.yml "$dest"

# 2. 在 $DSH_HOME/cordis.patch.yml 中加入
# - insert:
#     - id: deepseek-visual
#       name: deepseek-visual-plugin
#       config:
#         model: <視覺模型名>
#         baseUrl: <OpenAI 兼容端點>
#         apiKeyEnv: <憑證引用名>

也可以作爲常規 bundle 安裝進單個 profile：

dsh plugin --profile web add C:\path\to\deepseek-visual-plugin

配置¶

插件通過 cordis.patch.yml 配置。可調參數如下：

API Key 的解析優先級：config.apiKey（顯式覆蓋）→ config.apiKeyEnv（credentials 服務解析 ~/.dsh/.credentials.yaml）→ 環境變量回退（QWEN_API_KEY / DASHSCOPE_API_KEY / OPENAI_API_KEY）。

推薦做法：把 key 存進 ~/.dsh/.credentials.yaml，配置裏只寫 apiKeyEnv 引用，避免明文密鑰落在配置文件裏。

# ~/.dsh/.credentials.yaml
DOUBAO_API_KEY: <你的 key>

# cordis.patch.yml
- insert:
    - id: deepseek-visual
      name: deepseek-visual-plugin
      config:
        model: doubao-seed-2-0-mini-260428
        baseUrl: https://ark.cn-beijing.volces.com/api/v3
        apiKeyEnv: DOUBAO_API_KEY

工作原理¶

插件按原生協議實現，主要包含以下邏輯：

1. 攔截與判斷：攔截含圖片的消息，查詢當前模型是否原生支持 image。
2. 分流處理：
   • 純文本模型：調用視覺模型生成詳細描述，再把圖片塊替換爲描述文本。
   • 多模態模型：圖片塊原樣進入模型請求，插件不介入。
3. 覆蓋範圍：替換髮生在內容寫入會話日誌之前。插件覆蓋 agent/pre-step（Web UI 粘貼/拖拽圖片、客戶端消息）與 tools/post-execute（read_image 等工具結果）。
4. 能力聲明：插件包裝 ctx.llm.resolveModelInfo / listModels，爲所有 provider 聲明 ['text','image']，使 Web 上傳、selectModel 切換、read_image 等能力閘門放行。
5. 異常處理：單張圖片解析失敗只替換爲佔位文本，不會中斷會話。原始圖片仍保存在附件存儲中。

使用示例¶

純文本模型通過本插件“看懂”圖片——多模態模型自動放行，純文本模型觸發翻譯。

1. 視覺模型描述 UI：視覺模型把 Windows 開始菜單截圖翻譯成詳細描述。
2. 純文本模型回答：純文本模型基於描述給出結構化回答。
3. 多類 UI 翻譯：DSH 側邊欄與模型下拉菜單截圖都能被準確描述。

注意事項¶

• 手動部署：需要手動部署文件到 $DSH_HOME/profiles/node_modules/deepseek-visual-plugin 並在 cordis.patch.yml 中添加配置（ID: deepseek-visual）。
• 熱更新限制：修改插件源碼後必須重啓 dsh web：web 組合禁用了模塊級 HMR，配置熱更新不會重新加載已變更的插件模塊。
• 憑證缺失行爲：未配置任何 key 時插件仍會加載：含圖片的消息會被佔位文本替換並給出日誌警告；純文本對話不受影響。
• 自檢腳本：verify.mjs 是本插件的功能自檢腳本。運行 npm test（等價 node verify.mjs）可驗證功能。

鏈接¶

• GitHub 倉庫：https://github.com/zhangzhimou78-code/deepseek-visual-plugin
• 插件目錄：https://www.skillhub.cn/plugins/zhangzhimou78-code/deepseek-visual-plugin