@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/comfyui/scripts/ws_monitor.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""
+ws_monitor.py — Real-time ComfyUI WebSocket monitor.
+
+Connects to /ws and pretty-prints execution events: node start/finish, sampling
+progress, cached nodes, errors. Optionally writes preview frames to disk.
+
+Useful for:
+  - Watching a long-running job in real time without parsing JSON yourself
+  - Saving in-progress preview frames for video / animation workflows
+  - Debugging "why is this hanging?" — see exactly which node is stuck
+
+Usage:
+    # 本地 — 监视此 client_id 的所有作业
+    python3 ws_monitor.py
+
+    # 云端 — 监视特定的 prompt_id
+    python3 ws_monitor.py --host https://cloud.comfy.org \
+        --prompt-id abc-123-def
+
+    # 将预览帧保存到 ./previews/
+    python3 ws_monitor.py --previews ./previews
+
+Requires: websocket-client (`pip install websocket-client`).
+Falls back to a clear error message when not installed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import struct
+import sys
+from pathlib import Path
+from urllib.parse import urlparse
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from _common import (  # noqa: E402
+    DEFAULT_LOCAL_HOST, ENV_API_KEY, log, new_client_id, resolve_api_key, is_cloud_host,
+)
+
+
+# 来自 ComfyUI WebSocket 协议的二进制帧类型
+BINARY_PREVIEW_IMAGE = 1
+BINARY_TEXT = 3
+BINARY_PREVIEW_IMAGE_WITH_METADATA = 4
+
+# PREVIEW_IMAGE 内部的图像类型代码
+IMAGE_TYPE_JPEG = 1
+IMAGE_TYPE_PNG = 2
+
+# ANSI 转义码（适用于大多数现代终端）
+RESET = "\033[0m"
+DIM = "\033[2m"
+BOLD = "\033[1m"
+GREEN = "\033[32m"
+YELLOW = "\033[33m"
+RED = "\033[31m"
+CYAN = "\033[36m"
+
+
+def fmt_color(s: str, color: str, *, color_on: bool = True) -> str:
+    return f"{color}{s}{RESET}" if color_on else s
+
+
+def parse_binary_frame(data: bytes) -> dict | None:
+    if len(data) < 8:
+        return None
+    type_code = struct.unpack(">I", data[0:4])[0]
+    if type_code == BINARY_PREVIEW_IMAGE:
+        image_type = struct.unpack(">I", data[4:8])[0]
+        ext = "jpg" if image_type == IMAGE_TYPE_JPEG else "png" if image_type == IMAGE_TYPE_PNG else "bin"
+        return {
+            "kind": "preview",
+            "image_type": image_type,
+            "ext": ext,
+            "image_bytes": data[8:],
+        }
+    if type_code == BINARY_PREVIEW_IMAGE_WITH_METADATA:
+        if len(data) < 12:
+            return None
+        meta_len = struct.unpack(">I", data[4:8])[0]
+        meta_end = 8 + meta_len
+        if len(data) < meta_end:
+            return None
+        try:
+            meta = json.loads(data[8:meta_end].decode("utf-8"))
+        except Exception:
+            meta = {"raw": data[8:meta_end][:200].decode("utf-8", "replace")}
+        return {
+            "kind": "preview_with_metadata",
+            "metadata": meta,
+            "image_bytes": data[meta_end:],
+            "ext": "png",
+        }
+    if type_code == BINARY_TEXT:
+        if len(data) < 8:
+            return None
+        nid_len = struct.unpack(">I", data[4:8])[0]
+        nid_end = 8 + nid_len
+        if len(data) < nid_end:
+            return None
+        return {
+            "kind": "text",
+            "node_id": data[8:nid_end].decode("utf-8", "replace"),
+            "text": data[nid_end:].decode("utf-8", "replace"),
+        }
+    return {"kind": "unknown", "type_code": type_code, "size": len(data)}
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description="Real-time ComfyUI WebSocket monitor")
+    p.add_argument("--host", default=DEFAULT_LOCAL_HOST, help="ComfyUI server URL")
+    p.add_argument("--api-key", help=f"API key for cloud (or set ${ENV_API_KEY} env var)")
+    p.add_argument("--client-id", default=None, help="Client ID (default: random UUID)")
+    p.add_argument("--prompt-id", default=None,
+                   help="Filter to a specific prompt_id (default: all jobs)")
+    p.add_argument("--previews", default=None,
+                   help="Directory to save in-progress preview frames")
+    p.add_argument("--no-color", action="store_true", help="Disable ANSI colour")
+    p.add_argument("--timeout", type=float, default=600.0,
+                   help="Hard cap on monitor duration (default 600s)")
+    args = p.parse_args(argv)
+
+    try:
+        import websocket  # type: ignore[import-not-found]
+    except ImportError:
+        print(json.dumps({
+            "error": "websocket-client not installed",
+            "install": "pip install websocket-client",
+        }))
+        return 1
+
+    api_key = resolve_api_key(args.api_key)
+    cloud = is_cloud_host(args.host)
+    client_id = args.client_id or new_client_id()
+
+    # 构建 WS URL，保留任何基础路径组件（例如位于反向代理之后）。
+    parsed = urlparse(args.host if "://" in args.host else f"http://{args.host}")
+    scheme = "wss" if parsed.scheme == "https" else "ws"
+    netloc = parsed.netloc
+    base_path = parsed.path.rstrip("/")
+    ws_url = f"{scheme}://{netloc}{base_path}/ws?clientId={client_id}"
+    if cloud and api_key:
+        ws_url += f"&token={api_key}"
+
+    color_on = not args.no_color and sys.stdout.isatty()
+
+    preview_dir = Path(args.previews).expanduser() if args.previews else None
+    if preview_dir:
+        preview_dir.mkdir(parents=True, exist_ok=True)
+        log(f"Saving previews to {preview_dir}")
+
+    log(f"Connecting to {ws_url} (client_id={client_id})")
+    if args.prompt_id:
+        log(f"Filtering messages to prompt_id={args.prompt_id}")
+
+    ws = websocket.create_connection(ws_url, timeout=args.timeout)
+    ws.settimeout(args.timeout)
+
+    preview_counter = 0
+    try:
+        while True:
+            try:
+                msg = ws.recv()
+            except websocket.WebSocketTimeoutException:
+                log(f"Idle for {args.timeout}s — exiting")
+                return 0
+            if isinstance(msg, bytes):
+                parsed = parse_binary_frame(msg)
+                if parsed is None:
+                    continue
+                if parsed["kind"] in {"preview", "preview_with_metadata"} and preview_dir:
+                    img_bytes = parsed.get("image_bytes", b"")
+                    if img_bytes:
+                        ext = parsed.get("ext", "png")
+                        out = preview_dir / f"preview_{preview_counter:05d}.{ext}"
+                        out.write_bytes(img_bytes)
+                        preview_counter += 1
+                        log(f"  [preview] saved {out.name} ({len(img_bytes)} bytes)")
+                continue
+
+            try:
+                payload = json.loads(msg)
+            except Exception:
+                continue
+            mtype = payload.get("type", "")
+            mdata = payload.get("data", {}) or {}
+            pid = mdata.get("prompt_id")
+
+            if args.prompt_id and pid and pid != args.prompt_id:
+                continue
+
+            if mtype == "status":
+                qr = mdata.get("status", {}).get("exec_info", {}).get("queue_remaining", "?")
+                print(fmt_color(f"[status] queue_remaining={qr}", DIM, color_on=color_on))
+            elif mtype == "execution_start":
+                print(fmt_color(f"[start] prompt_id={pid}", BOLD, color_on=color_on))
+            elif mtype == "executing":
+                node = mdata.get("node")
+                if node:
+                    print(fmt_color(f"  [executing] node={node}", CYAN, color_on=color_on))
+                else:
+                    print(fmt_color(f"  [executing] (workflow done) prompt_id={pid}", DIM, color_on=color_on))
+            elif mtype == "progress":
+                v, m = mdata.get("value", 0), mdata.get("max", 0)
+                pct = (v / m * 100) if m else 0
+                print(f"    [progress] {v}/{m} ({pct:5.1f}%) node={mdata.get('node')}")
+            elif mtype == "progress_state":
+                # 较新的扩展进度消息
+                nodes = mdata.get("nodes") or {}
+                running = [k for k, v in nodes.items() if v.get("running")]
+                if running:
+                    print(fmt_color(f"    [progress_state] running={running}", DIM, color_on=color_on))
+            elif mtype == "executed":
+                node = mdata.get("node")
+                out = mdata.get("output") or {}
+                summary_parts = []
+                for key in ("images", "video", "videos", "gifs", "audio", "files"):
+                    if out.get(key):
+                        summary_parts.append(f"{key}={len(out[key])}")
+                summary = ", ".join(summary_parts) if summary_parts else "(no files)"
+                print(fmt_color(f"  [executed] node={node} {summary}", GREEN, color_on=color_on))
+            elif mtype == "execution_cached":
+                cached = mdata.get("nodes") or []
+                if cached:
+                    print(fmt_color(f"  [cached] {len(cached)} nodes skipped", DIM, color_on=color_on))
+            elif mtype == "execution_success":
+                print(fmt_color(f"[success] prompt_id={pid}", GREEN + BOLD, color_on=color_on))
+                if args.prompt_id:
+                    return 0
+            elif mtype == "execution_error":
+                exc_type = mdata.get("exception_type", "?")
+                exc_msg = mdata.get("exception_message", "?")
+                print(fmt_color(f"[error] {exc_type}: {exc_msg}", RED + BOLD, color_on=color_on))
+                tb = mdata.get("traceback")
+                if tb:
+                    if isinstance(tb, list):
+                        for line in tb:
+                            print(fmt_color(f"  {line}", RED, color_on=color_on))
+                    else:
+                        print(fmt_color(f"  {tb}", RED, color_on=color_on))
+                if args.prompt_id:
+                    return 1
+            elif mtype == "execution_interrupted":
+                print(fmt_color(f"[interrupted] prompt_id={pid}", YELLOW, color_on=color_on))
+                if args.prompt_id:
+                    return 1
+            elif mtype == "notification":
+                v = mdata.get("value", "")
+                print(fmt_color(f"[notification] {v}", DIM, color_on=color_on))
+            else:
+                # 未知 / 很少使用的类型：紧凑打印
+                print(fmt_color(f"[{mtype}] {json.dumps(mdata, default=str)[:200]}", DIM, color_on=color_on))
+
+    except KeyboardInterrupt:
+        log("Interrupted")
+        return 130
+    finally:
+        try:
+            ws.close()
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/extensions/skills/builtin/creative/comfyui/tests/README.md

