ComfyUI 智能体桥 hallozyf/comfyui-agent-bridge

ComfyUI Agent Bridge

DSH-only plugin / 为 DSH 打造的插件

这个节点专为 DSH (DeepSeek Harness) 编写——一个桌面智能体运行时，靠 LLM 工具循环驱动 ComfyUI。它的端点形态（/agent/txt2img → prompt_id → /agent/result/{id}）、预设默认值、自动选择加载器、错误消息，全都假定由智能体来驱动，而不是人点画布。安装方式和普通自定义节点一样，但请把它当作 DSH 侧的集成来用：dsh/ 输出子目录、自动挑选模型、「一次调用进、图片出」的约定，都不是为交互式使用设计的。

技术上它并不锁定 DSH——任何 HTTP 客户端（curl、Python、别的智能体框架）都能调用同样的端点——但 DSH 是它唯一构建并验证过的环境。如果你在找 GUI 侧的辅助节点，那它不是。

中文说明见文末「关于 DSH」一节。

面向智能体的 REST 端点，为 ComfyUI 而做，打包成普通自定义节点。文生图变成一次 HTTP 调用，不用再手工拼 API 格式的提示词图。

curl -X POST http://127.0.0.1:8188/agent/txt2img \
-H "Content-Type: application/json" \
-d '{"preset":"sdxl","params":{"prompt":"a red fox in a snowy forest, golden hour"}}'
-> {"prompt_id":"...","seed":123456,"workflow":{...}}

curl http://127.0.0.1:8188/agent/result/<prompt_id>
-> {"state":"done","images":[{"filename":"agent_00001_.png","subfolder":"dsh/sdxl","type":"output"}]}

不用 pip 依赖，不加额外进程，不占额外端口。
* 按你实际装了什么，挑对应的加载器节点（CheckpointLoaderSimple / UNETLoader / UnetLoaderGGUF + DualCLIPLoader(GGUF)）。
* 入队前先拿实时节点注册表校验图，所以控件改名后会直接报 node 'DualCLIPLoader' requires inputs not provided: ['device']，而不是过一会儿冒出一个莫名其妙的 400。
* 补上一个真实缺口：现在的 ComfyUI-GGUF 构建不再向 folder_paths 注册 .gguf，量化模型因此从节点下拉框里消失。这个节点会在启动时和每次请求时注册它（并清掉文件列表缓存）。

为什么不用 MCP 服务器？

智能体本来就会说 MCP 时，MCP 很好用。但对普通脚本 / LLM 工具循环来说，它多一个进程、多一套协议、多一处故障面，却没多出任何能力——有用的部分始终是同一件事： POST /prompt，然后等，然后 /view。这个节点就在服务端把这件事包好，那里能拿到节点注册表。如果你确实想要 MCP，用你选的服务器把这俩端点包一层，大约 30 行。

安装

cd ComfyUI/custom_nodes
git clone https://github.com/hallozyf/comfyui-agent-bridge
restart ComfyUI

没有要 pip install 的东西。要求：

| ComfyUI | 任意较新版本（在 0.42.0 上测试过） |
| Python | 3.10+（在 3.14 上测试过） |
| 可选 | ComfyUI-GGUF，用于 .gguf 预设 |

检查是否加载成功：curl http://127.0.0.1:8188/agent/health

{
"ok": true, "bridge": "comfyui-agent-bridge", "version": "1.2.0",
"torch": "2.9.1+cu128", "cuda_available": true,
"gpu": {"name": "NVIDIA GeForce RTX 5060 Laptop GPU", "capability": "12.0",
"vram_total_gb": 7.93, "vram_free_gb": 6.82},
"gguf_nodes": ["UnetLoaderGGUF", "DualCLIPLoaderGGUF"],
"gguf_extension_registered": true,
"presets": ["sd15", "sdxl", "flux"]
}

API

| 方法 | 路径 | 请求体 / 查询参数 | 返回 |
| GET | /agent/health | — | 设备、VRAM、torch、预设、GGUF 状态 |
| GET | /agent/models | — | {checkpoints: [...], diffusion_models: [...], vae: [...], text_encoders: [...]} |
| POST | /agent/workflow | {preset, params} | {prompt: <API graph>} — 只构建，不入队 |
| POST | /agent/txt2img | {preset, params} | {prompt_id, number, preset, seed, workflow} |
| GET | /agent/result/{prompt_id} | — | {state: pending\|done\|error, images, messages} |
| POST | /agent/free | {} | 卸载模型，释放 VRAM |

/dsh/... 是每条路由的别名，老脚本照常能用。

params

| 键 | 默认值 | 说明 |
| prompt | 内置示例 | 实际使用中必填 |
| negative | 质量类负面提示词（sd15/sdxl） | flux 忽略此项（改用 FluxGuidance） |
| width / height | 512×512 sd15，1024×1024 sdxl/flux | Flux 用 EmptySD3LatentImage |
| steps | 30 sd15，28 sdxl，20 flux | |
| cfg | 7.0 sd15，6.5 sdxl，1.0 flux | flux 要求 1.0 |
| guidance | 3.5 | 仅 flux（FluxGuidance） |
| sampler_name / scheduler | dpmpp_2m/karras，flux：euler/simple | |
| seed | 随机 | 响应里会返回，方便复现同一次运行 |
| batch_size | 1 | |
| ckpt_name | 自动 | 把文件放进 models/checkpoints，显式传入即可覆盖 |
| unet_name | 自动 | models/diffusion_models/.safetensors |
| unet_gguf | 自动 | models/diffusion_models/.gguf |
| vae_name / t5_name / clip_l_name | 自动 | |
| filename_prefix | dsh/<preset> | 每次请求追加一个 uuid |

