dsh-imagegen-plugin

Readme

# dsh-imagegen-plugin

给 DeepSeek Harness（DSH）加上**第三方生图**能力的插件：主模型（如 dsV4）不会画图没关系——本插件把「生图」做成一个可配置、可对话召唤的能力。

```
┌ 设置 → 插件 → 插件配置 ────────────────────────────────┐
│  终端            Agent 循环        网页搜索             │
│  ┌──────────────────────────────────────────────────┐  │
│  │ 生图配置   配置第三方生图 API；对话里提到「生图」│  │
│  │            即可自动生成。          ▾              │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
```

- **设置卡片**：`设置 → 插件 → 插件配置` 里多一张「生图配置」卡片，填接口类型 / 地址 / 模型 / Key / 默认尺寸 / 张数 / 产物目录，保存即热生效。
- **对话召唤**：装好配置后，直接在对话框说「生图：一只橘色小猫坐在窗台上」即可；也可以 `$dsh-imagegen` 显式召唤技能。
- **自动触发**：当你提到 生图 / 画图 / 出一张图 / 文生图 / 改背景 等需求时，模型会自动加载 `dsh-imagegen` skill 并调用 `image_generate` 工具。
- **一键配置**：生图 API 与主对话模型同一服务商时，对 agent 说一句「复用主模型配置生图，模型是 `<模型ID>`」即可——`imagegen_configure {fromMainModel:true}` 自动复用主模型的服务地址与 key 凭据，只补模型 ID，无需重复填地址和 Key。
- **四种接口类型**：
  - `openai` —— OpenAI 兼容 `/v1/images/generations`（文生图）与 `/v1/images/edits`（图生图 / 局部重绘 / 指令编辑）。覆盖 OpenAI、OpenRouter、硅基流动等绝大多数端点；
  - `dashscope` —— 阿里百炼通义万相（`wanx*`）异步任务模式（提交 → 轮询任务 → 取图）；
  - `replicate` —— Replicate `/predictions` 异步任务（模型 ID 形如 `owner/name:version`）；
  - `fal` —— fal.ai 队列异步任务（模型 ID 即队列子路径）。
  - 除 OpenAI 兼容外都只走文生图（改图需要公开图片 URL，暂不支持本地文件）。
- **产物落盘**：生成的图片保存为 `<会话工作区>/<产物目录>/<时间戳>-<序号>.png`，工具返回绝对路径。
- **对话里直接看到图**：生图 API 返回的临时 https 链接会随工具结果给出（`viewableUrls`），模型在回复里用 Markdown 展示——对话流里直接出现图片（点击放大），不依赖宿主版本；链接过期后对话里的图失效属正常，落盘文件是最终版本。图片同时进入模型上下文，后续轮次模型「看得到」刚生成的图（「改一下刚才那张」可直接引用）。端点只返回 b64（无 URL）时，回复里给文件绝对路径。

## 安装

需要已有一个 DSH web 部署（`dsh web` 或桌面版）。

```bash
# 方式一：本仓库目录（默认；开发期 link: 软链安装，改动即时生效）
bash scripts/install.sh

# 方式二：发布后（npm / GitHub）
bash scripts/install.sh dsh-imagegen-plugin@1.0.0
bash scripts/install.sh git+https://github.com/<owner>/dsh-imagegen-plugin.git
```

等价的手工步骤（`-w` 必需：profile 是 pnpm workspace 根）：

```bash
dsh plugin --profile web add -w /path/to/dsh-imagegen-plugin
```

**然后重启 DSH。** 重启后：

1. `设置 → 插件 → 插件配置` 出现「生图配置」卡片（本插件启动时幂等地把 `imagegen` 命名空间加入 Web 设置页的 api-proxy 白名单，故卡片在 *下一次* 启动生效）；
2. `~/.dsh/skills/dsh-imagegen/SKILL.md` 写入（生图技能，模型目录可见）；
3. `image_generate` / `imagegen_status` / `imagegen_test` / `imagegen_configure` 四个工具注册进会话。

## 配置

### 卡片（推荐）

