前言¶
在 DeepSeek Harness（下稱 DSH）裏做智能體開發，遲早會碰到圖片生成或編輯的需求。麻煩在於各家服務商的接口並不一致：OpenAI 系的服務走 Images 兼容接口，Google Gemini 走 Interactions API，鑑權方式和參數體系各不相同。如果讓智能體直接綁定某一家，之後想換服務商、做故障轉移，就得重新折騰一遍。
dsh-image-tools 的思路是把這件事收攏成兩個工具：image-generate 和 image-edit。對模型暴露的是 provider 中立的統一參數，背後可以掛多個服務商，按優先級依次嘗試。下面介紹它的功能、安裝和典型用法。
這是什麼¶
dsh-image-tools 是一個 DSH 插件，通過 provider 中立的 image-generate / image-edit 工具，提供統一的多服務商圖片生成與編輯能力，覆蓋 OpenAI Images 兼容服務與 Google Gemini Interactions API 兩類後端。由 JuneLearn 維護，許可證爲 MIT，當前版本 0.1.0。
核心功能¶
有序的多服務商管理¶
插件管理一組有序的圖片服務，每個服務使用獨立的 API key，並各自配置一個模型。服務按從高到低的優先級排列，可以在設置裏上下調整故障轉移順序。新增服務時從三類協議/預設中選擇：OpenAI Images、OpenAI Compatible、Google Gemini（Interactions API）。
生成與編輯參數¶
image-generate 的參數如下：
prompt：必填，圖片提示詞；profile：可選，指定服務 ID，省略即啓用順序故障轉移；count：1–8，默認 1；size、aspect_ratio、resolution（Gemini 支持 auto / 0.5K / 1K / 2K / 4K）、quality、output_format、compression、background：模型支持時生效。
image-edit 的參數：
refs：必填，本地路徑或asset:image-*引用的數組；mask：可選，alpha PNG，模型支持蒙版時可用。
參數在請求前校驗，而不是靜默丟棄不支持的值。構圖比例建議只傳 aspect_ratio；如果模型同時傳了同向的冗餘參數（如 portrait 加 3:4），顯式比例優先，真實方向衝突仍會被拒絕。
結果預覽與資產引用¶
生成結果會在會話內預覽，並保存到 outputs/images/ 目錄，文件形如 image-YYYYMMDD-HHMMSS-xxxxxxxx.png，互斥寫入與隨機後綴防止覆蓋。每個輸出附帶同名的脫敏 JSON 元數據 sidecar，不含 API key、完整響應體或 headers。結果可以通過穩定的 asset:image-* 引用複用，進程重啓後仍可解析。
故障轉移與計費安全¶
插件只在連接類故障時做順序故障轉移，避免對計費情況不明確的請求自動重試。對 Gemini 的請求始終設置 store=false，不依賴廠商的會話狀態。
同時掛載 Host 與 Web 客戶端¶
包內的 dsh.bundle 聲明會同時掛載 Host 與 Web 客戶端，不需要手動修改 profile。
安裝與啓用¶
運行要求：
- Node.js 20 或更新（推薦 Node.js 24 LTS）；
- Git；
- pnpm；
- DeepSeek Harness 0.1.0-rc.6。
從 GitHub 直接安裝：
npx --yes -p @deepseek-ai/dsh dsh plugin --profile web add github:JuneLearn/dsh-image-tools
安裝完成後啓動 Web UI：
npx --yes -p @deepseek-ai/dsh dsh web
Web UI 默認監聽 http://127.0.0.1:3080。
配置圖片服務¶
先啓動 Web UI，再按下面的步驟添加服務：
- 打開 Settings > Plugins > Configurable plugins > Image Tools；
- 點擊 Add service，在專用編輯器裏選擇 OpenAI、OpenAI Compatible 或 Google Gemini；
- 填入服務名、端點、API key 和模型，保存；
- 可選：測試已保存的 URL、key 和模型的連通性，測試不會生成圖片。
API key 通過 DSH credentials 存儲，常規設置狀態不會返回密鑰。設置列表會顯示每個服務的名稱、類型、模型、key 狀態和行操作。需要注意，沒有模型列表端點的 OpenAI 兼容中轉會被報告爲可達但無法驗證。
典型用法¶
配置好服務之後，在會話裏不需要指定工具、模型或參數，直接描述需求即可：
Create a cute moe-style image of a blue whale maid.
DSH 會自動調用 image-generate，並按順序嘗試已配置的服務。數量、構圖、質量也可以用自然語言表達：
Create two high-quality 16:9 cinematic concept images of a futuristic city.
編輯同樣在會話內繼續：
Change the background of the previous image to an underwater castle, but keep the character unchanged.
DSH 會自動引用上一個結果並調用 image-edit，也可以上傳當前會話工作目錄內的本地圖片作爲參考。遠程引用 URL 與會話工作目錄之外的路徑會被拒絕。
適用場景與注意事項¶
這個插件適合需要在 DSH 智能體裏接入圖片生成/編輯能力、又不想綁死單一服務商的場景。多服務商有序故障轉移對可用性敏感的會話流程比較有用；僅對連接類故障轉移的設計，則把計費風險控制在明確範圍內。
安裝前有幾點需要確認：
- 插件以當前 dsh 進程的權限運行，安裝前應檢查源碼與許可證（本項目爲 MIT）；
- README 中包含 WPIronman API Relay 的推廣（affiliate）鏈接及優惠碼
99F509ABC6C38F77，插件聲明獨立於該中轉，不要求使用任何特定中轉，選擇服務時請自行評估價格、可靠性與隱私政策； - 如果之前用過 dsh-image2-draw，需要先移除舊包再安裝，兩者使用不同的設置命名空間，舊設置、密鑰、工具和結果卡片不會被導入，API key 也不會自動複製：
npx --yes -p @deepseek-ai/dsh dsh plugin --profile web remove dsh-image2-draw
npx --yes -p @deepseek-ai/dsh dsh plugin --profile web add github:JuneLearn/dsh-image-tools
移除後需要在 Image Tools 設置裏重新創建服務。
結尾¶
dsh-image-tools 把多服務商圖片生成與編輯統一到兩個工具之下，用有序服務和剋制的故障轉移策略換取靈活性，同時通過參數校驗、脫敏 sidecar 和 credentials 存儲把安全邊界交代清楚。如果你在 DSH 裏需要圖片能力，值得一試。
- 社區目錄頁：https://www.skillhub.cn/plugins/JuneLearn/dsh-image-tools
- GitHub 倉庫：https://github.com/JuneLearn/dsh-image-tools
