\r \r

ComfyUI 工作流客户端\r

\r

概述\r

\r 本技能封装了 ComfyUI 工作流调用能力，用于通过 ComfyUI API 生成图片和视频。核心功能包括：加载工作流 JSON、修改 prompt 和图片节点、提交到 ComfyUI 队列、轮询任务状态、自动下载生成结果。\r \r 适用场景：\r

• 用户要求根据文本描述生成图片\r
• 用户要求根据参考图生成变体或编辑\r
• 用户要求生成图片转视频、图生视频\r
• 需要批量或自动化调用 ComfyUI 工作流\r \r 前置条件：\r
• ComfyUI 服务已启动（默认 http://127.0.0.1:8188）\r
• 工作流 JSON 文件可用\r
• 工作流所需模型已安装到 ComfyUI\r \r

触发条件\r

\r 当满足以下条件时应使用此技能：\r \r

1. 用户表达生成意图\r
   • 要求"用 ComfyUI 生成图片"、"根据 prompt 画图"\r
   • 要求"图生图"、"图片编辑"、"生成视频"\r
   • 提供文本描述并希望得到 AI 生成的图像\r \r
2. 技术上下文明确\r
   • 用户提到 ComfyUI、工作流、txt2img、img2img 等\r
   • 用户提供工作流文件路径或项目内已知工作流\r \r
3. 服务可用\r
   • 可先检查 ComfyUI 服务是否可访问\r
   • 若不可用，应提示用户启动 ComfyUI\r \r

捆绑资源\r

\r 脚本： scripts/comfyUIClient.js - ComfyUI 工作流调用主脚本\r \r 工作流： assets/workflows/ - 5 个常用工作流（Z-Image、Qwen 编辑、Wan 视频等）\r \r 执行方式：\r

• 技能内脚本：node .claude/skills/comfyui-client/scripts/comfyUIClient.js [选项]\r
• 项目脚本（等效）：node scripts/comfyUIClient.js [选项]\r \r 路径解析： 技能内脚本会自动解析项目根目录，工作流路径和输出目录支持相对路径（相对于项目根）。\r \r

核心能力\r

\r

1. 文生图（txt2img）\r

\r 使用文本 prompt 生成图片。\r \r 基本用法：\r

node scripts/comfyUIClient.js --workflow \x3C工作流路径> --prompt "\x3C提示词>"\r
```\r
\r
**示例：**\r
```bash\r
# 使用技能内工作流（推荐）\r
node .claude/skills/comfyui-client/scripts/comfyUIClient.js \\r
  --workflow .claude/skills/comfyui-client/assets/workflows/image_z_image_turbo.json \\r
  --prompt "a beautiful landscape at sunset"\r
\r
# 带负面提示词\r
node .claude/skills/comfyui-client/scripts/comfyUIClient.js \\r
  --workflow .claude/skills/comfyui-client/assets/workflows/image_z_image_turbo.json \\r
  --prompt "a beautiful landscape at sunset" \\r
  --negative-prompt "blurry, low quality, watermark"\r
```\r
\r
**自动查找 prompt 节点：** 若不指定 `--prompt-node`，脚本会自动查找工作流中标题含 "Positive" 的 `CLIPTextEncode` 节点注入正面 prompt，标题含 "Negative" 的节点用于负面 prompt。对于 `TextEncodeQwenImageEditPlus`，优先选择有非空文本或标题含 "Positive" 的节点。\r
\r
### 2. 指定 prompt 节点\r
\r
当工作流中有多个 CLIPTextEncode 节点时，可指定要修改的节点 ID。\r
\r
```bash\r
node scripts/comfyUIClient.js --workflow \x3C工作流路径> --prompt-node "45" --prompt "新的提示词"\r
```\r
\r
### 3. 图生图 / 图片编辑（img2img）\r
\r
需要提供输入图片。可使用 `--image-path` 指定本地路径（自动上传到 ComfyUI），或先将图片放入 ComfyUI 的 `input/` 目录后使用 `--image-file` 指定文件名。\r
\r
#### 3a. Z-Image Turbo + ControlNet（结构引导重绘）\r
\r
基于 Canny 边缘检测提取输入图片轮廓，用 ControlNet 引导模型生成新图。适合风格转换、基于轮廓的重绘。\r
\r
- **输入**：1 张图片 + 文本 prompt\r
- **速度**：快（9 步，CFG=1）\r
- **LoadImage 节点 ID**：`58`\r
- **Prompt 节点**：自动查找（子图内部 CLIPTextEncode 会被展开到顶层）\r
\r
```bash\r
# 使用 --image-path 自动上传本地图片（推荐）\r
node .claude/skills/comfyui-client/scripts/comfyUIClient.js \\r
  --workflow .claude/skills/comfyui-client/assets/workflows/image_z_image_turbo_fun_union_controlnet.json \\r
  --prompt "oil painting style, vibrant colors" \\r
  --image-node 58 --image-path "path/to/input_photo.png"\r
