comfyui

ComfyUI：驱动本地安装

只要任务涉及使用 ComfyUI 生成或渲染图像、视频或音频，或构建／运行 ComfyUI 工作流，就使用本指南。先阅读，再开始操作。

本工具包中的文件（按需读取对应文件）

只有此 SKILL.md 会自动加载；其他内容仅在相关时读取，因此请转到对应文件，而不是让它一直处于未读状态。 **两种布局，文件相同：**在已安装的技能中，所有文件都平铺在此文件旁，因此下文的 docs/TASKS.md 表示此处的 TASKS.md，而 docs/NODE_LIBRARY/ocio.md 表示此处的 NODE_LIBRARY/ocio.md；同样，文档中提到的仓库内 shared/tools/ 下的脚本，安装后会位于此文件旁的 tools/ 中。在仓库中，这些前缀是实际路径。如果某个路径无法解析，请先去掉 docs/，并在得出文件缺失的结论前检查此文件旁边。

• MODELS.md（与本文件同目录）——各模型提示词配方的索引。先在表格中查找模型，再在编写提示词前读取 MODELS/ 下对应的模型系列文件。要读两份文件，而不是一份：索引中没有配方。
• 同级的 minimax-h3 技能（按名称调用；在磁盘上与本技能并列，Claude Code 和 Codex 中位于 ../minimax-h3/，Gemini 和 Qwen 中位于 minimax-h3/）——专门介绍 MiniMax H3（Hailuo 3）的技能：提示词格式（三个命名字段、<d> 对话、摄像机词汇）、参考素材标注、量化与加速，以及症状到原因对照表。遇到任何 H3 提示词或本地权重问题时都要阅读；MODELS.md 保留了节点级详情。
• 同级的 krea 技能（按名称调用；在磁盘上与本技能并列）——专门介绍 Krea 的技能：Krea 托管 API（Krea2ImageNode / Krea2StyleReferenceNode、按图计费、情绪板、上限为 1K）与开放权重之间的选择、FLUX.1 Krea Dev 图、Krea Realtime 14B，以及它唯一的 ComfyUI 套件为何只是未经验证的线索，还有用于 ControlNet / 身份编辑 / 条件控制的 Krea 2 自定义节点套件。遇到 API 路径或模型选择问题时要阅读；MODELS.md 保留了本地 Krea 2 图。
• 同级的 seedance 技能（按名称调用；在磁盘上与本技能并列）——专门介绍 ByteDance Seedance 的技能：三种任务类型以及用于切换任务类型的词、@Image 1 标签语法、全角符号集、镜头排序、素材数量规则、在 2.5 中发生反转的时序规则，以及故障对照表。遇到任何 Seedance 提示词时都要阅读；MODELS.md 保留了节点级详情和价格计算。
• docs/TASKS.md——常见任务列表（生成图像 / 视频 / 音频 / 3D、放大、移除背景）：该任务的本地端到端流程，是本手册的快捷入口。
• docs/NODE_LIBRARY/smart-upscaler.md——我们的 Smart Upscaler 套件（11 个节点）：分块放大，并为每个图块单独编写经过验证的提示词。当 BUSY 或 MIXED 场景的分块放大持续生成自信但错误的图块，或接缝不一致时，请阅读此文；对于主体统一的图像，ADVANCED.md 中成本更低的采样器分块工具仍是正确选择。
• docs/MODEL_INDEX.md——全部 160 个模型的完整分类列表（配方 / 实用工具 / 仅模板）；检查指定模型是否有配方、是否为实用工具，或是否仅提供模板。
• docs/NODE_LIBRARY/training.md——让图真正能够制作模型，而不只是提示模型的节点：核心节点中的 TrainLoraNode / SaveLoRA / LossGraphNode，加上 16 个数据集节点（MakeTrainingDataset、 ResolutionBucket、图文加载器、视频时序裁剪）以及端到端连接的完整链路。有人询问训练或微调任何内容时都要阅读；docs/TASKS.md 提供简短路径。
• docs/ADVANCED.md——高难度任务：实际优势、注意事项与解决方法、时序稳定性、高细节抠像、裁剪拼接式局部重绘、PBR，以及经验证的工具和许可证表。
• docs/KNOWN_ISSUES.md——构建前先阅读，避免围绕当前已损坏的路径搭建。
• docs/NODE_LIBRARY/_INDEX.md——逐节点参考手册（Nuke 风格）：说明每个节点的输入 / 输出用途、行为、错误与修复方法、反模式，以及在图中的位置。遇到任何节点问题都从这里开始，然后调用 get_node_info 查询实时 I/O。使用或遇到尚未收录的节点时，在完成前添加条目（docs/NODE_LIBRARY/_SCHEMA.md）。
• workflow_layout.py——保存构建的任何工作流前，都要先用代码排布并验证：auto_layout(wf) 按依赖深度从左到右排列节点，将并行分支上下堆叠，确保完全没有重叠；inspect(wf) 根据坐标报告重叠 / 交叉 / 边界；fit_group(wf, title) 在已排布的节点外包上背景框，使其完全覆盖功能组（边到边，不露出任何节点）。切勿根据截图判断图的布局（这会浪费 token，而且客户端也会遇到同样的问题）——应读取坐标。
• docs/NODE_LIBRARY/ocio.md——我们自己的 ComfyUI-OCIO 套件，v1.3.0（11 个 Nuke 风格的 OpenColorIO 节点：Read / Write / Player、六种颜色运算节点，以及可在解码时不使用默认 0..1 钳制的 OCIO VAE Decode / VAE Encode 配对节点；已发布，github.com/SlavaSexton/ComfyUI-OCIO）。遇到任何色彩管理 / VFX 色彩任务时都要阅读（加载序列、在 ACES 中调色、写入 ProRes / EXR，或在生成模型中保留大于 1.0 且小于 0 的值）。v1.3.0 将 OCIO Write 的 from_colorspace 重命名为 input_colorspace，携带旧键的 API 格式图会遭到拒绝，因此构建前要阅读此文件。
• docs/BUILDING_NODES.md——编写自定义节点套件的实战指南，凝结了重要经验（部件顺序、组合框验证陷阱、JS 前端、服务器路由、ComfyUI 特性、用真实文件验证）。编写或修改自定义节点时，先阅读此文，并同时参考 comfyui-node-* 技能。
• docs/KIJAI.md——kijai 生态（他的 ComfyUI 封装器和节点：Wan / Hunyuan / CogVideoX / Florence2 / KJNodes / SUPIR / FramePack / SAM2 / FluxTrainer / IC-Light / DepthAnythingV2 等约 50 个工具）：各工具的功能与节点 I/O、按日期区分仍活跃与已过时的工具，以及替代关系表（旧工具 -> 更好的工具）。遇到任何 kijai 工具时都要阅读，也可据此选择当前方案，替代即将淘汰的封装器。
• docs/NODE_LIBRARY/radiance.md——对 fxtdstudios/radiance 进行逆向工程后整理的参考资料（专业的 32 位色彩科学 / HDR / VFX 套件，包含 78 个节点和一次 v3 重写；是 OCIO / 色彩领域最强的公开套件）。需要色彩科学 / HDR / VFX 查看器参考实现、改进我们自己的 ComfyUI-OCIO 套件（其中列有按优先级排序的“值得借鉴之处”：处理器缓存、WebGL 32 位查看器、OpenEXR 写入器、LogC3-EI / LogC4），或任务涉及 radiance 节点时，请阅读此文。其节点构建经验已纳入 BUILDING_NODES.md。
• docs/LTX2_TRAINING.md——用户使用 LTX-2 并希望 LoRA 捕捉某种行为时，可建议训练一个（使用 Lightricks 官方训练器）。
• docs/EXAMPLE_WORKFLOWS.md——完整的端到端示例 + 多模型图像编辑对比测试。
• **docs/NODES.md介绍图中的 Claude 节点（计费 / 用途）；docs/LAYERS.md介绍四个安装层；docs/BOOTSTRAP.md介绍首次运行时的机器设置；docs/AGENTS.md介绍各 Agent 的对应关系（Claude / Codex / Gemini / Qwen）；docs/UPDATING.md**介绍每周模型与错误更新流程。