@@ -0,0 +1,44 @@
+# tests 说明
+
+涵盖该技能脚本的 Pytest 套件。纯标准库单元测试无需任何设置即可运行；云端集成测试需要 Comfy Cloud API 密钥。
+
+## 运行
+
+```bash
+# Unit tests only (no network required) — runs in <1s
+python3 -m pytest tests/ -c tests/pytest.ini -o addopts="-p no:xdist"
+
+# Including cloud integration tests
+COMFY_CLOUD_API_KEY="comfyui-..." python3 -m pytest tests/ \
+  -c tests/pytest.ini -o addopts="-p no:xdist"
+
+# Just cloud tests
+COMFY_CLOUD_API_KEY="comfyui-..." python3 -m pytest tests/test_cloud_integration.py \
+  -c tests/pytest.ini -o addopts="-p no:xdist" -v
+```
+
+`-c` 和 `-o` 覆盖项可将此测试套件与任何父级 `pyproject.toml` 的 pytest 配置（例如父仓库的 `-n auto`）隔离开来。
+
+## 测试文件
+
+| File | Coverage |
+| ------ | ---------- |
+| `test_common.py` | Cloud detection, URL routing, format validation, embeddings, paths, seeds, model-list parsing, folder aliases |
+| `test_extract_schema.py` | Connection tracing、positive/negative prompt detection、dedup logic、embedding deps |
+| `test_run_workflow.py` | Param injection (incl. -1 seed, link refusal), output download walk, runner construction |
+| `test_check_deps.py` | Model-name fuzzy matching, install 命令 suggestions |
+| `test_cloud_integration.py` | Live cloud API contract tests (auto-skipped without API key) |
+
+## Adding tests
+
+当你修改脚本时：
+
+1. 如果改动是纯 logic（cloud detection、parsing 等），请添加 unit test。
+2. 如果改动依赖于 cloud API 行为，请添加 cloud integration test
+   （使用 `pytestmark = pytest.mark.cloud`，以便在没有密钥时自动跳过）
+3. 工作流 fixtures 位于 `conftest.py` 中 (`sd15_workflow`, `flux_workflow`,
+   `video_workflow`)
+
+## Why the explicit `-c` / `-o`?
+
+父级 hermes-agent 仓库的 `pyproject.toml` 默认启用了 `pytest-xdist` (`-n auto`)。此套件规模足够小，开启并行化并不值得增加这种复杂性，而且 pytest-xdist 并不总是安装在用户的环境中。`-c tests/pytest.ini -o addopts="-p no:xdist"` 标志可确保无论父项目的配置如何，该套件的运行方式都完全一致。