自动选择

flux 预设按顺序检查下面几项，用第一个可用的：

1. 传了 unet_name → UNETLoader（+ DualCLIPLoader、VAELoader）
2. 存在 .gguf（或传了 unet_gguf）→ UnetLoaderGGUF（+ DualCLIPLoaderGGUF）
3. 否则用 flux1* checkpoint → CheckpointLoaderSimple

如果 T5 编码器是 .gguf，会自动决定用 DualCLIPLoaderGGUF 还是 DualCLIPLoader。同一个 GGUF 双加载器里混用 clip_l.safetensors + t5.gguf 没问题。

示例

examples/ 里有两个 API 格式的计算图，可以直接 POST 到 ComfyUI 自己的 /prompt（不需要 bridge），也可以把同样的节点 id 传给 --set 覆盖：

SDXL, plain checkpoint
curl -X POST http://127.0.0.1:8188/prompt \
-H "Content-Type: application/json" \
-d @examples/sdxl.api.json

独立客户端

client/comfy_agent.py 是不依赖第三方库的命令行工具（只用标准库），对接下面这些端点，shell 或智能体一条命令就能出图并保存 PNG：

python client/comfy_agent.py status
python client/comfy_agent.py models
python client/comfy_agent.py gen --preset flux --prompt "a fox in snow" --out out.png
python client/comfy_agent.py gen --preset sdxl --ckpt "juggernaut_fp8.safetensors" --steps 30 --out out.png
python client/comfy_agent.py free

小显存提示

桥接层本身不占内存，但 ComfyUI 的默认设置对小显存显卡不友好。在 8 GB / 16 GB 的机器上跑 SDXL 和 Flux，需要加这些参数：

python main.py --reserve-vram 0.6 --cache-none --disable-pinned-memory

--disable-pinned-memory 最关键：默认会锁住几 GB 系统内存，在 16 GB 机器上就会变成 DefaultCPUAllocator: not enough memory。--normalvram 已经不存在了，--highvram 会让 8 GB 显卡 OOM。

兼容性

端到端测试过的环境：Windows 11、ComfyUI 0.42.0、Python 3.14、torch 2.9.1+cu128、RTX 5060 Laptop（8 GB），模型覆盖 SD1.5 / SDXL / SDXL fp8 / FLUX.1-dev Q4 / FLUX.1-schnell Q4。代码里没有任何 Windows 专属逻辑；节点图构建器只读 ComfyUI 自己的注册表，所以跟着已安装的版本走，不预设某个版本。

许可证

MIT —— 见 LICENSE。

中文说明

关于 DSH（重要）

这个插件是给 DSH（DeepSeek Harness）专用的，不是通用 ComfyUI 插件：

- 它是在 DSH 里写出来并验证的，接口形状（一次提交拿 prompt_id、再轮询 result）就是按 LLM 工具循环设计的，目的是让智能体少绕弯路；
- 默认值、模型自动选型、报错文案都按「智能体在驱动」而不是「人在点界面」来设计（比如自动挑 GGUF 还是 safetensors、自动补 filename_prefix、错误直接告诉缺哪个节点）；
- 出图默认落在 dsh/<preset> 子目录，这是 DSH 会话的归档约定。

它不锁定 DSH：任何 HTTP 客户端（curl / Python / 别的 agent 框架）都能直接调同样接口；但 DSH 是唯一经过完整验证的环境。如果你要的是「在界面上点着用」的节点，这个不是。

这是什么

把「让智能体驱动 ComfyUI 出图」收敛成几次 HTTP 调用：插件挂在 ComfyUI 自己的 web 服务上，自动根据你装了哪些加载器节点（普通 safetensors / GGUF / 单体 checkpoint）拼好工作流，不用外部脚本手写 API 格式的节点图。

安装

cd ComfyUI/custom_nodes
git clone https://github.com/hallozyf/comfyui-agent-bridge
重启 ComfyUI

无需 pip install，无需额外进程和端口。要跑 FLUX 量化模型请另外装 ComfyUI-GGUF。

用法

健康检查（显卡、显存、可用预设、GGUF 是否就绪）
curl http://127.0.0.1:8188/agent/health

出图（sdxl / sd15 / flux 三种预设）
curl -X POST http://127.0.0.1:8188/agent/txt2img -H "Content-Type: application/json" \
-d '{"preset":"flux","params":{"prompt":"a red fox in a snowy forest","steps":4}}'

拿结果（pending / done / error）
curl http://127.0.0.1:8188/agent/result/<prompt_id>

取图
curl "http://127.0.0.1:8188/view?filename=<filename>&subfolder=<subfolder>&type=output" -o out.png

配套的命令行客户端在 client/comfy_agent.py，只用标准库：

python client/comfy_agent.py gen --preset flux --prompt "雪地里的红狐" --out out.png

顺手修的一个坑

当前 ComfyUI-GGUF 不再把 .gguf 注册进 folder_paths.supported_pt_extensions，导致 GGUF 模型在节点下拉框和 get_filename_list() 里根本看不见。本插件在启动时和每次请求时补注册并清缓存，所以量化模型在下拉框里正常可见。

小显存提示

插件本身不占显存，但 ComfyUI 默认参数对小显存显卡不友好。8GB 显存 / 16GB 内存建议：

python main.py --reserve-vram 0.6 --cache-none --disable-pinned-memory

--disable-pinned-memory 最关键：默认会预留数 GB 的内存缓冲，16GB 机器上会直接报 DefaultCPUAllocator: not enough memory。