@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/comfyui/SKILL.md

@@ -0,0 +1,609 @@
+---
+name: comfyui
+description: "使用 ComfyUI 生成图像、视频和音频 —— 包含安装、启动、管理节点/模型、以及通过参数注入运行工作流。使用官方 comfy-cli 进行生命周期管理，并使用直接的 REST/WebSocket API 执行任务。"
+version: 5.1.0
+author: [kshitijk4poor, alt-glitch, purzbeats]
+license: MIT
+platforms: [macos, linux, windows]
+compatibility: "需要 ComfyUI（本地、Comfy Desktop 或 Comfy Cloud）以及 comfy-cli（由安装脚本通过 pipx/uvx 自动安装）。"
+prerequisites:
+  commands: ["python3"]
+setup:
+  help: "首先运行 scripts/hardware_check.py 决定使用本地还是 Comfy Cloud；然后 scripts/comfyui_setup.sh 将自动在本地安装（或使用 Cloud API key 访问 platform.comfy.org）。"
+metadata:
+  hermes:
+    tags:
+      - comfyui
+      - image-generation
+      - stable-diffusion
+      - flux
+      - sd3
+      - wan-video
+      - hunyuan-video
+      - creative
+      - generative-ai
+      - video-generation
+    related_skills: [stable-diffusion-image-generation, image_gen]
+    category: creative
+---
+
+# ComfyUI
+
+通过 ComfyUI 生成图像、视频、音频和 3D 内容，使用官方 `comfy-cli`
+进行设置/生命周期管理，并使用直接的 REST/WebSocket API 执行工作流。
+
+## 此 skill 包含的内容
+
+**参考文档 (`references/`)：**
+
+- `official-cli.md` — 涵盖所有 `comfy ...` 命令及其参数
+- `rest-api.md` — REST + WebSocket 端点（本地 + 云端），payload 架构
+- `workflow-format.md` — API 格式 JSON，常见节点类型，参数映射
+- `template-integrity.md` — 将 `comfyui-workflow-templates` 从编辑器格式
+  转换为 API 格式：Reroute 绕过，带点的动态输入键
+  (`values.a`, `resize_type.width`)，云端怪癖（302 重定向，免费层 1 个
+  并发任务，1080p VRAM 上限），兼容 Discord 的 ffmpeg 拼接。
+  由 [@purzbeats](https://github.com/purzbeats) 编写。当你从官方模板
+  开始时，请加载此文档。
+
+**脚本 (`scripts/`)：**
+
+| 脚本 | 用途 |
+|--------|---------|
+| `_common.py` | 共享的 HTTP，云端路由，节点目录（不要直接运行） |
+| `hardware_check.py` | 探测 GPU/VRAM/磁盘 → 推荐本地或 Comfy Cloud |
+| `comfyui_setup.sh` | 硬件检查 + comfy-cli + ComfyUI 安装 + 启动 + 验证 |
+| `extract_schema.py` | 读取工作流 → 列出可控制的参数 + 模型依赖 |
+| `check_deps.py` | 将工作流与运行中的服务器进行比对 → 列出缺失的节点/模型 |
+| `auto_fix_deps.py` | 运行 check_deps，然后执行 `comfy node install` / `comfy model download` |
+| `run_workflow.py` | 注入参数，提交，监控，下载输出（HTTP 或 WS） |
+| `run_batch.py` | 通过扫描提交工作流 N 次，根据你的套餐等级并行执行 |
+| `ws_monitor.py` | 用于执行任务的实时 WebSocket 查看器（实时进度） |
+| `health_check.py` | 验证清单运行器 — comfy-cli + 服务器 + 模型 + 冒烟测试 |
+| `fetch_logs.py` | 获取给定 prompt_id 的 traceback / 状态消息 |
+
+**示例 workflows (`workflows/`)：** SD 1.5, SDXL, Flux Dev, SDXL img2img,
+SDXL inpaint, ESRGAN upscale, AnimateDiff video, Wan T2V。参见
+`workflows/README.md`。
+
+## 何时使用
+
+- 用户要求使用 Stable Diffusion, SDXL, Flux, SD3 等生成图像。
+- 用户想要运行特定的 ComfyUI 工作流文件。
+- 用户想要串联生成步骤（txt2img → 放大 → 面部修复）。
+- 用户需要 ControlNet、inpainting、img2img 或其他高级流水线。
+- 用户要求管理 ComfyUI 队列、检查模型或安装自定义节点。
+- 用户想要通过 AnimateDiff、Hunyuan、Wan、AudioCraft 等生成视频/音频/3D。
+
+## 架构：两层结构
+
+```
+┌─────────────────────────────────────────────────────┐
+│ Layer 1: comfy-cli (official lifecycle tool)        │
+│   Setup, server lifecycle, custom nodes, models     │
+│   → comfy install / launch / stop / node / model    │
+└─────────────────────────┬───────────────────────────┘
+                          │
+┌─────────────────────────▼───────────────────────────┐
+│ Layer 2: REST/WebSocket API + skill scripts         │
+│   Workflow execution, param injection, monitoring   │
+│   POST /api/prompt, GET /api/view, WS /ws           │
+│   → run_workflow.py, run_batch.py, ws_monitor.py    │
+└─────────────────────────────────────────────────────┘
+```
+
+**为什么分两层？** 官方 CLI 非常适合用于安装和服务器
+管理，但对工作流执行的支持极少。REST/WS API 填补了
+这一空白 —— 脚本处理了 CLI 未提供的参数注入、执行监控和
+输出下载。
+
+## 快速开始
+
+### 探测环境
+
+```bash
+# 有哪些可用？
+command -v comfy >/dev/null 2>&1 && echo "comfy-cli: installed"
+curl -s http://127.0.0.1:8188/system_stats 2>/dev/null && echo "server: running"
+
+# 这台机器能在本地运行 ComfyUI 吗？(GPU/VRAM/磁盘检查)
+python3 scripts/hardware_check.py
+```
+
+如果尚未安装任何内容，请参阅下方的 **配置 & Onboarding** — 但务必先
+运行硬件检查。
+
+### 一行命令健康检查
+
+```bash
+python3 scripts/health_check.py
+# → JSON: comfy_cli 是否在 PATH 上？服务器是否可访问？至少有一个 checkpoint？冒烟测试通过？
+```
+
+## 核心工作流
+
+### 步骤 1：获取 API 格式的工作流 JSON
+
+工作流必须为 API 格式（每个节点都有 `class_type`）。它们来源于：
+
+- ComfyUI web UI → **Workflow → Export (API)**（较新的 UI）或
+  传统的 "Save (API Format)" 按钮（较旧的 UI）
+- 本 skill 的 `workflows/` 目录（可直接运行的示例）
+- 社区下载 (civitai, Reddit, Discord) — 通常为编辑器格式，
+  必须加载到 ComfyUI 中然后重新导出
+
+编辑器格式（包含顶层的 `nodes` 和 `links` 数组）**无法直接
+执行**。脚本会检测到这种情况并提示你重新导出。
+
+### 步骤 2：查看哪些参数是可控制的
+
+```bash
+python3 scripts/extract_schema.py workflow_api.json --summary-only
+# → {"parameter_count": 12, "has_negative_prompt": true, "has_seed": true, ...}
+
+python3 scripts/extract_schema.py workflow_api.json
+# → 包含参数、模型依赖、embedding 引用的完整架构
+```
+
+### 步骤 3：使用参数运行
+
+```bash
+# 本地（默认为 http://127.0.0.1:8188）
+python3 scripts/run_workflow.py \
+  --workflow workflow_api.json \
+  --args '{"prompt": "a beautiful sunset over mountains", "seed": -1, "steps": 30}' \
+  --output-dir ./outputs
+
+# 云端（导出 API key 一次；会自动使用正确的 /api 路由）
+export COMFY_CLOUD_API_KEY="comfyui-..."
+python3 scripts/run_workflow.py \
+  --workflow workflow_api.json \
+  --args '{"prompt": "..."}' \
+  --host https://cloud.comfy.org \
+  --output-dir ./outputs
+
+# 通过 WebSocket 实现实时进度（需要 `pip install websocket-client`）
+python3 scripts/run_workflow.py \
+  --workflow flux_dev.json \
+  --args '{"prompt": "..."}' \
+  --ws
+
+# img2img / inpaint：传入 --input-image 以自动上传 + 引用
+python3 scripts/run_workflow.py \
+  --workflow sdxl_img2img.json \
+  --input-image image=./photo.png \
+  --args '{"prompt": "make it watercolor", "denoise": 0.6}'
+
+# 批量 / 扫描：8 个随机 seed，根据云端层级限制进行并行
+python3 scripts/run_batch.py \
+  --workflow sdxl.json \
+  --args '{"prompt": "abstract"}' \
+  --count 8 --randomize-seed --parallel 3 \
+  --output-dir ./outputs/batch
+```
+
+将 `seed` 设置为 `-1`（或省略它并使用 `--randomize-seed`）会在每次
+运行时生成一个新的随机 seed。
+
+### 步骤 4：展示结果
+
+脚本会向 stdout 输出描述每个输出文件的 JSON：
+
+```json
+{
+  "status": "success",
+  "prompt id": "abc-123",
+  "outputs": [
+    {"file": "./outputs/sdxl_00001_.png", "node_id": "9",
+     "type": "image", "filename": "sdxl_00001_.png"}
+  ]
+}
+```
+
+## 决策树
+
+| 用户指令 | 工具 | 命令 |
+|-----------|------|---------|
+| **生命周期管理（使用 comfy-cli）** |  |  |
+| "install ComfyUI" | comfy-cli | `bash scripts/comfyui_setup.sh` |
+| "start ComfyUI" | comfy-cli | `comfy launch --background` |
+| "stop ComfyUI" | comfy-cli | `comfy stop` |
+| "install X node" | comfy-cli | `comfy node install <name>` |
+| "download X model" | comfy-cli | `comfy model download --url <url> --relative-path models/checkpoints` |
+| "list installed models" | comfy-cli | `comfy model list` |
+| "list installed nodes" | comfy-cli | `comfy node show installed` |
+| **执行（使用脚本）** |  |  |
+| "is everything ready?" | script | `health_check.py` (可选择加上 `--workflow X --smoke-test`) |
+| "what can I change in this workflow?" | script | `extract_schema.py W.json` |
+| "check if W's deps are met" | script | `check_deps.py W.json` |
+| "fix missing deps" | script | `auto_fix_deps.py W.json` |
+| "generate an image" | script | `run_workflow.py --workflow W --args '{...}'` |
+| "use this image" (img2img) | script | `run_workflow.py --input-image image=./x.png ...` |
+| "8 variations with random seeds" | script | `run_batch.py --count 8 --randomize-seed ...` |
+| "show me live progress" | script | `ws_monitor.py --prompt-id <id>` |
+| "fetch the error from job X" | script | `fetch_logs.py <prompt_id>` |
+| **直接 REST** |  |  |
+| "what's in the queue?" | REST | `curl http://HOST:8188/queue` (本地) 或 `--host https://cloud.comfy.org` |
+| "cancel that" | REST | `curl -X POST http://HOST:8188/interrupt` |
+| "free GPU memory" | REST | `curl -X POST http://HOST:8188/free` |
+
+## 配置 & Onboarding
+
+当用户要求设置 ComfyUI 时，**要做的第一件事就是询问他们
+想要使用 Comfy Cloud（云端托管，免安装，API key）还是 Local
+（在他们的机器上安装 ComfyUI）**。在他们回答之前，不要
+开始运行安装命令或硬件检查。
+
+**官方文档：** https://docs.comfy.org/installation
+**CLI 文档：** https://docs.comfy.org/comfy-cli/getting-started
+**云端文档：** https://docs.comfy.org/get_started/cloud
+**云端 API：** https://docs.comfy.org/development/cloud/overview
+
+### 步骤 0：询问选择本地还是云端（始终是第一步）
+
+建议的对话脚本：
+
+> “你是想在你的机器上本地运行 ComfyUI，还是使用 Comfy Cloud？
+>
+> - **Comfy Cloud** — 托管在 RTX 6000 Pro GPU 上，预装了所有
+>   常见模型，零设置。需要 API key（实际运行工作流需付费
+>   订阅；免费层为只读模式）。如果你没有高性能 GPU，这是最佳选择。
+> - **Local** — 免费，但你的机器必须满足硬件要求：
+>   - 拥有 **≥6 GB VRAM** 的 NVIDIA GPU（SDXL 需 ≥8 GB，Flux/视频需 ≥12 GB），或者
+>   - 支持 ROCm 的 AMD GPU（Linux），或者
+>   - 拥有 **≥16 GB 统一内存**（推荐 ≥32 GB）的 Apple Silicon Mac (M1+)。
+>   - Intel Mac 和没有 GPU 的机器将**无法工作** — 请改用 Cloud。
+>
+> 你想选择哪一种？”
+
+路由分发：
+
+- **Cloud** → 跳至 **路径 A**。
+- **Local** → 首先运行硬件检查，然后根据结果从路径 B–E 中选择一条。
+- **不确定** → 运行硬件检查，让结果来决定。
+
+### 步骤 1：验证硬件（仅在用户选择本地时）
+
+```bash
+python3 scripts/hardware_check.py --json
+# 可选：探测 `torch` 获取实际的 CUDA/MPS 支持：
+python3 scripts/hardware_check.py --json --check-pytorch
+```
+
+| 判定结果 | 含义 | 操作 |
+|------------|---------------------------------------------------------------|--------|
+| `ok` | ≥8 GB VRAM（独立显卡）或 ≥32 GB 统一内存 | 本地安装 — 使用报告中的 `comfy_cli_flag` |
+| `marginal` | SD1.5 可运行；SDXL 较勉强；Flux/视频不太可能 | 轻量级工作流可以进行本地安装，否则选择 **路径 A (Cloud)** |
+| `cloud` | 没有可用的 GPU，<6 GB VRAM，<16 GB Apple 统一内存，Intel Mac，Rosetta Python | **切换至 Cloud**，除非用户明确强制要求本地 |
+
+该脚本还会显示 `wsl: true`（带 NVIDIA 直通的 WSL2）和
+`rosetta: true`（Apple Silicon 上的 x86_64 Python — 必须重新安装为 ARM64）。
+
+如果判定结果为 `cloud` 但用户想要在本地运行，不要默默地继续。
+原样显示 `notes` 数组，并询问他们是想切换到 Cloud 还是
+强制进行本地安装（在现代模型上会出现 OOM 或慢得无法使用）。
+
+### 选择安装路径
+
+首先使用硬件检查。下表适用于用户已经告知其硬件情况的备选方案：
+
+| 状况 | 推荐路径 |
+|-----------|------------------|
+| 硬件检查结果为 `verdict: cloud` | **路径 A: Comfy Cloud** |
+| 没有 GPU / 想在无承诺的情况下尝试 | **路径 A: Comfy Cloud** |
+| Windows + NVIDIA + 非技术人员 | **路径 B: ComfyUI Desktop** |
+| Windows + NVIDIA + 技术人员 | **路径 C: Portable** 或 **路径 D: comfy-cli** |
+| Linux + 任何 GPU | **路径 D: comfy-cli**（最简单） |
+| macOS + Apple Silicon | **路径 B: Desktop** 或 **路径 D: comfy-cli** |
+| 无头 / 服务器 / CI / agents | **路径 D: comfy-cli** |
+
+关于全自动路径（硬件检查 → 安装 → 启动 → 验证）：
+
+```bash
+bash scripts/comfyui_setup.sh
+# 或者使用覆盖参数：
+bash scripts/comfyui_setup.sh --m-series --port=8190 --workspace=/data/comfy
+```
+
+它会在内部运行 `hardware_check.py`，在结果为
+`cloud` 时拒绝在本地安装（除非使用 `--force-cloud-override`），选择正确
+的 `comfy-cli` 参数，并倾向于使用 `pipx`/`uvx` 而不是全局 `pip` 以免污染
+系统 Python。
+
+---
+
+### 路径 A: Comfy Cloud（无需本地安装）
+
+适用于没有高性能 GPU 或希望零设置的用户。托管在 RTX 6000 Pro 上。
+
+**文档：** https://docs.comfy.org/get_started/cloud
+
+1. 在 https://comfy.org/cloud 注册
+2. 在 https://platform.comfy.org/login 生成 API key
+3. 设置 key：
+   ```bash
+   export COMFY_CLOUD_API_KEY="comfyui-xxxxxxxxxxxx"
+   ```
+4. 运行工作流：
+   ```bash
+   python3 scripts/run_workflow.py \
+     --workflow workflows/flux_dev_txt2img.json \
+     --args '{"prompt": "..."}' \
+     --host https://cloud.comfy.org \
+     --output-dir ./outputs
+   ```
+
+**价格：** https://www.comfy.org/cloud/pricing
+**并发任务：** 免费/标准版 1 个，创作者版 3 个，专业版 5 个。免费层
+**无法通过 API 运行工作流** — 只能浏览模型。
+`/api/prompt`, `/api/upload/*`, `/api/view` 等需要付费订阅。
+
+---
+
+### 路径 B: ComfyUI Desktop（Windows / macOS）
+
+面向非技术人员的一键安装程序。目前为 Beta 版。
+
+**文档：** https://docs.comfy.org/installation/desktop
+- **Windows (NVIDIA):** https://download.comfy.org/windows/nsis/x64
+- **macOS (Apple Silicon):** https://comfy.org
+
+Linux **不支持** Desktop — 请使用路径 D。
+
+---
+
+### 路径 C: ComfyUI Portable（仅限 Windows）
+
+**文档：** https://docs.comfy.org/installation/comfyui_portable_windows
+
+从 https://github.com/comfyanonymous/ComfyUI/releases 下载，解压，
+运行 `run_nvidia_gpu.bat`。通过 `update/update_comfyui_stable.bat` 进行更新。
+
+---
+
+### 路径 D: comfy-cli（所有平台 — 推荐 Agents 使用）
+
+官方 CLI 是进行无头/自动化设置的最佳路径。
+
+**文档：** https://docs.comfy.org/comfy-cli/getting-started
+
+#### 安装 comfy-cli
+
+```bash
+# 推荐：
+pipx install comfy-cli
+# 或者使用 uvx 而不安装：
+uvx --from comfy-cli comfy --help
+# 或者（如果 pipx/uvx 不可用）：
+pip install --user comfy-cli
+```
+
+以非交互方式禁用数据分析：
+```bash
+comfy --skip-prompt tracking disable
+```
+
+#### 安装 ComfyUI
+
+```bash
+comfy --skip-prompt install --nvidia              # NVIDIA (CUDA)
+comfy --skip-prompt install --amd                 # AMD (ROCm, Linux)
+comfy --skip-prompt install --m-series            # Apple Silicon (MPS)
+comfy --skip-prompt install --cpu                 # 仅 CPU (慢)
+comfy --skip-prompt install --nvidia --fast-deps  # 基于 uv 的依赖解析
+```
+
+默认位置：`~/comfy/ComfyUI` (Linux), `~/Documents/comfy/ComfyUI`
+(macOS/Win)。使用 `comfy --workspace /custom/path install` 覆盖。
+
+#### 启动 / 验证
+
+```bash
+comfy launch --background                       # 后台守护进程监听 :8188
+comfy launch -- --listen 0.0.0.0 --port 8190    # 局域网可访问的自定义端口
+curl -s http://127.0.0.1:8188/system_stats      # 健康检查
+```
+
+---
+
+### 路径 E: 手动安装（高级 / 不受支持的硬件）
+
+适用于 Ascend NPU、Cambricon MLU、Intel Arc 或其他不受支持的硬件。
+
+**文档：** https://docs.comfy.org/installation/manual_install
+
+```bash
+git clone https://github.com/comfyanonymous/ComfyUI.git
+cd ComfyUI
+pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130
+pip install -r requirements.txt
+python main.py
+```
+
+---
+
+### 安装后：下载模型
+
+```bash
+# SDXL（通用，~6.5 GB）
+comfy model download \
+  --url "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors" \
+  --relative-path models/checkpoints
+
+# SD 1.5（更轻量，~4 GB，适合 6 GB 显存的显卡）
+comfy model download \
+  --url "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors" \
+  --relative-path models/checkpoints
+
+# Flux Dev fp8（更小的变体，~12 GB）
+comfy model download \
+  --url "https://huggingface.co/Comfy-Org/flux1-dev/resolve/main/flux1-dev-fp8.safetensors" \
+  --relative-path models/checkpoints
+
+# CivitAI（首先设置 token）：
+comfy model download \
+  --url "https://civitai.com/api/download/models/128713" \
+  --relative-path models/checkpoints \
+  --set-civitai-api-token "YOUR_TOKEN"
+```
+
+列出已安装的模型：`comfy model list`。
+
+### 安装后：安装自定义节点
+
+```bash
+comfy node install comfyui-impact-pack             # 流行的实用工具包
+comfy node install comfyui-animatediff-evolved     # 视频生成
+comfy node install comfyui-controlnet-aux          # ControlNet 预处理器
+comfy node install comfyui-essentials              # 常用辅助工具
+comfy node update all
+comfy node install-deps --workflow=workflow.json   # 安装工作流所需的所有依赖
+```
+
+### 安装后：验证
+
+```bash
+python3 scripts/health_check.py
+# → comfy_cli 是否在 PATH 上？服务器是否可访问？checkpoints？冒烟测试？
+
+python3 scripts/check_deps.py my_workflow.json
+# → 此工作流的节点/模型/embeddings 是否已安装？
+
+python3 scripts/run_workflow.py \
+  --workflow workflows/sd15_txt2img.json \
+  --args '{"prompt": "test", "steps": 4}' \
+  --output-dir ./test-outputs
+```
+
+## 图像上传（img2img / Inpainting）
+
+最简单的方法是将 `--input-image` 与 `run_workflow.py` 结合使用：
+
+```bash
+python3 scripts/run_workflow.py \
+  --workflow workflows/sdxl_img2img.json \
+  --input-image image=./photo.png \
+  --args '{"prompt": "make it cyberpunk", "denoise": 0.6}'
+```
+
+该参数会上传 `photo.png`，然后将其在服务器端的文件名注入
+到架构中名为 `image` 的参数中。对于 inpainting，需同时传入两者：
+
+```bash
+python3 scripts/run_workflow.py \
+  --workflow workflows/sdxl_inpaint.json \
+  --input-image image=./photo.png \
+  --input-image mask_image=./mask.png \
+  --args '{"prompt": "fill with flowers"}'
+```
+
+通过 REST 手动上传：
+```bash
+curl -X POST "http://127.0.0.1:8188/upload/image" \
+  -F "image=@photo.png" -F "type=input" -F "overwrite=true"
+# 返回：{"name": "photo.png", "subfolder": "", "type": "input"}
+
+# 云端等效操作：
+curl -X POST "https://cloud.comfy.org/api/upload/image" \
+  -H "X-API-Key: $COMFY_CLOUD_API_KEY" \
+  -F "image=@photo.png" -F "type=input" -F "overwrite=true"
+```
+
+## 云端特性
+
+- **Base URL：** `https://cloud.comfy.org`
+- **认证：** `X-API-Key` 请求头（WebSocket 则使用 `?token=KEY`）
+- **API key：** 设置一次 `$COMFY_CLOUD_API_KEY`，脚本会自动获取
+- **输出下载：** `/api/view` 返回一个指向签名 URL 的 302 重定向；脚本
+  会跟随它并在从存储后端获取之前剥离 `X-API-Key`
+  （不会将 API key 泄露给 S3/CloudFront）。
+- **与本地 ComfyUI 的端点差异：**
+  - `/api/object_info`, `/api/queue`, `/api/userdata` — **免费层返回 403**；
+    仅限付费用户。
+  - `/history` 在云端被重命名为 `/history_v2`（脚本会自动
+    路由）。
+  - `/models/<folder>` 在云端被重命名为 `/experiment/models/<folder>`（脚本
+    会自动路由）。
+  - WebSocket 中的 `clientId` 目前会被忽略 — 一个
+    用户的所有连接都会收到相同的广播。请在客户端按 `prompt_id` 进行过滤。
+  - 上传时接受 `subfolder`，但会被忽略 — 云端使用扁平命名空间。
+- **并发任务：** 免费/标准版：1，创作者版：3，专业版：5。Extras 队列
+  会自动排队。使用 `run_batch.py --parallel N` 来充分利用你的套餐算力。
+
+## 队列与系统管理
+
+```bash
+# 本地
+curl -s http://127.0.0.1:8188/queue | python3 -m json.tool
+curl -X POST http://127.0.0.1:8188/queue -d '{"clear": true}'    # 取消待处理任务
+curl -X POST http://127.0.0.1:8188/interrupt                      # 取消正在运行的任务
+curl -X POST http://127.0.0.1:8188/free \
+  -H "Content-Type: application/json" \
+  -d '{"unload_models": true, "free_memory": true}'
+
+# 云端 — 相同的路径位于 /api/ 下，此外：
+python3 scripts/fetch_logs.py --tail-queue --host https://cloud.comfy.org
+```
+
+## 常见陷阱
+
+1. **需要 API 格式** — 每个脚本以及 `/api/prompt` 端点都期望
+   API 格式的工作流 JSON。脚本会检测编辑器格式（顶层的
+   `nodes` 和 `links` 数组）并提示你通过
+   "Workflow → Export (API)"（较新的 UI）或 "Save (API Format)"（较旧的 UI）重新导出。
+
+2. **服务器必须正在运行** — 所有执行都需要一个在线的服务器。
+   `comfy launch --background` 会启动一个。使用
+   `curl http://127.0.0.1:8188/system_stats` 进行验证。
+
+3. **模型名称必须精确** — 区分大小写，包含文件扩展名。
+   `check_deps.py` 会进行模糊匹配（带/不带扩展名和文件夹
+   前缀），但工作流本身必须使用规范名称。使用
+   `comfy model list` 查看已安装的内容。
+
+4. **缺少自定义节点** — "class_type not found" 意味着未安装所需的节点。
+   `check_deps.py` 会报告需要安装哪个包；
+   `auto_fix_deps.py` 会为你执行安装。
+
+5. **工作目录** — `comfy-cli` 会自动检测 ComfyUI 工作区。
+   如果命令失败并提示 "no workspace found"，请使用
+   `comfy --workspace /path/to/ComfyUI <command>` 或
+   `comfy set-default /path/to/ComfyUI`。
+
+6. **云端免费层 API 限制** — `/api/prompt`、`/api/view`、`/api/upload/*`、
+   `/api/object_info` 在免费账户下均会返回 403。`health_check.py` 和
+   `check_deps.py` 会优雅地处理此情况并显示清晰的提示信息。
+
+7. **视频/音频工作流的超时问题** — 当输出节点为
+   `VHS_VideoCombine`、`SaveVideo` 等时会自动检测；
+   默认超时时间从 300 秒跃升至 900 秒。可以使用 `--timeout 1800` 显式覆盖。
+
+8. **输出文件名中的路径遍历** — 服务器提供的文件名会
+   通过 `safe_path_join` 传递，以拒绝任何试图逃逸 `--output-dir` 的路径。
+   请保持此保护处于开启状态 — 带有自定义保存节点的工作流可能会产生
+   任意路径。
+
+9. **工作流 JSON 即任意代码** — 自定义节点会运行 Python，因此
+   提交未知工作流具有与 `eval` 相同的信任风险。
+   在运行前检查来自不受信任来源的工作流。
+
+10. **自动随机 seed** — 在 `--args` 中传入 `seed: -1`（或使用
+    `--randomize-seed` 并省略 seed）以在每次运行时获取新的 seed。
+    实际使用的 seed 会记录到 stderr 中。
+
+11. **`tracking` 提示** — 首次运行 `comfy` 可能会提示进行数据分析。
+    使用 `comfy --skip-prompt tracking disable` 以非交互方式跳过。
+    `comfyui_setup.sh` 会为你完成此操作。
+
+## 验证清单
+
+使用 `python3 scripts/health_check.py` 一次运行整个清单。手动检查：
+
+- [ ] `hardware_check.py` 的判定结果为 `ok`，或者用户明确选择了 Comfy Cloud
+- [ ] `comfy --version` 可正常工作（或 `uvx --from comfy-cli comfy --help`）
+- [ ] `curl http://HOST:PORT/system_stats` 返回 JSON
+- [ ] `comfy model list` 显示至少一个 checkpoint（本地）或
+      `/api/experiment/models/checkpoints` 返回模型（云端）
+- [ ] 工作流 JSON 为 API 格式
+- [ ] `check_deps.py` 报告 `is_ready: true`（或者在云端免费层仅有 `node_check_skipped`）
+- [ ] 使用小型工作流进行的测试运行完成；输出内容存入 `--output-dir`