前言¶
DeepSeek Harness (DSH) 採用插件化架構，擴展行爲通常通過掛載鉤子實現。在 Web GUI 的交互場景中，用戶經常會附加圖片。如果底層模型是純文本模型（例如 DeepSeek），這些圖片會被系統默認忽略，導致模型無法理解視覺內容。dsh-image-bridge 插件通過攔截消息組裝前的鉤子，利用視覺模型將圖片轉爲文字描述，再注入對話，從而讓純文本模型具備“看圖”能力。
插件介紹¶
dsh-image-bridge 是一個 DSH 插件，由 Seryta 維護，遵循 MIT 許可證。它主要解決的問題是：當模型不支持圖片輸入時，自動將 Web GUI 中的圖片通過視覺模型（默認使用智譜 GLM-4V-Flash）轉錄爲文字，並替換原圖片塊進入對話流程。
核心功能¶
該插件在 agent/pre-step 鉤子處運行，核心能力包括：
- 攔截與重寫：攔截
agent/pre-step瀑布事件，讀取消息中的圖片內容塊（{ type: 'image', attachment: ImageAttachmentRef }），通過ctx.attachments.readImage取出圖片字節。 - 自動轉錄：將圖片轉爲文字描述，並替換原圖片塊爲
[圖片描述]文本塊。 - 緩存機制：使用
attachmentId作爲緩存鍵，記錄已識別的圖片描述。同一張圖片在後續步驟中不再重複識別（緩存上限 100，FIFO 淘汰）。失敗結果不緩存。 - 韌性策略：
- 單模型重試：遇到 429/503 錯誤時，進行指數退避重試（默認額外 2 次：1s、2s）。
- 模型回退：遇到 404 或重試耗盡（5xx），自動切換到下一個備選模型（默認鏈：
glm-4.6v-flash → glm-4.1v-thinking-flash → glm-4v-flash）。 - 失敗降級：全部嘗試失敗後，將圖片塊替換爲
[圖片識別失敗]文本，避免觸發UNSUPPORTED_CONTENT導致整輪對話失敗。
- 限制與防護：
- 限制圖片體積（默認 10MB）和分辨率（默認 40MP），超限直接報錯。
- 處理
content parts數組健壯性，網關返回[{text}]數組時按序拼接。 - 剝離 thinking 模型的
</tool_call>推理塊。
- 遞歸處理：支持
tool-result嵌套圖片的遞歸轉錄。
安裝與啓用¶
安裝命令如下：
dsh plugin --profile web add github:Seryta/dsh-image-bridge
安裝完成後，重啓 dsh web 進程即可生效。
配置說明¶
插件支持通過環境變量進行配置，主要包括模型選擇、重試策略、限流設置等：
| 配置項 | 環境變量 | 默認值 | 說明 |
|---|---|---|---|
| 主模型名 | IMAGE_BRIDGE_MODEL |
glm-4v-flash |
用於圖片轉錄的視覺模型 |
| 回退模型鏈 | IMAGE_BRIDGE_FALLBACKS |
glm-4.6v-flash,glm-4.1v-thinking-flash,glm-4v-flash |
逗號分隔，依次嘗試 |
| 重試次數 | IMAGE_BRIDGE_RETRIES |
2 |
單模型在 429/503 上的額外重試次數 |
| 描述語言 | IMAGE_BRIDGE_LOCALE |
zh |
zh 中文 / 其他英文 |
| 圖片字節上限 | IMAGE_BRIDGE_MAX_IMAGE_BYTES |
10485760 |
超限直接失敗，不自動壓縮 |
| 圖片像素上限 | IMAGE_BRIDGE_MAX_IMAGE_PIXELS |
40000000 |
width×height 超限直接失敗 |
憑證讀取¶
插件會按順序嘗試以下環境變量讀取視覺 API 密鑰：
* ZHIPU_API_KEY
* ZHIPUAI_API_KEY
* VISION_API_KEY
* DASHSCOPE_API_KEY
模型限制說明¶
若所選模型聲明 inputModalities: ['text']，DSH 會在消息進入循環前拒絕圖片。本插件本身不修改模型聲明，因此需要配合一個補 image 模態聲明的插件（例如 llm-deepseek-image-admit）才能讓所有模型支持圖片輸入。
注意事項¶
- 圖片處理：一次消息中的多張圖片會合併爲一次視覺 API 調用。緩存按有序
attachmentId組合鍵命中，圖片順序不同則視爲新請求。 - 無預處理：圖片不做壓縮或縮放預處理，僅做體積和像素限制。
- 限流風險：免費檔 VLM 可能存在限流問題，插件雖提供重試和回退機制，但仍需關注 API 配額。
- 依賴環境：插件純手寫 JS，零構建、零第三方依賴，但依賴 Node 內置模塊。
總結¶
dsh-image-bridge 提供了一個從 Web GUI 到純文本模型的視覺信息橋接方案。它通過攔截、轉錄、緩存和降級策略，確保了圖片信息能被模型理解，同時保持了對話的穩定性。適合需要在 DeepSeek 等純文本模型上處理 Web GUI 圖片輸入的開發者使用。
