介绍
# ComfyUI Runner
## 概述
在本地服务器（默认 127.0.0.1:8188）上使用 API 格式的 JSON 运行 ComfyUI 工作流并返回输出图像。
## 运行前编辑工作流
运行脚本仅接受 `--workflow <path>` 参数。在运行之前，您必须**检查并编辑工作流 JSON**，利用您对 ComfyUI API 格式的充分了解。不要假设固定的节点 ID、`class_type` 名称或 `_meta.title` 值——用户可能已更新默认工作流或提供了自定义工作流。
**对于每次运行（包括默认工作流）：**
1. 读取工作流 JSON（默认：`skills/comfyui/assets/default-workflow.json`，或用户指定的路径/文件）。 2. **通过检查图结构识别提示词相关的节点**：查找包含主要文本提示词的节点——例如 `PrimitiveStringMultiline`、`CLIPTextEncode`（正向文本），或任何 `_meta.title` 或 `class_type` 表明为“Prompt”、“positive”或“text”的节点。将相应的输入（例如 `inputs.value`，或编码器的文本输入）更新为您从用户处推导出的图像提示词（主题、风格、光照、质量）。如果用户未要求自定义图像，您可以保留现有提示词，或仅在需要时进行调整。 3. **（可选）识别风格/前缀节点**：例如 `StringConcatenate`，或作为风格的第二个字符串输入。如果用户要求特定风格或清除默认前缀，请进行设置。 4. **（可选）设置新的随机种子**：查找类似采样器的节点（例如 `KSampler`、`BasicGuider` 或任何带有 `seed` 输入的节点），并将 `seed` 设置为一个新的随机整数，以便每次运行可以有所不同。 5. 将修改后的工作流写入临时文件（例如 `skills/comfyui/assets/tmp-workflow.json`）。对于任何内联 Python，请使用 `~/ComfyUI/venv/bin/python`；不要直接使用 `python`。 6. 运行：`comfyui_run.py --workflow <path-to-edited-json>`。
如果工作流结构不清楚，或者您找不到提示词/采样器节点，请按原样运行文件，并且只更改您可以可靠识别的内容。对于任意用户提供的 JSON 也是如此：首先检查，根据您的最佳知识进行编辑，然后运行。
## 运行脚本（单一职责） ```bash ~/ComfyUI/venv/bin/python skills/comfyui/scripts/comfyui_run.py \ --workflow <path-to-workflow.json> ```
该脚本仅将工作流加入队列并轮询直到完成。它会打印包含 `prompt_id` 和输出 `images` 的 JSON。所有提示词/风格/种子的更改都由您在 JSON 中预先完成。
## 如果服务器无法访问
如果运行脚本因连接错误而失败（例如连接被拒绝或对 127.0.0.1:8188 超时），则可能未安装 ComfyUI 或未运行。
**检查：** `~/ComfyUI` 是否存在并包含 `main.py`？
- **如果未安装：** 安装 ComfyUI（例如克隆仓库、创建 venv、安装依赖，然后启动服务器）。示例： ```bash git clone https://github.com/comfyanonymous/ComfyUI.git ~/ComfyUI cd ~/ComfyUI python3 -m venv venv ~/ComfyUI/venv/bin/pip install -r requirements.txt ``` 然后启动服务器（见下文）。告知用户他们可能需要根据工作流将模型权重安装到 `~/ComfyUI/models/` 中。
- **如果已安装但未运行：** 启动 ComfyUI 服务器，以便 API 在 8188 端口可用。示例： ```bash ~/ComfyUI/venv/bin/python ~/ComfyUI/main.py --listen 127.0.0.1 ``` 在后台或单独的终端中运行，以便其保持运行状态。然后重试工作流运行。
使用 `~`（或用户的主目录）作为路径，以便在其机器上运行。
## 从 URL 获取模型权重
当用户粘贴或发送**模型权重 URL 列表**（每行一个，或逗号分隔）时，将这些文件下载到 ComfyUI 安装目录中，以便工作流后续使用。
1. **规范化列表**——每行一个 URL；去除空行和注释（以 `#` 开头的行）。 2. **运行下载脚本**，并指定 ComfyUI 基础路径（默认 `~/ComfyUI`）。该脚本在可用时使用 [pget](https://github.com/replicate/pget) 进行并行下载；如果 PATH 中没有 `pget`，它会自动将其安装到 `~/.local/bin`（无需 sudo）。如果无法安装 pget（例如不支持的操作系统/架构），它会回退到内置下载。使用 ComfyUI venv Python，以便脚本正确运行： ```bash ~/ComfyUI/venv/bin/python skills/comfyui/scripts/download_weights.py --base ~/ComfyUI ``` 将 URL 作为参数传递，或通过管道传输文件/列表到标准输入： ```bash echo "https://example.com/model.safetensors" | ~/ComfyUI/venv/bin/python skills/comfyui/scripts/download_weights.py --base ~/ComfyUI ``` 或者将用户的列表保存到临时文件并运行： ```bash ~/ComfyUI/venv/bin/python skills/comfyui/scripts/download_weights.py --base ~/ComfyUI < /tmp/weight_urls.txt ``` 要强制使用内置下载（不使用 pget）：添加 `--no-pget`。 3. **子文件夹：** 脚本根据 URL/文件名推断 ComfyUI 模型子文件夹（例如 `vae`、`clip`、`loras`、`checkpoints`、`text_encoders`、`controlnet`、`upscale_models`）。用户可以选择每行指定一个子文件夹，格式为 `url subfolder`（例如 `https://.../model.safetensors vae`）。您也可以传递一个默认值，如 `--subfolder loras`，以便该次运行中的所有 URL 都进入 `models/loras/`。 4. **现有文件：** 默认情况下，脚本会跳过磁盘上已存在的 URL；使用 `--overwrite` 进行替换。 5. **路径：** 文件写入 `~/ComfyUI/models/<subfolder>/` 之下。告知用户每个文件的保存位置，如果需要，他们可以在 ComfyUI 服务器（重新）启动后运行工作流。
支持的子文件夹（在 `ComfyUI/models/` 下）：`checkpoints`、`clip`、`clip_vision`、`controlnet`、`diffusion_models`、`embeddings`、`loras`、`text_encoders`、`unet`、`vae`、`vae_approx`、`upscale_models` 等。当自动推断不正确时，使用 `--subfolder <name>`。
## 运行后
输出保存在 `ComfyUI/output/` 下。使用脚本输出中的 `images` 列表来定位文件（文件名 + 子文件夹）。
### ⚠️ 始终将输出发送给用户
ComfyUI 成功运行后，**您必须将生成的图像发送给用户**。不要仅用文本回复文件名或使用 NO_REPLY。
1. 解析脚本输出 JSON 中的 `images`（每个包含 `filename`、`subfolder`、`type`）。 2. 构建完整路径：`ComfyUI/output/` + subfolder + filename（例如 `ComfyUI/output/z-image_00007_.png`）。 3. **将图像发送给用户**，通过他们所在的渠道（例如使用 message/send 工具并传入图像 `path`，以便用户接收文件）。如有帮助，可以包含简短说明（例如“给您。”或“东京街景。”）。
每次成功运行都必须导致用户收到图像。绝不要只给他们留下文件名或不交付任何内容。
## 资源
### scripts/
- `comfyui_run.py`：将工作流加入队列，轮询直到完成，打印 `prompt_id` 和 `images`。无参数——您在运行前编辑 JSON。 - `download_weights.py`：将模型权重 URL 下载到 `~/ComfyUI/models/<subfolder>/`。可用时使用 [pget](https://github.com/replicate/pget)（如果缺失则安装到 `~/.local/bin`）；回退到内置下载。输入：作为参数的 URL 或 stdin 上的每行一个。选项：`--base`、`--subfolder`、`--overwrite`、`--no-pget`。未指定时根据 URL/文件名推断子文件夹。
### assets/
- `default-workflow.json`：默认工作流。复制并编辑（提示词、风格、种子），然后使用编辑后的路径运行；或者直接运行以进行通用运行。