dsh-tool-image-gen

一个 DeepSeek Harness 图像生成工具插件：对接 ToAPIs 异步图像 API（GPT-Image-2.5 Flare / Sunburst 等），提供两个模型可调用工具：

• image_gen：文生图 / 图生图。提交任务 → 轮询 → 下载到工作区 generated/，返回本地路径 + 公开 URL。
• image_upload：把本地图片上传到 ToAPIs，换取公开 URL（可作 image_gen 的参考图）。

特性

• 默认模型 GPT-Image-2.5 Flare：官方定位为默认款，画质高于旧版 gpt-image-2，延迟约低 50%；同价可切换到 gpt-image-2.5-sunburst（更慢但细节保留更好），或旧版 gpt-image-2。
• 参数在对话里全部可调：model/size/resolution/background/n/referenceImages 每次调用都能由模型按需指定，不传则回退到部署的默认配置。
• background: "transparent"（已实测有效）：请求透明背景会返回真正带 alpha 通道的 PNG（实测：主体外区域透明、主体本身不透明），适合贴纸/抠图/图标场景；不传则为正常不透明背景。
• n（多图）走客户端并发补偿（已实测底层 API 忽略 n）：ToAPIs 普通版接口无论请求体里的 n 是多少，每个任务永远只返回 1 张图。本插件在 n > 1 时并发提交多个独立任务来拼出多张图（结果因采样而略有差异），并用 maxImagesPerCall（默认 4）做安全上限，避免一次调用无限扇出。
• 异步任务管理：POST /v1/images/generations 建任务，轮询 GET /v1/images/generations/{id} 取结果。
• 本地参考图自动上传：image_gen 的 referenceImages 直接接受本地文件路径（自动走上传接口换 URL），也接受公开 URL。
• 内联预览：结果注册进 DSH 附件系统（超 5MB 自动用 sips 压缩 JPEG，仅 macOS；其他平台超限会静默回退为仅路径，见下方「已知限制」），并在文本里附带 Markdown 图片链接。
• 凭据：key 从环境变量或 ~/.dsh/.credentials.yaml 读取（TOAPIS_API_KEY），永不进对话。
• 尺寸 1:1/3:2/2:3/4:3/3:4/5:4/4:5/16:9/9:16/2:1/1:2/21:9/9:21，分辨率 1k/2k/4k。

安装

# 1. 装进 profile
cd ~/.dsh/profiles
npm install dsh-tool-image-gen
# 或者本地开发：npm link dsh-tool-image-gen

# 2. 接线（cordis.patch.yml，本包自带 bundle manifest，dsh plugin add 可自动接线）
# - insert:
#     - id: image-gen
#       name: 'dsh-tool-image-gen'

# 3. 配 key：~/.dsh/.credentials.yaml 里加
# TOAPIS_API_KEY: 你的key
# chmod 600 ~/.dsh/.credentials.yaml

# 4. 重启 dsh

配置

字段	默认	说明
apiKeyEnv	TOAPIS_API_KEY	凭据引用名
baseURL	https://api.toapis.com/v1	API 基址；中国大陆网络建议改用 https://api.toapis.cn/v1（同 key 同 API，.com host 在部分大陆网络下无代理会连接超时——已实测确认）
model	gpt-image-2.5-flare	默认模型；也可用 gpt-image-2.5-sunburst、旧版 gpt-image-2
size	1:1	默认比例
resolution	1k	默认分辨率
background	不设置（不透明）	设为 transparent 可把每次调用默认改成透明背景
maxImagesPerCall	4	单次 image_gen 调用在 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" }

已实测结论

• n 参数（服务端）：请求体里传 n: 2 等，ToAPIs 普通版接口仍然只返回 1 张图（result.data 长度恒为 1）。插件通过并发提交多个独立任务规避这个限制，语义上是"多次独立生成"而非"服务端一次出多张"，多张之间会有正常的采样差异。
• background: "transparent"：真实生效。实测输出 PNG 的 IHDR colorType = 6（RGBA），且透明区域的 alpha 通道值确实接近 0（非仅仅声称透明、实际不透明的假透明）。
• Flare vs Sunburst：接口、参数、价格完全一致，仅模型名不同。实测同一提示词、1K、1:1：Flare ~38s，Sunburst ~62s（单次样本，非稳定速度比）。默认用 Flare；对细节 / 多轮精细改图要求高时切 Sunburst。

已知限制

• n 不是服务端原生多图：见上，n > 1 会产生 maxImagesPerCall 次计费，请按需设置该上限。
• Windows 上超大图（>4.5MB）的内联预览压缩依赖 macOS 的 sips：非 macOS 平台该压缩步骤会静默失败并回退为仅路径（文件仍会完整落盘到 outputDir，只是可能不在对话里内联显示）。
• VIP / official 变体暂不支持：gpt-image-2.5-*-vip 用像素尺寸（如 1024x1024）而非比例、且不接受 resolution；-official 变体按 token 计费、支持 low/medium/high/xhigh/max 五档质量。这些和普通版参数形状不同，本插件的 size/resolution 枚举暂未覆盖，需要的话请另行扩展。

注意

• ToAPIs 为第三方 API 平台（按量计费），获取 key：https://toapis.com/console/token
• 上传上限 10MB，支持 jpg/png/webp/gif