dsh-plugin-use-images

Readme

# dsh-plugin-use-images

把生成图片的 HTTP API 适配成 DeepSeek Harness (dsh) 可选模型。用户在聊天框选中图片模型后，最后一条用户文本会作为 prompt 发送给图片 API；响应会被转换为 DSH 原生图片块，持久化到会话附件存储中。

## 支持的响应

- JSON URL，如 `data[*].url`
- JSON base64，如 `data[*].b64_json`
- JSON data URL
- `text/plain` 的 URL 或 data URL
- HTTP 直接返回 `image/png` / `image/jpeg` / `image/webp` / `image/gif`

请求 body 是可配置的 JSON 模板，可用 `{{prompt}}`、`{{model}}`、`{{n}}` 和 `{{apiKey}}`。响应字段使用简化路径，例如 `data[*].url`、`output.images[*]`。

## 在设置页添加 API

安装并重启 DSH 后，打开「设置 → 图片 / 视频 API」。点击「新增 API」并选择接口预设，填写 Base URL、API Key 和模型 ID 即可。高级接口还可在同一页调整请求 JSON、Headers 和响应提取路径。

页面内可以直接新增、编辑和删除接口，保存后 DSH 模型列表会热更新，无需手工编辑 `settings.yaml`。

## 安装

```bash
# 从 GitHub 直接安装（推荐）
dsh plugin --profile web add github:chuling-lingling/dsh-plugin-use-images

# 卸载
dsh plugin --profile web remove dsh-plugin-use-images
```

安装后重启 `dsh web` 即可生效。完整的接口配置见 [EXAMPLE.md](./EXAMPLE.md)。

## YAML 备用配置方式

通常不需要手工改 YAML。如果 Web 设置页不可用，仍可用 `inbox` 导入：

```yaml
use-images:
  inbox: |-
    {"把 EXAMPLE.md 中的 JSON 粘贴到这里": true}
```

如果解析失败，错误会保留在 `use-images.lastError`。已生效的路由保存在 `use-images.routes`，修改设置后会热更新模型列表。

## 关键字段

| 字段 | 用途 |
|---|---|
| `id` | DSH 供应商 id，只能用小写字母、数字和 `-` |
| `models` | 在聊天模型选择器中显示的模型 |
| `request` | 发送给生图 API 的 JSON 模板 |
| `extractUrls` | 从 JSON 响应提取 URL 的路径 |
| `extractB64` | 从 JSON 响应提取 base64 的路径 |
| `responseMode` | `auto`、`json` 或 `binary` |
| `maxResponseBytes` | 单张下载图片上限，默认 20 MiB |
| `timeoutMs` | 生成及下载的总超时，默认 120 秒 |

## 设计说明

DSH 的 LLM runtime 只接收统一的流事件，而图片 API 通常是一次性 JSON 或二进制响应。本插件实现自定义 `LlmAdapter`：先执行图片 HTTP 请求，再把结果存入 `attachments`，最后发出 `block-start(image)` / `block-end(image)` / `finish` 事件。因此不需要修改 DSH 的文本适配器。