comfyui-core

ComfyUI 核心知识

工作流 JSON 格式（API 格式）

ComfyUI 工作流是 JSON 对象，将字符串节点 ID 映射到节点定义：

{
  "1": {
    "class_type": "CheckpointLoaderSimple",
    "inputs": { "ckpt_name": "sd_xl_base_1.0.safetensors" },
    "_meta": { "title": "Load Checkpoint" }
  },
  "2": {
    "class_type": "CLIPTextEncode",
    "inputs": { "text": "a cat", "clip": ["1", 1] },
    "_meta": { "title": "Positive Prompt" }
  }
}

关键规则

• 节点 ID 是整数的字符串（"1"、"2" 等）
• class_type 是节点对应的 Python 类名，必须完全一致
• inputs 同时包含控件值（标量）和连接（数组）
• 连接采用 ["sourceNodeId", outputIndex] 格式，是一个包含 2 个元素的数组，其中：
  • 第一个元素是源节点的字符串 ID
  • 第二个元素是源节点 output 列表中的整数索引（从 0 开始）
• _meta 是可选项，仅用于显示标题

连接示例

"model": ["1", 0]       // Connect to node 1's first output (MODEL)
"clip": ["1", 1]        // Connect to node 1's second output (CLIP)
"vae": ["1", 2]         // Connect to node 1's third output (VAE)
"positive": ["2", 0]    // Connect to node 2's first output (CONDITIONING)
"samples": ["5", 0]     // Connect to node 5's first output (LATENT)
"images": ["6", 0]      // Connect to node 6's first output (IMAGE)

重要：API 格式与 Web UI 格式

• API 格式（用于执行／分析）为 { "1": { class_type, inputs }, "2": { ... } }。它简洁紧凑，供 enqueue_workflow、create_workflow (action:"validate")、create_workflow (action:"modify") 等使用。
• Web UI 格式（用于保存和在前端编辑）为 { "nodes": [...], "links": [...] }。它包含布局位置、尺寸、分组和视觉元数据，ComfyUI 画布可据此打开和编辑工作流
• 执行工具期望接收并返回 API 格式
• 请使用 Web UI 格式保存，这样保存的工作流才能在 ComfyUI 前端保持可读、可编辑。原始 API 格式的保存文件无法在画布中编辑。它虽然“存在”于库中，但在画布中加载时会显示为空白，导致用户陷入困境，也会诱使 Agent 创建另一个新工作流，而不是重新打开旧工作流。因此，save_workflow 会自动将 API 格式输入转换为 Web UI 格式，并生成布局。建议优先传入真实的 Web UI 格式（来自 get_workflow(action="get", filename=…, format="ui")），因为生成的布局会丢失原有的节点位置和分组
• get_workflow 默认使用 format="api"，用于分析／执行；加载工作流以便重新保存或在画布中编辑时，请使用 format="ui"
• 静音／旁路节点会通过 _meta.mode: "muted" 保留。它们处于非活动状态，但仍可见，便于理解工作流
• Get/Set 虚拟连线节点会通过 _meta.title 和 Constant 键保留，以便追踪数据流

工作流库工具

• get_workflow(action="analyze", filename=…) 是理解任何已保存工作流时的首个调用。它会返回结构化文本摘要，包含各个区段、节点 ID、关键设置、虚拟连线和连接图。不会返回原始 JSON，只提供推理所需的信息。支持的视图：summary（默认）、overview（mermaid）、detail（section mermaid）、list、flat。
• get_workflow (action:"list") 会列出 ComfyUI 用户库中的所有已保存工作流
• get_workflow(action="get", filename=…) 会加载原始工作流 JSON。仅在需要将实际 JSON 用于 enqueue_workflow、create_workflow (action:"modify") 或 save_workflow 时使用。理解工作流时请改用 action="analyze"。如果要将 JSON 传回 save_workflow，请指定 format="ui"，以便工作流在前端保持可编辑。
• save_workflow(action="save", filename=…, workflow=…) 会将工作流保存到用户库。请传入 Web UI 格式（{ nodes, links }），这样工作流就能在 ComfyUI 画布中保留真实布局。API 格式的图也可以传入，并会自动转换为 Web UI 格式（同时生成布局）；之所以提供此转换，正是因为原始 API 格式的保存文件无法在画布中编辑，前端无法打开。重新保存现有工作流时，请使用 get_workflow(action="get", filename=…, format="ui") 加载并编辑，这样才能保留位置和分组。

数据类型

ComfyUI 节点通过连接传递类型化数据：

类型	描述	常见来源
MODEL	扩散模型权重	CheckpointLoaderSimple（输出 0）
CLIP	文本编码器	CheckpointLoaderSimple（输出 1）
VAE	变分自编码器	CheckpointLoaderSimple（输出 2）
CONDITIONING	编码后的文本提示词	CLIPTextEncode（输出 0）
LATENT	潜空间张量	EmptyLatentImage、KSampler、VAEEncode
IMAGE	像素图像张量（BHWC）	VAEDecode、LoadImage、SaveImage
MASK	单通道蒙版	LoadImage（输出 1）
UPSCALE_MODEL	放大模型	UpscaleModelLoader

