dsh-tool-comfyui

dsh plugin --profile web add dsh-tool-comfyui

dsh-tool-comfyui


在 dsh 里一句话出图 —— 装完这个插件，你的 Agent 就能直接调用本机 /

局域网的 ComfyUI 机队生成图片，不用切窗口、不用手搓 API 请求。

npm 包名：dsh-tool-comfyui ｜ 给 DeepSeek Harness 用的工具插件，

在 dsh 里一句话直接调用本机/局域网的 ComfyUI 机队 出图。

以上两张是本机 RTX 5090D + SDXL 通过本插件真实生成的产物，非示意图。

Compatibility: built and tested against dsh 0.2.0-rc.2 (preview).

声明见 package.json 顶层 engines.dsh（>=0.2.0-rc.2）。

The apply(ctx) plugin spec is stable; verify against your own dsh version if newer.

---

一行安装

从 npm 装（推荐，也是 DSH 内置插件市场能一键装的唯一形式）：

dsh plugin --profile web add dsh-tool-comfyui
# 桌面版把 web 换成 desktop
dsh plugin --profile desktop add dsh-tool-comfyui

从 GitHub 源码装（未发 npm 时可用，功能相同但不会出现在 DSH 内置市场）：

dsh plugin --profile desktop add github:yuehancn/dsh-tool-comfyui

支持的 profile：web / desktop（桌面版）。装完重启 dsh 即可用。

手动安装（本机开发用）

<details>

<summary>展开：不走 CLI 的手工装法</summary>

1. 插件位置

C:\Users\<你>\.dsh\plugins\dsh-tool-comfyui\
├─ lib\index.js            插件实现（三个工具全在这）
├─ workflows\txt2img.json  SDXL 文生图模板
├─ cordis.patch.yml        bundle 补丁：把插件行插进 profile
├─ start-comfyui-worker.bat  素材机上的 ComfyUI 启动器（GBK+CRLF）
└─ package.json

2. 让 profile 认识它

%USERPROFILE%\.dsh\profiles\desktop\package.json：

{
  "dependencies": {
    "dsh-tool-comfyui": "link:C:/Users/<你>/.dsh/plugins/dsh-tool-comfyui"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-tool-comfyui"
      ]
    }
  }
}

bundles 里必须列出包名，dsh 才会去读它的 dsh.bundle.patch。

只在 dependencies 里出现是不够的 —— 那不叫启用。

3. 在 profile 的 node_modules 建链接

mklink /J "%USERPROFILE%\.dsh\profiles\desktop\node_modules\dsh-tool-comfyui" ^
          "%USERPROFILE%\.dsh\plugins\dsh-tool-comfyui"

</details>

---

它做什么

注册三个模型可调用的工具：

工具 · 作用

comfyui_status · 探测全机队：谁在线、ComfyUI 版本、显卡型号/显存、队列深度；顺带列出可用工作流模板

comfyui_generate · 按命名工作流模板出图：提交 prompt → 等 GPU 跑完 → 把成图下载到本地，返回文件路径

comfyui_queue · 查某台机器的运行/排队情况，或一键中断+清空队列

关键点：轮询是它存在的理由。 ComfyUI 出图是两段式协议（POST /prompt 拿

prompt_id，再轮询 /history/<id> 直到出图）。裸 web_fetch 做不到「提交后等待」，

所以必须写成插件。

实测：RTX 5090D 上 SDXL 1024×1024 三十步，单张约 15.1 秒，

批量两张约 16.7 秒；同 seed 两次输出字节完全一致。

