# DSH Image Tools

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

![DSH Image Tools 生成的蓝色鲸鱼女仆示例](./docs/images/demo.jpg)

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

[English](./README.md)

## 第三方服务推荐（含邀请链接）
>
> 如果你正在寻找支持 OpenAI 兼容接口的 API 中转服务，可以了解一下
> [WPIronman API 中转站](https://api.wpironman.top/register?aff=JUNE)。这是我的邀请
> 链接；通过该链接注册可能会为我带来邀请奖励，具体活动规则和优惠以服务商页面
> 为准。本插件与该服务相互独立，不要求使用任何指定中转站，请根据价格、稳定性
> 和隐私政策自行选择。
>
> 新用户可使用兑换码 `99F509ABC6C38F77` 兑换赠送额度。

## 目录

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

## 安装

### 环境要求

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

### 从源码克隆并运行

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

```powershell
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](http://127.0.0.1:3080)。

### 直接从 GitHub 安装

不需要本地克隆时：

```powershell
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` 中运行：

```powershell
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 有序服务配置界面](./docs/images/configuration.png)

### 2. 生成图片

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

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

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

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

<details>
<summary>查看可用工具参数</summary>

- `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`；方向相反时仍会拒绝。

</details>

### 3. 编辑图片

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

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

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

<details>
<summary>查看图片编辑参数</summary>

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

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

</details>

### 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 迁移

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

```powershell
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：

```text
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。

## 测试

```powershell
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](https://github.com/JuneLearn/dsh-image-tools/issues) 提交问题。报告中请包含
Harness 与 Node.js 版本、所选协议、脱敏后的错误代码和复现步骤，不要公开 API Key。

## 致谢

聊天内附件和专用结果卡的部分实现思路源自 MIT 许可的
[dsh-multimodal](https://github.com/MC5lan/dsh-multimodal)，详见
[THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)。

## 许可证

本项目采用 [MIT License](./LICENSE)，与仓库中的 `LICENSE` 文件一致。