@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/comfyui/references/official-cli.md

@@ -0,0 +1,252 @@
+# comfy-cli 命令参考
+
+来自 [Comfy-Org/comfy-cli](https://github.com/Comfy-Org/comfy-cli) 的官方 CLI。
+文档：https://docs.comfy.org/comfy-cli/getting-started
+
+## 安装
+
+推荐安装顺序：
+
+```bash
+pipx install comfy-cli            # 推荐（隔离环境）
+uvx --from comfy-cli comfy --help # 通过 uv 零安装
+pip install --user comfy-cli      # 备选方案
+```
+
+此 skill 的 `comfyui_setup.sh` 会自动选择最佳可用方案。
+
+首次运行可能会提示启用数据分析。非交互式禁用该提示：
+```bash
+comfy --skip-prompt tracking disable
+```
+
+## 全局选项
+
+| 选项 | 说明 |
+| -------- | ------------- |
+| `--workspace <path>` | 指定特定的 ComfyUI workspace |
+| `--recent` | 使用最近使用的 workspace |
+| `--here` | 使用当前目录作为 workspace |
+| `--skip-prompt` | 无交互提示（使用默认值） |
+| `-v` / `--version` | 打印版本号 |
+
+Workspace 解析优先级：
+1. `--workspace`（显式路径）
+2. `--recent`（从配置读取）
+3. `--here`（当前工作目录）
+4. `comfy set-default` 路径
+5. 最近使用的路径
+6. `~/comfy/ComfyUI`（Linux）或 `~/Documents/comfy/ComfyUI`（macOS/Win）
+
+## 生命周期命令
+
+### `comfy install`
+
+下载并安装 ComfyUI + ComfyUI-Manager。
+
+```bash
+comfy install                    # 交互式选择 GPU
+comfy install --nvidia
+comfy install --amd              # ROCm (Linux)
+comfy install --m-series         # Apple Silicon (MPS)
+comfy install --cpu              # 仅 CPU（较慢）
+comfy install --fast-deps        # 使用 uv 安装依赖
+comfy install --skip-manager     # 跳过 ComfyUI-Manager
+```
+
+| 选项 | 说明 |
+| -------- | ------------- |
+| `--nvidia` / `--amd` / `--m-series` / `--cpu` | GPU 类型 |
+| `--cuda-version` | 11.8, 12.1, 12.4, 12.6, 12.8, 12.9, 13.0 |
+| `--rocm-version` | 6.1, 6.2, 6.3, 7.0, 7.1 |
+| `--fast-deps` | 基于 uv 的依赖解析 |
+| `--skip-manager` | 不安装 ComfyUI-Manager |
+| `--skip-torch-or-directml` | 跳过 PyTorch 安装 |
+| `--version <ver>` | `0.2.0`, `latest`, `nightly` |
+| `--commit <hash>` | 安装特定 commit |
+| `--pr "#1234"` | 从特定 PR 安装 |
+| `--restore` | 为已存在的安装恢复依赖 |
+
+### `comfy launch`
+
+```bash
+comfy launch                                   # 前台运行 :8188
+comfy launch --background                      # 后台守护进程
+comfy launch -- --listen 0.0.0.0               # 局域网可访问
+comfy launch -- --port 8190                    # 自定义端口
+comfy launch -- --cpu                          # 强制 CPU 模式
+comfy launch -- --lowvram                      # 6 GB 显存显卡
+comfy launch --background -- --listen 0.0.0.0 --port 8190
+```
+
+在 `--` 之后常用的额外参数：`--listen`, `--port`, `--cpu`, `--lowvram`、`--novram`, `--fp16-vae`, `--force-fp32`, `--disable-cuda-malloc`。
+
+### `comfy stop`
+
+```bash
+comfy stop
+```
+
+### `comfy run`
+
+向正在运行的服务器提交原始的 workflow JSON。**受限功能** — 不支持参数注入，也不支持结构化输出下载。对于 Agent，请改用
+`scripts/run_workflow.py`。
+
+```bash
+comfy run --workflow workflow_api.json
+comfy run --workflow workflow_api.json --host 10.0.0.5 --port 8188
+comfy run --workflow workflow_api.json --timeout 300 --wait
+```
+
+### `comfy which`
+
+```bash
+comfy which          # 显示目标 workspace
+comfy --recent which
+```
+
+### `comfy set-default`
+
+```bash
+comfy set-default /path/to/ComfyUI
+comfy set-default /path/to/ComfyUI --launch-extras="--listen 0.0.0.0"
+```
+
+### `comfy update`
+
+```bash
+comfy update               # 更新 ComfyUI 核心
+comfy node update all      # 更新所有 custom node
+```
+
+---
+
+## `comfy node` — Custom Node 管理
+
+所有 node 操作底层均使用 ComfyUI-Manager（`cm-cli`）。
+
+```bash
+comfy node show installed              # 列出已安装
+comfy node show enabled                # 列出已启用
+comfy node show all                    # 注册表中所有可用项
+comfy node simple-show installed       # 精简列表
+
+comfy node install comfyui-impact-pack
+comfy node install <name> --uv-compile # ComfyUI-Manager v4.1+ 统一解析器
+comfy node uninstall <name>
+comfy node update <name> | all
+comfy node enable <name>
+comfy node disable <name>
+comfy node fix <name>                  # 修复损坏的依赖
+
+comfy node install-deps --workflow=workflow.json
+comfy node deps-in-workflow --workflow=w.json --output=deps.json
+
+comfy node save-snapshot
+comfy node restore-snapshot <file>
+
+comfy node bisect start                # 二分查找排查问题 node
+comfy node bisect good
+comfy node bisect bad
+comfy node bisect reset
+```
+
+### 依赖解析选项
+
+| 标志 | 说明 |
+| ------ | ------------- |
+| `--fast-deps` | comfy-cli 内置 uv 解析器 |
+| `--uv-compile` | ComfyUI-Manager v4.1+ 统一解析器（推荐） |
+| `--no-deps` | 跳过依赖安装 |
+
+将 `uv-compile` 设为默认：`comfy manager uv-compile-default true`
+
+---
+
+## `comfy model` — 模型管理
+
+```bash
+comfy model list
+comfy model list --relative-path models/checkpoints
+
+comfy model download --url <URL>
+comfy model download --url <URL> --relative-path models/loras
+comfy model download --url <URL> --filename custom_name.safetensors
+
+comfy model remove                     # 交互模式
+comfy model remove --relative-path models/checkpoints --model-names "model.safetensors"
+```
+
+| 选项 | 说明 |
+| -------- | ------------- |
+| `--url` | 下载 URL（CivitAI, HuggingFace, 直链） |
+| `--relative-path` | workspace 下的子目录（如 `models/checkpoints`） |
+| `--filename` | 自定义保存的文件名 |
+| `--set-civitai-api-token` | 持久化保存 CivitAI token |
+| `--set-hf-api-token` | 持久化保存 HuggingFace token |
+| `--downloader` | `httpx`（默认）或 `aria2` |
+
+标准模型目录：
+```
+ComfyUI/models/
+├── checkpoints/        # 完整模型文件
+├── loras/              # LoRA 适配器
+├── vae/                # VAE 模型
+├── controlnet/         # ControlNet 模型
+├── clip/               # CLIP / T5 文本编码器
+├── clip_vision/        # CLIP 视觉编码器
+├── upscale_models/     # ESRGAN / SwinIR / 等
+├── embeddings/         # Textual inversion embeddings
+├── unet/               # 独立的 UNet 权重
+├── diffusion_models/   # Flux / SD3 / Wan diffusion models
+├── animatediff_models/ # AnimateDiff motion modules
+├── ipadapter/          # IPAdapter 权重
+└── style_models/       # 风格适配器
+```
+
+---
+
+## `comfy manager` — ComfyUI-Manager 设置
+
+```bash
+comfy manager disable               # 彻底禁用 Manager
+comfy manager enable-gui            # 启用新 GUI
+comfy manager disable-gui           # 仅限 API 模式
+comfy manager enable-legacy-gui     # 旧版 GUI
+comfy manager uv-compile-default true   # 将 --uv-compile 设为默认
+comfy manager clear                 # 清除启动动作
+```
+
+---
+
+## `comfy pr-cache` — 前端 PR 缓存
+
+```bash
+comfy pr-cache list
+comfy pr-cache clean
+comfy pr-cache clean 456
+```
+
+缓存在 7 天后过期；最多保留 10 个构建版本。
+
+---
+
+## 配置
+
+| OS | Path |
+| ---- | ------ |
+| Linux | `~/.config/comfy-cli/config.ini` |
+| macOS | `~/Library/Application Support/comfy-cli/config.ini` |
+| Windows | `~/AppData/Local/comfy-cli/config.ini` |
+
+存储内容：默认 workspace、最近的 workspace、后台服务器 PID、API token、manager GUI 模式、启动附加参数。
+
+## 相关资源
+
+Custom-node 注册表：
+- https://registry.comfy.org/
+
+模型浏览器：
+- https://huggingface.co/models
+- https://civitai.com (NSFW；许多内容需要 API token)
+- https://comfyworkflows.com (社区 workflow)

package/extensions/skills/builtin/creative/comfyui/references/rest-api.md

@@ -0,0 +1,297 @@
+# ComfyUI REST + WebSocket API 参考
+
+ComfyUI 暴露了一个 REST + WebSocket 接口用于工作流的执行与管理。**该接口在本地和 Comfy Cloud 上保持一致，仅在认证/路径上有所差异。**
+
+## 连接
+
+|  | 本地 ComfyUI | Comfy Cloud |
+|---|---|---|
+| Base URL | `http://127.0.0.1:8188` | `https://cloud.comfy.org` |
+| API 路径前缀 | 无 (`/prompt`, `/view`, …) | `/api/...` (`/api/prompt`, `/api/view`, …) |
+| 认证 | 无（若进行了配置则为 bearer token） | `X-API-Key` header |
+| WebSocket | `ws://host:port/ws?clientId={uuid}` | `wss://cloud.comfy.org/ws?clientId={uuid}&token={API_KEY}` |
+| `/api/view` 响应 | 直接返回字节流 | 302 重定向 → 签名 URL（使用 `curl -L`） |
+
+技能脚本会通过 `_common.resolve_url()` 自动路由 URL。
+
+## Comfy Cloud 上的 Endpoint 差异
+
+云端接口在几个方面与本地 ComfyUI 存在差异。技能脚本会透明地处理这些问题；在此将其记录下来，以便任何直接调用 `curl` 的人都能了解。
+
+| 本地路径 | 云端路径 | 备注 |
+|------------|-----------|-------|
+| `/system_stats` | `/api/system_stats` | 云端版本是**公开的**（无需认证） |
+| `/object_info` | `/api/object_info` | **仅限付费套餐** — 免费版返回 403 |
+| `/queue` | `/api/queue` | 仅限付费套餐 |
+| `/userdata` | `/api/userdata` | 仅限付费套餐 |
+| `/prompt` (POST) | `/api/prompt` (POST) | 仅限付费套餐 |
+| `/upload/image` | `/api/upload/image` | 仅限付费套餐；接受 `subfolder` 但会忽略 |
+| `/upload/mask` | `/api/upload/mask` | 同上 |
+| `/view` | `/api/view` | 仅限付费套餐；**返回 302** 指向签名 URL |
+| `/history` | `/api/history_v2` | **已重命名**；旧路径返回 404 |
+| `/history/{id}` | `/api/history_v2/{id}` 或 `/api/jobs/{id}` | 均可生效；`/jobs` 返回完整的任务 |
+| `/models` | `/api/experiment/models` | **已重命名** |
+| `/models/{folder}` | `/api/experiment/models/{folder}` | **已重命名**；响应结构不同（见下文） |
+
+### 云端模型列表响应结构
+
+- **本地:** `["a.safetensors", "b.safetensors", …]` — 扁平的字符串列表。
+- **云端:** `[{"name": "a.safetensors", "pathIndex": 0}, …]` — 对象列表。
+- **云端返回 404 且带有 `code: "folder_not_found"`** — 表示文件夹为空或未知，而不是“缺少 endpoint”的错误。请通过读取响应体来进行区分。
+
+技能辅助函数 `_common.parse_model_list()` 会将两者统一标准化。
+
+## 工作流执行
+
+### 提交工作流
+
+```bash
+# Local
+curl -X POST "http://127.0.0.1:8188/prompt" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": '"$(cat workflow_api.json)"', "client_id": "'"$(uuidgen)"'"}'
+
+# Cloud
+curl -X POST "https://cloud.comfy.org/api/prompt" \
+  -H "X-API-Key: $COMFY_CLOUD_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": '"$(cat workflow_api.json)"'}'
+```
+
+**响应:**
+```json
+{"prompt_id": "abc-123-def", "number": 1, "node_errors": {}}
+```
+
+如果 `node_errors` 不为空，说明工作流存在验证错误（缺少节点或输入错误）。
+
+### 检查任务状态 (Cloud)
+
+```bash
+curl -X GET "https://cloud.comfy.org/api/job/{prompt_id}/status" \
+  -H "X-API-Key: $COMFY_CLOUD_API_KEY"
+```
+
+| Status | 说明 |
+| ------------- | ---------------------------------- |
+| `pending` | 任务已排队，等待开始 |
+| `in_progress` | 任务正在执行 |
+| `completed` | 任务成功完成 |
+| `failed` | 任务遇到错误 |
+| `cancelled` | 任务被用户取消 |
+
+### 包含输出的任务详情 (Cloud)
+
+```bash
+curl -X GET "https://cloud.comfy.org/api/jobs/{prompt_id}" \
+  -H "X-API-Key: $COMFY_CLOUD_API_KEY"
+```
+
+响应包含以节点 ID 为键的 `outputs`。云端在输出结构中使用 `video`（单数）；本地使用 `videos`（复数）。技能脚本两者皆可接受。
+
+### 获取历史记录 (Local)
+
+```bash
+curl -s "http://127.0.0.1:8188/history"          # all
+curl -s "http://127.0.0.1:8188/history/{id}"     # one prompt_id
+```
+
+本地条目结构：
+```json
+{
+  "<prompt_id>": {
+    "prompt": [...],
+    "outputs": {"<node_id>": {"images": [...]}},
+    "status": {
+      "status_str": "success" | "error",
+      "completed": true | false,
+      "messages": [["execution_start", {...}], ["execution_error", {...}], …]
+    }
+  }
+}
+```
+
+**重要提示：** 在读取状态时，必须先检查 `status_str == "error"`，再检查 `completed`，因为对于失败的任务，这两者有可能同时为 true。
+
+### 下载输出
+
+```bash
+# Local (direct bytes)
+curl -s "http://127.0.0.1:8188/view?filename=ComfyUI_00001_.png&subfolder=&type=output" \
+  -o output.png
+
+# Cloud (302 → signed URL; -L follows; STRIP X-API-Key for the second hop)
+curl -L "https://cloud.comfy.org/api/view?filename=...&type=output" \
+  -H "X-API-Key: $COMFY_CLOUD_API_KEY" \
+  -o output.png
+```
+
+技能脚本的 `run_workflow.py` 会在跨主机重定向时自动移除 `X-API-Key`，因此签名 URL 永远不会获取到你的认证信息。
+
+## WebSocket 监控
+
+连接以获取实时的执行事件。
+
+```bash
+# Local
+wscat -c "ws://127.0.0.1:8188/ws?clientId=MY-UUID"
+
+# Cloud
+wscat -c "wss://cloud.comfy.org/ws?clientId=MY-UUID&token=$COMFY_CLOUD_API_KEY"
+```
+
+**注意：** 在云端，目前会忽略 `clientId` —— 某个用户的所有消息都会广播到它的每一个连接中。请在客户端通过 `data.prompt_id` 过滤消息。
+
+### JSON 消息类型
+
+| Type | 何时触发 | 关键字段 |
+|------|---------------------|------------|
+| `status` | 队列发生改变 | `status.exec_info.queue_remaining` |
+| `notification` | 用户友好的状态字符串 | `value` |
+| `execution_start` | 工作流开始执行 | `prompt_id` |
+| `executing` | 节点运行中（或在本地环境中，如果 `node` 为 null 则表示运行结束） | `node`, `prompt_id` |
+| `progress` | 采样步骤 | `node`, `value`, `max` |
+| `progress_state` | 带有每个节点元数据的扩展进度 | `nodes` (dict) |
+| `executed` | 节点输出已就绪 | `node`, `output` (包含 `images`/`video`/等) |
+| `execution_cached` | 节点因为缓存被跳过 | `nodes` (ID 列表) |
+| `execution_success` | 全部完成 | `prompt_id` |
+| `execution_error` | 失败 | `exception_type`, `exception_message`, `traceback`, `node_id` |
+| `execution_interrupted` | 已取消 | `prompt_id` |
+
+### 二进制帧（预览图像）
+
+| Type code | 含义 |
+|-----------|---------|
+| `0x00000001` | `PREVIEW_IMAGE` — `[type:4][image_type:4][data]` (image_type 1=JPEG, 2=PNG) |
+| `0x00000003` | `TEXT` — `[type:4][nid_len:4][nid][text]` (UTF-8) |
+| `0x00000004` | `PREVIEW_IMAGE_WITH_METADATA` — `[type:4][meta_len:4][json][image_data]` |
+
+`scripts/ws_monitor.py --previews <dir>` 可将预览帧保存到磁盘。
+
+## 文件上传
+
+```bash
+# Image
+curl -X POST "http://127.0.0.1:8188/upload/image" \
+  -F "image=@photo.png" -F "type=input" -F "overwrite=true"
+# Returns: {"name": "photo.png", "subfolder": "", "type": "input"}
+
+# Mask (linked to a previously uploaded image)
+curl -X POST "http://127.0.0.1:8188/upload/mask" \
+  -F "image=@mask.png" -F "type=input" \
+  -F 'original_ref={"filename":"photo.png","subfolder":"","type":"input"}'
+```
+
+对应的云端操作：在前面加上 `https://cloud.comfy.org/api` 并添加 `-H "X-API-Key: $COMFY_CLOUD_API_KEY"`。
+
+## 节点与模型发现
+
+```bash
+# All node types and their input specs
+curl -s "http://127.0.0.1:8188/object_info" | python3 -m json.tool
+
+# Specific node
+curl -s "http://127.0.0.1:8188/object_info/KSampler"
+
+# Models per folder (local)
+curl -s "http://127.0.0.1:8188/models/checkpoints"
+curl -s "http://127.0.0.1:8188/models/loras"
+
+# Models per folder (cloud — note the experimental prefix)
+curl -s "https://cloud.comfy.org/api/experiment/models/checkpoints" \
+  -H "X-API-Key: $COMFY_CLOUD_API_KEY"
+```
+
+## 队列管理
+
+```bash
+# View queue
+curl -s "http://127.0.0.1:8188/queue"
+
+# Clear all pending
+curl -X POST "http://127.0.0.1:8188/queue" \
+  -H "Content-Type: application/json" \
+  -d '{"clear": true}'
+
+# Delete specific items
+curl -X POST "http://127.0.0.1:8188/queue" \
+  -H "Content-Type: application/json" \
+  -d '{"delete": ["prompt_id_1", "prompt_id_2"]}'
+
+# Cancel currently-running job
+curl -X POST "http://127.0.0.1:8188/interrupt"
+```
+
+## 系统管理
+
+```bash
+# Stats (VRAM, RAM, GPU, ComfyUI version)
+curl -s "http://127.0.0.1:8188/system_stats"
+
+# Free GPU memory
+curl -X POST "http://127.0.0.1:8188/free" \
+  -H "Content-Type: application/json" \
+  -d '{"unload_models": true, "free_memory": true}'
+```
+
+## ComfyUI-Manager Endpoints (可选)
+
+这些操作需要安装 ComfyUI-Manager。适合用于通过 API 安装节点/模型，而不是使用 `comfy-cli`。
+
+```bash
+# Install a custom node from a git URL
+curl -X POST "http://127.0.0.1:8188/manager/queue/install" \
+  -H "Content-Type: application/json" \
+  -d '{"git_url": "https://github.com/user/comfyui-node.git"}'
+
+# Check install queue status
+curl -s "http://127.0.0.1:8188/manager/queue/status"
+
+# Install model
+curl -X POST "http://127.0.0.1:8188/manager/queue/install_model" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://...", "path": "models/checkpoints", "filename": "model.safetensors"}'
+```
+
+## POST /prompt Payload 格式
+
+```json
+{
+  "prompt": {
+    "3": {
+      "class_type": "KSampler",
+      "inputs": {
+        "seed": 42,
+        "steps": 20,
+        "cfg": 7.5,
+        "sampler_name": "euler",
+        "scheduler": "normal",
+        "denoise": 1.0,
+        "model": ["4", 0],
+        "positive": ["6", 0],
+        "negative": ["7", 0],
+        "latent_image": ["5", 0]
+      }
+    }
+  },
+  "client_id": "unique-uuid-for-ws-filtering",
+  "extra_data": {
+    "api_key_comfy_org": "optional-PARTNER-NODE-key (NOT the cloud auth key)"
+  }
+}
+```
+
+- `prompt`: API 格式的工作流图
+- `client_id`: UUID — 本地服务器用它来过滤 WebSocket 事件；云端会忽略它。
+- `extra_data.api_key_comfy_org`: 仅当工作流使用合作节点（Flux Pro, Ideogram 等）时才需要。不要与 `X-API-Key` 混淆。
+
+## 错误类别 (云端 `execution_error` `exception_type`)
+
+| Type | 含义 |
+|------|---------|
+| `ValidationError` | 错误的工作流/输入（通常从 `node_errors` 获取会更直观） |
+| `ModelDownloadError` | 所需的模型不可用 |
+| `ImageDownloadError` | 无法从 URL 获取输入图像 |
+| `OOMError` | GPU 内存不足 |
+| `InsufficientFundsError` | 账户余额不足（合作节点） |
+| `InactiveSubscriptionError` | 订阅未激活 |