# koishi-plugin-comfyui-client

[![npm](https://img.shields.io/npm/v/koishi-plugin-comfyui-client?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-comfyui-client)
[![GitHub](https://img.shields.io/github/stars/flymyd/koishi-plugin-comfyui-client?style=flat-square)](https://github.com/flymyd/koishi-plugin-comfyui-client)

一个为 [Koishi](https://koishi.chat/) 设计的 [ComfyUI](https://github.com/comfyanonymous/ComfyUI) 客户端插件。通过 Koishi 机器人执行 ComfyUI 工作流，支持文生图、图生图（改图）。

## ✨ 功能特性

- **高度可定制**：加载任意 ComfyUI 工作流（JSON）。
- **文生图指令**：`comfy <prompt>` 直接生成图片。
- **图像输入改图**：发送图片或使用 `-i/--image <url>`，插件自动上传到 ComfyUI 并替换工作流占位符，适配重绘/图生图流程。
- **动态连接**：自动处理 HTTP + WebSocket，带重试与进度日志。

## 💿 安装

在 Koishi 插件市场搜索 `comfyui-client` 并安装。

## ⚙️ 配置项

| 配置项 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `serverEndpoint` | `string` | `127.0.0.1:8188` | ComfyUI 服务器地址，格式 `域名/IP:端口`。|
| `isSecureConnection` | `boolean` | `false` | 是否使用 `https`/`wss`。|
| `imageUploadMode` | `string` | `base64-first` | 图片上传方式：`base64-first`（默认，内联为 data URI），或 `image-first`（优先上传到 ComfyUI，失败回退 base64）。|
| `httpProxy` | `string` | `""` | 上传/请求的 HTTP(S) 代理（留空跟随环境变量 http_proxy/https_proxy）。|
| `uploadTimeoutMs` | `number` | `15000` | 上传图片单次超时时间，毫秒。|
| `uploadMaxAttempts` | `number` | `1` | 上传图片最大重试次数，>1 可在弱网下多试。|
| `logEnabled` | `boolean` | `true` | 是否记录与 ComfyUI 的交互日志。|
| `debug` | `boolean` | `false` | 调试模式：打印 debug 级别的中间件/占位符日志。|
| `workflowDir` | `string` | `data/comfyworkflow` | 工作流文件存储目录（可选）。|
| `defaultWorkflowName` | `string` | `""` | 默认工作流名（可匹配预设或文件名）。为空则用 `workflowJSON`。|
| `workflowPresets` | `array` | `[]` | 在 Koishi 控制台维护的工作流预设。|
| `workflowJSON` | `string` | `""` | 直接填入工作流 JSON 字符串（含占位符）。|
| `steps` | CLI 选项 | - | 通过 `-s/--steps` 传入，占位符 `{{steps}}`。|

### 工作流占位符约定

- 文本提示：在正面提示节点使用占位符 `{{prompt}}`，运行时会替换为用户输入。
- 图像输入：将需要读取外部图片的字段改为 `{{image}}`；如需子目录/类型，可用 `{{imageSubfolder}}`、`{{imageType}}`（默认 `subfolder=""`、`type="input"`）。
- 采样步数：在采样节点的 `steps` 字段填 `{{steps}}`，指令里用 `-s 24` 即可。
- 其它变量：支持自定义占位符，通过指令参数 `--vars '{"style":"film"}'` 或 `-r 16:9` 等方式传入。

---

### 导出工作流并填入配置

1. **在 ComfyUI 中构建工作流**
   - 文本提示节点填入 `{{prompt}}` 作为占位符。
   - 图生图/重绘时，把 `LoadImage` 等节点的文件名改为 `{{image}}`（可选 `{{imageSubfolder}}`、`{{imageType}}`）。
   - 确保有 `SaveImage` 或 `ImagePreview` 输出节点，插件会自动选择有图片输出的节点。

2. **导出工作流 JSON**
   - 点击 ComfyUI 右侧 **Save (API Format)**。
   - 复制生成的 JSON 内容。

3. **填入 Koishi 配置**
   - 将 JSON 粘贴到 `workflowJSON` 或保存为文件并在 `workflowDir` 下引用。

## 🚀 使用方法

```bash
comfy <prompt>
```

示例（文生图）：
```bash
comfy a cute cat sitting on a sofa
```

示例（图生图/改图）：
```bash
comfy --image https://example.com/source.png 温柔胶片风格
```
或直接在消息里附带图片，不写 `--image`。

示例（指定采样步数与比例）：
```bash
comfy -s 24 -r 16:9 dreamy portrait
```

## 📄 许可协议

本项目使用 [MIT](./LICENSE) 许可协议。

## ❤️ 作者

**koishi-plugin-comfyui-client** © [flymyd](https://github.com/flymyd), Released under the MIT License.

> GitHub [@flymyd](https://github.com/flymyd) · 夏雪冬花