dsh-comfyui-ctl

Readme

# dsh-comfyui-ctl

原生 DSH（DeepSeek Harness）插件：让 AI 伙伴直接控制本机 ComfyUI——查队列、中断/清理任务、看历史与产出图、盘点模型与系统、上传图片、提交生成工作流。

核心逻辑独立成零依赖的 `ComfyClient` 模块（`src/client.js`），不绑定 DSH，将来可以原样套上 MCP 壳复用。

## 架构

```
src/
  client.js       ComfyClient —— 零依赖的 ComfyUI HTTP API 客户端（可独立复用）
  index.js        DSH 插件入口：name / inject / Config / apply()，注册 11 个工具
  safety.js       本地上传白名单、文件大小、图片签名与虚拟路径校验
  mock-server.mjs 测试用模拟 ComfyUI（内存画布、历史、模型清单、/prompt 提交）
  test.mjs        客户端单元测试（含超时、断连、大小上限、取消与 node_errors）
  test-safety.mjs 本地上传安全边界测试
  test-apply.mjs  插件 apply() 离线注册测试（不连真实 ComfyUI）
  test-bundle.mjs DSH Bundle manifest 与补丁一致性测试
```

依赖关系：插件只安装公开发布的配置模式模块（schemastery），工具定义适配器随包交付，Cordis 由 DSH 宿主提供；`client.js` 本身零第三方依赖。

## 安装

推荐通过 DSH 插件命令安装到 Web profile：

```powershell
dsh plugin --profile web add github:liyi3068238601-oss/dsh-comfyui-ctl
```

安装完成后重启 DSH。插件包自带 `cordis.patch.yml`，会以 `comfyui-ctl` ID 自动加入 profile，无需手动写 `insert`。

如果旧版本已经通过 `file:///...` 手动插入，请先删除 profile 中旧的 `comfyui-ctl` `insert` 条目，再运行安装命令，避免同一个 ID 被加载两次。

### 配置

在 Web profile 的 `cordis.patch.yml` 中按 ID 覆盖配置：

```yaml
- id: comfyui-ctl
  config:
    baseUrl: 'http://127.0.0.1:8188'
    outputDir: 'C:\path\to\ComfyUI\output'
    allowedUploadRoots:
      - 'C:\Users\your-name\Pictures'
```

仅在源码开发时才需要 `file:///C:/path/to/dsh-comfyui-ctl/src/index.js`。Windows 源码绝对路径必须转换成 `file:///` URL，不能直接写 `C:\...`。

## 配置项（Config）

| 键 | 默认值 | 说明 |
|---|---|---|
| `baseUrl` | `http://127.0.0.1:8188` | ComfyUI 服务地址 |
| `requestTimeoutMs` | `30000` | 单次 HTTP 请求超时 |
| `pollIntervalMs` | `1500` | 等待生成完成时的轮询间隔 |
| `generateTimeoutMs` | `300000` | `comfyui_generate` 同步等待上限 |
| `maxInlineImages` | `4` | 生成结果最多内联返回多少张图 |
| `maxResponseBytes` | `33554432` | 单个 JSON/文本响应上限（32 MiB） |
| `maxMediaBytes` | `67108864` | 单个下载媒体上限（64 MiB） |
| `maxUploadBytes` | `67108864` | 单个本地上传文件上限（64 MiB） |
| `allowedUploadRoots` | `[]` | 允许本地路径上传的绝对目录；空数组表示禁用路径上传 |
| `outputDir` | （空） | ComfyUI 输出目录；设置后 `comfyui_output_list` 支持 `directory`/`auto` 模式 |

## 工具清单