标准工作流模式

文生图（txt2img）

CheckpointLoaderSimple → MODEL, CLIP, VAE
  ├─ CLIP → CLIPTextEncode (positive) → CONDITIONING
  ├─ CLIP → CLIPTextEncode (negative) → CONDITIONING
  │
EmptyLatentImage → LATENT
  │
KSampler (model, positive, negative, latent_image) → LATENT
  │
VAEDecode (samples, vae) → IMAGE
  │
SaveImage (images)

节点 ID 通常为：1=Checkpoint、2=Positive、3=Negative、4=EmptyLatent、5=KSampler、6=VAEDecode、7=SaveImage

图生图（img2img）

与 txt2img 相同，但将 EmptyLatentImage 替换为：

LoadImage → IMAGE
VAEEncode (pixels, vae) → LATENT → KSampler.latent_image

将 KSampler.denoise 设为 0.5 到 0.8（数值越低，结果越接近输入图像）。

放大

LoadImage → IMAGE
UpscaleModelLoader → UPSCALE_MODEL
ImageUpscaleWithModel (upscale_model, image) → IMAGE
SaveImage (images)

局部重绘

LoadImage (image) → IMAGE → VAEEncode → LATENT
LoadImage (mask) → MASK
SetLatentNoiseMask (samples, mask) → LATENT → KSampler.latent_image

MCP 工具使用指南

快速生成

1. 使用模板 "txt2img" 和你的参数调用 create_workflow
2. 使用返回的 JSON 调用 enqueue_workflow(action="enqueue")。它会立即返回 prompt_id
3. 使用 prompt_id 轮询 queue（action:"status"），直到 done 为 true
4. 使用 get_image (action:"list_outputs")（limit 1）查找生成的图像，然后用 Read 显示

检查和修改

• create_workflow (action:"node_info") 查询可用节点及其架构
• create_workflow (action:"modify") 修改现有工作流（set_input、add_node、remove_node、connect、insert_between）
• visualize_workflow 将工作流显示为 mermaid 图表

逆向工程

• visualize_workflow 将工作流 JSON 转换为 mermaid 图表
• visualize_workflow (action:"mermaid") 将 mermaid 图表转换为工作流 JSON（使用 /object_info 解析架构）

模型管理

• list_local_models 显示已安装的模型
• download_model 的 action:"search" 可在 HuggingFace 上查找模型
• download_model 将模型下载到 ComfyUI 的模型目录

切勿要求用户手动下载模型。如果缺少所需模型，请自行搜索并下载：

1. 首先检查 list_local_models
2. 如果缺少，通过 download_model 的 action:"search" 在 HuggingFace 上搜索，或通过其 REST API 在 CivitAI 上搜索
3. 使用 download_model 将模型直接安装到正确的子文件夹

CivitAI API（当 CIVITAI_API_TOKEN 环境变量可用时）：

• 搜索：GET https://civitai.com/api/v1/models?query={query}&types=Checkpoint&sort=Most+Downloaded&limit=5
• 详情：GET https://civitai.com/api/v1/models/{modelId}
• 下载：GET https://civitai.com/api/download/models/{modelVersionId}?token={token}

微调模型、社区评分较高的检查点和专用 LoRA 优先使用 CivitAI。 官方／基础模型（SDXL、Flux、SD 1.5）优先使用 HuggingFace。

自定义节点

• search_custom_nodes 搜索 ComfyUI Registry（action: "search"）或获取某个包的详情（action: "details"）
• list_packs（action: "generate_skill"）自动为节点包生成技能文件

工作流执行

enqueue_workflow 将任务提交到 ComfyUI 队列，并立即返回 prompt_id 和队列位置。它不会阻塞。

后台进度监控

将一个或多个工作流加入队列后，使用后台 Bash 任务静默监控进度：

# Single job
Bash(run_in_background: true):
node "${CLAUDE_PLUGIN_ROOT}/scripts/monitor-progress.mjs" <prompt_id>

# Multiple jobs (batch)
Bash(run_in_background: true):
node "${CLAUDE_PLUGIN_ROOT}/scripts/monitor-progress.mjs" <id1> <id2> <id3>

该脚本会连接到 ComfyUI 的 WebSocket，并报告：

• 逐步进度（例如，KSampler step 12/20 (60%)）
• 成功状态、输出文件名和耗时
• 错误及节点详情和消息

标准生成流程：

1. create_workflow，或构建工作流 JSON + enqueue_workflow(action="enqueue")（批量处理时重复此步骤）
2. 启动后台监控任务，并传入所有 prompt_ids
3. 继续对话。任务完成后会显示结果
4. 使用 get_image (action:"list_outputs") 或 Read 显示生成的图像

不要循环轮询 queue (action:"status")。后台监控会完全取代轮询。

如果监控脚本不可用，则回退到 queue (action:"status") 并持续轮询，直到 done 为 true。

队列管理

queue 工具由其 action 参数控制：

