dsh-comfyui-ctl

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

从 0.3.0 起，一次插件加载可管理多个具名实例。各实例独立配置地址、输出目录和上传白名单，工具使用 instance_id 选择目标；旧单实例配置继续兼容。

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

架构

src/
  client.js       ComfyClient —— 零依赖的 ComfyUI HTTP API 客户端（可独立复用）
  index.js        DSH 插件入口：name / inject / Config / apply()，注册 12 个工具
  instances.js    具名实例配置、客户端及节点缓存隔离、默认实例路由
  safety.js       本地上传白名单、文件大小、图片签名与虚拟路径校验
  mock-server.mjs 测试用模拟 ComfyUI（内存画布、历史、模型清单、/prompt 提交）
  test.mjs        客户端单元测试（含超时、断连、大小上限、取消与 node_errors）
  test-safety.mjs 本地上传安全边界测试
  test-apply.mjs  插件 apply() 离线注册测试（不连真实 ComfyUI）
  test-instances.mjs 双 HTTP 模拟服务上的插件级多实例隔离测试
  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'

上述旧配置等价于一个 ID 为 default 的实例，现有工具调用不必修改。

多设备配置示例：

- id: comfyui-ctl
  config:
    defaultInstanceId: local
    instances:
      - id: local
        baseUrl: 'http://127.0.0.1:8188'
        outputDir: 'C:\path\to\ComfyUI\output'
        allowedUploadRoots:
          - 'C:\Users\your-name\Pictures'
      - id: gpu-server
        baseUrl: 'http://192.168.1.20:8188'
        allowedUploadRoots:
          - 'C:\Users\your-name\Pictures'

instances 非空时，以这个列表为完整实例配置：旧的顶层 baseUrl、outputDir 和 allowedUploadRoots 不会继承到任何实例，防止远程实例意外读取本地输出或获得额外上传权限。超时、轮询、大小上限和内联图片数量仍由顶层配置共同控制。

实例 id 必须唯一、非空且不含空白或控制字符。未配置 defaultInstanceId 时使用列表中的第一个实例；显式配置的默认 ID 必须存在。工具省略 instance_id 时使用默认实例，未知 ID 会在发出请求前报错，不会自动转发到其他设备。comfyui_instances_list 可查看实例 ID、地址、默认实例和输出来源，即使服务器离线也能调用。

远程 ComfyUI 必须已运行并监听 DSH 可访问的可信内网或 VPN 地址。outputDir 和 allowedUploadRoots 都是 DSH 进程所在机器可访问的路径；不能把远程机器的磁盘路径直接当作本地路径。远程实例通常不设置 outputDir，通过 history 模式列出产出，再通过 HTTP /view 取图。多个 ID 若指向同一个 ComfyUI 服务，仍共享该服务的实际队列。

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

配置项（Config）

键	默认值	说明
`instances`	`[]`	具名实例数组；每项包含 `id`、必填 `baseUrl`、可选 `outputDir` 和默认空数组的 `allowedUploadRoots`
`defaultInstanceId`	第一个实例 / 旧配置的 `default`	省略工具 `instance_id` 时的目标
`baseUrl`	`http://127.0.0.1:8188`	旧单实例服务地址；具名实例使用各自的地址。地址须为 HTTP/S，不含凭据、查询或片段
`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`	（空）	旧单实例输出目录；具名实例分别配置。目录须为绝对路径并可由 DSH 读取

工具清单

原有 11 个工具均新增可选 instance_id，返回值顶层和展示文本标明目标实例。队列条目、历史条目和产出文件引用也携带实例 ID；后续查询或取图应沿用这个 ID，避免同名文件或相同 prompt_id 混淆。图片附件仍使用标准 DSH 元数据格式。

工具	能力	关键参数
`comfyui_instances_list`	列出已配置实例和默认目标，不连接服务	—
`comfyui_queue_get`	查看运行中与待执行队列	—
`comfyui_interrupt`	中断当前生成	—
`comfyui_queue_delete`	清空队列或删除指定待执行项	`clear`、`prompt_ids`
`comfyui_history_get`	查询历史（可带 prompt id）	`prompt_id`、`max_items`
`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": {} }
  },
  "instance_id": "gpu-server",
  "wait": true,
  "timeout_ms": 300000,
  "inline_images": true
}

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

多设备同时生成

DSH 会串行调度当前的生成工具。要让不同设备同时工作，先分别向各实例提交 wait: false，不要等待第一台完成后再提交第二台：

调用 comfyui_generate，参数为 instance_id: local、wait: false 和完整 API 工作流 A。
调用 comfyui_generate，参数为 instance_id: gpu-server、wait: false 和完整 API 工作流 B。
分别记录返回的 instance_id 和 prompt_id，两台 ComfyUI 可独立推进自己的队列。
使用同一对 ID 调用 comfyui_history_get，再按文件信息调用 comfyui_output_get。

提交与查询请求仍遵守各实例的超时和大小上限。超时或取消等待不会自动停止服务器任务；需要停止生成时，显式调用该实例的 comfyui_interrupt。这个工具中断所选服务当前正在执行的任务，清队列也作用于所选服务的待执行队列。

第一版不自动选设备、重试提交或负载均衡，离线实例的请求报错不会改投其他实例。服务器节点和模型可能不同，提交的工作流必须适合所选设备。

验证状态

0.3.0 使用两个独立 HTTP 模拟服务验证插件工具的实例路由、节点缓存、目录/上传白名单、队列操作和离线/超时/取消隔离；任务 ID 和文件名故意相同，媒体内容和服务器清单不同。自动测试不等同于真实多设备 GPU 或完整 DSH Web 端到端验收。

以下为 0.2.0 的历史单实例真机验证记录（ComfyUI 0.33.1 / RTX 5070 Ti Laptop），不代表 0.3.0 多设备实测：

工具	状态
`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。
仅配置可信的本地、内网或 VPN 实例。插件不提供远程进程启动、系统管理或服务端认证配置；baseUrl 不能嵌入用户名/密码。