# DeepSeek Harness 版 88API Image Studio

中文 | [English](README.md)

不再分别安装 Image2 和 Nano Banana 插件。88API Image Studio 用一个插件、一个 Key 统一接入六款 88api.ai 生图模型，在 DSH 对话中覆盖文生图、按顺序多参考图编辑、2K/4K 输出、顺序批量任务和默认模型持久化。

88API Image Studio 提供三个 Agent 工具：

- `image_generate_88api`：统一文生图和参考图编辑。
- `image_model_88api`：列出模型、查看当前默认模型，或在用户明确要求后修改默认模型。
- `image_key_88api`：查看、保存或清除 Key；适合用户明确要求 Agent 代为配置的场景。

插件遵循当前可用的 DSH/Cordis bundle contract，不把仍处于 Draft 的 Community Fabric manifest 当作发布接口。

## 模型与协议

| 模型 | 系列 | 协议 | 分辨率 |
| --- | --- | --- | --- |
| `gpt-image-2` | Image2 | OpenAI Images API | 固定 2K |
| `gpt-image-2-4k` | Image2 | OpenAI Images API | 固定 4K |
| `gpt-image-2.5-flare` | Image 2.5 | OpenAI Images API | 插件 2K 预设 |
| `gpt-image-2.5-sunburst` | Image 2.5 | OpenAI Images API | 插件 2K 预设 |
| `gemini-3.1-flash-image` | Nano Banana | OpenAI Chat Completions | 1K / 2K / 4K |
| `gemini-3-pro-image` | Nano Banana | OpenAI Chat Completions | 1K / 2K / 4K |

两个 Image 2.5 模型 ID 和 Images API 路由已于 2026-09-10 从 88API 实时目录核实，沿用插件 2K 尺寸预设，不代表上游仅支持 2K。可按精确 ID 单次选择或保存为默认值。

出厂默认模型是 `gpt-image-2`，用户保存的默认值优先。单次任务显式指定模型只影响本次调用，不修改长期默认值。插件不会静默切换模型、提供方或协议。

## 安装

安装到实际使用的 profile：

```sh
dsh plugin --profile web add github:blackdm666/dsh-plugin-88api-image
```

DSH Desktop 用户可按实际情况把 `web` 换成当前 Desktop profile 名称。建议锁定已审查的 commit，避免后续推送改变安装内容：

```sh
dsh plugin --profile web add github:blackdm666/dsh-plugin-88api-image#<commit-sha>
```

仓库直接交付可运行 JavaScript，因此从 GitHub 安装不需要 `prepare` 构建，也不需要为 pnpm 配置 `allowBuilds`。

启动前验证组合层：

```sh
dsh --profile web --dump-config
```

输出中应包含 `88api-image` 行。

## 配置 Key：推荐的安全方法

运行下面这一整条命令：

```sh
dsh plugin --profile web exec 88api-image set-key
```

> **先不要粘贴 Key，也不要替换命令中的任何文字。下面整条命令只是打开 Key 配置程序，命令里面没有 Key。**

必须按以下顺序操作：

1. 原样运行整条 `dsh plugin --profile web exec 88api-image set-key` 命令，然后按一次 Enter。
2. 等待终端另起一行显示 `88API Key:`。
3. 看到该提示后，才粘贴真实 Key，再按一次 Enter。输入时不显示字符属于正常现象。

各部分含义如下：

| 命令片段 | 含义 |
| --- | --- |
| `dsh plugin` | 使用 DSH 插件管理命令 |
| `--profile web` | 在 `web` profile 中执行；如果实际 profile 不是 `web`，请替换 |
| `exec` | 执行该 profile 中插件提供的命令 |
| `88api-image` | 本插件的命令名称 |
| `set-key` | 进入 Key 配置模式 |

第 1 步按 Enter 执行整条命令后，终端会显示：

```text
88API Key:
```

第 3 步才粘贴真实 Key，再按 Enter。不要把 `88api-image`、`set-key` 或命令中的其他部分替换成 Key。输入过程会隐藏字符，完整 Key 不会出现在命令行参数中。

非交互环境可以通过标准输入传入：

```sh
printf '%s' "$API88_KEY" | dsh plugin --profile web exec 88api-image set-key --stdin
```

查看脱敏配置：

```sh
dsh plugin --profile web exec 88api-image config
```

