@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/comfyui/references/template-integrity.md

@@ -0,0 +1,227 @@
+# ComfyUI Workflow-Template 完整性
+
+> **由 [@purzbeats](https://github.com/purzbeats) 编写** — 改编自
+> [purzbeats/hermes-agent-comfyui-helper](https://github.com/purzbeats/hermes-agent-comfyui-helper)。
+> 当你需要将官方 `comfyui-workflow-templates` 包（editor 格式）中的工作流转换为 API 格式以便通过 `/api/prompt` 提交时，请参考此文档。如果不遵循这些规则，转换过程中出现的细微陷阱将导致难以排查的验证错误。
+
+## 背景
+
+官方 ComfyUI 模板包（`comfyui-workflow-templates`，目前版本为
+v0.9.69）安装在 ComfyUI venv 中，路径类似于：
+
+```
+<comfy-install>/.venv/lib/python3.*/site-packages/comfyui_workflow_templates_*/templates/
+```
+
+确切路径取决于 ComfyUI 的安装方式（comfy-cli 默认安装、
+Comfy Desktop、手动 venv 等）。可以使用以下命令一次性找到它：
+
+```bash
+comfy --workspace <ws> run-python -c "import comfyui_workflow_templates, pathlib; print(pathlib.Path(comfyui_workflow_templates.__file__).parent / 'templates')"
+```
+
+模板以 **editor 格式** 提供 — `nodes` / `links` 数组位于
+`data['definitions']['subgraphs'][0]` 内部。在提交之前，必须将它们转换为
+**API 格式**（一种 `node_id -> {class_type, inputs}` 映射）。
+
+---
+
+## 规则 #1：尽可能保持模板与原版一致
+
+- **绝不剥离、简化或“最小化”模板中的节点。**
+- 完整的模板架构（dual-pass pipelines, LoRA chains, distilled
+  sigmas, conditioning paths）都是刻意设计的 — 移除任何部分都会破坏画质。
+- 如果存在依赖图像的路径，但任务是 text-to-video，**请保留其连线并启用 bypass 开关** — 不要移除节点。
+- 仅允许更改：prompt 文本、seed 和尺寸（当明确被要求时）。
+
+## 规则 #2：服务器验证错误是事实依据
+
+当工作流提交失败时，服务器响应如下所示：
+
+```json
+{
+  "node_errors": {
+    "238": {
+      "errors": [{
+        "message": "Required input is missing",
+        "details": "width",
+        "extra_info": { "input_name": "resize_type.width" }
+      }]
+    }
+  }
+}
+```
+
+**`extra_info.input_name` 字段会明确告诉你服务器所需的 JSON key 到底是什么。请原样使用。** 如果它显示 `"values.a"` 或 `"resize_type.width"`，那么这些就是 JSON 对象中实际的键名。不要基于对该字段“应该”叫什么的假设，将它们“简化”为扁平名称。
+
+## 规则 #3：不要从头重建 — 修补失败的节点
+
+每次从模板重新生成都会再次引入相同的 bug。相反，请执行以下操作：
+
+1. 提交工作流一次。
+2. 阅读服务器错误详情以获取确切的键名。
+3. 对磁盘上的工作流文件使用针对性的 patch/fix 调用。
+4. 重新提交并检查错误是否已解决。
+
+---
+
+## Reroute nodes：绕过，不要删除
+
+大多数服务器（本地、Cloud）没有 `Reroute` 节点类型。转换
+模板时：
+
+1. 通过查看 `target_id` = Reroute 节点 ID 的连线，找到输入到 Reroute 的内容。
+2. 将所有引用 Reroute 的输入替换为
+   `[source_node_id, source_slot]`。
+3. 从 API 映射中删除 Reroute 节点。
+
+**真实示例 — LTX 2.3 t2v 模板：**
+
+- Reroute 节点 255 从 `CheckpointLoaderSimple 236` 的槽位 2 接收 VAE。
+- 三个节点为其 VAE 输入引用了 Reroute 255：
+  `LTXVImgToVideoInplace` (230), `LTXVLatentUpsampler` (253),
+  `VAEDecodeTiled` (251)。
+- 修复：将所有出现的 `vae: ["255", 0]` 替换为 `vae: ["236", 2]`。
+- `CheckpointLoaderSimple` 槽位 2 = VAE（而不是槽位 0 = MODEL）。
+
+|  |  |
+| --- | --- |
+| ❌ 错误 | `vae: ["236", 0]` → `MODELV mismatch input_type(VAE)` |
+| ✅ 正确 | `vae: ["236", 2]` |
+
+---
+
+## 动态模板节点：带有点号的键名是正确的
+
+### ComfyMathExpression (COMFY_AUTOGROW_V3)
+
+```json
+{
+  "class_type": "ComfyMathExpression",
+  "inputs": {
+    "expression": "a/2",
+    "values.a": ["257", 0]
+  }
+}
+```
+
+- `values` 是一个 `COMFY_AUTOGROW_V3` 模板。
+- links 中的输入名称为 `values.a`, `values.b` 等。
+- **保持带有点号的格式作为 JSON keys。**
+- 不要转换为 `{"values": {"a": ...}}` 或展平为仅 `"a"`。
+
+### ResizeImageMaskNode (COMFY_DYNAMICCOMBO_V3)
+
+```json
+{
+  "class_type": "ResizeImageMaskNode",
+  "inputs": {
+    "input": ["276", 0],
+    "scale_method": "lanczos",
+    "resize_type": "scale dimensions",
+    "resize_type.width": 1920,
+    "resize_type.height": 1088,
+    "resize_type.crop": "center"
+  }
+}
+```
+
+- `resize_type` 是一个 `COMFY_DYNAMICCOMBO_V3`。
+- 特定于模式的字段：`resize_type.width`, `resize_type.height`, `resize_type.crop`。
+- `scale_method` 选项：`"nearest-exact"`, `"bilinear"`, `"area"`, `"bicubic"`, `"lanczos"`。
+- **保持带有点号的格式作为 JSON keys。**
+- 不要将 `resize_type.width` 展平为仅 `"width"`。
+
+---
+
+## 转换方案
+
+1. 从安装的包路径加载模板。
+2. 解析 `data['definitions']['subgraphs'][0]`。
+3. 对于每个节点（跳过 Reroute）：
+   - 从 `sg['links']` 字典解析链接的 inputs。
+   - 将 `widgets_values` 映射到 input 字段名称。
+   - 保持所有带点号的键名与模板中完全一致。
+4. 绕过 Reroute：追踪源，替换引用。
+5. 仅更改：prompt 文本、seed 值和用户请求的参数。
+6. 如果模板仅使用 `CreateVideo`，则添加 `SaveVideo` 终端节点。
+7. 提交 → 读取错误 → 修补特定节点 → 重新提交。
+
+## 模板中绝不更改的内容
+
+| 元素 | 原因 |
+| --------- | ----- |
+| Node topology | Graph 是为特定模型设计的 |
+| Sigmas 值 | 为 model/sampler 组合调整 |
+| LoRA/distilled 路径 | 质量必需，即使它们看起来未被使用 |
+| Model 参数 (cfg, steps, shifts) | 特定于模型 |
+| Conditioning 链 (zero-out, crop guides) | 正确的 conditioning 所需 |
+| Pass-through wiring | 不要移除节点，绕过它们 |
+
+---
+
+## Cloud 兼容性（已于 2025 年 5 月验证）
+
+完整的 LTX 2.3 T2V 模板（`video_ltx2_3_t2v.json`）在 Comfy Cloud 上**无需修改**即可运行。
+
+**确认可在 Cloud 上运行（所有自定义节点均可用）：**
+`ComfyMathExpression`, `ResizeImageMaskNode`, `ResizeImagesByLongerEdge`,
+`PrimitiveInt`, `PrimitiveStringMultiline`, `PrimitiveBoolean`, `SaveVideo`,
+`LTXVCropGuides`, `LTXVImgToVideoInplace`, `LTXVConcatAVLatent`,
+`LTXVSeparateAVLatent`, `LTXVLatentUpsampler`, `LTXVAudioVAELoader`,
+`LTXVAudioVAEDecode`, `LTXVEmptyLatentAudio`, `LTXVPreprocess`,
+`LTXVConditioning`, `ManualSigmas`, `LTXAVTextEncoderLoader` 以及所有核心
+节点。
+
+**针对 LTX 2.3 的 Cloud 与本地对比 (768x512)：**
+
+- Cloud：每个视频约 39 秒（快 4 倍）。
+- 本地（RTX 5090）：每个视频约 160 秒。
+- `example.png` 占位符在 Cloud 上适用于已绕过的依赖图像的路径。
+- 提交格式在本地和 Cloud 之间是**完全相同**的：
+  `{"prompt": wf, "extra_data": {}}` 发送至 `/api/prompt`。
+- 免费套餐 = 1 个并发任务。
+
+**Cloud 提交陷阱：**
+
+- `/api/object_info/<node>` 在免费套餐上返回 404 — 无法远程查询 node schemas，但工作流仍能正常运行。在构建工作流之前，请务必在本地探测 `object_info`。
+- Cloud 快约 4 倍 — 除非需要本地调试，否则批量运行时首选 Cloud。
+- Cloud `/api/view` 返回 **302 重定向至已签名的 GCS URL** — 使用
+  `curl -s -L` 进行跟随和下载。Python `urllib` 会因 401 失败
+  （将 auth headers 转发给 GCS CDN）。
+- `COMFY_CLOUD_API_KEY` 仅存在于 terminal/bash 环境中，而不在 Python sandbox 中。对于 Cloud API 调用，请使用 subprocess 或终端脚本。
+- Cloud 免费套餐**按顺序**处理任务（一次 1 个）。提交所有内容，然后轮询历史记录。
+- LTX 2.3 在 **1920x1080 下本地会 OOM**（即使是 RTX 5090）— upscaler pass 超出 VRAM。1080p 首选 Cloud；本地使用 1280x720（约 90 秒/视频）。
+
+---
+
+## FFmpeg 拼接设置（兼容 Discord）
+
+生成的 ComfyUI 视频通常使用 `yuv444p` 像素格式，这在 Discord 上无法使用。请使用以下命令重新编码：
+
+```bash
+ffmpeg -y -i input.mp4 \
+  -c:v libx264 -profile:v main -preset medium -crf 13 -pix_fmt yuv420p \
+  -c:a aac -b:a 192k \
+  output_discord.mp4
+```
+
+关键设置：
+
+- `-pix_fmt yuv420p` — **Discord 必需**，ComfyUI 默认输出 `yuv444p`。
+- `-crf 13` — 高质量且不会产生超大文件（默认的 23 质量损失过大）。
+- `-profile:v main` — 广泛兼容。
+
+对于多视频交叉淡入淡出拼接，链接 `xfade`（视频）和 `acrossfade`
+（音频）：
+
+```bash
+ffmpeg -y -i a.mp4 -i b.mp4 -i c.mp4 \
+  -filter_complex "[0:v][1:v]xfade=transition=fade:duration=1:offset=3.04[v1];[v1][2:v]xfade=transition=fade:duration=1:offset=6.08[vout];[0:a][1:a]acrossfade=duration=1:c1=tri:c2=tri[a1];[a1][2:a]acrossfade=duration=1:c1=tri:c2=tri[aout]" \
+  -map "[vout]" -map "[aout]" \
+  -c:v libx264 -profile:v main -crf 13 -pix_fmt yuv420p \
+  -c:a aac -b:a 192k \
+  output.mp4
+```
+
+xfade #N 的 Offset = `(N+1) × duration - N × overlap`。

package/extensions/skills/builtin/creative/comfyui/references/workflow-format.md

@@ -0,0 +1,205 @@
+# ComfyUI Workflow JSON 格式
+
+## 两种格式 — 仅 API 格式可执行
+
+`/api/prompt` 和此技能中的每个脚本都需要 **API 格式**。
+Web UI 也会生成一种用于可视化编辑的“编辑器格式”，该格式**不能**直接提交。
+
+### API 格式
+
+顶层键是字符串形式的 node ID。每个 node 都有 `class_type` 和 `inputs`：
+
+```json
+{
+  "3": {
+    "class_type": "KSampler",
+    "inputs": {
+      "seed": 156680208700286,
+      "steps": 20,
+      "cfg": 8,
+      "sampler_name": "euler",
+      "scheduler": "normal",
+      "denoise": 1.0,
+      "model": ["4", 0],
+      "positive": ["6", 0],
+      "negative": ["7", 0],
+      "latent_image": ["5", 0]
+    },
+    "_meta": {"title": "KSampler"}
+  },
+  "4": {
+    "class_type": "CheckpointLoaderSimple",
+    "inputs": {"ckpt_name": "v1-5-pruned-emaonly.safetensors"}
+  }
+}
+```
+
+**检测方式：** 每个顶层值都包含 `class_type`。该技能的 `_common.is_api_format()` 会执行此检查。
+
+### 编辑器格式（不可直接执行）
+
+包含 `nodes[]` 和 `links[]` 数组 — 即可视化图形。要转换格式：在 ComfyUI 的 Web UI 中打开，并使用 **Workflow → Export (API)**（较新的 UI）或 "Save (API Format)" 按钮（较旧的 UI）。
+
+**检测方式：** 顶层含有 `"nodes"` 和 `"links"` 键。
+
+## Inputs：字面量与 Links
+
+```json
+"inputs": {
+  "text": "a cat",         // 字面量 — 可修改
+  "seed": 42,              // 字面量 — 可修改
+  "clip": ["4", 1]         // link — 连线；请勿覆盖
+}
+```
+
+Links 是长度为 2 的数组，格式为 `[upstream_node_id, output_slot]`。该技能的参数注入器会拒绝使用字面量覆盖 link（会记录警告并跳过）。
+
+## 常见 Node 类型及其可控参数
+
+完整目录位于 `scripts/_common.py`（`PARAM_PATTERNS` 和 `MODEL_LOADERS`）。重点如下：
+
+### 文本提示词
+
+| Node Class | Key Fields |
+| ------------ | ------------ |
+| `CLIPTextEncode` | `text` |
+| `CLIPTextEncodeSDXL` | `text_g`, `text_l`, `width`, `height` |
+| `CLIPTextEncodeFlux` | `clip_l`, `t5xxl`, `guidance` |
+
+为了区分正向和负向，该技能会通过 Reroute / Primitive 节点将 `KSampler.negative` 回溯到源 CLIPTextEncode。如果回溯失败，则使用 `_meta.title` 启发式规则进行判断（"negative"、"neg"、"anti"）。
+
+### 采样
+
+| Node Class | Key Fields |
+| ------------ | ------------ |
+| `KSampler` | `seed`, `steps`, `cfg`, `sampler_name`, `scheduler`, `denoise` |
+| `KSamplerAdvanced` | `noise_seed`, `steps`, `cfg`, `start_at_step`, `end_at_step` |
+| `SamplerCustom` | `noise_seed`, `cfg`, `sampler`, `sigmas` |
+| `SamplerCustomAdvanced` | `noise_seed` (通过 RandomNoise 输入) |
+| `RandomNoise` | `noise_seed` |
+| `BasicScheduler` | `steps`, `scheduler`, `denoise` |
+| `KSamplerSelect` | `sampler_name` |
+| `BasicGuider` / `CFGGuider` | `cfg` |
+| `ModelSamplingFlux` | `max_shift`, `base_shift`, `width`, `height` |
+| `SDTurboScheduler` | `steps`, `denoise` |
+
+### Latent / 尺寸
+
+| Node Class | Key Fields |
+| ------------ | ------------ |
+| `EmptyLatentImage` | `width`, `height`, `batch_size` |
+| `EmptySD3LatentImage` | `width`, `height`, `batch_size` |
+| `EmptyHunyuanLatentVideo` | `width`, `height`, `length`, `batch_size` |
+| `EmptyMochiLatentVideo` | `width`, `height`, `length`, `batch_size` |
+| `EmptyLTXVLatentVideo` | `width`, `height`, `length`, `batch_size` |
+
+### 模型加载
+
+| Node Class | Key Fields | Folder |
+| ------------ | ------------ | -------- |
+| `CheckpointLoaderSimple` | `ckpt_name` | `checkpoints` |
+| `LoraLoader` | `lora_name`, `strength_model`, `strength_clip` | `loras` |
+| `LoraLoaderModelOnly` | `lora_name`, `strength_model` | `loras` |
+| `VAELoader` | `vae_name` | `vae` |
+| `ControlNetLoader` | `control_net_name` | `controlnet` |
+| `CLIPLoader` | `clip_name` | `clip` |
+| `DualCLIPLoader` | `clip_name1`, `clip_name2` | `clip` |
+| `TripleCLIPLoader` | `clip_name1/2/3` | `clip` |
+| `UNETLoader` | `unet_name` | `unet` |
+| `DiffusionModelLoader` | `model_name` | `diffusion_models` |
+| `UpscaleModelLoader` | `model_name` | `upscale_models` |
+| `IPAdapterModelLoader` | `ipadapter_file` | `ipadapter` |
+| `ADE_AnimateDiffLoaderWithContext` | `model_name`, `motion_scale` | `animatediff_models` |
+
+### 图像输入/输出
+
+| Node Class | Key Fields |
+| ------------ | ------------ |
+| `LoadImage` | `image`（服务器端文件名，上传后确定） |
+| `LoadImageMask` | `image`, `channel` (`red` / `green` / `blue` / `alpha`) |
+| `VAEEncode` / `VAEDecode` | （没有可控字段） |
+| `VAEEncodeForInpaint` | `grow_mask_by` |
+| `SaveImage` | `filename_prefix` |
+| `VHS_VideoCombine` | `frame_rate`, `format`, `filename_prefix`, `loop_count`, `pingpong` |
+
+### ControlNet
+
+| Node Class | Key Fields |
+| ------------ | ------------ |
+| `ControlNetApply` | `strength` |
+| `ControlNetApplyAdvanced` | `strength`, `start_percent`, `end_percent` |
+
+### IPAdapter（社区包 `comfyui_ipadapter_plus`）
+
+| Node Class | Key Fields |
+| ------------ | ------------ |
+| `IPAdapterAdvanced` | `weight`, `start_at`, `end_at` |
+| `IPAdapter` | `weight` |
+
+### Embeddings（在提示词字符串内引用）
+
+ComfyUI 会扫描提示词文本中的 `embedding:NAME` 语法。该技能的 `_common.iter_embedding_refs()` 会将这些内容提取为模型依赖项。
+
+```text
+"a beautiful cat, embedding:goodvibes:1.2, embedding:art-style"
+```
+
+`extract_schema.py` 和 `check_deps.py` 会在 `embedding_dependencies` / `missing_embeddings` 中展示这些内容。
+
+## 参数注入模式
+
+```python
+import json, copy
+
+with open("workflow_api.json") as f:
+    workflow = json.load(f)
+
+wf = copy.deepcopy(workflow)
+wf["6"]["inputs"]["text"] = "a beautiful sunset"
+wf["7"]["inputs"]["text"] = "ugly, blurry"
+wf["3"]["inputs"]["seed"] = 42
+wf["3"]["inputs"]["steps"] = 30
+wf["5"]["inputs"]["width"] = 1024
+wf["5"]["inputs"]["height"] = 1024
+```
+
+`scripts/extract_schema.py` 会自动发现哪些 node ID/字段对应于哪些面向用户的参数。它返回一个 `parameters` 字典，`run_workflow.py` 会读取该字典以注入来自 `--args` 的值。
+
+## 识别可控参数（启发式规则）
+
+对于未知的 workflow：
+
+1. **提示词文本** — 任何 `CLIPTextEncode.text`。使用从 `KSampler.positive` / `.negative` 的连接回溯来消除歧义（不要仅依赖 meta-title）。
+2. **Seed** — `KSampler.seed` / `KSamplerAdvanced.noise_seed` / `RandomNoise.noise_seed`。
+3. **尺寸** — `Empty*LatentImage.width/height`（必须是 8 的倍数）。
+4. **Steps / CFG** — `KSampler.steps`, `KSampler.cfg`。Steps 通常为 20–50。
+   CFG 通常为 5–15（Flux 使用的是 guidance，而不是 CFG）。
+5. **模型 / checkpoint** — `CheckpointLoaderSimple.ckpt_name`。文件名必须与已安装的文件*完全*匹配。
+6. **LoRA** — `LoraLoader.lora_name`, `.strength_model`。
+7. **用于图生图 / inpaint 的图像** — `LoadImage.image`。上传后的服务器端文件名。
+8. **Denoise** — `KSampler.denoise`。0.0–1.0；1.0 = 忽略输入图像，
+   0.0 = 直接透传。图生图的最佳区间：0.4–0.7。
+
+## 输出节点
+
+输出由这些 node 类型生成。该技能的 `OUTPUT_NODES` 集合已扩展至常见的社区包。
+
+| Node | Output Key | Content |
+| ------ | ----------- | --------- |
+| `SaveImage` | `images` | `{filename, subfolder, type}` 的列表 |
+| `PreviewImage` | `images` | 临时预览（未保存） |
+| `VHS_VideoCombine` | `gifs`（较旧）或 `videos`/`video`（较新的云端） | 视频文件引用 |
+| `SaveAudio` | `audio` | 音频文件引用 |
+| `SaveAnimatedWEBP` / `SaveAnimatedPNG` | `images` | 动画图像 |
+| `Save3D` | `3d` | 3D 资产引用 |
+
+执行后，从 `/history/{prompt_id}`（本地）或 `/api/jobs/{prompt_id}`（云端）获取输出 → `outputs` → `{node_id}` → `{key}`。
+
+## Wrapper 变体
+
+一些保存的 JSON 文件会将 workflow 包装在 `"prompt"` 键下（与 `/api/prompt` 负载结构相匹配）。该技能的 `_common.unwrap_workflow()` 会处理此问题 — 支持传入以下任一种：
+
+- 原始 API 格式：`{"3": {...}, "4": {...}}`
+- 包装格式：`{"prompt": {"3": {...}}, "client_id": "..."}`
+
+它会拒绝编辑器格式，并提供清晰的错误提示及重新导出的说明。