你的机器

**在会话中首次调用 ComfyUI 前，请先阅读本文件旁边的 machine.md。**其中记录了此安装的实际路径、GPU、模板库位置和启动命令。它被有意放在本文件之外： 安装程序每次更新都会覆盖 SKILL.md，因此，保存在此处的机器信息会在下一次 git pull 并重新安装时被清除，导致必须重新运行初始化（2026-08-06 审计）。machine.md 只写入一次，之后不会覆盖。

如果 machine.md 缺失或仍充满尖括号，请立即运行初始化（docs/BOOTSTRAP.md）： 运行 health_check，或运行 comfy_client.alive()，再调用 GET /system_stats 和 /object_info，然后将实际值写入 machine.md。不要假设其他机器与示例一致。

四个层（此工具包安装的内容）

1. 知识 + 客户端：此 SKILL.md 和 comfy_client.py（仅标准库，无依赖项）。
2. MCP 驱动程序：comfyui-mcp（artokun，MIT）：约 90 个结构化工具，让 Claude 直接操作 ComfyUI （生成、构建/编辑/验证图、下载模型、排队、VRAM、诊断、重启）。如果有这些工具， 优先使用它们，而不是手动 POST 到 /prompt。它使用 MCP SDK 的 1.x 版本线，即无状态 2026-07-28 规范之前的版本；该版本仍处于 为期 12 个月的弃用窗口内，因此无需更改。如果你要编写自己的 MCP 服务，请先阅读 docs/LAYERS.md 中的协议部分： 现在，无上限的 mcp>=x 版本约束会拉取 SDK 2.x，该版本移除了 mcp.server.fastmcp，会导致全新安装失败。
3. 图内 Claude 节点：将 Claude 作为工作流内部的一个步骤（丰富提示词、对输出进行视觉 QA）。
4. 节点构建技能：在编写或修改自定义节点时使用 comfyui-node-*（V3 API）。

docs/LAYERS.md 说明了每一层；install.ps1 / install.sh 会完成配置。

客户端（无额外依赖，仅标准库）

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）。 MCP 驱动程序（第 2 层）也能完成相同操作且功能更多；如果可用，请使用它，否则使用此客户端。

工作流 JSON（API 格式）

ComfyUI 运行“API 格式”图：一个字典 { "<nodeId>": { "class_type": "...", "inputs": {...} }, ... }。 获取方法：在 ComfyUI 中启用 Settings -> Enable Dev mode Options，构建图，然后选择 Save (API Format)。 官方起始图：Workflow -> Templates 浏览器（按模型分类）。将它们保存为 API 格式，然后参数化。

要参数化图，请阅读图并找到：

• 正向提示词：CLIPTextEncode 节点，覆盖 .text。
• 种子：KSampler / 采样器节点，覆盖 .seed（每次调用使用不同的种子；不要硬编码）。
• 尺寸：EmptyLatentImage / EmptySD3LatentImage 节点，覆盖 .width / .height。
• 步数/CFG/采样器/调度器：位于采样器节点上。除非另有要求，否则保留模板中的值；这些值已针对模型调优。

模板库（事实来源，可自由组合）

Comfy-Org 官方工作流模板是 ComfyUI 中各项任务的事实来源。该工具包会将它们稀疏克隆到本地文件夹，并建立精简的查找索引。默认位置由安装程序设置；请将其记录在上方的机器信息块中。主索引：templates/_quick_index.json（名称 -> 标题、类别、模型、标签、媒体类型、显存、描述），使用 shared/tools/gen_quick_index.py 重新生成。更新：在克隆目录中运行 git pull，然后重新运行生成器。

**流程：**读取 _quick_index.json，找到名称／模型／标签与请求匹配的模板，读取对应的那个 templates/<name>.json，并对其参数化。新模板使用 SUBGRAPHS：实际管线位于 definitions.subgraphs[0] 中，公开的参数（文本、宽度、高度、种子、步数、模型名称）位于 subgraphs[0].inputs 中，并通过外层节点的 properties.proxyWidgets 追溯到内部节点。自由组合 blueprints/（可复用的子图模块：text_to_image_z_image_turbo、image_to_video_ltx_2_3、image_upscale_z_image_turbo、remove_background_birefnet 等）。

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

用各个模块组合新工作流（正确组装并连线）

如果没有单个模板适用，请通过串联模块来构建工作流。本技能用于组装工作流，而不只是运行工作流。

1. 将任务分解为多个阶段，每个阶段对应一个模块，例如：文生图 -> 放大 -> 图生视频 -> 添加音频。为每个阶段选取一个模板或 blueprints/ 子图（通过 _quick_index.json／blueprint 名称进行匹配），并阅读每个文件，了解其实际输入和输出节点。

2. 了解节点如何连接（关键机制）。

• **API 格式：**每个输入要么是字面值，要么是对另一节点输出的引用，写作一个包含 2 项的列表 ["<sourceNodeId>", <outputSlotIndex>]。要在阶段 A 后运行阶段 B，将 B 的输入设为 ["<A_id>", <slot>]，其中 <slot> 是 A 对应输出的索引。例如，将解码节点的 IMAGE 输入放大器 -> "image": ["8", 0]（节点 8，输出 0）。
• **GUI 格式：**连接存储在顶层 links 数组中；每条连接的格式为 [link_id, src_node, src_slot, dst_node, dst_slot, type]，每个节点的 inputs[].link／outputs[].links 中都包含对应的连接 ID。编写此格式，以便在画布中显示图（桥接）；编写 API 格式以运行。

