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