ComfyUI 本地绘图 QXingYShu/dsh-comfyui-image

dsh-comfyui-image

用本地 ComfyUI 从 DeepSeek Harness 生成图像、视频、音频和 3D 资产——不需要 API key，不依赖云，不按张计费。智能体挑模型、写提示词、把工作流排到你自己的 GPU 上，拿回一个真实文件。

开箱即用的有两块。第一块是两个手工调好的文生图工作流：

| 工作流 | 擅长 | 速度 | 负面提示词 |
| Z-Image-Turbo | 草稿、批量、快速迭代 | 秒级 | 无（CFG 1，只吃提示词） |
| Qwen-Image-2.1 | 成品资产、图内文字清晰、构图精确 | 几十秒 | 有 |

第二块是其余全部：ComfyUI 自带 116 个工作流模板，覆盖 67 个开放权重模型家族——图像编辑、视频生成、ControlNet 与姿态控制、深度估计、抠背景、放大、3D、音乐与音频。这个插件让智能体可以驱动其中任何一个。

注册了什么

- comfyui_generate —— 文生图，进一个提示词，出一组调好的参数。
- comfyui_templates —— 浏览本机模板目录，查看某个模板的输入，或问哪个模型适合某类任务（recommend=true）。
- comfyui_run_template —— 跑一个模板并保存输出。
- comfyui_status —— 报告装了什么、什么已就绪。生成失败时很有用。
- 技能 comfyui-image —— 模型选择、提示词写法、采样器调参和负面提示词支持，让智能体有依据地做选择。

模板目录

ComfyUI 把模板存成浏览器图：画布坐标、链接对象，真正的图还包在子图里。/prompt 这些一概不收——它要 API 形式。服务端没有转换路径；转换只存在于前端的 JavaScript 里。

lib/blueprint.js 就是那个转换。它每一部分都对应一个真实 bug：

- 拆子图，因为模板顶层节点类型是个 UUID
- 对齐 widget，因为 widgets_values 只按位置对应 widget 输入，而带种子的 widget 后面还跟着它的 control-after-generate 设置——对错了，后面每个值都会落到错误的输入上
- 依赖顺序，因为画布按创建顺序存节点，照文件顺序转换会丢掉必需输入，ComfyUI 却去怪几步之外的一个节点
- Reroute 是夹板，不是装饰：去掉它，它后面所有链接全断
- 被旁路的节点根本不在提交的图里。没人消费它的输出时，它直接丢掉；有人消费时，消费者被改接到上游输出，而这个改接要过类型检查——一个被旁路的 PreviewAny 可能正带着两个通配跳之外来的 STRING，接到第一个通配就会把非字符串塞给 CLIPTextEncode.text
- 模板默认值挂在暴露输入所喂的那个节点上，不在顶层
- 模板不带 SaveImage，而执行器只持久化 OUTPUT_NODE 结果，所以会追加一个无冲突的 id

全部 348 个模板文件都能干净转换，覆盖 67 个模型家族。之后跳过的 117 个不是转换失败——它们根本不驱动任何采样器（调色、裁剪、加字幕），没有东西可渲染。

模板能否真正运行是另一个问题，答案来自转换后的计算图，而不是模板的模型清单——清单会列出模板可能用到的每个模型，因为可选 ControlNet 拒绝一次运行，和漏掉必需模型一样错。权重不在本机的模板会在到达执行器之前被拒绝，并列出缺失的文件，而不是返回一个看不懂的 HTTP 400。

下载走镜像

模型权重默认来自 hf-mirror.com。有意思的不是插件打印的 URL——而是 ComfyUI 进程启动时设置了 HF_ENDPOINT，因为 huggingface_hub 在导入时读取这个变量，并从此改写它构建的每个 URL。没有它，插件可以给你一个镜像链接，而你手动安装任何东西时 ComfyUI 仍然会爬向 huggingface.co。

直连源可达时覆盖它：

DSH_HF_ENDPOINT=https://huggingface.co # or just set HF_ENDPOINT

HF_HUB_ENABLE_HF_TRANSFER 故意保持关闭：它会选择一个镜像不提供的 Rust 下载器，所以打开它会把慢下载变成失败下载。

插件仍然不会主动下载任何东西。它报告文件、大小、许可证和剩余空间，只有在你读完报告后传入 download=true 时才获取。

知识层

能力不是难点——知道如何驱动模型才是。目录提供每个模板的默认值，但不提供推理，所以 lib/model-knowledge.js 记录每个家族需要什么：采样器范围、负面提示词支持、文本渲染可靠性，以及提示词提示。

每个值都从本地蓝图读回，而不是凭记忆写入，任何未经验证的内容都标记为未验证。

推理能抓住静默失败的东西。Z-Image-Turbo 把采样器的负面槽接到一个将其归零的节点，所以负面提示词会产生字节完全相同的图像，而不是报错。不知道这一点的智能体会「优化」提示词，结果什么都没改变。

要求

- Comfy Desktop 并安装模型模板（它自带「Z-image」和「Qwen-Image-2.1」模板），或者任何磁盘上有模型权重的 ComfyUI 检出。
- DeepSeek Harness 0.2.0-rc.2 或更新版本。
- 没有 npm 依赖。插件通过自己的 HTTP API 与 ComfyUI 通信。

你不需要 ComfyUI 正在运行。插件在首次使用时以无头模式启动它，之后复用。

安装

dsh plugin --profile desktop add https://github.com/<you>/dsh-comfyui-image.git
或者从克隆开始：

git clone https://github.com/<you>/dsh-comfyui-image.git
dsh plugin --profile desktop add ./dsh-comfyui-image

重启 Harness，然后让它生成图片。

