前言¶

在 DeepSeek Harness（DSH）裏做智能體開發，常會遇到一個別扭的問題：主模型是純文本模型，用戶卻往對話裏發截圖。dsh 0.1.1+ 對這種情況做了內置降級——請求不會報錯，但模型只能看到一個圖片佔位，實際看不到圖片內容。想讓模型真正基於圖片回答，要麼換主模型，要麼自己寫一層轉發邏輯。

dsh-image-vision-bridge 解決的就是這個問題：它把用戶消息中的圖片自動發給視覺模型（默認是 opencode-go 路由上的 mimo-v2.5），把返回的文本描述餵給主文本模型，聊天記錄保持原圖顯示。DSH 的理念是「一切皆插件」，圖片理解這類能力正好可以用插件補上。下面介紹它的原理、安裝和配置。

這是什麼¶

dsh-image-vision-bridge 是一個 DSH 宿主插件，由 Icestab 維護，許可證爲 MIT，當前版本 0.1.2。它的工作位置在 llm/stream 水線上：把發給主模型的請求裏的圖片塊（含 tool-result 嵌套）替換爲視覺模型生成的文本描述，構造的是重寫後的請求，原請求對象與會話日誌不被修改。

它聲明瞭 dsh.bundle，是標準的可分發 bundle，安裝時自動插入插件行，不需要手改 cordis.patch.yml。插件不修改 dsh 安裝、不寫 dsh 目錄、不碰會話日誌。

核心功能¶

• 水線改寫：在 llm/stream 水線上把主模型請求中的圖片塊（含 tool-result 嵌套）替換爲視覺模型 mimo-v2.5 生成的文本描述，原請求對象與會話日誌不被修改。
• 聊天保持原圖：圖片消息原樣進入 agent 並寫入會話日誌，聊天記錄顯示的就是用戶發的圖；描述只進模型、不進聊天。
• 進程內緩存：描述結果按附件 id 緩存，重試和後續輪次不會重複調用視覺模型。
• 失敗降級：視覺調用失敗時降級爲一段失敗說明文本，不打斷對話；用戶取消時錯誤照常拋出。
• 多種安裝方式：支持 npm / GitHub / 本地目錄 / tarball 安裝，另提供不通過 dsh plugin 的手工平鋪安裝。
• 可配置項：enabled、provider、model、maxTokens、maxDescriptionChars、prompt。

安裝與啓用¶

標準安裝¶

本包是標準 bundle，用 dsh plugin add 一條命令即可，GitHub 方式可以鎖定版本：

dsh plugin --profile web add github:Icestab/dsh-image-vision-bridge#c67b4b3

也可以改用 npm 包名、本地目錄或 tarball：

dsh plugin --profile web add dsh-image-vision-bridge              # npm
dsh plugin --profile web add ./dsh-image-vision-bridge            # 本地目錄
dsh plugin --profile web add ./dsh-image-vision-bridge-0.1.0.tgz  # tarball

必做配置：讓主模型聲明可接收圖片¶

這一步插件無法替用戶完成。主機的 API 邊界（dsh-host-apiproxy）會校驗消息與當前模型的輸入模態，主模型若不聲明 input 含 image，圖片消息會被直接拒絕，客戶端提示「當前模型不支持圖片」。

先編輯 $DSH_HOME/settings.yaml（也可通過 Web 界面的 Models 頁維護，該文件熱重載、免重啓），在 llm-pi-ai.providers.<路由> 下爲主模型加 modelOverrides：

llm-pi-ai:
  providers:
    opencode-go:
      modelOverrides:
        deepseek-v4-pro:
          input: [text, image]

這條聲明只是放行 API 邊界：插件在水線上就把圖片換成了文本描述，主模型請求裏不會真的出現圖片塊。

然後重啓 dsh web——web profile 已禁用 HMR，必須重啓插件才生效。

手工平鋪安裝（可選）¶

如果不想走 dsh plugin，可以先複製包目錄到 profile 的模塊解析路徑：

cp -r ./dsh-image-vision-bridge "$DSH_HOME/profiles/node_modules/"

再在 $DSH_HOME/profiles/<name>/cordis.patch.yml 中加入插件行：

- insert:
    - id: image-vision-bridge
      name: 'dsh-image-vision-bridge'
      config:
        provider: opencode-go
        model: mimo-v2.5

settings.yaml 的 modelOverrides 配置同樣是必做前提，改完同樣重啓 dsh web。注意：以後若在 profile 裏運行過 dsh plugin add/install，pnpm 可能清掉這個手工放置的目錄，重新執行上面的 cp 命令即可恢復。

配置¶

六個配置項的作用分別是：enabled 設爲 false 時完全透傳、不做橋接；provider 是視覺模型所在的 LLM 路由（必須已在 settings.yaml 的 llm-pi-ai.providers 裏配置）；model 是視覺模型 id；maxTokens 限制視覺調用的最大輸出 token；maxDescriptionChars 限制注入主模型前的描述長度；prompt 是發給視覺模型的指令。默認走 opencode-go 路由上的 mimo-v2.5，默認複用 OPENCODE_GO_API_KEY。

bundle 默認配置可以在 profile 自己的 cordis.patch.yml 裏按行 id image-vision-bridge 重寫（後層勝出）。自定義示例：

- insert:
    - id: image-vision-bridge
      name: 'dsh-image-vision-bridge'
      config:
        model: mimo-v2.5
        maxTokens: 4096
        prompt: 'Describe this image in English, including all visible text.'

自測¶

安裝後可以先跑一遍離線自測，確認插件在你當前環境下工作正常：

cd "$DSH_HOME/profiles"
node node_modules/dsh-image-vision-bridge/test/transform.test.mjs

作者已在 DeepSeek Harness 0.1.0-rc.6 與 0.1.1-rc.2（@deepseek-ai/dsh、dsh-llm 同版本、cordis 4.0.1）上測試，11 項離線自測均通過。插件的 peerDependencies 爲 @deepseek-ai/cordis ^4.0.1 和 @deepseek-ai/dsh-llm ^0.1.0-rc.6，均爲 optional。

適用場景與注意¶

適合的場景：

• 主模型固定用純文本模型（如 deepseek-v4-pro），但用戶會發截圖、照片，希望模型能基於圖片內容回答；
• 希望聊天記錄保持原圖顯示，不出現「圖片解析結果」之類的中間文本；
• 環境裏已有一個配置好的、可以調用視覺模型的 LLM 路由。

使用前需要注意：

• 非官方承諾的用法：插件會重寫進入水線的請求，而框架文檔要求監聽器只讀不改。升級 dsh 前，建議先在臨時 profile 裏冒煙測試——發一張圖即可。
• 與內置降級互補：dsh 0.1.1+ 內置的圖片佔位降級不報錯但模型看不到圖片內容，本插件提供的是真正的視覺描述，二者互補。
• 運行權限：插件以當前 dsh 進程的權限運行，安裝前建議先檢查源碼與許可證（本項目爲 MIT）。

小結¶

dsh-image-vision-bridge 做的事情很單一：把圖片變成文本描述，讓純文本主模型也能處理圖片輸入，同時不污染聊天記錄。如果你的 DSH 環境裏已有可用的視覺模型路由，裝上插件、加一條 modelOverrides、重啓 dsh web 就能跑通。

• GitHub：https://github.com/Icestab/dsh-image-vision-bridge
• 社區目錄：https://www.skillhub.cn/plugins/Icestab/dsh-image-vision-bridge