`设置 → 插件 → 插件配置 → 生图配置`：

| 字段 | 说明 |
|---|---|
| 接口类型 | `OpenAI 兼容`（默认）/ `阿里百炼 DashScope` / `Replicate` / `fal.ai` |
| 接口地址 | 默认空，由你填写；OpenAI 兼容端点通常以 `/v1` 结尾。留空时百炼 / Replicate / fal.ai 使用官方默认地址（切换类型且该栏为空时自动预填） |
| 模型 ID | 端点提供的模型名称（格式按各家文档），文生图与改图都用它。如 `gpt-image-1`、`flux-dev`、`wanx2.1-t2i-turbo` |
| API Key | 存凭据服务（固定条目 `DSH_IMAGEGEN_API_KEY`），不写入设置文件；已配置时输入框保持密文并显示「已配置」标签（跨页面刷新 / 宿主重启保持；读取失败会自动重试修复）。改 Key：点击输入框 → 密文清除 → 填新 Key → 保存，即以最新值为准。想复用主模型已有的 Key？不用碰这张卡片——直接对 agent 说「复用主模型配置生图，模型是 `<ID>`」 |
| 默认尺寸 / 默认张数 | 每次生成未显式指定时的兜底值 |
| 产物目录 | 相对会话工作区，默认 `imagegen/` |

### 对话配置（免点页面，也是复用已有 Key 的唯一入口）

**同一服务商（最常见）**——对 agent 说：

> 复用主模型配置生图，模型是 qwen-image

agent 调用 `imagegen_configure {fromMainModel:true, model:"qwen-image"}`：自动读取主模型 provider 的 baseURL 与 key 凭据名写入生图配置，一步完成（卡片里会显示复用后的值与「已配置」标签）。

**完全手动**——直接对 agent 说：

> 配置生图：接口 openai，地址 https://api.example.com/v1，模型 gpt-image-1，Key sk-xxxx

agent 会调用 `imagegen_configure` 写入并（建议）用 `imagegen_test` 验证。

### 环境变量

`DSH_IMAGEGEN_API_KEY`（或 `apiKeyEnv` 指定的同名变量）——共享部署下比把 Key 写进凭据库更稳妥。

## 使用示例

```
你：生图：一只橘色小猫坐在窗台上，午后阳光，电影感
agent：（调用 image_generate，约 6s）
       ![1](/…/工作区/imagegen/2026-08-17-09-55-00-1.png)

你：把这张图改成黄昏油画质感，改动大一点
agent：（image_generate + image=上一步路径 + strength=0.7）

你：把背景换成海边，其他都别动
agent：（image_generate + edit=true，指令编辑，用已配置的模型）
```

## 工具清单

| 工具 | 作用 |
|---|---|
| `image_generate` | 文生图（`prompt`）/ 图生图（`image`+`strength`）/ 局部重绘（`image`+`mask`）/ 指令编辑（`image`+`edit:true`）；可选 `size` `n` `negativePrompt` `seed` `steps`；成功时结果内联展示图片（可点击放大）并返回绝对路径 |
| `imagegen_status` | 查看当前配置就绪度、Key 来源层、主模型信息（`mainModel`）、一键复用建议（`reuseHint`）、内联展示能力（`inlineImages`）、skill / 白名单补丁安装情况 |
| `imagegen_test` | 连通性 + 鉴权 + 模型是否在端点列表 |
| `imagegen_configure` | 对话中热配置 `api` / `baseURL` / `model` / `apiKey` / `apiKeyEnv`（复用已有凭据）/ `fromMainModel:true`（一键复用主模型服务商） |

## 工作原理