**3. 匹配类型，或进行转换。**每个输出和输入都有一个 TYPE：IMAGE、LATENT、MODEL、CLIP、VAE、CONDITIONING、AUDIO、MASK、CONTROL_NET 等。只能连接类型匹配的接口。根据 /object_info/<NodeType> 中的信息（input.required／output／output_name）读取各节点的输入和输出类型。如果连接两端的类型不同，请插入转换器：VAEEncode（IMAGE -> LATENT）、VAEDecode（LATENT -> IMAGE）、CLIPTextEncode（文本 -> CONDITIONING）、ImageScale／放大器（调整尺寸）。切勿将 IMAGE 接入 LATENT 输入。 常见节点 I/O（请记住这些；其他情况请读取 /object_info/<NodeType>）。 节点的 WIDGETS 是你设置的值；其 INPUT SLOTS 必须接收来自另一个节点 OUTPUT 的匹配 TYPE。你不能把文本接入 LoRA 输入，也不能把 MODEL 接入文本框。

• CheckpointLoaderSimple -> 输出：MODEL、CLIP、VAE。（Flux / 较新的拆分加载器：UNETLoader -> MODEL；DualCLIPLoader/CLIPLoader -> CLIP；VAELoader -> VAE。）
• LoraLoader：输入 MODEL + CLIP（+ 名称/强度 widgets）-> 输出 MODEL、CLIP。LoRA 是应用到 MODEL + CLIP 流中的，绝不能作为文本连接。
• CLIPTextEncode：输入 CLIP + 文本 widget -> 输出 CONDITIONING。你的提示词会在此处变为 CONDITIONING；下游节点需要的是 CONDITIONING，而不是原始文本。
• EmptyLatentImage / EmptySD3LatentImage：仅 widgets -> 输出 LATENT。
• KSampler / KSamplerAdvanced：输入 MODEL + 正向 CONDITIONING + 负向 CONDITIONING + LATENT（+ seed/steps/cfg/sampler/scheduler/denoise widgets）-> 输出 LATENT。
• VAEDecode：输入 LATENT + VAE -> 输出 IMAGE。VAEEncode：输入 IMAGE + VAE -> 输出 LATENT。
• ControlNetLoader -> CONTROL_NET；ControlNetApplyAdvanced：输入 CONDITIONING + CONTROL_NET + IMAGE -> 输出 CONDITIONING。
• LoadImage -> IMAGE、MASK；SaveImage / PreviewImage：输入 IMAGE。 基础 txt2img 流程：loader ->（LoraLoader）-> CLIPTextEncode x2（正向/负向）-> KSampler（+ EmptyLatentImage）-> VAEDecode -> SaveImage。开始构建前，还要查看 KNOWN_ISSUES.md（与此文件同目录或位于 docs/KNOWN_ISSUES.md）和 ADVANCED.md，了解当前的错误和解决方法，以免绕过一条已知有问题的路径。

4. 干净地合并图。 拼接两个模板时：重新编号其中一个图的节点 ID，避免冲突；共享加载器（使用一个 CheckpointLoader / UNETLoader / VAELoader / CLIPLoader 为两个阶段供数，不要重复加载同一个模型）；然后连接交界处（阶段 A 的最终输出 -> 阶段 B 的第一个输入）。每个模型都要保留自己的 VAE / 编码器（Wan VAE 不是 SDXL VAE；LTX 将其 VAE 打包在检查点中）。

5. 运行前先验证。 检查：每个 class_type 都存在于 /object_info 中；每个输入都是字面值，或指向现有节点的 [node, slot] 引用；每个交界处的类型都匹配；模型文件名在本地存在；并且图中至少有一个承载用户意图的 INPUT 节点，以及至少有一个连接到最终张量的 OUTPUT/保存节点（SaveImage / SaveAudio / SaveVideo / VHS_VideoCombine，或 PreviewImage）。API / 合作伙伴节点（Kling、Nano Banana、Veo、Gemini 等）通常会输出张量，但默认不包含保存节点——请添加并连接一个，否则任务可能会“成功”运行，却没有任何可检索的输出，白白浪费算力。 然后先运行小尺寸 / 低分辨率版本，确认连接无误后再进行完整渲染。输出两种格式：GUI 格式用于在画布中显示，API 格式用于运行。不确定节点的确切输入/输出时，请查询 /object_info/<NodeType>，不要猜测。

共享工作流 + 模型对比（为某种效果挑选最佳模型）

除了具名模板库，ComfyHub 还托管着数千个社区共享工作流，网址为 comfy.org/workflows/<hash>。任何 ComfyHub 分享都能通过可预测的 URL 下载为纯 JSON： https://comfy.org/workflows/download/<hash>.json。因此，你可以按需获取任何共享工作流，然后阅读或运行 它。辅助工具：python shared/tools/fetch_workflow.py <hash> <outdir>（标准库）。<hash> 是分享 URL 中的 ID。注意：cloud.comfy.org/?share=<hash> 链接仅适用于 Comfy Cloud，无法通过这种方式下载（请在 Comfy Cloud 中打开，并从画布导出）。

**模型对比（哪款模型最适合此提示词）：**模板库已提供一个对比网格 templates-all_in_one-image_edit_models（“1 张输入图像和多个编辑模型对比”）：它会将一张输入图像同时交给 7 款图像编辑模型处理（Flux.2 Dev/Klein、GPT-Image-1.5、Grok、Nano Banana Pro、Qwen-Image-Edit、 Seedream），并将每个输出并排保存，方便你在确定采用哪种效果之前进行挑选。对于视频，社区分享的 “Adjustment Frame”（哈希 7dca0438edf4）可对比视频后端（Grok/Kling/Veo/Seedance/Wan2.2/LTX-2）。先以较小尺寸 / 低分辨率运行并进行比较，再提高选中方案的规模。这与下方的各模型配方以及硬件适配检查相辅相成。

值得研究的真实生产工作流图：Comfy-Org/creative-campus（github.com/Comfy-Org/creative-campus）收录了 Comfy Education Initiative 案例研究中的实际工作流，以及获奖艺术家的真实工作流图（例如 Xindi Zhang 的 Song of Drifters，一部 Student Academy Award 电影：采用 IP-Adapter + ControlNet 的 SD1.5 风格迁移，以及一套 3D + AI 变形工作流图）。打开并研究这些工作流，了解制作技巧。仅供链接和研究（无许可证文件；经艺术家许可分享），因此可以引用，但不要随附这些 JSON 文件。

紧跟最新动态（新模型和工作流）

