# DSH 生图插件

为 **DeepSeek Harness（DSH）** 添加「设置 → 生图」页面和可在对话中直接调用的生图工具。支持自定义 OpenAI Images API 兼容接口、API Key 和模型，生成结果可在对话内预览，并保存原图。

## 功能

- **接口配置**：设置 Base URL 和 API Key，支持第三方兼容服务。
- **显式选择模型**：手动维护模型 ID，或从接口读取模型列表；可设置对话默认模型，也可以每次在对话中指定。
- **对话生图**：助手通过 `imagegen_status` 查询配置，通过 `imagegen_generate` 生成图片。
- **图片编辑**：对话工具 `imagegen_edit` 与「编辑图片」页面支持上传单张 PNG/JPEG/WebP，调用 `/images/edits`，保留输入原图并另存结果。
- **直接生成**：在「设置 → 生图 → 生成图片」中输入提示词、选择模型并生成。
- **图片输出**：支持 base64 和图片 URL 响应，提供图片预览与原图下载。
- **技能复用**：附带 imagegen 提示词规范和示例，并注册 DSH 专用的 `dsh-imagegen` 技能。
- **密钥隔离**：API Key 存入 DSH 凭据存储，按 Base URL 分开保存，不在配置查询中回显。

## 环境要求

- 已验证的 DSH 版本：**0.2.0-rc.2**，桌面版的 Web 界面。
- 安装目标需要提供 DSH 的插件管理、设置插槽、工具、凭据和图片附件服务。
- 一个支持 `POST /images/generations` 的 OpenAI Images API 兼容服务及有效 API Key。
- 从源码克隆安装需要 Git；运行测试建议 Node.js 24 或更新版本。

仓库已经包含可直接加载的 Host / Client 文件，**不需要编译前端、不需要安装 Python，也没有运行时第三方 npm 依赖**。其他 DSH 版本尚未验证。

## 安装

### 方式一：克隆到本地后安装（推荐）

1. 在本仓库页面复制克隆地址，克隆到一个长期保留的目录：

   ```sh
   git clone https://git.crash.work/cneicy/dsh-imagegen.git dsh-imagegen
   ```

2. 打开 DSH 左侧的「插件」页面，使用安装入口，填写克隆目录的**绝对路径**。例如 Windows：

   ```text
   D:\Plugins\dsh-imagegen
   ```

   如果通过 DSH 助手安装，可以直接说：

   > 请把 D:\Plugins\dsh-imagegen 作为插件包安装并启用。

   对应的插件管理工具调用：

   ```json
   {
     "action": "install_bundle",
     "target": "D:\\Plugins\\dsh-imagegen",
     "enabled": true
   }
   ```

3. 确认插件包 `dsh-imagegen-local` 已启用，然后打开「设置 → 生图」。启用后若入口没有出现，先刷新界面；如果安装结果提示需要重启，请重启 DSH。

本地目录可能以链接方式安装，安装后请保留该目录，不要移动或删除。

### 方式二：从 Git 地址安装

也可以在 DSH 的插件安装入口填写本仓库的 Git 安装地址：

```text
git+https://git.crash.work/cneicy/dsh-imagegen.git
```

插件管理器会下载仓库并安装，默认启用。若希望固定版本，可以使用 `#<提交哈希>` 后缀。此方式需要 DSH 所在环境能访问 Gitea，并可调用 Git。

> 仓库包名为 `dsh-imagegen-local`。本项目尚未发布到 npm，不能直接用 `npm install dsh-imagegen-local` 从公共注册表安装。

## 配置

打开 **设置 → 生图 → 接口设置**：

| 配置项 | 说明 |
| --- | --- |
| Base URL | API 根地址，例如 `https://api.openai.com/v1`；不要填写完整的 `/images/generations` 路径。 |
| API Key | 对应这个接口地址的密钥。保存后不回显；留空会保持已有密钥。 |
| 可选模型 | 每行填写一个完整、精确的模型 ID。名称是否可用取决于服务商。 |
| 对话默认模型 | 用户显式选定的默认模型；留空时，助手应先询问或使用本次对话明确指定的模型。 |

点击「保存设置」。保存接口与密钥后，可使用「从接口读取模型」，检查列表并再次保存。部分服务不提供 `/models`，或会同时返回聊天模型，此时手动填写可生图的模型 ID 即可。

