liyi3068238601-oss/dsh-comfyui-ctl

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：

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 覆盖配置：

- 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：

{
"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） |

开发与测试

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 指到不受信任的远程实例。