见下方[实测数据](#实测数据)一节。

---

🔐 权限与隐私

这是理解本插件安全边界最重要的一节。

项目 · 说明

网络访问 · 仅访问你在配置文件里 workers[].url 指定的地址。默认只连 127.0.0.1:8188 和你的局域网机器。不访问任何第三方服务

凭据 · 不需要任何 API key。ComfyUI 默认无鉴权；本插件不读取、不存储、不传输任何凭据

数据外发 · 无。prompt 发给你的 ComfyUI，成图下载到你的 outputDir。插件本身没有任何遥测

文件写入 · 只写 outputDir（默认 comfyui-output），每次调用生成一个子目录

进程启动 · 插件本身不启动任何进程。仓库里的 start-comfyui-worker.bat 是给你手动双击的素材机启动脚本，不会被插件自动执行

生命周期脚本 · 无 preinstall / postinstall / prepare。安装时不会跑任何代码

运行时依赖 · 仅 @deepseek-ai/schemastery（配置校验）。其余为 peer，由 dsh 提供

⚠️ comfyui_queue 的 cancelAll 参数会中断并清空目标机器的队列。这是破坏性操作，

只在你明确要求时使用。

---

用法

装好并在 profile 里启用后，在 dsh 对话里直接说人话即可：

帮我出一张白底咖啡杯的电商图
→ 调 comfyui_generate(prompt="a white ceramic mug on pure white background, e-commerce catalog photo")

先看看素材机活着没
→ 调 comfyui_status

把 109 上排队的任务清掉
→ 调 comfyui_queue(worker="spark5060", cancelAll=true)

---

配置机队

在 profile 的 cordis.patch.yml 覆盖插件行：

- id: tool-comfyui
  config:
    workers:
      - id: local5090
        url: http://127.0.0.1:8188
        label: RTX 5090D 主力机
      - id: spark5060
        url: http://192.168.11.109:8188
        label: 5060 Ti 素材机 A
    workflowsDir: <插件目录>/workflows
    outputDir: C:/Users/<你>/Pictures/comfyui
    defaultWorkflow: txt2img
    maxBatchSize: 8
    timeoutMs: 900000

加机器 = 往 workers 追加一项。

---

素材机上跑 ComfyUI

把 start-comfyui-worker.bat 拷到素材机，双击：

start-comfyui-worker.bat          :: 只听 127.0.0.1
start-comfyui-worker.bat 8188 lan :: 听 0.0.0.0，允许本机 dsh 跨机调用

脚本会先 taskkill /F /IM pminer.exe 停矿（否则 GPU 满载，出图极慢）。

---

配置项

键 · 默认 · 说明

workers[] · 必填 · 机队。每项 {id, url, label?, timeoutMs?}

workflowsDir · workflows · 命名工作流模板目录（<名字>.json → 模板名）

defaultWorkflow · txt2img · 不传 workflow 时用哪个

timeoutMs · 600000 · 单次调用的协作超时预算

pollIntervalMs · 2000 · 轮询 /history 的间隔

outputDir · comfyui-output · 成图落地目录

generate / status / queue · true · 分别开关三个工具

maxBatchSize · 8 · 单次最多出几张

---

工作流模板

模板是 ComfyUI API 格式的图（不是 UI 格式），存在 workflows/ 下，

文件名即模板名。

插件按 _meta.title 约定注入参数：

节点 title 命中 · 注入

prompt / positive / 提示词 · args.prompt

negative / 负面 · args.negativePrompt

seed / noise_seed / 随机种子 · args.seed

任意带 batch_size 的节点 · args.batchSize

只覆盖字面量输入；被连线（link）的输入绝不碰，所以不会把

CLIP 文本节点接错。找不到 prompt 节点会直接报错并提示你去给节点起名。

加一个新模板（比如电商场景图）：

1. 在 ComfyUI 里搭好图 → 「导出（API 格式）」

2. 把 CLIPTextEncode 的 _meta.title 改成 prompt / negative

3. 存成 workflows/scene.json

4. 直接调 comfyui_generate(prompt="...", workflow="scene")

---

实测数据

在 RTX 5090D 主力机上、SDXL base 1.0、1024×1024、30 步：

场景 · 耗时

单张（冷启动首次） · ~15.1 s

单张（模型已驻留） · ~8.0 s

批量 2 张 · ~16.7 s（摊薄后 8.4 s/张）

同 seed 两次输出字节完全一致（可复现）。

数字取自本机实跑：2026-10-19 复测两张，分别为 28.2 s（含模型加载）与 8.0 s（驻留后）。

README 顶部的两张截图正是这两次调用的原始输出。

产出示例（本机实跑，白底电商图）：

comfyui-output/2026-10-19T01-57-02-local5090/
  └─ dsh_comfyui_00001_.png   1024×1024  ← 白底咖啡杯，可直接用作商品主图

截图原件在 docs/ 下（screenshot-1.jpg / screenshot-2.jpg）；实跑输出保存在你的

outputDir 下，每次调用都会生成带时间戳的子目录。

---

故障排查

症状 · 原因 / 解法

comfyui_status 全部 offline · ComfyUI 没起，或素材机没加 lan 参数（只听 127.0.0.1）

出图极慢（几分钟一张） · 素材机在挖矿（pminer.exe 占满 GPU）。用 start-comfyui-worker.bat 启动，它会先停矿

`unkn

…(truncated)