更换 Base URL 后，需要为新地址配置密钥。勾选「清除这个地址已保存的密钥」并保存，才会删除该地址的凭据。不要把 API Key 发到聊天里。

## 使用

### 在对话中生图

配置完成后，直接对 DSH 助手描述图片：

> 用 gpt-image-2 生成一张雨夜霓虹街道，电影摄影风格，横版。

或者，在设置中已经选定默认模型时：

> 画一只趴在窗台上晒太阳的橘猫，柔和水彩风格。

模型名称仅作示例，以你的服务实际支持的模型为准。助手会调用插件，返回图片预览和保存路径。插件**不会自动更换模型，也不会自动重试收费请求**。

### 在设置页面直接生图

1. 进入「设置 → 生图 → 生成图片」。
2. 选择或输入本次生成模型。
3. 输入画面描述。
4. 按需展开尺寸、质量与数量设置。
5. 点击「生成图片」，完成后预览并下载原图。

### 编辑已有图片（1.1.0）

先确认服务商和所选模型支持 `POST /v1/images/edits`（`edits` 为复数；Base URL 已有 `/v1` 时只追加 `/images/edits`）。支持生图不代表支持编辑。

- **对话中**：上传图片，或指定已有图片的本机路径，例如「把这张图的背景改成海边，保持人物、衣服和姿势不变，用我设置的默认模型」。助手使用附件的本机路径调用 `imagegen_edit`。
- **设置页**：进入「设置 → 生图 → 编辑图片」，选择图片并预览，选择模型，输入修改要求，然后点击「编辑图片」。
- 输入仅支持一张 PNG/JPEG/WebP，最大 20 MiB；DSH 附件服务还会检查图片能否解码及部署的像素限制。暂不支持 GIF、蒙版或多图输入。
- 原图字节会发送到所配置的服务商；请求可能收费，失败不自动重试。输出另存为新文件，输入不会被覆盖。
- 对话附件可能已经过 DSH 缩放；要使用原始分辨率，请选择本机原文件或在设置页上传原文件。

工具参数示例（路径替换为实际存在的绝对路径）：

```json
{
  "image_path": "D:/Pictures/input.png",
  "model": "gpt-image-2.5-sunburst",
  "prompt": "只将背景改成夕阳下的海边，保持人物、衣服和姿势不变"
}
```

编辑工具复用生图的 `n`、`size`、`quality`、`background`、`output_format` 可选参数；是否支持由服务商决定。设置页通过 `POST /api/imagegen/edit` 提交 multipart 表单：`image` 为文件，`input` 为上述生成参数的 JSON（不包含 `image_path`）。浏览器路由只接收上传文件，不读取请求提供的本机路径。

### 对话工具

| 工具 | 用途 |
| --- | --- |
| `imagegen_status` | 返回 Base URL、是否已配置、候选模型、默认模型与输出目录；不返回密钥。 |
| `imagegen_generate` | 以明确的模型和提示词生成图片，并返回 DSH 图片附件及原图路径。 |
| `imagegen_edit` | 上传 `image_path` 指定的图片，按提示词编辑并返回新图片附件和路径。 |

生成参数示例：

```json
{
  "model": "gpt-image-2",
  "prompt": "一只趴在窗台上晒太阳的橘猫，柔和水彩风格",
  "n": 1,
  "size": "1024x1024"
}
```

必填参数是 `model`、`prompt`；`n` 默认为 1，范围为 1–4。可选参数还有 `size`、`quality`、`background`、`output_format`。这些参数是否可用取决于选定模型与服务商；未指定的可选参数不会额外发送。网页生成表单目前提供尺寸、质量和数量，背景与格式可通过对话工具设置。

## 数据保存

- 普通配置：`$DSH_HOME/imagegen/settings.json`。
- 生成原图：`$DSH_HOME/imagegen/outputs/`。
- 未设置 `DSH_HOME` 时，默认根目录为用户主目录下的 `.dsh`。
- API Key：由 DSH 凭据服务保存，不写入插件目录或上述普通配置文件。
- 对话预览：使用 DSH 持久化附件。预览可能被缩小，输出目录里的原图保留服务返回的原始字节。

使用插件会将提示词和生成参数发送到配置的服务商，并按其规则计费。请求最多等待 15 分钟，适用于 `gpt-image-2` 等处理较慢的模型；等待期间仍可手动取消。点击「停止等待」不能保证服务商已经取消生成或计费。