• queue (action:"list") 显示正在运行和待处理的任务数量及 prompt_ids
• queue (action:"status") 检查指定的 prompt_id 正在运行、待处理还是已完成
• queue (action:"cancel") 中断正在运行的任务（传入可选的 prompt_id 可指定目标任务）
• queue (action:"cancel_queued") 根据 prompt_id 从队列中移除指定的待处理任务
• queue (action:"clear") 移除所有待处理任务（不会停止当前正在运行的任务）

何时使用队列工具：

• 检查状态时，使用 queue (action:"status") 快速确认状态（持续跟踪时优先使用后台监控）
• 中止任务时，queue (action:"cancel") 会停止当前正在运行的任务，queue (action:"cancel_queued") 会移除待处理任务
• 重新开始时，使用 queue (action:"clear")，然后可选择使用 queue (action:"cancel")`

监控与恢复

• get_system_stats 报告 GPU、VRAM、Python 版本和操作系统详情
• queue (action:"list") 显示正在运行和待处理的任务（上文“队列管理”中也有说明）

当 ComfyUI 无响应或崩溃时：

1. 尝试使用 get_system_stats。如果失败，说明 ComfyUI 已停止运行
2. 使用 restart_comfyui，并设置 action: "restart"（会保留之前 action: "stop" 时的启动参数）
3. 如果重启失败（没有已保存的进程信息），则使用 restart_comfyui，并设置 action: "start"，或请用户手动启动。在 Windows 上，action: "start" 不会启动 ComfyUI（会拒绝执行），因此请用户从桌面应用或其启动器启动
4. ComfyUI 恢复后，重新将失败或丢失的工作流加入队列

维护时停止 ComfyUI 之前：

1. 先调用 restart_comfyui，并设置 action: "status"。此操作只读。然后查看 stop.recoverable_by_start：
   • "yes"：可通过 action: "start" 重新启动
   • "no"：停止后必须由人员重新启动 ComfyUI（stop.manual_recovery_reason 会说明原因），因此停止前要告知用户
   • "unknown"：尚未确定能否重新启动。维护停止前，应先确认这一点，或告知用户。如果 target_stable 为 false，表示检查期间目标发生了变化，此时只需再次调用 status
   • "not-applicable"：停止操作不可用（stop.allowed 不是 "yes"），因此无需通过 start 恢复。stop.manual_recovery_reason 会说明原因
2. 要重启 ComfyUI，请使用 action: "restart"，不要先 stop 再 start。如果无法恢复，重启操作会拒绝执行，而不是让 ComfyUI 停止运行
3. 仅当 ComfyUI 应保持停止时，才使用 action: "stop"

任务似乎卡住时（监控显示 [STALL]）：

1. 检查 get_system_stats 并查看 VRAM 使用情况（OOM 会导致卡顿）
2. 尝试使用 queue (action:"cancel") 中断卡住的任务
3. 如果取消失败，使用 restart_comfyui 强制重启
4. 重启后使用 clear_vram 释放 GPU 内存，再重试

KSampler 参数

参数	类型	常见值
seed	int	随机值（0 到 2^48）。省略则自动随机化。
steps	int	20（标准），4-8（turbo/lightning 模型）
cfg	float	7-8（SD 1.5/SDXL），1.0（Flux），3.5（turbo）
sampler_name	string	"euler"、"euler_ancestral"、"dpmpp_2m"、"dpmpp_sde"
scheduler	string	"normal"、"karras"、"sgm_uniform"
denoise	float	1.0（txt2img），0.5-0.8（img2img），0.75-0.9（inpaint）

Mermaid 可视化约定

visualize_workflow 工具会生成 Mermaid 流程图，其中包含：

• 按类别对节点进行分组的子图：loading、conditioning、sampling、image、output
• 显示数据类型的边标签：-->|MODEL|、-->|CLIP|、-->|LATENT| 等
• 显示 class_type 以及可选控件值的节点标签
• 默认采用 LR（从左到右）方向；大型工作流采用 TB（从上到下）

visualize_workflow (action:"mermaid") 工具会将 Mermaid 解析回工作流 JSON，并使用连接类型标签通过 /object_info 架构确定正确的输入/输出槽位。

应避免的常见错误

1. 连接格式错误。 使用 ["1", 0]，而非 [1, 0]；节点 ID 是字符串
2. Web UI 格式。 不要传入 { nodes: [], links: [] }；请使用 API 格式
3. 缺少 VAE。 CheckpointLoaderSimple 有 3 个输出：MODEL(0)、CLIP(1)、VAE(2)
4. 输出索引错误。 通过 create_workflow (action:"node_info") 查看节点的输出列表顺序
5. Seed 处理。 默认情况下，enqueue_workflow 会随机化种子，除非设置 disable_random_seed: true

来源

• 官方： ComfyUI 工作流/API 约定，参见 https://github.com/comfyanonymous/ComfyUI 和 https://docs.comfy.org
• 经验总结： MCP 工具配方和 KSampler 默认值表属于产品/经验笔记，并非供应商的提示词指南。