ComfyUI 不断推出新模型，它们会最先出现在模板库中。查看新内容的方法：对模板克隆仓库执行 git pull 并重新生成快速索引（gen_quick_index.py），然后对比模型列表（此前未出现过的名称 = 新模型 / 新模板）。还要阅读公告 RSS：https://blog.comfy.org/feed。工具包附带 shared/tools/check_updates.py，可通过一条命令完成上述所有操作（拉取 + 对比 + RSS）。如果出现了确实全新的生成模型，但尚无配方，请研究其官方提示词指南（制造商文档 / 模型卡 / docs.comfy.org），并按相同格式将其添加到 MODELS.md；新的实用工具 / 超分模型则添加到 Enhancement 部分。不要抓取 LinkedIn（需要身份验证、有反抓取措施，且违反服务条款）；博客 RSS 和模板仓库包含相同资讯，并且都是机器可读的。完整流程：工具包中的 docs/UPDATING.md。

按模型编写提示词（超级大脑）：使用具名模型前请先阅读

每种生成模型都有自己的表达方式。SDXL 需要逗号分隔的标签，FLUX 需要自然语言句子，视频模型需要摄像机方向和运动方向，音频模型需要流派／节奏／乐器；对负面提示词的支持也各不相同（FLUX 和许多 turbo 模型会忽略负面提示词，或因此出错）。本工具包附带按模型整理的提示词参考 MODELS.md（与本文件同目录），内容取自官方来源：各厂商文档／模型卡、docs.comfy.org，以及 anthropic-claude 节点的按模型模板。

**自动查阅规则，且需要阅读两份内容：**当请求、工作流或选定的模板中指定了具体模型时，打开 MODELS.md，在其中的“每个都有配方的模型”表格中找到该模型，然后在编写提示词前阅读 MODELS/ 下对应的模型系列文件。遵循该文件中的提示词结构、负面提示词规则和设置。切勿把一种模型的风格套用到另一种模型上。

MODELS.md 是索引，不是参考资料。它曾是一个单独文件；在 2026-08-06 的审计中，测得文件大小为 174 KB，且有 57% 的条目超出了单次读取能够返回内容的范围。这导致大多数模型的这条规则悄无声息地失效，看起来却像是正常运行。现在，每个系列文件都能在一次调用中完整读取。

MODELS.md 涵盖：（图像）FLUX.1/.2 + Kontext、Z-Image-Turbo、Qwen-Image/Edit、SDXL、SD1.5、SD3.5、HiDream、Ideogram、Nano Banana Pro/2、Seedream 4.x/5 Lite/5 Pro（含 5.0 Pro Layer Separation）、Qwen Image 3.0 Pro（合作伙伴节点随 core v0.32.0 发布）、Recraft、GPT-Image、Grok（含 Grok Imagine Image 2.0 和 V2 编辑节点）、Reve（在 core v0.31.0 中弃用）、Kandinsky、BRIA、OmniGen、Chroma、Krea（含 core 节点上的 Turbo 图像风格参考 LoRA）、ERNIE-Image、Mage-Flow（Microsoft 4B、原生分辨率、MIT）；（图像编辑）FLUX Kontext、Qwen-Image-Edit、FireRed、LongCat、ChronoEdit、JoyAI Image Edit、Mage-Flow-Edit；（视频）Wan 2.1-2.7（含 Uni3C 摄像机轨迹 ControlNet）、Wan Animate 2（本地角色动画，不提取姿势）、LTX-2.5（开放权重和 API 合作伙伴节点，随 core v0.32.0 首日发布）、LTX-2.3 / 2 Pro（其 API 节点现已弃用）、Hunyuan Video、SVD、Kling、Veo、Sora、FLUX 3 Video（BFL，带同步音频）、Seedance（1.0 / 1.5 Pro / 2.0 / 2.5）、Luma、Runway、MiniMax（含 H3、API + 本地开放权重）、PixVerse、Vidu、Pika、Sync 3（唇形同步）、HeyGen（虚拟形象视频、会说话的照片、视频翻译、TTS）、HappyHorse、HuMo、SCAIL-2；（音频）Stable Audio、ACE-Step、MiniMax Music 3（开放权重、带人声的完整歌曲，随 core v0.33.1 发布）、ElevenLabs、ChatterBox、Seed Audio、Sonilo；（3D）Hunyuan3D、Tripo、Rodin、Meshy；（较新／小众）Capybara、Bernini-R、Anima（含 ControlNet-LLLite 控制和局部重绘补丁）、NewBie、PixelDiT、Ovis-Image、Lens、Quiver。

**说话头像路由：**对于静态肖像加音轨，Sync 3 和 HeyGen Talking Photo 都适用；如果任务纯粹是对已有素材进行高保真唇形同步，优先选择 Sync 3；如果需要模型朗读脚本（内置文本转语音和语音库）或制作可重复使用的虚拟形象，则选择 HeyGen。两者都不需要场景提示词。

其中还包含一个增强与实用工具部分（不由提示词驱动，应作为带设置的处理流程步骤，而非提示词使用）：放大／修复／插帧（Real-ESRGAN、SUPIR、SeedVR2、FlashVSR、Topaz、Magnific、FILM、RIFE），以及分割／深度／姿势／条件控制（SAM3、BiRefNet、Depth Anything、DWPose、MoGe、IP-Adapter、LivePortrait、Mediapipe），还有视频对象移除（VOID）。对于其中未详细介绍的任何模型，备用方案是模板库 + /object_info；相应的官方文档链接即为参考来源。

图内 Claude 节点（第 3 层）：选择合适的节点

安装后可以有三个 Claude 节点；它们在计费方式和用途上各不相同（参见 docs/NODES.md）：

• AnthropicClaudeNode（类别 LLM/Anthropic，社区节点，使用你自己的密钥），提供 40 多个模板，可针对特定模型改写提示词（Ideogram 3、LTX 2.5、LTX 2.3 / LTX 2 Pro、Wan 2.1 & 2.2、FLUX、Nano Banana、Veo 3、Sora 2 等）。支持视觉和扩展思考。需要设置 CLAUDE_API_KEY 环境变量。用于在图内自主增强提示词的主力节点。
• ClaudeNode（类别 partner/text/Anthropic，官方 Comfy-Org 节点），通过 Comfy.org 积分计费，无需自己的密钥。支持最新的 Opus 模型。备用方案。
• ClaudeCustomPrompt（Claude 提示词生成器），简单易用，将 api_key 作为字符串输入。

只有当工作流必须在没有 Claude 参与的情况下增强提示词时，你才需要 Claude 节点（例如，无人值守的自动主视觉生成工作流）。如果你已经在操作，自己编写提示词就好，这样更好，而且免费。

构建工作流并在所有者的 GUI 中显示（双向桥接）