## 更新与卸载

- 本地克隆方式安装：在插件目录执行 `git pull --ff-only`，然后重启 DSH，以加载新的 Host / Client 代码。
- Git 地址方式安装：通过 DSH 插件管理器安装所需的新提交或版本，然后按提示重启。
- 在 DSH「插件」页面停用或卸载 `dsh-imagegen-local`。
- 卸载不会自动删除已保存的图片和凭据。如需清理密钥，请先在生图设置里清除对应地址的密钥，再卸载。

### 1.0.1 凭据兼容修复（从 1.0.0 升级必读）

1.0.0 曾将凭据名称写成 `dsh-imagegen:<SHA-256>`，不符合 DSH 的 `scope/id` 校验规则，可能导致凭据服务在下次启动时失败。1.0.1 统一使用 `imagegen-local/endpoint-<SHA-256>`；`endpoint-` 保证 ID 始终以字母开头，scope 与注册的 Host 插件名称一致。读、写、删除都使用同一格式。

- **DSH 已能启动**：先更新插件并重启 DSH，再在「设置 → 生图」重新保存 API Key。旧版配置的 Base URL、模型列表和原图不受影响。
- **DSH 因旧记录无法启动**：先退出 DSH，安全备份 `$DSH_HOME/.credentials.yaml`，只移出 `records` 下本插件的旧条目（`dsh-imagegen:<哈希>`，或曾手动改成的 `dsh-imagegen/<哈希>`），保留其他凭据和 YAML 结构；启动后更新插件，再重新保存 API Key。备份含密钥，请勿上传。
- 不要仅替换冒号：十六进制哈希可能以数字开头，仍不符合 ID 规则。
- 插件不会自动读取备份、恢复被移出的旧密钥，或直接改写全局凭据文件。凭据服务先于插件加载，启动被旧记录阻断时，插件自身无法执行迁移。

回归测试现在在每次凭据读写、删除及持久化重载时校验名称，并覆盖哈希首字符的全部 16 种情况。

## 常见问题

**出现 HTTP 401 / 403**：检查 API Key、Base URL 以及账号是否有该模型的权限。

**出现 HTTP 404**：检查地址是否包含服务商要求的 `/v1`，以及是否支持 Images API。不要把完整生成端点填进 Base URL。

**出现 HTTP 502 / 503 或超时**：通常是服务或网关暂时不可用。确认服务状态后手动重试；插件不会自动重试。单次网络操作最多等待 180 秒。

**模型列表读取失败**：可以手动填写模型，不要求服务必须支持 `/models`。

**模型不支持尺寸、质量或透明背景**：去掉不受支持的可选参数，或显式选择支持这些能力的模型。第三方服务也可能忽略某些参数。

**能否用参考图或修改已有图片？** 1.1.0 起支持单张图片加文字指令编辑，调用 `/images/edits`。暂不支持蒙版和多图输入。若编辑返回 404，请检查服务商是否提供该端点；插件不会自动降级成文生图。

## 开发与验证

```sh
node --test test/*.test.mjs
```

测试使用本地模拟 HTTP 服务和隔离的临时目录，不会访问付费生图接口。覆盖参数校验、模型选择、base64 / URL 返回、下载时不携带密钥、错误处理、取消、响应大小限制、设置与凭据隔离、图片附件和路径校验。

项目结构：

```text
lib/index.mjs          Host 插件、设置路由、聊天工具和附件
lib/client.js          DSH ModuleLoader 格式的设置界面
lib/engine.mjs         Images API 请求与校验
skills/SKILL.md        DSH 生图技能适配层
vendor/imagegen/       上游 imagegen 技能与许可证
bundle.yaml           DSH 插件安装补丁
test/                 本地模拟接口测试
```

接口响应与解码图片总量有 64 MiB 限制。网络引擎校验图片格式签名，DSH 附件服务负责进一步验证与预览处理。

## 技能来源与许可证

`vendor/imagegen/` 复用 OpenAI Codex 的 imagegen 技能资源，包含原始脚本、提示词参考、示例和 Apache-2.0 许可证。上游资源完整保留，DSH 的执行适配放在 `skills/SKILL.md` 中；插件本身通过原生 JavaScript 调用 Images API，不运行附带的 Python CLI。

本项目采用 Apache-2.0 许可证，详见 [LICENSE](LICENSE)；第三方资源归属说明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。