前言¶
在 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