package/extensions/skills/builtin/creative/comfyui/tests/conftest.py

@@ -0,0 +1,64 @@
+"""Pytest configuration for the comfyui skill test suite.
+
+Adds `scripts/` to sys.path so tests can `from _common import ...`, and
+provides a few common fixtures.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPTS = ROOT / "scripts"
+WORKFLOWS = ROOT / "workflows"
+
+sys.path.insert(0, str(SCRIPTS))
+
+
+@pytest.fixture
+def sd15_workflow() -> dict:
+    return json.loads((WORKFLOWS / "sd15_txt2img.json").read_text())
+
+
+@pytest.fixture
+def flux_workflow() -> dict:
+    return json.loads((WORKFLOWS / "flux_dev_txt2img.json").read_text())
+
+
+@pytest.fixture
+def video_workflow() -> dict:
+    return json.loads((WORKFLOWS / "wan_video_t2v.json").read_text())
+
+
+@pytest.fixture
+def workflows_dir() -> Path:
+    return WORKFLOWS
+
+
+@pytest.fixture
+def scripts_dir() -> Path:
+    return SCRIPTS
+
+
+@pytest.fixture
+def cloud_key() -> str | None:
+    """Cloud API key if set, otherwise None.
+
+    Tests that need cloud connectivity should skip when this is None.
+    """
+    return os.environ.get("COMFY_CLOUD_API_KEY")
+
+
+def pytest_collection_modifyitems(config, items):
+    """Auto-skip cloud tests when no API key is set."""
+    if os.environ.get("COMFY_CLOUD_API_KEY"):
+        return
+    skip_cloud = pytest.mark.skip(reason="Set COMFY_CLOUD_API_KEY to run cloud tests")
+    for item in items:
+        if "cloud" in item.keywords:
+            item.add_marker(skip_cloud)

package/extensions/skills/builtin/creative/comfyui/tests/pytest.ini

@@ -0,0 +1,5 @@
+[pytest]
+markers =
+    cloud: tests that hit live Comfy Cloud API (require COMFY_CLOUD_API_KEY)
+testpaths = .
+addopts = -p no:xdist

package/extensions/skills/builtin/creative/comfyui/tests/test_check_deps.py

@@ -0,0 +1,68 @@
+"""Tests for check_deps.py — focuses on parsing logic that doesn't need a server."""
+
+from __future__ import annotations
+
+from check_deps import (
+    NODE_TO_PACKAGE,
+    model_present,
+    normalize_for_match,
+    suggest_install_command,
+)
+
+
+class TestNormalizeForMatch:
+    def test_basic(self):
+        s = normalize_for_match("model.safetensors")
+        assert "model.safetensors" in s
+        assert "model" in s
+
+    def test_subfolder(self):
+        s = normalize_for_match("subdir/model.pt")
+        assert "subdir/model.pt" in s
+        assert "model.pt" in s
+        assert "model" in s
+
+
+class TestModelPresent:
+    def test_exact_match(self):
+        assert model_present("a.safetensors", {"a.safetensors", "b.safetensors"}) is True
+
+    def test_extension_difference(self):
+        # User said "model" but installed is "model.safetensors"
+        assert model_present("model", {"model.safetensors"}) is True
+        # Reverse direction — also matches
+        assert model_present("model.safetensors", {"model"}) is True
+
+    def test_subfolder_match(self):
+        # Installed list has "subdir/model.safetensors", workflow asks "model.safetensors"
+        assert model_present("model.safetensors", {"subdir/model.safetensors"}) is True
+
+    def test_missing(self):
+        assert model_present("missing.safetensors", {"a.safetensors", "b.safetensors"}) is False
+
+    def test_empty_installed(self):
+        assert model_present("anything.safetensors", set()) is False
+
+
+class TestSuggestInstallCommand:
+    def test_known_node(self):
+        cmd = suggest_install_command("VHS_VideoCombine")
+        assert cmd == "comfy node install comfyui-videohelpersuite"
+
+    def test_unknown_node(self):
+        assert suggest_install_command("SomeRandomNodeName123") is None
+
+
+class TestNodePackageMap:
+    def test_no_duplicates(self):
+        # Each node should map to exactly one package
+        keys = list(NODE_TO_PACKAGE.keys())
+        assert len(keys) == len(set(keys))
+
+    def test_packages_are_safe_for_shell(self):
+        # Registry slugs must be alphanumerics + hyphens/underscores only
+        # (passed straight to `comfy node install <pkg>`).
+        import re
+        safe = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._\-]*$")
+        for pkg in NODE_TO_PACKAGE.values():
+            assert safe.match(pkg), f"Unsafe package slug: {pkg!r}"