| 工具 | 能力 | 关键参数 |
|---|---|---|
| `comfyui_queue_get` | 查看运行中与待执行队列 | — |
| `comfyui_interrupt` | 中断当前生成 | — |
| `comfyui_queue_delete` | 清空队列或删除指定待执行项 | `clear`、`promptIds` |
| `comfyui_history_get` | 查询历史（可带 prompt id） | `promptId`、`maxItems` |
| `comfyui_output_list` | 列出产出文件 | `source`（auto/history/directory）、`limit`（≤500） |
| `comfyui_output_get` | 按文件名取回产出图片（内联返回） | `filename`、`subfolder`、`type` |
| `comfyui_models_list` | 盘点模型（JSON 与纯文本两种响应都兼容） | `folder`（checkpoints/loras/vae/…） |
| `comfyui_system_stats` | ComfyUI 版本、Python、显存/内存 | — |
| `comfyui_nodes_list` | 节点类与扩展清单 | `search`、`node_class` |
| `comfyui_upload_image` | 上传本地图片到 ComfyUI input 目录 | `path`、`name`、`subfolder`、`overwrite` |
| `comfyui_generate` | 提交 API 格式工作流并按需等待结果 | `prompt`、`wait`、`timeout_ms`、`inline_images`、`client_id` |

`comfyui_generate` 接受完整 ComfyUI API prompt：

```json
{
  "prompt": {
    "1": { "class_type": "KSampler", "inputs": {} }
  },
  "wait": true,
  "timeout_ms": 300000,
  "inline_images": true
}
```

`wait: false` 只提交任务并返回 `prompt_id`；后续使用 `comfyui_history_get` 查询状态。本版本不提供内置 txt2img/img2img/video 模板。

## 验证状态（真机，ComfyUI 0.33.1 / RTX 5070 Ti Laptop）

| 工具 | 状态 |
|---|---|
| `comfyui_system_stats` | ✅ 通过（ComfyUI 0.33.1，python 3.13.12，显存 10.7/11.9 GiB 空闲） |
| `comfyui_models_list` | ✅ 通过（checkpoints=5、loras=47；clip 等空目录优雅报错） |
| `comfyui_history_get` | ✅ 通过（0 条记录） |
| `comfyui_nodes_list` | ✅ 通过（311 个扩展、3494 个节点类） |
| `comfyui_queue_get` | ✅ 通过 |
| `comfyui_output_get` | ✅ 通过（`ComfyUI_00330_.png`，2,980,023 字节，image/png） |
| `comfyui_output_list` | ✅ 通过（directory 模式，334 个文件；`modified_ms` 取整修复已生效） |
| `comfyui_upload_image` | ✅ 通过（`6efdb11e6c8e93c4b9a1adce6b8f3d93_720.jpg`，160,906 B 上传成功） |
| `comfyui_interrupt` / `comfyui_queue_delete` | ✅ 通过（空操作无副作用；queue_delete 空参数按设计被参数校验拒绝） |
| `comfyui_generate` | ✅ 通过（Anima 文生图模板图→API 提取 + 真实生成 `dsh-comfyui-ctl-test_00001_.png`，768×1152，1.14 MB） |

## 开发与测试

```bash
npm install
npm test
npm pack --dry-run
```

测试覆盖：队列/历史/模型/上传/生成、`node_errors` 透传、超时、断连、响应大小上限、取消监听器清理、本地路径白名单、图片签名、工具生命周期与 Bundle manifest。

## 已知问题与边界

- `comfyui_output_list` 的 `directory` 模式需要配置 `outputDir`；未配置时 `auto` 回退到 `history` 模式（读 ComfyUI 服务端历史，跨机器也可用）。
- `comfyui_upload_image` 默认拒绝本地路径；必须先配置 `allowedUploadRoots`。插件使用规范化后的真实路径检查目录边界，并拒绝伪装扩展名、超限文件和 `..` 子目录。
- 图片内联返回遵循 DSH 附件机制（attachment ref），模型为纯文本时只看到附件元信息，不消耗图片 token。
- 本插件只读/控制本机 ComfyUI；请勿将 `baseUrl` 指到不受信任的远程实例。