# DSH 生图插件

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

## 功能

- **接口配置**：设置 Base URL 和 API Key，支持第三方兼容服务。
- **显式选择模型**：手动维护模型 ID，或从接口读取模型列表；可设置对话默认模型，也可以每次在对话中指定。
- **对话生图**：助手通过 `imagegen_status` 查询配置，通过 `imagegen_generate` 生成图片。
- **直接生成**：在「设置 → 生图 → 生成图片」中输入提示词、选择模型并生成。
- **图片输出**：支持 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. 点击「生成图片」，完成后预览并下载原图。

### 对话工具

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

生成参数示例：

```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 持久化附件。预览可能被缩小，输出目录里的原图保留服务返回的原始字节。

使用插件会将提示词和生成参数发送到配置的服务商，并按其规则计费。点击「停止等待」不能保证服务商已经取消生成或计费。

## 更新与卸载

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

## 常见问题

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

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

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

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

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

**能否用参考图或修改已有图片？** 当前只实现文生图，不支持参考图输入、图像编辑或蒙版。附带的上游 imagegen 技能资源包含编辑说明，但不代表本插件已实现编辑接口。

## 开发与验证

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