必须重启，不能省：配置档只在启动时加载一次插件，所以改了 lib/，或者 git pull 之后插件有更新，正在运行的进程都不会感知。只有 Web GUI 的客户端插件会热重载，而且只在 pnpm run dev:web 重新构建期间生效；本插件的工具和技能都在服务端。

它如何找到你的 ComfyUI

插件优先使用已经在运行的服务，找不到就自己启动一个：

1. 先探测配置的端口，再探测 8188–8192，看有没有可用的 /system_stats。
2. 如果都没有响应，就找一个本地 ComfyUI 检出，要求它真能加载工作流所需的权重——按模型文件判断，不看文件夹名字，所以不会误选一个无关的安装。
3. 用该安装自带的 virtualenv 和它的 extra_model_paths.yaml 以无头模式启动（正是这个文件让 Comfy Desktop 的共享模型目录可见）。

配置

全部可选。设置环境变量，或者直接用默认值。

| 变量 | 作用 |
| DSH_COMFY_PORT | 为所有工作流强制指定一个端口（默认：探测 8188–8192） |
| DSH_COMFY_PORT_Z_IMAGE_TURBO | 只为 Z-Image-Turbo 强制指定端口 |
| DSH_COMFY_PORT_QWEN_IMAGE_2_1 | 只为 Qwen-Image-2.1 强制指定端口 |
| DSH_COMFYUI_PATH | 指向手动安装的 ComfyUI 检出，而不是 Comfy Desktop |
| DSH_ZIMAGE_MODELS | 覆盖 Z-Image-Turbo 的模型文件名（JSON） |
| DSH_QWEN_IMAGE_MODELS | 覆盖 Qwen-Image-2.1 的模型文件名（JSON） |

当你的权重和默认值不一样时，就覆盖模型名，比如你量化过 Qwen-Image-2.1：

export DSH_QWEN_IMAGE_MODELS='{"unet_name":"qwen_image_2.1_fp8.safetensors","clip_name":"qwen3vl_8b_fp8.safetensors","vae_name":"qwen_image_2.1_vae_bf16.safetensors"}'

在会话中使用

draw a small green plant in a terracotta pot, soft window light, photograph

智能体会加载 comfyui-image 技能，选 Z-Image-Turbo 出草稿，把结果存到 ./generated-images/ 下。

想要更多控制，直接提要求：

use qwen-image-2.1 to make a 16:9 poster that says "DEEP DIVE" in bold letters
above a stylised submarine, screen-print texture, negative prompt: blurry text

工作流

两张图都放在 workflows/ 下，是 ComfyUI API 格式的 JSON，里面带 {{placeholder}} 字符串。它们来自官方 Comfy 模板工作流，并从子图里展平，所以不用前端，直接走普通 HTTP 就能排队。

要新增或调整工作流：

1. 在 ComfyUI 界面里搭好。
2. 存成 API 格式（Developer → Save (API Format)）。
3. 把想参数化的值换成 {{snake_case}} 名字。
4. 放进 workflows/，并在 lib/workflows.js 里加一条 spec。
参数缺失或拼错时，会在任何数据到达 GPU 之前直接报错——你会看到一条指名道姓的错误，而不是一张悄悄出错的图。

开发

npm test # schema shape, parameter resolution, apply(), blueprint conversion, catalogue, knowledge
npm run test:host # the installed Harness's own skill validator, extracted from app.asar
npm run test:smoke # discovery + a real generation of both workflows through the tool
node scripts/boot-check.mjs <node_modules> <plugin-dir> # apply() under the real Cordis loader

npm test 会跑六组测试。前三组是自包含的；blueprint、catalogue 和 knowledge 三组会读取本机安装的 ComfyUI 模板，因为它们研究的对象就是那些真实文件——用合成 fixture 能跑通，而实际转换却依然坏着。没有安装 ComfyUI 时，每组都会干净地跳过。

npm test 自包含，既不需要 ComfyUI，也不需要 Harness。另外三组需要两者之一，而 boot-check 还需要一份能提供 @deepseek-ai/cordis 的检出。

define-tool.mjs 断言的是编译后工具 schema 的形状，不只是行为：JSON Schema 把 required 定义为由所属对象拥有的属性名数组，所以属性节点上残留的 required: true 会让 schema 失效，而校验收到的工具列表的网关会拒绝整个列表——所有工具，不只是坏掉的那个。

test:host 是最有意思的一个。ctx.skills.register() 只校验 name、description 和 invocation，所以缺少 source 字段的技能能干净地注册，出现在目录里，然后每次模型尝试加载它时都失败。第二道校验在 @deepseek-ai/dsh-skill 里；这个脚本把真正的函数从已安装的 app.asar 里提取出来，让插件的技能跑一遍，并配一个反向对照，证明这项检查仍然能失败。npm test 里带了一份同样规则的转写，这样没有安装 Harness 也能抓到回归。

test:smoke 用模型实际产出的最小参数形状来跑两个工作流的生成——只有 prompt，所有可选参数都省略——因为默认值被抹掉的 bug 正是在这里露头。

设计说明

- 没有运行时依赖。 从 git clone 安装会创建一个目录联接，所以导入 peer 包时必须从 clone 的真实路径解析，而不是从配置档的 node_modules。只用 ctx.tools 和 ctx.skills，插件就能从任何位置安装。lib/define-tool.js 是一个本地的小型 defineTool，把参数 DSL 编译成 JSON Schema，并在分发前校验参数。
- 插件只停止自己启动的进程。 你自己启动的 ComfyUI 在插件销毁时会继续运行。
- 图片会复制进工作区，而不是在 Comfy 桌面端托管的输出文件夹，这样之后 Comfy Desktop 清理时，不会删掉智能体刚完成的工作。

许可证

MIT — 见 LICENSE。