# 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 格式核心规则

### 节点结构
```python
{
    "节点ID(字符串)": {
        "class_type": "节点类型名",
        "inputs": { ... }
    }
}
```

### 节点间连接
```python
"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` 筛查死链和遗漏！