\r
# 或使用已上传到 ComfyUI input/ 的图片\r
node .claude/skills/comfyui-client/scripts/comfyUIClient.js \\r
  --workflow .claude/skills/comfyui-client/assets/workflows/image_z_image_turbo_fun_union_controlnet.json \\r
  --prompt "oil painting style, vibrant colors" \\r
  --image-node 58 --image-file "input_photo.png"\r
```\r
\r
> 注意：该工作流使用子图（subgraph），脚本会自动展开子图内部节点。\r
\r
#### 3b. Qwen 图片编辑（语义级多图编辑）\r
\r
基于 Qwen 视觉语言模型的智能编辑。支持自然语言编辑指令和最多 3 张参考图片。适合材质替换、风格迁移、多图参考编辑。\r
\r
- **输入**：1-3 张图片 + 自然语言编辑指令\r
- **速度**：中等（20 步，CFG=4）\r
- **LoadImage 节点 ID**：主图 `41`，参考图2 `83`，参考图3 `87`（默认禁用）\r
- **Prompt 节点 ID**：正面 `68`，负面 `69`\r
- 可选 Lightning LoRA 加速到 4 步（节点 74，默认禁用）\r
\r
```bash\r
# 单图编辑\r
node .claude/skills/comfyui-client/scripts/comfyUIClient.js \\r
  --workflow .claude/skills/comfyui-client/assets/workflows/image_qwen_image_edit_2511.json \\r
  --prompt-node 68 --prompt "将背景改为海边夕阳" \\r
  --image-node 41 --image-file "sofa.png"\r
\r
# 多图材质替换（图1 主图 + 图2 参考材质）\r
node .claude/skills/comfyui-client/scripts/comfyUIClient.js \\r
  --workflow .claude/skills/comfyui-client/assets/workflows/image_qwen_image_edit_2511.json \\r
  --prompt-node 68 --prompt "Change the furniture leather in image 1 to the fur material in image 2." \\r
  --image-node 41 --image-file "leather_sofa.png" \\r
  --image-node2 83 --image-file2 "texture_fur.png"\r
