dsh-tool-comfyui

在 dsh 里一句话出图 —— 装完这个插件，你的 Agent 就能直接调用本机 / 局域网的 ComfyUI 机队生成图片，不用切窗口、不用手搓 API 请求。

给 DeepSeek Harness 用的自建工具插件：在 dsh 里一句话直接调用本机/局域网的 ComfyUI 机队 出图。

Compatibility: built and tested against dsh 0.2.0-rc.2 (preview). The apply(ctx) plugin spec is stable; verify against your own dsh version if newer.

一行安装

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

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

安装

dsh plugin --profile desktop add github:yuehancn/dsh-tool-comfyui
# or, if published to npm:
# dsh plugin --profile desktop add dsh-tool-comfyui

Replace desktop with your own profile name. After install, restart the profile — the three tools appear immediately.

手动安装（本机开发用）

展开：不走 CLI 的手工装法

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"

它做什么

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

工具	作用
`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 节点会直接报错并提示你去给节点起名。

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

在 ComfyUI 里搭好图 → 「导出（API 格式）」
把 CLIPTextEncode 的 _meta.title 改成 prompt / negative
存成 workflows/scene.json
直接调 comfyui_generate(prompt="...", workflow="scene")

实测数据

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

场景	耗时
单张	~15.1 s
批量 2 张	~16.7 s（摊薄后 8.4 s/张）

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

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

comfyui-output/2026-10-01T23-30-12-local5090/
  └─ dsh_comfyui_00001_.png   1024×1024  ← 白底咖啡杯，可直接用作商品主图

本仓库不内嵌截图；实跑输出保存在你的 outputDir 下，每次调用都会生成带时间戳的子目录。

故障排查

症状	原因 / 解法
`comfyui_status` 全部 offline	ComfyUI 没起，或素材机没加 `lan` 参数（只听 127.0.0.1）
出图极慢（几分钟一张）	素材机在挖矿（`pminer.exe` 占满 GPU）。用 `start-comfyui-worker.bat` 启动，它会先停矿
`unknown workflow "xxx"`	模板文件名与 `workflow` 参数不符；错误信息里会列出全部可用模板
`unknown worker "xxx"`	worker id 拼错；错误信息里会列出配置里的全部 id
找不到 prompt 节点	模板里 `CLIPTextEncode` 的 `_meta.title` 没改成 `prompt` / `negative`
局域网机器连不上	⚠️ 先测 TCP 端口，别 ping —— 本机 OpenVPN 场景下 ICMP 常不通

开发笔记（踩过的坑）

parameters 是扁平属性表，不是 JSON Schema 包装对象。 defineTool({ parameters: { prompt: {type:"string", required:true} } })，由 parameterSchemaSpecToJsonSchema 编译成 {type:"object", properties, required}。直接塞 {type:"object", properties:{...}} 会被当成一个叫 type、properties 的参数，模型侧完全不可用。
Config 用 z.object({...})，必填项写 .required()，可选项写 .default(...)。
bundle 补丁只能用 insert: 加新行。 直接写 - id: xxx 会被报 patch: entry "xxx" not found —— 因为补丁是按 id 改现有行的，新行必须放进 insert: 数组。
插件包本身不要带 node_modules。 dsh 的 desktop profile node_modules 只是 局部 overlay，@deepseek-ai/cordis 等包只在 app.asar 里；运行时由 dsh 自己兜底解析。给插件塞一份 node_modules 反而会在 Windows junction 的 realpath 语义下解析到错的地方。
package.json 要有 dsh.bundle.patch 指向自己的 cordis.patch.yml，否则 dsh 不认这是个 bundle。

许可

MIT

dsh-tool-comfyui

在 dsh 里一句话出图 —— 装完这个插件，你的 Agent 就能直接调用本机 / 局域网的 ComfyUI 机队生成图片，不用切窗口、不用手搓 API 请求。

给 DeepSeek Harness 用的自建工具插件：在 dsh 里一句话直接调用本机/局域网的 ComfyUI 机队 出图。

Compatibility: built and tested against dsh 0.2.0-rc.2 (preview). The apply(ctx) plugin spec is stable; verify against your own dsh version if newer.

一行安装

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

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

安装

dsh plugin --profile desktop add github:yuehancn/dsh-tool-comfyui
# or, if published to npm:
# dsh plugin --profile desktop add dsh-tool-comfyui

Replace desktop with your own profile name. After install, restart the profile — the three tools appear immediately.

手动安装（本机开发用）

展开：不走 CLI 的手工装法

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"

它做什么

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

工具	作用
`comfyui_status`	探测全机队：谁在线、ComfyUI 版本、显卡型号/显存、队列深度；顺带列出可用工作流模板
`comfyui_generate`	按命名工作流模板出图：提交 prompt → 等 GPU 跑完 → 把成图下载到本地，返回文件路径
`comfyui_queue`	查某台机器的运行/排队情况，或一键中断+清空队列

实测：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 节点会直接报错并提示你去给节点起名。

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

在 ComfyUI 里搭好图 → 「导出（API 格式）」
把 CLIPTextEncode 的 _meta.title 改成 prompt / negative
存成 workflows/scene.json
直接调 comfyui_generate(prompt="...", workflow="scene")

实测数据

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

场景	耗时
单张	~15.1 s
批量 2 张	~16.7 s（摊薄后 8.4 s/张）

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

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

comfyui-output/2026-10-01T23-30-12-local5090/
  └─ dsh_comfyui_00001_.png   1024×1024  ← 白底咖啡杯，可直接用作商品主图

本仓库不内嵌截图；实跑输出保存在你的 outputDir 下，每次调用都会生成带时间戳的子目录。

故障排查

症状	原因 / 解法
`comfyui_status` 全部 offline	ComfyUI 没起，或素材机没加 `lan` 参数（只听 127.0.0.1）
出图极慢（几分钟一张）	素材机在挖矿（`pminer.exe` 占满 GPU）。用 `start-comfyui-worker.bat` 启动，它会先停矿
`unknown workflow "xxx"`	模板文件名与 `workflow` 参数不符；错误信息里会列出全部可用模板
`unknown worker "xxx"`	worker id 拼错；错误信息里会列出配置里的全部 id
找不到 prompt 节点	模板里 `CLIPTextEncode` 的 `_meta.title` 没改成 `prompt` / `negative`
局域网机器连不上	⚠️ 先测 TCP 端口，别 ping —— 本机 OpenVPN 场景下 ICMP 常不通

开发笔记（踩过的坑）

parameters 是扁平属性表，不是 JSON Schema 包装对象。 defineTool({ parameters: { prompt: {type:"string", required:true} } })，由 parameterSchemaSpecToJsonSchema 编译成 {type:"object", properties, required}。直接塞 {type:"object", properties:{...}} 会被当成一个叫 type、properties 的参数，模型侧完全不可用。
Config 用 z.object({...})，必填项写 .required()，可选项写 .default(...)。
bundle 补丁只能用 insert: 加新行。 直接写 - id: xxx 会被报 patch: entry "xxx" not found —— 因为补丁是按 id 改现有行的，新行必须放进 insert: 数组。
插件包本身不要带 node_modules。 dsh 的 desktop profile node_modules 只是 局部 overlay，@deepseek-ai/cordis 等包只在 app.asar 里；运行时由 dsh 自己兜底解析。给插件塞一份 node_modules 反而会在 Windows junction 的 realpath 语义下解析到错的地方。
package.json 要有 dsh.bundle.patch 指向自己的 cordis.patch.yml，否则 dsh 不认这是个 bundle。

许可

MIT

yuehancn/dsh-tool-comfyui

dsh-tool-comfyui

一行安装

安装

手动安装（本机开发用）

它做什么

🔐 权限与隐私

用法

配置机队

素材机上跑 ComfyUI

配置项

工作流模板

实测数据

故障排查

开发笔记（踩过的坑）

许可

Community comments

yuehancn/dsh-tool-comfyui

dsh-tool-comfyui

一行安装

安装

手动安装（本机开发用）

它做什么

🔐 权限与隐私

用法

配置机队

素材机上跑 ComfyUI

配置项

工作流模板

实测数据

故障排查

开发笔记（踩过的坑）

许可

Community comments