npm - better-dsh - Versions diffs - 0.2.5 → 0.3.0-c - Mend

better-dsh 0.2.5 → 0.3.0-c

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1002) hide show

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/creative/creative-comfyui.md DELETED Viewed

@@ -1,547 +0,0 @@
----
-title: "Comfyui"
-sidebar_label: "Comfyui"
-description: "使用 ComfyUI 生成图像、视频和音频——安装、启动、管理节点/模型、运行带参数注入的工作流"
----
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-# Comfyui
-使用 ComfyUI 生成图像、视频和音频——安装、启动、管理节点/模型、运行带参数注入的工作流。使用官方 comfy-cli 进行生命周期管理，使用直接 REST/WebSocket API 执行工作流。
-## Skill 元数据
-| | |
-|---|---|
-| 来源 | 内置（默认安装） |
-| 路径 | `skills/creative/comfyui` |
-| 版本 | `5.1.0` |
-| 作者 | ['kshitijk4poor', 'alt-glitch', 'purzbeats'] |
-| 许可证 | MIT |
-| 平台 | macos, linux, windows |
-| 标签 | `comfyui`, `image-generation`, `stable-diffusion`, `flux`, `sd3`, `wan-video`, `hunyuan-video`, `creative`, `generative-ai`, `video-generation` |
-| 相关 skill | [`stable-diffusion-image-generation`](/user-guide/skills/optional/mlops/mlops-stable-diffusion) |
-## 参考：完整 SKILL.md
-:::info
-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时看到的指令内容。
-:::
-# ComfyUI
-通过 ComfyUI 生成图像、视频、音频和 3D 内容，使用官方 `comfy-cli` 进行安装/生命周期管理，使用直接 REST/WebSocket API 执行工作流。
-## 此 skill 包含的内容
-**参考文档（`references/`）：**
-- `official-cli.md` — 所有 `comfy ...` 命令及其标志
-- `rest-api.md` — REST + WebSocket 端点（本地 + 云端），payload（载荷）schema
-- `workflow-format.md` — API 格式 JSON、常见节点类型、参数映射
-- `template-integrity.md` — 将 `comfyui-workflow-templates` 从编辑器格式转换为 API 格式：Reroute bypass、点分动态输入键（`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` | 以 sweep 方式提交工作流 N 次，并行数量受限于你的套餐层级 |
-| `ws_monitor.py` | 执行中任务的实时 WebSocket 查看器（实时进度） |
-| `health_check.py` | 验证清单运行器——comfy-cli + 服务器 + 模型 + 冒烟测试 |
-| `fetch_logs.py` | 拉取指定 prompt_id 的 traceback / 状态消息 |
-**示例工作流（`workflows/`）：** SD 1.5、SDXL、Flux Dev、SDXL img2img、SDXL inpaint、ESRGAN 放大、AnimateDiff 视频、Wan T2V。参见 `workflows/README.md`。
-## 使用场景
-- 用户要求使用 Stable Diffusion、SDXL、Flux、SD3 等生成图像
-- 用户想运行特定的 ComfyUI 工作流文件
-- 用户想串联生成步骤（txt2img → 放大 → 人脸修复）
-- 用户需要 ControlNet、inpainting、img2img 或其他高级 pipeline
-- 用户要管理 ComfyUI 队列、检查模型或安装自定义节点
-- 用户想通过 AnimateDiff、Hunyuan、Wan、AudioCraft 等进行视频/音频/3D 生成
-## 架构：两层
-<!-- ascii-guard-ignore -->
-```
-┌─────────────────────────────────────────────────────┐
-│ 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    │
-└─────────────────────────────────────────────────────┘
-```
-<!-- ascii-guard-ignore-end -->
-**为什么要两层？** 官方 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
-```
-如果未安装任何内容，请参阅下方的**安装与引导**——但始终先运行硬件检查。
-### 一行健康检查
-```bash
-python3 scripts/health_check.py
-# → JSON: comfy_cli 在 PATH 中？服务器可达？至少有一个 checkpoint？冒烟测试通过？
-```
-## 核心工作流
-### 第一步：获取 API 格式的工作流 JSON
-工作流必须为 API 格式（每个节点有 `class_type`）。来源包括：
-- ComfyUI Web UI → **Workflow → Export (API)**（新版 UI）或旧版"Save (API Format)"按钮（旧版 UI）
-- 此 skill 的 `workflows/` 目录（可直接运行的示例）
-- 社区下载（civitai、Reddit、Discord）——通常为编辑器格式，必须加载到 ComfyUI 后重新导出
-编辑器格式（顶层含 `nodes` 和 `links` 数组）**不可直接执行**。脚本会检测此情况并提示你重新导出。
-### 第二步：查看可控内容
-```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
-# → 完整 schema，包含参数、模型依赖、embedding 引用
-```
-### 第三步：带参数运行
-```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}'
-# 批量 / sweep：8 个随机种子，并行数量受限于云端套餐层级
-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）可在每次运行时生成新的随机种子。
-### 第四步：呈现结果
-脚本向 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）** | | |
-| "安装 ComfyUI" | comfy-cli | `bash scripts/comfyui_setup.sh` |
-| "启动 ComfyUI" | comfy-cli | `comfy launch --background` |
-| "停止 ComfyUI" | comfy-cli | `comfy stop` |
-| "安装 X 节点" | comfy-cli | `comfy node install <name>` |
-| "下载 X 模型" | comfy-cli | `comfy model download --url <url> --relative-path models/checkpoints` |
-| "列出已安装模型" | comfy-cli | `comfy model list` |
-| "列出已安装节点" | comfy-cli | `comfy node show installed` |
-| **执行（使用脚本）** | | |
-| "一切准备好了吗？" | 脚本 | `health_check.py`（可选加 `--workflow X --smoke-test`） |
-| "这个工作流我能改什么？" | 脚本 | `extract_schema.py W.json` |
-| "检查 W 的依赖是否满足" | 脚本 | `check_deps.py W.json` |
-| "修复缺失依赖" | 脚本 | `auto_fix_deps.py W.json` |
-| "生成一张图片" | 脚本 | `run_workflow.py --workflow W --args '{...}'` |
-| "使用这张图片"（img2img） | 脚本 | `run_workflow.py --input-image image=./x.png ...` |
-| "8 个随机种子变体" | 脚本 | `run_batch.py --count 8 --randomize-seed ...` |
-| "显示实时进度" | 脚本 | `ws_monitor.py --prompt-id <id>` |
-| "获取任务 X 的错误" | 脚本 | `fetch_logs.py <prompt_id>` |
-| **直接 REST** | | |
-| "队列里有什么？" | REST | `curl http://HOST:8188/queue`（本地）或 `--host https://cloud.comfy.org` |
-| "取消那个" | REST | `curl -X POST http://HOST:8188/interrupt` |
-| "释放 GPU 内存" | REST | `curl -X POST http://HOST:8188/free` |
-## 安装与引导
-当用户要求安装 ComfyUI 时，**首先要询问他们想要 Comfy Cloud（托管，零安装，API key）还是本地安装（在其机器上安装 ComfyUI）**。在得到答复之前，不要开始运行安装命令或硬件检查。
-**官方文档：** https://docs.comfy.org/installation
-**CLI 文档：** https://docs.comfy.org/comfy-cli/getting-started
-**Cloud 文档：** https://docs.comfy.org/get_started/cloud
-**Cloud API：** https://docs.comfy.org/development/cloud/overview
-### 第零步：询问本地还是云端（始终优先）
-建议话术：
-> "您想在本地机器上运行 ComfyUI，还是使用 Comfy Cloud？
->
-> - **Comfy Cloud** — 托管于 RTX 6000 Pro GPU，所有常用模型预装，零配置。需要 API key（实际运行工作流需要付费订阅；免费层仅限只读）。如果您没有性能足够的 GPU，推荐此选项。
-> - **本地** — 免费，但您的机器必须满足硬件要求：
->   - NVIDIA GPU，**≥6 GB VRAM**（SDXL 需 ≥8 GB，Flux/视频需 ≥12 GB），或
->   - 支持 ROCm 的 AMD GPU（Linux），或
->   - Apple Silicon Mac（M1+），**≥16 GB 统一内存**（推荐 ≥32 GB）。
->   - Intel Mac 和无 GPU 的机器**不可用**——请改用 Cloud。
->
-> 您选择哪种？"
-路由逻辑：
-- **Cloud** → 跳至**路径 A**。
-- **本地** → 先运行硬件检查，再根据结果从路径 B–E 中选择。
-- **不确定** → 运行硬件检查，由结果决定。
-### 第一步：验证硬件（仅当用户选择本地时）
-```bash
-python3 scripts/hardware_check.py --json
-# 可选：同时探测 `torch` 以获取实际 CUDA/MPS 信息：
-python3 scripts/hardware_check.py --json --check-pytorch
-```
-| 结果 | 含义 | 操作 |
-|------------|---------------------------------------------------------------|--------|
-| `ok` | ≥8 GB VRAM（独立显卡）或 ≥32 GB 统一内存（Apple Silicon） | 本地安装——使用报告中的 `comfy_cli_flag` |
-| `marginal` | SD1.5 可用；SDXL 较紧张；Flux/视频不太可能 | 轻量工作流可本地，否则选**路径 A（Cloud）** |
-| `cloud` | 无可用 GPU、&lt;6 GB VRAM、&lt;16 GB Apple 统一内存、Intel Mac、Rosetta Python | **切换至 Cloud**，除非用户明确强制本地 |
-脚本还会显示 `wsl: true`（带 NVIDIA 直通的 WSL2）和 `rosetta: true`（Apple Silicon 上的 x86_64 Python——必须重新安装为 ARM64）。
-如果结果为 `cloud` 但用户想要本地，不要静默继续。逐字显示 `notes` 数组，并询问他们是否要（a）切换至 Cloud 或（b）强制本地安装（在现代模型上会 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/agent | **路径 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 个，Creator 3 个，Pro 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（全平台——推荐用于 Agent）
-官方 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：手动安装（高级 / 不支持的硬件）
-适用于昇腾 NPU、寒武纪 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 中？服务器可达？有 checkpoint？冒烟测试？
-python3 scripts/check_deps.py my_workflow.json
-# → 此工作流的节点/模型/embedding 是否已安装？
-python3 scripts/run_workflow.py \
-  --workflow workflows/sd15_txt2img.json \
-  --args '{"prompt": "test", "steps": 4}' \
-  --output-dir ./test-outputs
-```
-## 图像上传（img2img / Inpainting）
-最简单的方式是在 `run_workflow.py` 中使用 `--input-image`：
-```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`，然后将其服务端文件名注入到 schema 中名为 `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` 返回 302 跳转至签名 URL；脚本会跟随跳转并在从存储后端（S3/CloudFront）获取前去除 `X-API-Key`（避免泄露 API key）。
-- **与本地 ComfyUI 的端点差异：**
-  - `/api/object_info`、`/api/queue`、`/api/userdata` — **免费层返回 403**；仅付费可用。
-  - `/history` 在云端重命名为 `/history_v2`（脚本自动路由）。
-  - `/models/<folder>` 在云端重命名为 `/experiment/models/<folder>`（脚本自动路由）。
-  - WebSocket 中的 `clientId` 目前被忽略——同一用户的所有连接接收相同广播。请在客户端按 `prompt_id` 过滤。
-  - 上传时接受 `subfolder` 但会被忽略——云端使用扁平命名空间。
-- **并发任务：** 免费/标准版：1，Creator：3，Pro：5。超出部分自动排队。使用 `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 workspace。如果命令报错"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. **自动随机化种子** — 在 `--args` 中传入 `seed: -1`（或使用 `--randomize-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` 中