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