```\r
\r
> 注意：Qwen Edit 工作流的 prompt 节点不是 CLIPTextEncode，需使用 `--prompt-node 68` 明确指定。\r
\r
#### 3c. 两种图片编辑工作流如何选择\r
\r
| 维度 | **Qwen 图片编辑** | **Z-Image Turbo + ControlNet** |\r
|------|------------------|--------------------------------|\r
| 技术路线 | Qwen 视觉语言模型，语义理解 | Canny 边缘 + ControlNet 结构引导 |\r
| 输入 | 1–3 张图 + 自然语言指令 | 1 张图 + 文本 prompt |\r
| 速度 | 较慢（约 20 步） | 快（9 步） |\r
| 结构保持 | 依赖模型理解，可能变化 | 强约束，轮廓基本不变 |\r
\r
**Qwen 编辑适用场景：**\r
- 材质替换（如「把图 1 的皮质换成图 2 的毛绒材质」）\r
- 多图参考编辑（主图 + 1–2 张参考图）\r
- 语义级修改（背景、颜色、风格等需理解图像内容的编辑）\r
- 自然语言编辑指令（支持「将背景改为海边夕阳」等描述）\r
\r
**ControlNet 适用场景：**\r
- 风格转换（保持轮廓，只改风格，如照片→油画、素描）\r
- 轮廓重绘（基于边缘线生成新图，构图基本不变）\r
- 线稿上色、结构保持的变体\r
- 追求速度、快速出图\r
\r
**快速选择：**\r
- 需要**理解图像内容**做语义修改 → 选 **Qwen 编辑**\r
- 需要**保持构图/轮廓**做风格转换 → 选 **ControlNet**\r
\r
### 4. 视频生成\r
\r
支持 img2video、flf2video 等工作流。视频生成耗时较长，建议适当增加超时时间。\r
\r
```bash\r
node .claude/skills/comfyui-client/scripts/comfyUIClient.js --workflow .claude/skills/comfyui-client/assets/workflows/video_wan2_2_14B_i2v.json --prompt "视频描述" --timeout 900\r
```\r
\r
## 命令行选项\r
\r
| 选项 | 说明 | 默认值 |\r
|-----|------|--------|\r
| `--workflow \x3Cfile>` | 工作流 JSON 文件路径（必需） | - |\r
| `--server \x3Curl>` | ComfyUI 服务器地址 | `http://127.0.0.1:8188` |\r
| `--client-id \x3Cid>` | 客户端 ID | 自动生成 |\r
| `--prompt-node \x3Cnode_id>` | 要修改的 prompt 节点 ID | 自动查找 |\r
| `--prompt \x3Ctext>` | 新的 prompt 文本 | - |\r
| `--negative-prompt-node \x3Cnode_id>` | 负面 prompt 节点 ID | 自动查找 |\r
| `--negative-prompt \x3Ctext>` | 负面 prompt 文本 | - |\r
| `--image-node \x3Cnode_id>` | 主图 LoadImage 节点 ID | - |\r
| `--image-file \x3Cfilename>` | 主图已上传文件名（或上传后的目标名） | - |\r
| `--image-path \x3Cpath>` | 主图本地路径，将自动上传 | - |\r
| `--image-node2 \x3Cnode_id>` | 第二张参考图 LoadImage 节点 ID | - |\r
| `--image-file2 \x3Cfilename>` | 第二张参考图已上传文件名 | - |\r
| `--image-path2 \x3Cpath>` | 第二张图本地路径，将自动上传 | - |\r
| `--image-node3 \x3Cnode_id>` | 第三张参考图 LoadImage 节点 ID | - |\r
| `--image-file3 \x3Cfilename>` | 第三张参考图已上传文件名 | - |\r
| `--image-path3 \x3Cpath>` | 第三张图本地路径，将自动上传 | - |\r
| `--output-dir \x3Cdir>` | 输出目录 | `./work_dir/comfyui_output` |\r
| `--session-name \x3Cname>` | 会话名称 | 自动生成时间戳 |\r
| `--timeout \x3Cseconds>` | 超时时间（秒） | 600 |\r
| `--poll-interval \x3Cms>` | 轮询间隔（毫秒） | 1000 |\r
| `--help` | 显示帮助信息 | - |\r
\r
## 环境变量\r
\r
- `COMFYUI_SERVER_URL` - ComfyUI 服务器地址，可覆盖 `--server` 默认值\r
\r
## 输出结构\r
\r
每次执行会创建独立会话目录：\r
\r
```\r
work_dir/comfyui_output/\r
└── comfyui_\x3C时间戳>/\r
    ├── session_info.json    # 会话配置信息\r
    ├── workflow.json        # 实际提交的工作流（含修改后参数）\r
    ├── result.json          # 执行结果（prompt_id、生成文件列表等）\r
    ├── \x3CnodeId>_\x3Cfilename>  # 生成的图片/视频文件\r
    └── error.json          # 失败时的错误信息（如有）\r
```\r
\r
## 捆绑工作流（assets/workflows）\r
\r
本技能在 `assets/workflows/` 目录下捆绑了常用工作流，优先使用：\r
\r
| 工作流 | 路径 | 用途 | Prompt 节点 | Image 节点 |\r
|-------|------|------|------------|-----------|\r
| z_image_turbo | `.claude/skills/comfyui-client/assets/workflows/image_z_image_turbo.json` | 文生图（快速出图，9 步） | 自动 | - |\r
| z_image_turbo_controlnet | `.claude/skills/comfyui-client/assets/workflows/image_z_image_turbo_fun_union_controlnet.json` | ControlNet 结构引导重绘 | 自动（子图展开后） | `58` |\r
| qwen_image_edit | `.claude/skills/comfyui-client/assets/workflows/image_qwen_image_edit_2511.json` | Qwen 多图语义编辑 | `68`（正面），`69`（负面） | `41`（主图），`83`（参考2），`87`（参考3） |\r
| wan_i2v | `.claude/skills/comfyui-client/assets/workflows/video_wan2_2_14B_i2v.json` | Wan 2.2 图生视频 | 自动 | - |\r
| wan_flf2v | `.claude/skills/comfyui-client/assets/workflows/video_wan2_2_14B_flf2v.json` | Wan 2.2 首尾帧视频 | 自动 | - |\r
\r
## 其他工作流（项目内）\r
\r
| 工作流 | 路径 | 用途 |\r
|-------|------|------|\r
| txt2img | `scripts/githubToXPost/workflows/txt2img.json` | 文生图 |\r
| img_edit | `scripts/githubToXPost/workflows/img_edit.json` | 图片编辑 |\r
| controlnet | `scripts/githubToXPost/workflows/controlnet.json` | ControlNet 图生图 |\r
| img2video | `scripts/githubToXPost/workflows/img2video.json` | 图生视频 |\r
| flf2video | `scripts/githubToXPost/workflows/flf2video.json` | 首尾帧生成视频 |\r
\r
## 模块引用\r
\r
脚本支持作为 Node.js 模块引用，用于集成到其他工作流（如 githubToXPost 的 imageGenerator）。\r
\r
```javascript\r
const ComfyUIClient = require('./scripts/comfyUIClient');\r
\r
const client = new ComfyUIClient({\r
    workflowFile: 'scripts/githubToXPost/workflows/txt2img.json',\r
    prompt: 'a beautiful landscape',\r
    serverUrl: 'http://127.0.0.1:8188',\r
    outputDir: './work_dir/comfyui_output'\r
});\r
\r
const result = await client.execute();\r
console.log('生成文件:', result.generatedFiles);\r
```\r
\r
## 工作流格式说明\r
\r
脚本支持两种工作流格式：\r
\r
1. **ComfyUI 完整格式**（含 `nodes`、`links` 数组）- 自动转换为 API 格式\r
2. **API 格式**（以节点 ID 为 key 的对象）- 直接使用\r
\r
**自动预处理：**\r
- **子图展开**：包含 `definitions.subgraphs` 的工作流会自动展开子图内部节点到顶层，重映射连接关系\r
- **旁路节点处理**：`mode=4`（旁路）的节点自动透传输入到输出；`mode=2`（静音）的节点自动移除\r
- **非执行节点**：MarkdownNote、Note 等非执行节点会自动跳过\r
\r
## 错误处理\r
\r
### 常见问题\r
\r
**1. ComfyUI 服务不可用**\r
- 确认 ComfyUI 已启动\r
- 检查 `--server` 或 `COMFYUI_SERVER_URL` 是否正确\r
- 可访问 `http://127.0.0.1:8188` 验证\r
\r
**2. 工作流文件不存在**\r
- 确认 `--workflow` 路径正确\r
- 从项目根目录执行，或使用绝对路径\r
\r
**3. 任务超时**\r
- 视频生成等耗时任务可增加 `--timeout`（如 900 或 1200）\r
- 检查 ComfyUI 队列是否堆积\r
\r
**4. 模型缺失**\r
- 工作流所需模型需预先下载到 ComfyUI 的 `models/` 目录\r
- 参考工作流内的 Model links 或 MarkdownNote 说明\r
\r
## 最佳实践\r
\r
1. **执行目录**：始终从项目根目录执行，确保相对路径正确\r
2. **超时设置**：图片生成默认 600 秒，视频生成建议 900 秒以上\r
3. **工作流选择**：根据需求选择合适工作流（文生图、图生图、视频等）\r
4. **结果位置**：生成文件在 `work_dir/comfyui_output/\x3C会话名>/`，便于查找和管理\r