comfyui

用途

本技能用于驱动本地安装的 ComfyUI，通过其 HTTP API 完成图像、视频、音频的生成、渲染与编辑，也用于构建和运行 ComfyUI 工作流。凡是涉及用 ComfyUI 生成或渲染图像、视频、音频，或搭建、运行工作流的任务，都应先阅读本技能再执行。

主要能力

• 知识 + 客户端：SKILL.md 与 comfy_client.py（仅用标准库，无额外依赖）。
• MCP 驱动：comfyui-mcp（artokun，MIT），约 90 个结构化工具，让 Claude 直接操作 ComfyUI，包括生成、构建/编辑/校验图、模型下载、队列、显存、诊断、重启。存在该驱动时优先使用其工具，而非手工 POST /prompt。
• 图内 Claude 节点：把 Claude 作为工作流中的一个步骤（提示词增强、对输出做视觉质检）。
• 节点构建技能：comfyui-node-*（V3 API），用于编写或修改自定义节点。

使用方式

客户端 comfy_client.py 与 SKILL.md 同目录，导入后使用：

import sys; sys.path.insert(0, r"<this skill dir>")
import comfy_client as c
c.alive()                                  # True if the API answers (override host with COMFY_HOST env)
c.run("path/to/workflow_api.json",
      overrides={"6.text": "a cinematic dragon, dark studio light", "3.seed": 12345},
      outdir=r"...\assets")                # queues, waits, downloads -> returns saved file paths

API 面：alive()、run(workflow_path, overrides, outdir, timeout)，以及 queue(workflow)、wait(prompt_id)、download_outputs(rec, outdir)、apply_overrides(wf, overrides)。覆盖键格式为 "<nodeId>.<inputName>"，节点 ID 与输入名直接来自工作流 JSON。

工作流 JSON 采用 API 格式：{ "<nodeId>": { "class_type": "...", "inputs": {...} }, ... }。获取方式：在 ComfyUI 中启用 Settings -> Enable Dev mode Options，构建图后 Save (API Format)。官方起始图来自 Workflow -> Templates 浏览器（按模型），保存为 API Format 后再参数化。

参数化时读取图并定位：正向提示词（CLIPTextEncode 节点，覆盖 .text）、种子（KSampler / sampler 节点，覆盖 .seed，每次调用使用变化的种子，不要硬编码）、尺寸（EmptyLatentImage / EmptySD3LatentImage 节点，覆盖 .width / .height）、steps/cfg/sampler/scheduler（在 sampler 节点上，除非被要求，否则保留模板值，它们是按模型调好的）。

模板库是事实来源：官方 Comfy-Org 工作流模板被稀疏克隆到本地文件夹并建立紧凑索引，主索引为 templates/_quick_index.json（name -> title、category、models、tags、mediaType、vram、description），可用 shared/tools/gen_quick_index.py 重新生成。流程：读 _quick_index.json，找到与请求匹配的模板，读取该模板 templates/<name>.json，再参数化。新模板使用 SUBGRAPHS：真实管线在 definitions.subgraphs[0] 内，暴露参数在 subgraphs[0].inputs，通过外层节点的 properties.proxyWidgets 追踪到内部节点。可混搭 blueprints/ 中的可复用子图积木。

widgets_values 按顺序排列、无字段名：KSampler = [seed, control_after_generate, steps, cfg, sampler, scheduler, denoise]；EmptySD3LatentImage = [width, height, batch]。模型文件名必须与已安装文件完全一致。写图前用 /object_info/<NodeType> 校验节点类型与输入。

当没有单一模板适配时，可自行组装：把任务分解为阶段，每阶段一个积木；了解节点连接机制（API 格式中每个输入要么是字面值，要么是 ["<sourceNodeId>", <outputSlotIndex>] 引用）；匹配类型或插入转换器（VAEEncode、VAEDecode、CLIPTextEncode、ImageScale 等）；干净地合并图（重编号避免冲突、共享加载器、接好接缝、各模型保留自己的 VAE/编码器）；运行前校验（class_type 存在、输入为字面值或有效引用、接缝类型匹配、模型文件存在、至少一个输入节点承载用户意图且至少一个输出/保存节点接到最终张量）。

适用场景

• 用 ComfyUI 生成、渲染或编辑图像、视频、音频。
• 构建、运行、参数化 ComfyUI 工作流。
• 需要按模型提示词配方写提示词（先查 MODELS.md 索引，再读 MODELS/ 下对应家族文件）。
• 需要处理特定模型或工具链：MiniMax H3、Krea、ByteDance Seedance、kijai 生态、LTX-2 训练、OCIO 色彩管理等，均有对应文档或兄弟技能。
• 需要编写或修改自定义节点（配合 comfyui-node-* 技能与 docs/BUILDING_NODES.md）。

限制

• 本技能面向本地 ComfyUI 安装，需先完成机器引导（docs/BOOTSTRAP.md），并在 machine.md 中记录真实路径、GPU、模板库位置与启动命令；machine.md 缺失或仍是占位符时不得假设其他机器与示例一致。
• 构建前应先读 docs/KNOWN_ISSUES.md，避免绕行当前已损坏的路径。
• 不得从截图判断图布局，应读取坐标（workflow_layout.py 的 auto_layout / inspect / fit_group）。
• 部分 API / 合作节点（Kling、Nano Banana、Veo、Gemini 等）默认不包含保存节点，需自行添加并接线。
• 关于收费、价格、平台、效果等具体信息，资料中暂未提供。