ComfyUI 工作流 — 代理使用指南

⚠️ 只读警告：此技能中的脚本（comfyrun.py、comfyapi.py）已通过生产验证，严禁修改。它们处理 33 个以上的工作流 JSON，涉及复杂的 LiteGraph→API 转换、子图扩展、旁路解析和多格式输出下载。任何修改都可能导致所有工作流失效。仅可读取和使用这些脚本 — 切勿编辑。

环境要求

使用此技能前，请确保环境满足以下要求：

安装 Python 依赖：
bash
pip install websocket-client requests

配置选项

凭据

需要个人配置

使用此技能前，请确保已为您的环境配置以下项目：

快速设置

1. 启动 ComfyUI

在执行任何工作流之前，请手动启动您的 ComfyUI 服务器。此技能期望 ComfyUI 在配置的主机上运行。

2. 配置连接

创建 scripts/config.json：

json
{
comfy_host: 127.0.0.1:8188,
workflow_dirs: []
}

或设置环境变量：
bash
export COMFY_HOST=127.0.0.1:8188

3. 安装依赖

bash
pip install websocket-client requests

4. 添加工作流

将工作流 JSON 文件放入 workflows/ 目录，按类别组织：

workflows/
├── 图像-文本/
│ ├── workflow1.json
│ └── workflow2.json
├── 图像-编辑/
│ └── ...
└── 视频/
└── ...

Shell 变量（用于所有命令）

bash
VENV=python3 # 或您的虚拟环境路径
SCRIPT=/path/to/comfyui-workflow-skill/scripts/comfy_run.py

端到端工作流（步骤 0–5）

步骤 0 — 确保 ComfyUI 正在运行

手动启动 ComfyUI。验证可通过 http://127.0.0.1:8188 访问。

步骤 1 — 列出可用工作流

bash
$VENV $SCRIPT --list

步骤 2 — 检查工作流

bash
$VENV $SCRIPT -w workflow_name --inspect

步骤 3 — 准备输入

bash
--prompt 您的提示词 # 文本提示词
--image /path/to/image.jpg # 图像输入
--audio /path/to/audio.wav # 音频输入
--video /path/to/video.mp4 # 视频输入
--width 1024 --height 1024 # 分辨率
--steps 50 --cfg 4.0 --seed 42 # 采样器设置
--override {node_id: {key: value}} # 高级覆盖

步骤 4 — 执行

bash
$VENV $SCRIPT -w workflow_name --prompt ... -o /tmp

步骤 5 — 收集输出

输出保存到 -o 目录，带有自动生成的前缀。

CLI 参考

用法: comfy_run.py [-w WORKFLOW] [选项]

模式:
--list 列出所有可用工作流
--inspect 人类可读的输入/输出检查
--inspect-json 机器可读的 JSON 检查
--dry-run 打印 API JSON 但不执行
--queue 提交到队列并立即返回
--status [IDs...] 检查队列状态

输入自定义:
--prompt, -p TEXT 正向提示词
--negative, -n TEXT 负向提示词
--image, -i PATH [...] 输入图像
--audio, -a PATH [...] 输入音频文件
--video, -v PATH [...] 输入视频文件

生成设置:
--width, -W INT 输出宽度
--height, -H INT 输出高度
--steps INT 采样步数
--cfg FLOAT CFG 尺度
--seed INT 随机种子

高级:
--override JSON 节点输入覆盖
--config PATH YAML/JSON 配置文件
--server HOST:PORT ComfyUI 服务器
--output-dir, -o PATH 输出目录
--output-prefix TEXT 输出文件名前缀
--no-ensure 跳过自动启动 ComfyUI
--no-validate 跳过输入验证

故障排除

知识缓存模式

MODELSINVENTORY.md 和 WORKFLOWSSUMMARY.md 作为代理关于用户实际 ComfyUI 设置的持久知识库。使用它们在会话间缓存已学习的信息：

⚠️ 请勿引用示例内容：这些文件中的默认内容描述的是经过清理的示例工作流，这些工作流将无法使用。代理必须在使用前用用户的实际数据更新它们。使用过时的示例数据将导致工作流失败。

初始设置（首次使用）

当用户首次提供自己的工作流文件时：

1. 1. 清理示例内容 — 从两个文件中删除经过清理的示例条目
2. 填充用户数据 — 对每个工作流运行 --inspect，将发现记录到 WORKFLOWSSUMMARY.md
3. 盘点模型 — 扫描用户的模型目录，用实际模型更新 MODELSINVENTORY.md

持续维护

• - 使用新工作流后 → 将其文档添加到 WORKFLOWSSUMMARY.md
• 下载模型后 → 更新 MODELSINVENTORY.md 状态
• 了解模型特定特性时 → 在相关部分记录技巧/窍门

会话工作流

1. 1. 读取 MODELSINVENTORY.md → 了解可用模型
2. 读取 WORKFLOWSSUMMARY.md → 了解工作流能力
3. 选择合适的工作流，无需重新检查
4. 如果发现新工作流 → 记录以供后续会话使用

此模式让代理跳过重复的发现过程，利用缓存的知识高效工作。

参考文档