From 109d0d805a98936e0cbb22cd9417e441890f47cb Mon Sep 17 00:00:00 2001 From: lgldlk <1851293758@qq.com> Date: Wed, 18 Mar 2026 02:07:56 +0800 Subject: [PATCH] docs: describe workflow import flows --- README.md | 21 ++++------ README.zh.md | 21 ++++------ SKILL.md | 15 +++++-- references/workflow-import.md | 77 +++++++++++++++++++++++++++++++++++ 4 files changed, 103 insertions(+), 31 deletions(-) create mode 100644 references/workflow-import.md diff --git a/README.md b/README.md index b9bb1a6..123abc6 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ For the upstream ComfyUI local server routes that back this skill, see [docs/com - Set up parameters in three steps: upload a workflow, pick the nodes to expose, then name and describe each parameter - Input nodes are detected automatically from the workflow — no need to hunt through the JSON by hand - When you update a workflow, preview the parameter changes first and carry over existing mappings +- Supports bulk workflow import from a ComfyUI server or local JSON files ### Multi-Server Management - Manage multiple ComfyUI servers and route jobs to different machines as needed @@ -28,7 +29,6 @@ For the upstream ComfyUI local server routes that back this skill, see [docs/com - Set a per-server output directory and choose a default server ### Web UI -- Frontend source lives in a [separate repository](https://github.com/HuangYuChuh/ComfyUI_Skills_OpenClaw-frontend); run `scripts/update_frontend.sh` to pull the latest build - A local web interface for managing all servers and workflows in one place - Reorder workflows by dragging, or sort by name, status, or custom order - Search and filter workflows across all servers @@ -211,7 +211,6 @@ Configure the server first. Minimal example: "id": "local", // Server ID, also used as the directory name and workflow prefix "name": "Local", // Display name "url": "http://127.0.0.1:8188", // ComfyUI server URL - "auth": "", // Optional: Authorization header value (e.g. "Bearer your-token") "enabled": true, // Whether this server is enabled "output_dir": "./outputs" // Image output directory } @@ -336,7 +335,6 @@ You can configure multiple ComfyUI servers so OpenClaw can route jobs across dif ### Core Concepts - **Dual-Layer Toggles**: Both *servers* and *individual workflows* can be enabled or disabled. A workflow is only visible to the AI agent if **both** the server and the workflow itself are enabled. - **Namespacing**: Workflows are identified with a composite ID: `/` (e.g., `local/sdxl-base` vs. `remote-a100/sdxl-base`). -- **Authentication**: Remote servers behind a reverse proxy can require an auth token. Set the `auth` field in the server config to the `Authorization` header value (e.g. `Bearer your-token`). The token is stored locally in `config.json` (gitignored) and never leaves your machine. Use the "Test Connection" button in the UI to verify access before saving. ### CLI Configuration On headless machines, you can use the built-in CLI tool `scripts/server_manager.py`: @@ -390,22 +388,17 @@ Default import behavior: ## Roadmap -- [x] Split frontend source into a standalone repository -- [x] Server health monitoring with live UI indicators -- [x] Configuration import/export for cross-machine migration -- [x] First-class support for OpenClaw, Claude Code, and Codex -- [x] Multilingual UI (English, Simplified Chinese, Traditional Chinese) +- [ ] Workflow version history and rollback - [x] Upgrade preview before applying a new workflow version - [x] Parameter migration support when upgrading a workflow - [x] Authentication support for remote ComfyUI servers +- [x] Better schema validation before queueing +- [x] Richer error reporting from ComfyUI node errors +- [ ] Optional batch generation / multi-seed helpers - [ ] Execution history with parameter and result tracking - [ ] Webhook callbacks on task completion - [ ] Scheduled workflow execution (cron-style) - [ ] Guided workflow rewrite recipes for agents -- [ ] Workflow version history and rollback -- [x] Better schema validation before queueing -- [x] Richer error reporting from ComfyUI node errors - --- @@ -432,7 +425,6 @@ ComfyUI_Skills_OpenClaw/ │ ├── server_manager.py # CLI tool for managing servers │ ├── registry.py # List workflows + exposed parameters for agent │ ├── comfyui_client.py # Inject args, queue prompt, poll history, download images -│ ├── update_frontend.sh # Download latest frontend build from GitHub Release │ └── shared/ # Shared config & JSON utils (reused across scripts) │ ├── config.py │ ├── json_utils.py @@ -442,11 +434,12 @@ ComfyUI_Skills_OpenClaw/ │ ├── open_ui.py # Agent-friendly UI launcher │ ├── services.py # Business logic (workflow CRUD) │ ├── models.py # Pydantic request/response models +│ ├── json_store.py # Low-level JSON file read/write helpers │ ├── settings.py # App-level settings │ ├── run_ui.sh # Start UI (macOS/Linux) │ ├── run_ui.command # Double-click launcher (macOS) │ ├── run_ui.bat # Launcher (Windows) -│ └── static/ # Pre-built frontend assets +│ └── static/ # Modular ES6 frontend (HTML/CSS/JS) └── outputs/ └── .gitkeep ``` diff --git a/README.zh.md b/README.zh.md index 57759c8..30b7703 100644 --- a/README.zh.md +++ b/README.zh.md @@ -16,6 +16,7 @@ - 三步完成参数配置：上传工作流 → 选择要暴露的节点 → 设定参数名称和说明 - 上传工作流后自动识别可配置的输入节点，不需要手动逐个查找 - 工作流更新时可以先预览参数变化，已有的映射关系会自动迁移 +- 支持从 ComfyUI 服务器或本地 JSON 文件批量导入工作流 ### 多服务器管理 - 同时管理多台 ComfyUI 服务器，按需把生图任务分发到不同机器 @@ -24,7 +25,6 @@ - 可以为每台服务器单独设置输出目录，并指定默认服务器 ### 管理界面 -- 前端源码位于[独立仓库](https://github.com/HuangYuChuh/ComfyUI_Skills_OpenClaw-frontend)；运行 `scripts/update_frontend.sh` 可拉取最新构建 - 提供本地 Web 界面，统一管理所有服务器和工作流 - 支持拖拽调整工作流顺序，也可按名称、启用状态等方式排序 - 可跨服务器搜索和筛选工作流 @@ -207,7 +207,6 @@ cp config.example.json config.json "id": "local", // 服务器 ID，后面会作为目录名和工作流调用前缀 "name": "Local", // 服务器显示名称 "url": "http://127.0.0.1:8188", // ComfyUI 服务地址 - "auth": "", // 可选：鉴权令牌，填入 Authorization header 的值（如 "Bearer your-token"） "enabled": true, // 是否启用这个服务器 "output_dir": "./outputs" // 图片输出目录 } @@ -333,7 +332,6 @@ python scripts/comfyui_client.py \ ### 核心概念 - **双层控制开关**：`服务器` 和 `独立工作流` 均有各自的开启/关闭状态。OpenClaw 只能发现**两者均开启**的工作流。 - **命名空间组合**：OpenClaw 识别工作流的唯一标识为 `/` 的复合格式（例如：`local/test` 与 `remote/test`）。 -- **远程鉴权**：如果远程服务器通过反向代理要求鉴权，可以在服务器配置中设置 `auth` 字段，填入 `Authorization` header 的值（如 `Bearer your-token`）。令牌仅存储在本地 `config.json` 中（已被 gitignore），不会上传。在 UI 中可以使用「测试连接」按钮验证访问是否正常。 ### 命令行工具配置 在无 GUI 的 Linux 机器部署时，可使用内置的 CLI 工具（`scripts/server_manager.py`）进行管理： @@ -387,22 +385,17 @@ python scripts/transfer_manager.py import --input ./openclaw-skill-export.json ## 路线图 -- [x] 前端源码分离到独立仓库 -- [x] 服务器健康状态检测与 UI 指示器 -- [x] 配置导入导出，支持跨机器迁移 -- [x] 多 Agent 支持（OpenClaw / Claude Code / Codex） -- [x] 多语言界面（英文 / 简体中文 / 繁体中文） +- [ ] 支持工作流版本历史和回滚 - [x] 上传新版本前先预览参数变化 - [x] 工作流升级时支持参数迁移 - [x] 远程 ComfyUI 服务器鉴权支持 +- [x] 增强提交前参数校验 +- [x] 更清晰展示 ComfyUI 返回的节点错误 +- [ ] 支持批量多 seed 生成 - [ ] 执行历史记录（参数 + 结果追溯） - [ ] 任务完成后 Webhook 回调通知 - [ ] 定时执行工作流（cron 风格） - [ ] 引导式工作流改写模板（Rewrite Recipe） -- [ ] 支持工作流版本历史和回滚 -- [x] 增强提交前参数校验 -- [x] 更清晰展示 ComfyUI 返回的节点错误 - --- @@ -429,7 +422,6 @@ ComfyUI_Skills_OpenClaw/ │ ├── server_manager.py # 管理多服务器配置的 CLI 工具 │ ├── registry.py # 列出可用工作流及参数 │ ├── comfyui_client.py # 注入参数、提交任务、轮询完成、下载图片 -│ ├── update_frontend.sh # 从 GitHub Release 下载最新前端构建 │ └── shared/ # 跨脚本共用的配置与 JSON 工具 │ ├── config.py │ ├── json_utils.py @@ -439,11 +431,12 @@ ComfyUI_Skills_OpenClaw/ │ ├── open_ui.py # 供 Agent 调用的 UI 启动入口 │ ├── services.py # 业务逻辑（工作流增删改查） │ ├── models.py # Pydantic 请求/响应模型 +│ ├── json_store.py # JSON 文件读写封装 │ ├── settings.py # 应用级配置 │ ├── run_ui.sh # 启动脚本（macOS/Linux） │ ├── run_ui.command # macOS 双击启动 │ ├── run_ui.bat # Windows 启动 -│ └── static/ # 预构建的前端资源 +│ └── static/ # 模块化 ES6 前端（HTML/CSS/JS） └── outputs/ └── .gitkeep ``` diff --git a/SKILL.md b/SKILL.md index 9cb25bf..2a57abd 100644 --- a/SKILL.md +++ b/SKILL.md @@ -1,11 +1,12 @@ --- name: comfyui-skill-openclaw description: | - Generate images utilizing ComfyUI's powerful node-based workflow capabilities. Supports dynamically loading multiple pre-configured generation workflows from different instances and their corresponding parameter mappings, converting natural language into parameters, driving local or remote ComfyUI services, and ultimately returning the images to the target client. + Generate images utilizing ComfyUI's powerful node-based workflow capabilities. Supports dynamically loading multiple pre-configured generation workflows from different instances and their corresponding parameter mappings, importing saved workflows in bulk from ComfyUI or local JSON files, converting natural language into parameters, driving local or remote ComfyUI services, and ultimately returning the images to the target client. **Use this Skill when:** (1) The user requests to "generate an image", "draw a picture", or "execute a ComfyUI workflow". (2) The user has specific stylistic, character, or scene requirements for image generation. + (3) The user asks you to import, register, sync, or configure saved ComfyUI workflows for later reuse. --- # ComfyUI Agent SKILL @@ -55,9 +56,17 @@ This returns JSON with `"status": "online"` or `"status": "offline"`. **Recommended agent flow:** Before Step 3 (Trigger Image Generation), run a server status check. If offline, ask the user to start ComfyUI and retry once it is online. -### Step 0: AI-Native Workflow Auto-Configuration (Optional) +### Step 0: Workflow Onboarding and Import (Optional) -If the user provides you with a new ComfyUI workflow JSON (API format) and asks you to "configure it" or "add it": +Use the manager UI/API when the user wants to register workflows into this skill instead of running them immediately. + +- For bulk import from ComfyUI `/userdata`, local files, manager API routes, and import result semantics, read [`references/workflow-import.md`](./references/workflow-import.md). +- Prefer the bulk import flow when the user wants to sync many saved workflows at once. +- Use single-workflow configuration only when the user gives one workflow and wants a targeted setup. + +#### Single-workflow auto-configuration + +If the user provides you with one new ComfyUI workflow JSON (API format) and asks you to "configure it" or "add it": 1. Check the existing server configurations or default to `local`. 2. Save the provided JSON file to `./data//workflows/.json`. 3. Analyze the JSON structure (look for `inputs` inside node definitions, e.g., `KSampler`'s `seed`, `CLIPTextEncode`'s `text` for positive/negative prompts, `EmptyLatentImage` for width/height). diff --git a/references/workflow-import.md b/references/workflow-import.md new file mode 100644 index 0000000..3f7b59c --- /dev/null +++ b/references/workflow-import.md @@ -0,0 +1,77 @@ +# Workflow Import Reference + +Use this reference only when the user is asking to register workflows into the skill instead of executing an already configured workflow. + +## When to use which path + +- Use ComfyUI bulk import when the user wants all saved workflows from a configured ComfyUI server. +- Use local bulk import when the user already has multiple JSON files or a local folder. +- Use single-workflow configuration when the user provides one workflow and wants a targeted setup. + +## Manager API routes + +### Import all saved workflows from ComfyUI + +```http +POST /api/servers/{server_id}/workflows/import/comfyui +``` + +Preconditions: + +- The target server must already exist in manager config. +- The server must have a valid `url`. +- The ComfyUI server should be reachable because editor-format conversion depends on `/object_info`. + +Behavior: + +- Reads saved workflow JSON files from ComfyUI `/userdata`. +- Accepts both API workflow JSON and editor workflow JSON. +- Converts editor workflow JSON to API workflow JSON through ComfyUI `/object_info`. +- Extracts a recommended schema automatically. +- Auto-renames conflicting workflow IDs instead of overwriting silently. +- Persists import metadata such as origin and source label. + +### Import local JSON files + +```http +POST /api/servers/{server_id}/workflows/import/local +Content-Type: application/json + +{ + "files": [ + { + "file_name": "my-workflow.json", + "content": "{...raw json string...}" + } + ] +} +``` + +Behavior: + +- Applies the same workflow normalization as the ComfyUI bulk import route. +- Processes files independently so partial success is allowed. +- Fails only the individual files that have invalid JSON or unsupported workflow data. +- Prefer this route over manual file placement when the JSON content is already available. + +## UI entry points + +- Server section: `Import All from ComfyUI` +- Workflow section: `Import Local Files` +- Workflow section: `Import Local Folder` + +## Import report semantics + +The bulk import response returns a report with summary counts and per-item results. + +- `created`: imported with the suggested workflow ID +- `renamed`: imported after auto-renaming due to an ID conflict +- `skipped`: nothing importable was found for that source +- `failed`: the source could not be parsed, normalized, or saved + +## Agent guidance + +- If the user says "import all my saved workflows", prefer the ComfyUI bulk import route. +- If the user uploads a folder or several JSON files, prefer the local bulk import route. +- If the user only wants to execute a workflow, do not import first unless configuration is actually missing. +- Do not expose node IDs to the user unless they explicitly ask for internal workflow details.