package/extensions/skills/builtin/creative/comfyui/tests/test_cloud_integration.py

@@ -0,0 +1,95 @@
+"""Integration tests against the live Comfy Cloud API.
+
+These tests are auto-skipped when COMFY_CLOUD_API_KEY is not set.
+They never SUBMIT workflows (would need a paid subscription) — they only
+verify the read-only endpoints we rely on.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from _common import http_get, parse_model_list, resolve_url
+
+
+pytestmark = pytest.mark.cloud
+
+
+class TestCloudEndpointsLive:
+    def test_system_stats_reachable(self, cloud_key):
+        url = resolve_url("https://cloud.comfy.org", "/system_stats")
+        r = http_get(url, headers={"X-API-Key": cloud_key})
+        assert r.status == 200
+        data = r.json()
+        assert "system" in data
+
+    def test_models_endpoint_routed_to_experiment(self, cloud_key):
+        # We expect the skill to route /models/checkpoints → /api/experiment/models/checkpoints
+        url = resolve_url("https://cloud.comfy.org", "/models/checkpoints")
+        assert "/api/experiment/models/checkpoints" in url
+        r = http_get(url, headers={"X-API-Key": cloud_key})
+        assert r.status == 200
+
+    def test_models_endpoint_returns_dicts(self, cloud_key):
+        url = resolve_url("https://cloud.comfy.org", "/models/checkpoints")
+        r = http_get(url, headers={"X-API-Key": cloud_key})
+        data = r.json()
+        assert isinstance(data, list)
+        if data:
+            # Cloud format: list of dicts with `name`
+            assert isinstance(data[0], dict)
+            assert "name" in data[0]
+            # Our parser normalizes both
+            normalized = parse_model_list(data)
+            assert len(normalized) == len(data)
+
+    def test_history_renamed_to_v2(self, cloud_key):
+        # /history → /api/history_v2 on cloud
+        url = resolve_url("https://cloud.comfy.org", "/history/some-fake-id")
+        assert "/api/history_v2/some-fake-id" in url
+
+    def test_object_info_paid_tier(self, cloud_key):
+        # On free tier, /object_info returns 403 with a recognizable message
+        url = resolve_url("https://cloud.comfy.org", "/object_info")
+        r = http_get(url, headers={"X-API-Key": cloud_key})
+        # Should be either 200 (paid) or 403 (free) — not 404 / 500
+        assert r.status in {200, 403}
+        if r.status == 403:
+            # Body should mention the limitation
+            assert "free tier" in r.text().lower() or "subscription" in r.text().lower()
+
+
+class TestCloudCheckDepsLive:
+    def test_check_deps_against_cloud(self, cloud_key, sd15_workflow):
+        from check_deps import check_deps
+        report = check_deps(sd15_workflow, host="https://cloud.comfy.org", api_key=cloud_key)
+        # Either node check passed OR was skipped (free tier)
+        assert "missing_models" in report
+        assert "is_cloud" in report and report["is_cloud"] is True
+
+    def test_flux_workflow_models_resolved_via_aliases(self, cloud_key, flux_workflow):
+        """Flux uses unet/clip folders; cloud has them in diffusion_models/text_encoders.
+        With folder aliasing, the check should still find them."""
+        from check_deps import check_deps
+        report = check_deps(flux_workflow, host="https://cloud.comfy.org", api_key=cloud_key)
+        # The exact required Flux files (flux1-dev.safetensors, t5xxl_fp16, clip_l, ae)
+        # are present on cloud; with folder aliasing, none should be missing.
+        # If this fails, either the cloud removed the model or the aliasing logic broke.
+        missing_filenames = {m["value"] for m in report["missing_models"]}
+        assert "ae.safetensors" not in missing_filenames, \
+            "ae.safetensors should be on cloud's vae folder"
+        # t5xxl_fp16 / clip_l should be reachable via the clip → text_encoders alias
+        # flux1-dev.safetensors likewise via unet → diffusion_models
+
+
+class TestHealthCheckLive:
+    def test_health_check_passes(self, cloud_key, capsys):
+        from health_check import main as health_main
+        rc = health_main(["--host", "https://cloud.comfy.org", "--api-key", cloud_key])
+        captured = capsys.readouterr()
+        # Should produce JSON
+        import json
+        report = json.loads(captured.out)
+        assert report["server"]["reachable"] is True
+        assert report["checkpoints"]["queryable"] is True
+        assert report["checkpoints"]["count"] > 0