dsh-tool-image-gen

Readme

# dsh-tool-image-gen

一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 图像生成工具插件：对接 ToAPIs 异步图像 API（GPT-Image-2 等），提供两个模型可调用工具：

- `image_gen`：文生图 / 图生图。提交任务 → 轮询 → 下载到工作区 `generated/`，返回本地路径 + 公开 URL。
- `image_upload`：把本地图片上传到 ToAPIs，换取公开 URL（可作 `image_gen` 的参考图）。

## 特性

- **异步任务管理**：`POST /v1/images/generations` 建任务，轮询 `GET /v1/images/generations/{id}` 取结果。
- **本地参考图自动上传**：`image_gen` 的 `referenceImages` 直接接受本地文件路径（自动走上传接口换 URL），也接受公开 URL。
- **内联预览**：结果注册进 DSH 附件系统（超 5MB 自动用 `sips` 压缩 JPEG），并在文本里附带 Markdown 图片链接。
- **凭据**：key 从环境变量或 `~/.dsh/.credentials.yaml` 读取（`TOAPIS_API_KEY`），永不进对话。
- 尺寸 `1:1`/`3:2`/`2:3`/`4:3`/`3:4`/`5:4`/`4:5`/`16:9`/`9:16`/`2:1`/`1:2`/`21:9`/`9:21`，分辨率 `1k`/`2k`/`4k`，`n` 张数。

## 安装

```bash
# 1. 装进 profile
cd ~/.dsh/profiles
npm install dsh-tool-image-gen
# 或者本地开发：npm link dsh-tool-image-gen

# 2. 接线（cordis.patch.yml，本包自带 bundle manifest，dsh plugin add 可自动接线）
# - insert:
#     - id: image-gen
#       name: 'dsh-tool-image-gen'

# 3. 配 key：~/.dsh/.credentials.yaml 里加
# TOAPIS_API_KEY: 你的key
# chmod 600 ~/.dsh/.credentials.yaml

# 4. 重启 dsh
```

## 配置

| 字段 | 默认 | 说明 |
|---|---|---|
| `apiKeyEnv` | `TOAPIS_API_KEY` | 凭据引用名 |
| `baseURL` | `https://toapis.com/v1` | API 基址 |
| `model` | `gpt-image-2` | 模型 id（也可用 gpt-image-2-vip、gemini 系列等） |
| `size` | `1:1` | 默认比例 |
| `resolution` | `1k` | 默认分辨率 |
| `pollIntervalMs` / `maxAttempts` | 3000 / 60 | 轮询策略 |
| `timeoutMs` | 600000 | 协作超时 |
| `outputDir` | `<cwd>/generated` | 图片落盘目录 |

## 用法

```json
// 文生图
{ "prompt": "赛博朋克城市夜景海报", "size": "16:9", "resolution": "2k" }

// 图生图（本地路径自动上传）
{ "prompt": "把这张图改成水彩画风格", "referenceImages": ["/path/to/photo.png"] }

// 上传换 URL
{ "filePath": "/path/to/photo.png" }
```

## 注意

- ToAPIs 为第三方 API 平台（按量计费），获取 key：https://toapis.com/console/token
- 上传上限 10MB，支持 jpg/png/webp/gif