所有者可能想在自己的 ComfyUI 画布中查看 Claude 构建的图并进行调整。桥接目录是 GUI 工作流文件夹，双方都可以读写：<ComfyUI>/user/default/workflows/。

请牢记这两种 JSON 格式：

• GUI 格式（画布加载和“Save”生成的格式）：顶层包含 nodes（每个节点包含 id、type、pos、size、widgets_values、inputs、outputs）、links、groups。将此格式写入 workflows 文件夹，以便所有者打开并查看图。按照从左到右的列自动布局节点（加载器 -> 编码 -> 采样器 -> 解码 -> 保存），每个阶段使用一个 Group 框，并为每列设置 y 游标，确保节点不会重叠。具体规范请参阅下文“整齐布局图”。
• API 格式（/prompt 执行的格式）：{ "<id>": {class_type, inputs} }。以此格式发送即可在无界面模式下运行。

流程：

• Claude 构建 -> 将 GUI 格式的 .json 写入 user/default/workflows/<name>.json -> 告知所有者刷新内置的 Workflows 侧边栏（文件夹图标）并打开文件 -> 所有者就能看到 Claude 构建的完整内容。
• 所有者构建或编辑 -> 使用 Save (API Format) 保存到共享的 workflows/ 文件夹 -> Claude 读取并运行。

清晰地布局图表（结构化区块，不重叠）

节点堆在 0,0 处或彼此重叠的图表无法在画布中使用。请像真正的流水线一样布局。每个节点都包含 pos:[x,y] + size:[w,h]；每个区块都是一个 groups 条目 {title, bounding:[x,y,w,h], color}。请计算位置，切勿凭目测摆放。

• 列 = 阶段，严格从左到右。 每个流水线阶段占一列（加载器 -> 条件处理 -> 采样 -> 解码 -> 保存 -> 后处理）。列的 x 坐标 = x0 + col * COL_W，COL_W = 最宽节点的宽度 + 80（通常约为 360）。数据流绝不向后（不接从右到左的连线）。
• 每列的 y 光标 = 确保不重叠。 将一列中的节点从上到下堆叠：y = y0；放置一个节点后，再执行 y += node_h + 60。下一个位置始终会避开上一个节点的完整高度，因此同一列中的节点不会重叠；COL_W >= 最宽节点宽度 + 80 则可避免水平方向重叠。请从模板读取真实的 size（假设约为 [320,200]，KSampler / CLIPTextEncode 更高）。绝不要让两个节点拥有相同的 pos。
• 每个阶段一个分组框（这是让图表呈现区块结构的关键）。 放置完某个阶段的节点后，添加一个分组，其 bounding 范围需包住这些节点并留出边距：[minX-30, minY-50, (maxX+w)-minX+60, (maxY+h)-minY+80]（标题栏上方留出额外空间）。标题使用阶段名称（“加载模型”“条件处理”“采样”“解码 + 保存”“放大”“图像转视频”）；按颜色区分（加载器为灰色，条件处理为蓝色，采样器为绿色，解码/保存为紫色，后处理为橙色）。共享加载器放在左上方的一个分组中，为每个阶段提供输入。
• 用 Reroute 节点整理较长或交叉的连线。 当共享输出必须连接到较远的列时，插入 Reroute 节点，让连线沿分组之间的水平走线槽延伸，而不是斜穿整个图表。这样能消除杂乱的连线。
• 保存前进行整理。 同一列中的节点宽度一致，左边缘对齐，种子节点 + 保存节点放在最后，所有节点都位于所属分组框内，分组框之间不得重叠。使用 MCP 时，visualize_workflow_hierarchical 会渲染布局，让你在交给负责人之前就能看到重叠问题。

将一个阶段折叠为可复用节点（Subgraphs）

ComfyUI Subgraphs（自 2025-08 起成为官方功能；它们取代了旧版 Group Nodes，后者仅为向后兼容而保留）可以让你选择一组节点并将其折叠成一个超级节点，只公开你关心的少数参数。这是构建和复用流水线模块最简洁的方式：经过测试的 20 节点放大或视频阶段可变成只有 3 个调节项的单个节点，并可嵌套到更大的流水线中。

在 GUI 中（告诉负责人，或者在操作时自行执行）：

• 折叠： 选择节点（以及分组和 reroute 节点），点击工具栏中的子图图标。ComfyUI 会自动连接所选内容与外部输入/输出之间的边界。
• 在内部编辑： 双击子图的空白区域进入；按 Esc 或使用顶部导航栏退出（导航栏会显示嵌套层级）。
• 只公开重要内容： Edit Subgraph Widgets 按钮（参数面板）可以重新排序并显示/隐藏小组件，无需进入子图；在编辑模式中，右键点击边界槽位即可重命名/删除/断开连接，带标签的默认槽位可添加新的输入/输出。显示种子/步数/cfg/提示词，隐藏其余内容。
• 将其制作为可复用模块： Add Subgraph to Library（发布/书本图标，ComfyUI v1.27.7+）会将其变成 Subgraph Blueprint，可像任何节点一样搜索和拖动。这正是本工具包 blueprints/ 中的模块。
• 可将子图嵌套在其他子图中，构建分层流水线；Unpack subgraph（右键点击或使用选择工具箱）可将其还原为原始节点。

自己构建 JSON 时（而非通过点击操作）：内部图表位于 definitions.subgraphs[]；外部 SubgraphNode 通过 properties.proxyWidgets 暴露参数，通过子图的输入/输出节点定义边界 I/O（请参阅上文的模板读取说明）。每个阶段交付一个整洁的模块，而不是 20 个松散的节点。来源：docs.comfy.org/interface/features/subgraph；blog.comfy.org/p/subgraph-official-release。

创作者级深度：优势、实际限制与高级序列处理

完整的创作者级参考（优势、实际问题及解决方法、高级序列技巧，以及经过验证并附带许可证的工具表）位于 ADVANCED.md（在已安装技能中与此文件同目录，或在仓库的 docs/ADVANCED.md 中）。处理复杂任务时请阅读。即使不打开文档，也要记住以下关键问题：

• 解码后图像变黑/出现 NaN，或颜色/对比度发生偏移 = VAE。 使用 --fp32-vae（或 --bf16-vae），只在最后解码一次，并通过直方图/LAB 匹配还原源素材。VFX 中绝不要使用 fp16 VAE。
• 自定义节点不再运行是 IS_CHANGED 陷阱：使用 return float("NaN") 强制重新运行。更改种子却没有效果 = 缓存过期；修改一个输入以清除缓存。
• **每次生成都重新加载模型，或 4090/5090 速度变慢（2026 年初及以后）**是 Dynamic VRAM 导致的：如果造成影响，请使用 --disable-dynamic-vram。
• 大型图的画布帧率只有个位数，问题出在 litegraph，而不是后端：将图折叠成子图，并静音分组。
• **自定义节点存在真实的恶意软件风险，且可能因 core/numpy 升级而失效：**只从经过验证的作者处安装，并固定版本。

