前言¶

在使用 DeepSeek Harness (DSH) 的 vision 模型（例如 meta/muse-glimmer）時，如果服務端是 LM Studio 這類 OpenAI 兼容網關，經常會遇到 400 錯誤。錯誤信息通常是 'url' field must be a base64 encoded image.。

根本原因在於 DSH 的默認附件插件 dsh-attachment-local 會將帶有 Alpha 通道的圖像（如 PNG 截圖）自動轉碼爲 image/webp 格式，而 LM Studio 的網關層在協議層只接受 image/png、image/jpeg 和 image/gif，直接拒絕了 WebP 格式。

dsh-image-base64 插件通過包裝附件存儲的 readImageRequest() 方法，在請求發送前將不支持的圖像格式轉碼爲 PNG，從而消除這種格式不兼容問題。

是什麼¶

這是一個 DeepSeek Harness 插件，由用戶 pureexe 維護，採用 MIT 許可證。

它的核心作用是在 vision 請求發出前，利用 sharp 庫將不符合網關要求的圖像格式轉碼爲 image/png。它不改變圖像的存儲方式，只修改發送給模型請求中的數據格式。

核心功能¶

1. 格式轉換：攔截 readImageRequest() 調用，檢查返回的媒體類型。
2. 轉碼邏輯：如果媒體類型不在接受列表中（默認爲 image/png, image/jpeg, image/gif），則使用 sharp 將其重新編碼爲 image/png。
3. 按需處理：原本就在接受列表中的格式會原樣通過，只有會導致錯誤的格式纔會被轉碼。

安裝與啓用¶

在執行安裝前，請確保已安裝該插件源碼，例如位於 /home/pakkapon/dsh-image-base64。

1. 在 DSH 的 profile 目錄下執行安裝命令：

dsh plugin --profile <name> add /home/pakkapon/dsh-image-base64

2. 在該 profile 的 package.json 中將該插件添加到 dsh.profile.bundles 列表：

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-image-base64"
      ]
    }
  }
}

3. 重啓 profile（或等待自動加載，取決於配置中的 patchReload 設置）以使插件生效。

配置¶

插件默認只接受 [image/png, image/jpeg, image/gif]，這與 LM Studio 的白名單一致。如果需要支持其他格式，可以在 profile 的 cordis.patch.yml 中針對插件 ID 進行配置。

- id: image-base64-compat
  config:
    acceptedMediaTypes: [image/png, image/jpeg, image/gif, image/webp]

注意事項¶

1. 僅修改請求投影：該插件只修補了發送給模型的請求圖像部分，不會改變圖像在附件存儲中的實際格式。
2. 文件體積增加：轉碼爲 PNG 是無損的，但對於原本是 JPEG 或 WebP 的大照片，PNG 編碼後的文件體積通常會比原圖更大。
3. 格式協商：如果網關實際支持 WebP，建議將其加入 acceptedMediaTypes 列表，而不是依賴插件轉碼。

結語¶

對於需要在 LM Studio 等嚴格網關上部署 vision 模型的開發者，dsh-image-base64 提供了一個輕量級的解決方案，避免了因 MIME 類型不匹配導致的請求失敗。插件源碼位於 GitHub 倉庫 pureexe/dsh-image-base64。