多服务图片生成JuneLearn/dsh-image-tools

DSH Image Tools

为 DeepSeek Harness 提供统一的多服务图片生成与编辑能力，通过中性的
image-generate 和 image-edit 工具连接 OpenAI Images 兼容服务与 Google Gemini
Interactions API。

DSH Image Tools 生成的蓝色鲸鱼女仆示例

由插件调用 image-generate 生成，展示 16:9 图片输出效果。

English

第三方服务推荐（含邀请链接）

如果你正在寻找支持 OpenAI 兼容接口的 API 中转服务，可以了解一下
WPIronman API 中转站。这是我的邀请
链接；通过该链接注册可能会为我带来邀请奖励，具体活动规则和优惠以服务商页面
为准。本插件与该服务相互独立，不要求使用任何指定中转站，请根据价格、稳定性
和隐私政策自行选择。

新用户可使用兑换码 99F509ABC6C38F77 兑换赠送额度。

目录

- 第三方服务推荐（含邀请链接）
- 安装
- 使用
- 功能
- 支持的协议
- 从 dsh-image2-draw 迁移
- 资产与元数据
- 失败与计费安全
- 贡献
- 测试
- 兼容性
- 支持
- 致谢
- 许可证

安装

环境要求

- Node.js 20 或更高版本，建议 Node.js 24 LTS；
- Git；
- pnpm；
- DeepSeek Harness 0.1.0-rc.6。

从源码克隆并运行

下面是从 git clone 到可运行的最短路径，不要求已有 Harness 源码仓库：

git clone https://github.com/JuneLearn/dsh-image-tools.git
cd dsh-image-tools
npm install
npm test
npx --yes -p @deepseek-ai/dsh dsh plugin --profile web add .
npx --yes -p @deepseek-ai/dsh dsh web

Web 默认监听 http://127.0.0.1:3080。

直接从 GitHub 安装

不需要本地克隆时：

corepack enable
npx --yes -p @deepseek-ai/dsh dsh plugin --profile web add github:JuneLearn/dsh-image-tools
npx --yes -p @deepseek-ai/dsh dsh web

使用 Harness 源码仓库时，可在 D:\deepseek-harness 中运行：

pnpm install
pnpm dsh plugin --profile web add github:JuneLearn/dsh-image-tools
pnpm dsh web

包内的 dsh.bundle 声明会自动挂载 Host 和 Web 客户端，不需要手工编辑 profile patch。

使用

1. 配置图片服务

1. 打开“设置 > 插件 > 插件配置 > 图片工具”。
2. 点击“添加服务”，在独立编辑页选择 OpenAI 官方、OpenAI 兼容或 Google Gemini。
3. 填写服务名称、接口地址、API Key 和模型名并保存。
4. 可选：点击“测试连接”验证已保存的 URL、Key 和模型；测试不会触发图片生成。

API Key 通过 DSH credentials 保存，普通设置状态不会返回密钥。多个服务按列表从上到下
排列；未显式指定服务时，第一项拥有最高优先级。

DSH Image Tools 有序服务配置界面

2. 生成图片

配置完成后，不需要写工具名、模型名或参数，直接在聊天中说你想要什么：

帮我生成一个蓝色鲸鱼女仆萌系图片

DSH 会自动调用 image-generate，并按设置中的服务顺序寻找可用服务。想控制数量、比例
或画质时，也可以继续用自然语言描述，例如：

帮我生成两张 16:9 的未来城市电影概念图，画质高一点。

查看可用工具参数

- prompt：必填提示词；
- profile：可选服务 ID；省略时按配置顺序尝试，指定时只调用该服务；
- count：1~8，默认 1；
- size：auto、square、portrait、landscape、OpenAI WIDTHxHEIGHT，或
Gemini 分辨率档位；
- aspect_ratio：auto 或模型支持的 W:H；
- resolution：Gemini 的 auto、0.5K、1K、2K、4K；
- quality、output_format、compression、background：仅在模型能力支持时可用。

指定画面比例时优先只传 aspect_ratio。为兼容模型偶尔生成的冗余参数，同方向组合
（如 portrait + 3:4）会采用更具体的 aspect_ratio；方向相反时仍会拒绝。

3. 编辑图片

生成后可以在同一段对话里直接接着修改：

把刚才那张图的背景改成海底城堡，角色保持不变。

DSH 会自动引用上一张结果并调用 image-edit。也可以上传当前会话工作目录中的本地图片
作为参考图。

查看图片编辑参数