该技能现在能够处理的高级任务（经过验证的工具和配方见 ADVANCED.md）：

• **序列的时间稳定性/抗闪烁：**原生视频模型（Wan 2.2 + VACE / HunyuanVideo 1.5 / LTX-2）> 上下文窗口 + FreeNoise > 逐帧深度/姿态 ControlNet 锁定结构 > 轻量 RIFE + 轻量去闪烁。SD 时代方案：反采样（Flip Sigma、Euler、关闭 add-noise）+ 流注意力。精细纹理/身份特征和窗口接缝仍会闪烁。
• **从影像素材生成 PBR/材质通道：**坦诚地说，截至 2026 年，原生且时间稳定的 PBR 还无法从 2D 序列中实现。逐帧分解（Apache-2.0 的 Marigold-IID + StableNormal + StableDelight）+ 光流时间平滑是现实可行的方案；rgb2x / CHORD 保真度更高，但不可商用；UniRelight 是唯一真正具备时间一致性的方法（仅反照率、不可商用、无节点）；TRELLIS.2（MIT）可生成真实 PBR，但应用于 3D 网格，而非逐帧处理。
• **最高细节 + 精确度：**使用平铺细化（Ultimate SD Upscale / Tiled Diffusion）+ ControlNet Tile 处理接缝，使用 Detail Daemon / PAG / FreeU 增强微细节，采用 dpmpp_2m + Karras，步数约为 20-35，使用 32 位 EXR 序列 I/O（HQ-Image-Save、CoCoTools）+ sRGB/Linear 转换进行 VFX 处理。逐帧细节与跨帧稳定性之间确实存在取舍（SeedVR2 批量处理 >= 5，或锁定结构，仅改变精细细节）。
• 高细节抠像（头发/毛发/半透明物体/运动模糊）：多阶段流程：粗选（SAM3 / BiRefNet）-> trimap -> Alpha Matte（ViTMatte / SDMatte / Matte-Anything）-> 边缘细化（LayerStyle MaskEdgeUltraDetailV2）。视频方案 = 时间模型 MatAnyone2（需要 SAM2/SAM3/SeC 关键帧蒙版；NTU 研究许可），或用于干净人物的 RVM。官方库提供 remove_background_birefnet（图像）+ SAM3 分割，但没有免费的本地时间视频抠像工具（视频抠像模板需付费使用 Bria API）。完整配方见 ADVANCED.md。
• 保持两种格式同步：构建一次，同时输出两种格式。编写前请通过 /object_info/<NodeType> 验证节点名称和输入，避免他打开图时出现红色/损坏节点。

无需额外的“Agent 面板”节点；内置的 Workflows 侧边栏就是连接桥梁。（comfyui-mcp 生态提供可选的实时流式面板；它只是锦上添花，并非必需。）

模型存放位置及下载方式（先检测，不要假设）

ComfyUI 会从一个或多个模型根目录读取模型。在 源码安装 中，根目录是 <ComfyUI>/models/<type>/。在 Comfy Desktop 中，当前使用的根目录通常是通过 extra_model_paths.yaml 设置的共享文件夹，而不是 <ComfyUI>/models。下载前务必检测实际根目录；放错文件夹的文件对 ComfyUI 不可见。

先检测实际模型根目录：

• 查看 ComfyUI 启动日志：每种模型类型都会显示 Adding extra search path <type> <PATH>，还会显示 Setting output/input directory to: ...。这些 PATH 才是准确信息（使用 MCP get_logs，或查看 Desktop 日志文件）。
• 或查看 <ComfyUI>/extra_model_paths.yaml（以及 .example）。
• 或询问正在运行的服务：/object_info/CheckpointLoaderSimple、/UNETLoader、/VAELoader、/CLIPLoader 会列出当前可见的文件；放入文件后查询，即可确认文件夹配置正确。

模型类型 -> 子文件夹（位于检测到的根目录下）：

• diffusion / UNET 单文件模型 -> diffusion_models（有时是 unet）
• 完整 checkpoint（打包了 model、clip、vae；部分视频模型如 LTX 采用这种形式）-> checkpoints
• 文本编码器 / CLIP（T5、umt5、gemma、clip_l、llava）-> text_encoders（较旧的安装：clip）
• VAE -> vae · LoRA -> loras · 放大模型（ESRGAN 等）-> upscale_models
• ControlNet -> controlnet · IP-Adapter -> ipadapter · CLIP vision -> clip_vision

下载方式（兼容 Desktop）：

• 直接下载最可靠：curl -fL -C - -o "<root>/<type>/<filename>" "<url>"。使用 Comfy-Org 重新打包的 Hugging Face 仓库（直接使用 .../resolve/main/... 链接）。-C - 可续传未完成的文件。 大型模型（数十 GB）可以在后台下载；下载后请确认文件大小。
• COMFYUI_PATH 不仅控制下载，还控制一整类 MCP 工具。 未设置时，任何读取安装目录文件系统（而非 HTTP API）的工具都会报错 COMFYUI_PATH is not configured： 最先遇到的通常是 list_output_images，因为这是查找刚渲染内容的常用方式。 此问题已于 2026-08-06 在实际运行中确认。**无需配置即可绕过：**从 GET /history/<prompt_id> 获取文件名，再通过 GET /view?filename=...&type=output&subfolder=... 获取文件内容；这完全通过 HTTP 实现，始终可用。若还要使用文件系统工具，请将 COMFYUI_PATH 设为实际的 ComfyUI 根目录。
• 只有在 MCP 服务设置了 COMFYUI_PATH 时，MCP download_model 才能工作；它会将文件写入 COMFYUI_PATH/models/<type>，而 Desktop 上这里通常不是共享根目录，因此 ComfyUI 可能看不到文件。请优先直接下载到检测到的根目录（或先将 COMFYUI_PATH 设为实际根目录）。
• 受限模型（例如 Stability Stable Audio）需要登录 Hugging Face 并接受许可：请模型所有者接受许可并放置文件，或提供 HF 令牌以进行身份验证下载。
• 每个模型所需的具体文件（diffusion model、text encoder，以及 VAE；还包括各文件应放置的文件夹）见模型的 docs.comfy.org/tutorials/... 页面；请按页面说明操作，不要猜测量化等级或文件名。
• 下载后，请确认 ComfyUI 能识别该文件：重新查询 /object_info/<LoaderNode>。大多数模型文件夹会实时刷新； 新建的子文件夹可能需要刷新 Workflows 侧边栏。

