Tool_Agent/tools/local/runcomfy_workflow_builder/skill.md

Agent Skill: RunComfy Workflow Builder

本工具是一个 HTTP API 服务，外部 Agent 通过 /run_tool 调用，内部按 action 参数分发到不同功能。

调用方式

POST /run_tool
{
  "tool_id": "runcomfy_workflow_builder",
  "params": {
    "action": "...",
    ...其他参数
  }
}

支持的 action

action	参数	说明
read_skill	无	返回本文档内容，Agent 首次使用时应先调用此 action 学习规则
search_models	category, keyword	查询环境中可用的模型文件
get_node_schema	class_type	获取指定 ComfyUI 节点的必填/选填参数
list_examples	category, keyword	浏览/搜索示例工作流库
load_example	name	加载一个具体的示例工作流 JSON
verify_workflow	workflow	验证手写的 API JSON 是否合法

参数说明

• category: 模型搜索时为 checkpoints/loras/vaes/controlnets；示例搜索时为子目录名如 flux/controlnet/inpaint
• keyword: 模糊匹配关键词（大小写不敏感）
• class_type: ComfyUI 节点类型名，如 KSampler、ControlNetApplySD3
• name: 示例名，支持精确 stem（flux_dev_example）、相对路径（flux/flux_dev_example_api.json）、部分关键词（flux_dev）
• workflow: 完整的 API JSON 字典

---

🎯 推荐工作流程

① action=read_skill          → 学习本文档规则（首次）
② action=list_examples       → 搜索相关示例
③ action=load_example        → 加载骨架 JSON
④ action=search_models       → 确认环境有哪些模型
⑤ action=get_node_schema     → 确认不确定的节点参数
⑥ 修改 workflow dict
⑦ action=verify_workflow     → 验证 → 有错就修 → 再验证
⑧ 调用 runcomfy_workflow_executor 执行（注：executor 已支持通过 `url` 传入 CDN 图片）

---

📐 API JSON 格式核心规则

节点结构

{
    "节点ID(字符串)": {
        "class_type": "节点类型名",
        "inputs": { ... }
    }
}

节点间连接

"model": ["源节点ID", 输出索引]   # 例: ["4", 0]

• ID 必须是字符串 "4" 而非整数
• 连接必须是列表 ["4", 0] 而非元组
• CheckpointLoaderSimple: [id, 0]→MODEL, [id, 1]→CLIP, [id, 2]→VAE
• 布尔值用 Python bool（False 非 "false"）
• _meta 和 is_changed 字段可省略

---

🧠 架构差异速查

	SD 1.5	SDXL	Flux (UNET)	Flux (Checkpoint)
分辨率	512	1024	1024	1024
模型加载	CheckpointLoaderSimple	CheckpointLoaderSimple	UNETLoader+DualCLIPLoader+VAELoader	CheckpointLoaderSimple
采样器	KSampler	KSamplerAdvanced	SamplerCustomAdvanced	KSampler
CFG	6~8	6~8	1.0	1.0
引导	cfg 参数	cfg 参数	FluxGuidance 节点	FluxGuidance 节点
潜空间	EmptyLatentImage	EmptyLatentImage	EmptySD3LatentImage	EmptySD3LatentImage
负向提示	正常写	正常写	空字符串 ""	空字符串 ""

不确定细节？直接 action=load_example, name=flux_dev_example 看原文。

Flux 变体

模型	FluxGuidance	特殊节点
dev	3.5	ModelSamplingFlux
schnell	不需要	无（4步直出）
fill (inpaint)	30.0	DifferentialDiffusion + InpaintModelConditioning
canny/depth	30.0	InstructPixToPixConditioning
kontext	2.5	FluxKontextImageScale + ReferenceLatent
redux	3.5	CLIPVisionLoader + StyleModelApply

---

🔌 功能模块连接思路

不需要背模板，碰到具体需求直接 load_example 看真实 JSON：

功能	找哪个示例
LoRA	lora / lora_multiple
ControlNet (SD1.5)	controlnet_example / mixing_controlnets
ControlNet (Flux)	flux_controlnet_example / flux_canny_model_example
Img2Img	img2img_workflow
Inpaint	inpaint_example / flux_fill_inpaint_example
Outpaint	yosemite_outpaint_example / flux_fill_outpaint_example
超分	esrgan_example / 2_pass_pose_worship
风格迁移	flux_redux_model_example
图像编辑	flux_kontext_example

---

🚨 最易犯的错

1. Flux 写了 cfg: 8.0 → 应为 1.0，引导靠 FluxGuidance
2. 编造不存在的模型文件名 → 先 search_models 查
3. 节点 ID 写成整数 → 必须是字符串
4. 分辨率不匹配架构 → SD1.5=512, SDXL/Flux=1024，且必须是 8 的倍数
5. 凭记忆写节点参数 → 不确定就 get_node_schema 或 load_example 查
6. 提交执行前不主动做检查 → 组装图表后必须先 action=verify_workflow 筛查死链和遗漏！