默认配置文件为 `~/.dsh/88api-image/config.json`。环境变量 `API88_KEY` 会覆盖本地保存的 Key，但不会写入磁盘。不要把真实 Key 提交到仓库、Issue、截图或命令行参数。

## 配置 Key：直接让 Agent 帮忙

不熟悉终端的用户也可以直接对 Agent 说：

```text
我的 88API Key 是 <在这里粘贴真实Key>，请使用 image_key_88api 帮我保存。配置完成后不要复述完整 Key，只告诉我脱敏预览和是否成功。
```

Agent 会调用 `image_key_88api` 的 `set` 操作保存 Key，结果只返回类似 `abcdef...1234` 的脱敏预览。

**隐私提示：**直接把 Key 发给 Agent 更方便，但 Key 可能保留在 DSH 的对话记录和工具调用参数中。个人长期使用更推荐上面的隐藏终端输入方式。如果已经把 Key 发进对话，建议配置完成后按需要删除该会话，或去 88api.ai 控制台轮换 Key。

## 选择和修改默认模型

可以直接对 Agent 说：

```text
列出 88API 可以使用的生图模型。
把我的默认生图模型改成 gemini-3.1-flash-image。
用默认模型生成一张 16:9 产品主视觉。
这次只用 gpt-image-2-4k，不要修改我的默认模型。
```

也可以在终端修改：

```sh
dsh plugin --profile web exec 88api-image set-default gemini-3-pro-image
```

只有用户明确要求长期变更时，Agent 才允许调用 `set_default`。普通生成任务不传 model，严格使用当前保存的默认模型。

## 生图与编辑

`image_generate_88api` 支持：

- 一个 `prompt`，可以通过 `count` 重复 1～4 次；
- 或一个 `prompts` 列表，最多 20 个不同提示词，按顺序发起付费请求；
- 单次显式 `model`；
- `aspect` 与所选提供方支持的 `resolution`；
- 按顺序传入本地 `reference_images`，此时自动走图片编辑；
- `dry_run: true`，无需 Key、不会调用付费接口，只输出脱敏请求计划。

Image2 固定使用 `/v1/images/generations` 或 `/v1/images/edits`。Nano Banana 固定使用 `/v1/chat/completions`，请求包含 `modalities: ["text", "image"]` 与 `extra_body.google.image_config`。

默认保存目录为 `~/Pictures/88api-image`。如果当前 DSH 模型声明支持图片输入，而且已挂载附件服务，插件还会把生成图作为附件加入工具结果；纯文本模型则只接收绝对保存路径，避免下一轮模型请求因图片输入不受支持而失败。

## 费用与重试安全

每个 `count` 或 `prompts` 项都是独立的付费请求。批量任务顺序执行，遇到第一次失败就停止。

带 `[NO-AUTO-RETRY]` 的错误表示请求已经受理，或云端状态无法确认。插件不会自动重发，也不会换模型兜底。应先向用户说明上一次请求可能仍会计费，只有用户明确要求重新提交后才能发起新的付费请求。

## 安全边界

DSH 插件以 Host 进程中的受信任本地代码运行，capability 元数据不是沙箱。安装前应审查源码并锁定 commit。本插件：

- 将 DSH 核心包声明为 peer dependency，避免重复 Cordis/工具运行时；
- 在平台支持时用严格文件权限保存 Key；
- 所有配置摘要都只显示脱敏 Key；
- 限制参考图与响应体大小；
- API Base URL 默认必须使用 HTTPS，只有部署者明确启用本地不安全测试端点时才允许 HTTP；
- 拒绝上游返回的非 HTTPS、本机或私网图片 URL；
- 只向 88API 同源下载请求携带 Key，不会把 Key 发给重定向或第三方图片主机。

## 当前范围

v0.1 已统一文生图、多参考图编辑、多张重复输出、不同提示词顺序批量、dry-run、持久化默认模型和 DSH 附件展示。旧 Codex 插件中的 SSE 中间预览、目录/模板 workflow、修复轮次和美甲压力测试尚未移植。

## 开发与验证

```sh
npm install
npm run check
npm run self-test
```

测试只使用本地 mock server，不会调用任何付费 88API 接口。CI 还会打包 tarball、装入干净的 DSH profile，并验证组合配置。

许可证：[MIT](LICENSE)。