- refs：必填数组；接受当前会话工作目录内的相对路径或 asset:image-；
- mask：可选；必须是与第一张参考图同尺寸且带 alpha 通道的 PNG，并且模型支持蒙版。

不接受远程 URL 参考图，也不允许路径越出当前会话工作目录。

4. 管理服务顺序

设置列表只显示每个服务的名称、类型、模型、API Key 状态和行操作。使用上移、下移按钮
调整故障转移顺序；添加或编辑时会进入独立详情页。OpenAI 兼容中转不支持模型列表时，
连接测试会显示“服务可达，但无法验证模型”。

功能

- 管理多个有序图片服务，每个服务使用独立 API Key 和一个模型名；
- 提供 OpenAI 官方、OpenAI 兼容和 Google Gemini 三种配置预设；
- 支持文生图、图生图、多参考图、蒙版和最多 8 张的顺序批量生成；
- 支持尺寸、宽高比、分辨率、质量、格式、压缩和背景参数，实际能力由协议和模型决定；
- 在聊天中预览结果，并将图片保存到会话工作目录的 outputs/images/；
- 为每张图片生成稳定的 asset:image- 引用和脱敏 JSON 元数据；
- 对连接类错误按服务顺序故障转移，不自动重试可能已经计费的请求。

支持的协议

| 协议 | 鉴权 | 生成 | 编辑 | 主要输出控制 |
| --- | --- | --- | --- | --- |
| OpenAI Images | Authorization: Bearer | /images/generations | /images/edits | 尺寸、质量、格式、压缩、背景、蒙版 |
| Gemini Interactions | x-goog-api-key | /v1beta/interactions | 同一端点携带参考图 | 宽高比、分辨率、格式 |

OpenAI 兼容服务的实际模型和参数支持取决于服务商实现。插件会在请求前校验参数，不会
静默忽略不支持的选项。Gemini 请求固定使用 store=false，不依赖供应商会话状态。

从 dsh-image2-draw 迁移

这是一个新包和新设置命名空间，不读取旧插件的配置、工具结果或结果卡。先卸载旧包，
再安装新包：

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

旧 API Key 不会自动复制。安装后请在“设置 > 插件 > 插件配置 > 图片工具”中重新建立服务。

资产与元数据

每张输出图片都带有同名 JSON sidecar：

outputs/images/image-YYYYMMDD-HHMMSS-xxxxxxxx.png
outputs/images/image-YYYYMMDD-HHMMSS-xxxxxxxx.json

asset:image-YYYYMMDD-HHMMSS-xxxxxxxx 可跨进程重新解析。文件使用随机后缀和独占写入，
不会覆盖已有结果。JSON 记录提示词、档案 ID、协议、模型、参数、时间、耗时、图片尺寸、
asset ID，以及可用的 revised prompt、request ID 和非敏感 usage；不会记录 API Key、完整
响应正文或请求头。

失败与计费安全

- 批量请求按顺序逐张执行，单次上游请求固定只取一张图片；
- 未指定 profile 时，首张图片因网络、超时、429、5xx、鉴权或缺少 Key 失败，会尝试
下一个服务；单个服务内部不重试；
- 参数错误、能力不匹配、无效参考图或蒙版、内容审核和取消不会触发服务切换；
- 某个服务已经生成至少一张图片后，后续失败会返回部分结果，不再切换服务；
- 显式指定 profile 时只调用该服务；
- 超时和其他可能已经计费的错误不会自动重试。

贡献

欢迎通过 issue 报告可复现的问题或提出功能建议，也欢迎提交范围清晰的 pull request。
提交前请运行下方测试，并避免在测试、日志或示例配置中提交真实 API Key。

测试

npm install
npm test
npm pack --dry-run

自动化测试使用模拟 HTTP 响应，不调用真实图片 API。真实 API 冒烟测试应由开发者使用
专用凭据和低成本提示词显式执行。

兼容性

当前目标为 DeepSeek Harness 0.1.0-rc.6 的公开双端插件、settings、credentials、
attachments、tools、client slots 和 WebServer 接口。Harness 仍处于 Developer Preview；
升级后若插件无法加载，应先核对这些接口与 dsh.client.inject 声明。

支持

请在 GitHub Issues 提交问题。报告中请包含
Harness 与 Node.js 版本、所选协议、脱敏后的错误代码和复现步骤，不要公开 API Key。

致谢

聊天内附件和专用结果卡的部分实现思路源自 MIT 许可的
dsh-multimodal，详见
THIRD_PARTY_NOTICES.md。

许可证

本项目采用 MIT License，与仓库中的 LICENSE 文件一致。