- **host 半（`lib/index.js`）**：注册 `imagegen` 设置命名空间（schema 默认值 → cordis 入口 `base` → `~/.dsh/settings.yaml` 用户层，三层解析、热更新）；注册 4 个工具；启动时做两件幂等的自举——
  1. **api-proxy 白名单补丁**：DSH 的 Web 设置页只服务 `dsh-host-apiproxy` 白名单内的命名空间（白名单是 host 代码而非插件声明），本插件在启动时向所有已知安装位置（当前运行的宿主、桌面版、npx 缓存、profile pnpm store）的 `WEB_SETTINGS_NAMESPACES` 数组幂等插入 `"imagegen"`；已补丁的文件跳过，结构变化的版本跳过并记日志。
  2. **skill 安装**：把 `SKILL.md`（内嵌于包内）写入 `~/.dsh/skills/dsh-imagegen/`，使生图技能进入模型目录——它的 description 命中 生图/画图 等关键词时由模型自动加载，`user-invocable` 默认可 `$dsh-imagegen` 召唤。
- **client 半（`lib/client.js`）**：向 `settings.plugin.item` 槽注册「生图配置」卡片，表单模型与核心插件卡片一致：暂存编辑、保存时经 `settings.mutate`（带 revision 栅栏）写回、Key 走 `credentials` 域（不回传明文）。
- **BYO endpoint**：插件不内置任何厂商密钥；OpenAI 兼容模式兼容 `url` / `b64_json` / 裸图片响应三种返回形态，改图走 multipart `FormData`。

## 文件结构

```
dsh-imagegen-plugin/
├── lib/
│   ├── index.js      # host 半：设置命名空间 + 4 个工具 + 启动自举
│   └── client.js     # client 半：「生图配置」卡片
├── scripts/install.sh
├── cordis.patch.yml  # bundle 声明（dsh.plugin CLI 自动挂载用）
├── package.json      # dsh.bundle.patch + dsh.client 声明
├── README.md
└── LICENSE
```

## 卸载

```bash
dsh plugin --profile web remove dsh-imagegen-plugin   # 移除依赖与挂载
rm -rf ~/.dsh/skills/dsh-imagegen                     # 移除技能（可选）
```

api-proxy 白名单里的 `"imagegen"` 行保留无害（命名空间不再注册时不渲染任何卡片）。

## FAQ

- **装插件后报 `Failed to load plugins ... keyed slot "settings.plugin.item" requires options.key`？** DSH rc.6+ 改过设置卡片的插槽 API；v0.4.4 起双兼容新旧版本——重新安装最新版再重启 DSH 即可。
- **第一次生图报「未配置」？** 这是预期路径：对 agent 说「复用主模型配置生图，模型是 `<ID>`」（同一服务商时一步到位），或在「设置 → 插件 → 插件配置 → 生图配置」卡片里填写（卡片未配置时会直接给出这条提示）。
- **重启后卡片没出现？** 对话里让 agent 跑 `imagegen_status`，看 `apiproxy` 段的 `skipped` 原因（通常是 DSH 版本结构变化，锚点失配）；或确认 `dsh-host-apiproxy` 版本仍是 rc.6 一系。
- **保存卡片报「本部署没有接受这些值」？** 多半是 `n` 超出 1-4 或 `api` 填了非法值；修正后重新保存。
- **`model_not_allowed`？** 你的端点密钥有模型白名单且不含该生图模型：在服务商控制台重建包含该模型的密钥。
- **想加新的接口协议？** 在 `lib/index.js` 里照 `dashscopeText2Image` 的模式加一个分支 + 卡片下拉项即可。
- **对话报「本轮运行失败 API key is invalid」？** 流程始终是：主对话模型（设置 → 模型，如 qwen3.8-flash）先理解「生图：…」，再调 `image_generate` 走生图 API。这个 401 是**主模型**的 key 问题（比如该 key 在服务商侧只开了生图 API 分组、没开对话模型分组），与生图 key 无关——给主模型 key 加上对话模型权限即可。生图 key 只对 `image_generate` 生效，两个 key 可以不同。

## 发布到 GitHub

1. 把 `package.json` 里 `repository.url` 改成你的仓库地址；
2. `git init && git add -A && git commit -m "dsh-imagegen-plugin 0.4.4"`；
3. 推仓库后，使用者 `bash scripts/install.sh git+https://github.com/<owner>/dsh-imagegen-plugin.git`，或 `npm publish` 后按版本安装。

## License

MIT