前言¶
在 DeepSeek Harness 的開發中，接入圖像生成能力通常需要處理異步任務輪詢、本地參考圖上傳以及文件預覽等細節。dsh-tool-image-gen 插件對接 ToAPIs 異步 API，提供文生圖和圖生圖工具，簡化了這些操作。
這是什麼¶
這是一個 DeepSeek Harness 圖像生成工具插件，由 zhangjunjesse 維護。它對接 ToAPIs 異步 API，提供文生圖與圖生圖工具。
核心功能¶
- 文生圖與圖生圖：提交任務 → 輪詢 → 下載到工作區
generated/。 - 透明背景生成：通過設置
background: "transparent"，返回帶 alpha 通道的 PNG。 - 多圖生成：插件通過客戶端併發補償（
n參數走客戶端而非服務端）實現多圖輸出。 - 異步任務輪詢：自動管理提交任務與輪詢取結果的過程。
- 本地參考圖自動上傳：
referenceImages支持本地文件路徑，自動上傳換取 URL。 - 多種尺寸和分辨率支持：支持 1:1 至 21:9 等多種比例及 1k/2k/4k 分辨率。
- 內聯預覽：結果註冊進 DSH 附件系統，超 5MB 自動壓縮（依賴 macOS sips）。
安裝與啓用¶
- 安裝插件包：
cd ~/.dsh/profiles
npm install dsh-tool-image-gen
- 插件自帶
cordis.patch.yml，DSH 會自動讀取並注入工具。也可手動在cordis.patch.yml中插入：
- id: image-gen
name: 'dsh-tool-image-gen'
- 配置憑據：
# 編輯 ~/.dsh/.credentials.yaml
# chmod 600 ~/.dsh/.credentials.yaml
# 添加內容：
TOAPIS_API_KEY: 你的key
配置¶
插件支持在配置文件中覆蓋默認參數：
| 字段 | 默認值 | 說明 |
|---|---|---|
apiKeyEnv |
TOAPIS_API_KEY |
憑據引用名 |
baseURL |
https://api.toapis.com/v1 |
API 基址；中國大陸網絡建議改用 https://api.toapis.cn/v1 |
model |
gpt-image-2.5-flare |
默認模型；可選 gpt-image-2.5-sunburst、gpt-image-2 |
size |
1:1 |
默認比例 |
resolution |
1k |
默認分辨率 |
background |
不設置 | 設爲 transparent 可生成透明背景 |
maxImagesPerCall |
4 |
單次 n > 1 時最多併發扇出的任務數 |
pollIntervalMs / maxAttempts |
3000 / 60 | 輪詢策略 |
timeoutMs |
600000 | 協作超時 |
outputDir |
<cwd>/generated |
圖片落盤目錄 |
典型用法¶
文生圖指定模型和尺寸：
{ "prompt": "賽博朋克城市夜景海報", "model": "gpt-image-2.5-sunburst", "size": "16:9", "resolution": "2k" }
生成透明背景貼紙：
{ "prompt": "一個紅色圓形貼紙", "background": "transparent" }
一次生成多張：
{ "prompt": "a small red apple on a white table, studio lighting", "n": 3 }
圖生圖（本地路徑自動上傳）：
{ "prompt": "把這張圖改成水彩畫風格", "referenceImages": ["/path/to/photo.png"] }
上傳本地圖片獲取公開 URL：
{ "filePath": "/path/to/photo.png" }
適用場景與注意¶
- ToAPIs 爲第三方 API 平臺，按量計費，需自行獲取 key。
n參數走客戶端併發補償，非服務端原生支持，會產生多次計費，建議設置maxImagesPerCall限制。- VIP (
gpt-image-2.5-*-vip) / official 變體暫不支持，本插件暫未覆蓋其參數。 - Windows 上超大圖（>4.5MB）的內聯預覽壓縮依賴 macOS 的
sips，非 macOS 平臺僅落盤不顯示。
短結尾¶
該插件通過封裝 ToAPIs 的異步流程，讓 DSH 智能體具備了圖像生成能力。更多細節可查看源碼：GitHub