为这台机器选择合适的模型变体（基于硬件，下载前给出建议）

安装或下载模型前，先根据实际硬件评估模型大小，然后给出建议，不要盲目下载。 检测以下三个数值，并与模型占用空间进行比较。

检测（复用启动阶段的机器信息块，或重新检测）：

• 每张 GPU 的 VRAM（可用 + 总量）：使用 MCP get_system_stats / health_check，或 GET /system_stats （devices[].vram_free / vram_total）。如果有两张显卡，请分别记录。
• 系统 RAM（可用 + 总量）：同样查看 /system_stats。RAM 会影响权重卸载和溢出。
• 模型所在磁盘的可用空间：检查存放已检测到的模型根目录的磁盘（不是系统盘）。 在 Git Bash 中运行 df -h "<model root>"，或使用平台对应的命令。下载文件可能达到几十 GB；空间不足时绝不要开始下载。

估算模型占用空间：

• 所需 VRAM 大致等于扩散模型的磁盘权重大小，加上 VAE、文本编码器和激活值 （经验法则：权重大小 + 约 2-6 GB 余量；视频模型的潜在帧会占用更多空间）。
• 精度梯度，越小越容易装下：bf16/fp16（完整）> int8-convrot 和 fp8（约一半）> GGUF Q8 > Q6 > int4-convrot 和 Q4（最小）。MODELS.md 列出了每个模型的推荐变体及 VRAM 注意事项。
• 在半尺寸档位，优先选择 int8-convrot，除非模型只提供 fp8。 自 core v0.27.0 起已原生支持， 运行速度快于 fp16，质量与 fp8 持平或更好，并明确支持 Turing 和 Ampere（RTX 20xx / 30xx）。 完整方法、ConvRot 论文、转换工具和已知的 int8 问题均见 docs/ADVANCED.md；选择变体前请先阅读， 因为这一行只是摘要，并非全部规则。
• “Pruned”是第四个维度，不是精度梯度中的一级。 Pruned 检查点会丢弃权重，而不是降低权重精度， 因此可以与以上任一选项叠加，其质量损失因模型而异。 nvfp4 是 Blackwell 世代格式（RTX 50xx）；Ampere 不支持此选项。
• 磁盘下载大小大致等于所有文件（模型 + 编码器 + VAE）的总和。请先计算总大小。

判断并给出建议：

• 一张显卡可装下且留有余量 -> 使用完整精度。
• 略超出一张显卡的容量 -> 使用 ComfyUI 权重卸载（权重放在 RAM 中，按需传输到 VRAM）或 fp8 变体； 建议采用该方案，不要强行使用 bf16。
• 远超一张显卡的容量，但两张卡合计可装下 -> 使用 MultiGPU DisTorch 分层拆分（仅在此情况下；速度较慢）。
• 即使拆分也超出总 VRAM，但 RAM 充足 -> 使用 CPU/RAM 卸载（速度较慢）或 GGUF Q4/Q5；建议使用量化版本。
• 任何精度下 VRAM 都不足，或磁盘可用空间不足 -> 不要下载。请说明具体差额（例如 “LTX-2.3 fp8 磁盘占用约 28 GB，需要约 24 GB VRAM，但模型所在磁盘只有 12 GB 可用”），并给出成本最低的解决方案（较小的变体、释放磁盘空间，或跳过）。
• 与其他 GPU 用户（Ollama）协调：可用 VRAM 可能已被占用，参见 VRAM 部分。

**每次下载前都必须：**将下载文件总大小与模型所在磁盘的可用空间进行比较，并将模型的 VRAM 需求与运行它的显卡进行比较。说明判断结果，让设备所有者了解推理过程，而不只是看到结果： “装得下，正在下载” / “24 GB 装不下，改用 fp8” / “E: 只有 10 GB 可用，无法容纳约 28 GB，停止”。

使用多块 GPU（这并不像分层切分的 LLM 服务）

一次生成只在一块显卡上运行；ComfyUI 不会自动将单个小任务分摊到多块显卡上。MultiGPU 节点（SelectModelDevice、SelectCLIPDevice、SelectVAEDevice、MultiGPU_WorkUnits）的优势：

• 将组件分配到不同显卡上（model -> cuda:0，CLIP + VAE -> cuda:1）：释放主显卡上的 VRAM，让大型模型（大型视频/图像模型）能够运行。
• DisTorch 分层切分（MultiGPU_WorkUnits）：将模型层分配到多块显卡上，供无法在一块显卡上运行的模型使用。只有当模型无法装入一块显卡时才使用。
• 提高并行吞吐量：同时运行两次独立生成，每块显卡各一次（非常适合批处理）。这不是把一张图像切分开来，而是生成双倍数量的图像。

涡轮图像模型通常能装入一块 24GB 显卡；大型视频任务才需要使用多 GPU。

VRAM 协调（重要注意事项）

如果其他工作负载（例如通过 Ollama 运行的本地 LLM）也在使用相同的 GPU，就会争用资源。在运行 ComfyUI 大型批处理之前，检查 GET /system_stats 中的可用 VRAM；如果较低，说明显卡正被其他工作负载占用。可选方案：释放显卡（ollama stop <model> / 停止其服务），运行批处理，然后让它重新加载；或者等其他工作负载空闲时再运行 ComfyUI。重新安装 NVIDIA 驱动后，请重启其他 GPU 服务（否则它可能会退回到 CPU）。

绝不要通过 MCP 重启 Comfy Desktop（重要注意事项）

对于 Comfy Desktop 安装，不要通过 MCP 调用 restart_comfyui / start_comfyui / stop_comfyui。 MCP 重新启动时会假设通过 CLI 启动（python main.py），因此会因 spawn ComfyUI\main.py ENOENT 而失败：它会终止服务，却无法将其重新启动，因为 Desktop 是一个 Electron 应用，会使用自己的参数（端口、指向共享模型目录的 extra_model_paths）启动服务。手动重新运行 python main.py 也会遗漏这些配置（可以通过传入 --base-directory / --extra-model-paths-config 修复，见下文“自行启动 ComfyUI”）；而且无法从非交互式 shell 启动 Electron GUI 窗口（但你不需要 GUI，只需要服务）。因此：不要通过 MCP 重启 Desktop；请自行启动服务。若要加载新安装的自定义节点，请让所有者重新打开应用。对于 CLI/源码版 ComfyUI，使用 MCP 重启没有问题。

ComfyUI 停止时自行启动（自动启动服务）

要进行生成，你需要的是 ComfyUI 服务端（端口 :8188 上的 API），而不是 GUI 窗口。服务端停止时，请自行在后台启动，而不是只让所有者打开应用。你需要使用记录的启动命令（保存在 BOOTSTRAP 机器信息块中），然后启动服务并等待 :8188 响应。

• 源码 / CLI 安装： 在 ComfyUI 目录中，将 python main.py 作为后台进程运行。它会绑定到 :8188（这是控制台服务，不是 GUI，因此可以通过后台 shell 启动）。只有在收到要求时才添加 --listen / --port。

• Comfy Desktop（Electron）： 无界面启动捆绑的服务端，而不是 Electron 窗口。在 ComfyUI 核心目录中，用 Desktop 的 venv Python 运行 main.py，并让它使用共享模型：直接运行 python main.py 可能会加载错误的（空）模型目录，因此请传入 --base-directory <Desktop base> 或 --extra-model-paths-config <the Desktop's extra_model_paths.yaml>，以便找到共享模型。每台机器只需在 BOOTSTRAP 机器信息块中记录一次准确可用的命令（进行测试：启动后，确认 /object_info/UNETLoader 列出了实际模型）。只有当所有者想要查看或调整画布时，才需要 GUI。

• Windows：启动时设置 PYTHONUTF8=1（或 PYTHONIOENCODING=utf-8）。自定义节点会记录表情符号（例如，rgthree 的“Loaded 48 nodes”后带有派对表情符号）；如果控制台代码页不是 UTF-8（例如 cp1251），日志记录器就会抛出 UnicodeEncodeError，导致启动中途崩溃（此时模型路径已经读取）。Desktop 应用会自行设置 UTF-8；直接无界面启动时也必须设置。已验证：不设置时，服务端会在启动时退出；设置后则能正常启动。

• 请勿在 Desktop 安装中使用 MCP restart_comfyui / start_comfyui（见上文的注意事项）；请使用自己记录的命令。

• 如果应用进程已经存在，但 :8188 没有响应， 服务端可能正在启动（首次启动时加载模型），也可能卡住了。等待一会儿并轮询；如果仍然没有响应，请让所有者重新打开应用，不要启动第二个服务端（两个服务端无法共用 :8188）。

• 向所有者展示正在运行的服务端： 无界面服务端已经在 http://127.0.0.1:8188 提供完整的 ComfyUI Web UI。若要让所有者查看画布或你创建的内容，请告知他们在浏览器中打开该 URL（界面与 Desktop 窗口相同），而不是点击 Comfy Desktop 快捷方式：该快捷方式会在 :8188 上启动第二个服务端并产生冲突。关闭浏览器标签页不会停止你的服务端。如果他们想使用完整的 Desktop 应用，请先停止你的服务端，然后让他们打开应用，再重新连接到应用的服务端。

启动后，轮询 GET /system_stats，直到收到响应（首次启动时，加载模型可能需要 10-30s），然后继续操作，并告知所有者你已启动服务端。

会话协议（询问如何启动，并保存工作流，方便所有者稍后查找）

两种访问模式，加上一条持久化规则。明确告知所有者，避免遗漏任何内容。

启动（ComfyUI 未运行时先询问）。 如果 :8188 已在运行，就直接使用（所有者已打开 ComfyUI，或服务正在运行），不要再启动另一个实例。如果服务未运行，只询问一次：“你是想自己打开 ComfyUI，由我连接；还是要我以无头模式启动服务（你可以在浏览器中查看 http://127.0.0.1:8188）？” 按照对方的选择操作；如果对方说“以后就自动启动”，记住这一偏好，下次跳过询问。

配置启动策略（项目 + 流水线）。 询问只适用于交互式场景。无人值守的流水线必须提前设置选项，确保 Agent 不会卡住。按以下顺序解析，以最先找到的配置为准：

1. 环境变量（优先级最高，适用于 CI / 单次运行）：COMFY_HOST（服务所在位置）；COMFYUI_START_POLICY = connect（使用正在运行的服务，若未运行则明确报错）| autostart（若服务未运行则启动无头服务）| ask（交互式）；COMFYUI_LAUNCH_CMD（autostart 使用的无头启动命令）。
2. **项目配置：**项目根目录下的 .comfyui-agent.json，例如： { "host": "127.0.0.1:8188", "startPolicy": "autostart", "launchCmd": "..." }。与项目一同提交，确保每个项目的流水线可复现。
3. **机器默认设置：**此技能机器配置块中的启动命令 + 主机。
4. **回退：**交互式场景 -> 询问；非交互式且未设置任何配置 -> 使用 connect，并明确报错（在 CI 中，未获指示时不要静默启动服务）。

因此，交互式场景会询问所有者；流水线只需设置一次 COMFYUI_START_POLICY=autostart + COMFYUI_LAUNCH_CMD（或创建 .comfyui-agent.json），之后即可无人值守运行。comfy_client 已读取 COMFY_HOST。以下持久化规则在两种场景中完全相同。

持久化（务必遵守，这是最重要的一条）。 每当你为所有者构建或运行工作流时，都要将其保存为 GUI 格式的 .json 文件，放入 <ComfyUI>/user/default/workflows/，并使用清晰且带日期的名称（例如： 2026-06-21_zimage_hero.json）。该文件会永久保存在用户目录中，因此即使无头服务停止，或之后使用 Desktop 会话，所有者仍可稍后从 Workflows 侧边栏打开它。仅通过 API 生成不会在画布上留下任何内容，因此不保存的话，你的工作就不会显示在那里。（GUI 格式的实现方式请参见双向桥接部分。）

交接。 完成后，告知所有者三件事：已保存的工作流名称（位于 Workflows 下）、输出文件的位置，以及现在如何查看（浏览器 :8188，或随时打开已保存的工作流）。如果对方需要完整的 Desktop 应用，先停止无头服务，释放 :8188 供应用使用。

操作流程（每次都执行）

1. 执行 health_check（MCP）或 comfy_client.alive()。如果服务正在运行，就使用它。如果未运行，遵循会话协议：询问所有者如何启动，或在所有者已明确选择后，使用记录的启动命令自动启动无头服务；等待 :8188 就绪，然后继续。新机器 -> 先执行 BOOTSTRAP。
2. 从模板克隆库中选择或加载合适的模板（根据 _quick_index.json 中的模型 / 标签进行匹配）。如果没有合适的模板，则构建图，并对照 /object_info 验证节点类型。
3. 通过 /system_stats 检查 VRAM；如果 VRAM 不足，与其他 GPU 任务协调。
4. 设置参数（提示词、不同的种子、尺寸），运行并获取输出。
5. 使用前先目视验证输出（读取已保存的图像 / 通过 MCP 查看）。绝不要交付未经查看的生成结果。
6. 务必将构建或运行的工作流保存为 GUI 格式的 .json 文件，放入 <ComfyUI>/user/default/workflows/，并使用清晰且带日期的名称（参见会话协议），方便所有者之后查找和打开。然后完成交接：告知名称、输出位置和查看方式。