dsh-comfyui-canvas 0.1.5 → 0.1.7

package/README.md

@@ -3,12 +3,14 @@
 > [中文](README.zh.md) · English
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.1.5-brightgreen.svg)](https://github.com/wbin0001/dsh-comfyui-canvas/releases)
+[![Version](https://img.shields.io/badge/version-0.1.7-brightgreen.svg)](https://github.com/wbin0001/dsh-comfyui-canvas/releases)
 [![GitHub Stars](https://img.shields.io/github/stars/wbin0001/dsh-comfyui-canvas.svg?style=social)](https://github.com/wbin0001/dsh-comfyui-canvas)
 [![DSH](https://img.shields.io/badge/DSH-v0.1.x-blueviolet.svg)](https://github.com/DeepSeek-Harness/DSH)
 [![ComfyUI](https://img.shields.io/badge/ComfyUI-0.34+-orange.svg)](https://github.com/comfyanonymous/ComfyUI)
 [![Canvas](https://img.shields.io/badge/canvas-split--screen-teal.svg)](docs/architecture.html)
 
+**Keywords**: ComfyUI · Stable Diffusion · 文生图 text-to-image · 图生图 img2img · AI 绘画 AI art · workflow 工作流 · music 音乐 · video 视频 · 3D · DeepSeek Harness · DSH
+
 > **✅ DSH version compatibility (since v0.1.4)**: the split-screen layout is **fully self-contained** in the plugin — it uses only official DSH slots (`conversation.session.header.utilities`) and DOM `data-*` anchors, with **zero core modifications**. Works on any official DSH **v0.1.x** (including v0.1.2+ with the breaking client refresh) without patches. The earlier split-rail implementation depended on private core patches; v0.1.4 removes that dependency entirely.
 > - ❌ **Non-official desktop wrappers** (e.g. the community `dsh-desktop`) are not guaranteed compatible — they bundle an upstream version that may be ahead of or behind this plugin's baseline; rely on official DSH.
 
@@ -20,7 +22,7 @@
 - **Production tasks** — batch parameter sweeps (`batch_run`) and automatic output-image retrieval back into the chat (`get_outputs`), powering multi-modal creative and batch generation across images, music, video, and 3D
 - **Environment upkeep** — one-click launch of ComfyUI and one-click upgrade of the core plus every custom node (`upgrade`), keeping the stack healthy without interruption
 
-This package is the DSH-side plugin, and it ships the ComfyUI-side bridge node too. For headless/scale workloads it can be paired with the official ComfyUI MCP server — see [Canvas vs MCP](#canvas-vs-mcp--two-ways-to-drive-comfyui).
+This package is the DSH-side plugin, and it ships the ComfyUI-side bridge node too. For headless/scale workloads it can be paired with the official ComfyUI MCP server — see [Canvas + MCP](#canvas--mcp--two-driving-modes-of-the-same-comfyui).
 
 > **Where this plugin fits**: use it while **building / tuning a workflow on the live canvas** (the "IDE" role). For **unattended / batch / production runs**, hand the exported workflow to **Comfy CLI** (`comfy-cli run_workflow`) — it runs headlessly without a browser, which this canvas plugin deliberately does not do (the agent drives the canvas you are looking at; a closed browser means no runner). Export a workflow once with `comfyui_export_api`, then script it with the CLI at scale.
 
@@ -30,8 +32,9 @@ This package is the DSH-side plugin, and it ships the ComfyUI-side bridge node t
 |---|---|
 | **ComfyUI canvas split** | Clicking the **ComfyUI** button in the session header drops you straight into **canvas-on-the-left + chat-rail-on-the-right** split mode — the canvas embeds the ComfyUI frontend (local or cloud) alongside the official conversation rail, so you can chat with the agent while watching it drive the canvas. The iframe stays alive (no reload); click the button again to exit split. |
 | **Visual canvas copilot** | The agent operates **the canvas you are looking at** — nodes appear, links wire, widgets change and runs trigger live on screen, so you watch every step instead of trusting an opaque JSON edit. Output images come back into the chat via `comfyui_get_outputs`. |
-| **Canvas ops tools** | `comfyui_read_workflow`, `add_node`, `connect`, `set_param`, `remove_node`, `inject_text`, `load_workflow`, `run`, `debug` — build and fix workflows on the live canvas; `inject_text` writes conversation text straight into a node or a new wirable source. |
-| **Production tools** | `comfyui_batch_run` sweeps a parameter matrix (seeds/prompts/strengths) in one go; `comfyui_get_outputs` pulls the resulting files back into the chat — images, videos, gifs, and audio — with optional `outputStem` auto-incrementing names (`stem.01.png`, never overwrites); `comfyui_attach_file` uploads any local file (image/audio/video/3D/text) into ComfyUI's input/ for the matching Load node; `comfyui_export_api` exports the live canvas as API-format workflow JSON for comfy-cli headless batch runs. |
+| **Canvas ops tools** | `comfyui_read_workflow`, `add_node`, `connect`, `set_param`, `remove_node`, `inject_text`, `load_workflow`, `run`, `debug`, `clear`, `group` — build and fix workflows on the live canvas; `clear` starts a blank canvas for a new workflow, `group` organizes complex workflows into named groups (prompt / sampler / output areas), and `inject_text` writes conversation text straight into a node or a new wirable source. |
+| **Production tools** | `comfyui_batch_run` sweeps a parameter matrix (seeds/prompts/strengths) in one go — either explicit `runs` or a declarative `matrix` (`zip` parallel slots / `product` cartesian expansion); `comfyui_get_outputs` pulls the resulting files back into the chat — images, videos, gifs, and audio — with optional `outputStem` auto-incrementing names (`stem.01.png`, never overwrites); `comfyui_attach_file` uploads any local file (image/audio/video/3D/text) into ComfyUI's input/ for the matching Load node; `comfyui_export_api` exports the live canvas as API-format workflow JSON for comfy-cli headless batch runs. |
+| **One-click bridge install** | `comfyui_setup_bridge` detects / installs / updates the ComfyUI-side bridge node into `custom_nodes/` (idempotent, verifies the files, tells you when to restart) — no more manual copy step; `comfyui_config` reports `bridgeInstalled` / `bridgeVersion` / `bridgeUpToDate` at a glance. |
 | **Projects & traceability** | Downloads default to the project directory (Settings → Project directory, default `<workspace>/projects`); every downloaded run appends `runs.json` (promptId / overrides / timestamp / files) so any output can be traced back to its parameters. Failed runs return a structured `executionError` (node id / node type / exception / message) instead of a raw JSON wall. |
 | **Skills (SOPs)** | Built-in skills teach the agent the right order of operations: `comfyui-canvas-ops` (read → confirm → edit → run → fetch → self-check), `comfyui-admin-ops` (configure/launch/upgrade/node management), `comfyui-video-audio-ops` (video + voiceover/audio track), and `comfyui-dev-ops` (develop/debug custom nodes). Install the plugin and the skills ship with it — no extra setup. |
 | **Upkeep tool** | `comfyui_upgrade` one-click updates the ComfyUI core and every git-backed custom node (concurrent, dirty-safe); `comfyui_config` reports the active connection, canvas focus, project directory, and a bridge-auth handshake check (`bridgeAuthEffective`). |
@@ -63,37 +66,50 @@ pnpm add <path-to-this-package>
 
 The bundled `cordis.patch.yml` mounts the plugin automatically (`dsh.bundle.patch`).
 
-### 2. Install the ComfyUI bridge node
+### 2. Install the ComfyUI bridge node (one-click)
 
-The agent tools talk to the ComfyUI page through a bridge (`/dsh-bridge/*`). The bridge node ships **inside this repo** at `comfyui-bridge/ComfyUI-DSH-Canvas` — copy it into ComfyUI's `custom_nodes`:
+The agent tools talk to the ComfyUI page through a bridge (`/dsh-bridge/*`). After installing the plugin, ask the agent to **"install the ComfyUI bridge node"** (or run `comfyui_setup_bridge` yourself): it detects whether the bridge is present in `custom_nodes/`, copies the version embedded in this package (idempotent — a same-or-newer installed copy is kept), verifies the files, and tells you when to restart ComfyUI.
 
-**Windows (PowerShell / cmd):**
+```text
+Agent: comfyui_setup_bridge → { installed, version, upToDate, restartNote }
+```
 
+Requires the **ComfyUI install directory** in **Settings → ComfyUI Canvas** (or the `COMFYUI_DIR` env var). If it is not set, `comfyui_config` reports `bridgeInstalled: false` — set it once and re-run.
+
+Manual copy is still supported (e.g. air-gapped machines) — the bridge ships **inside this package** at `comfyui-bridge/ComfyUI-DSH-Canvas`:
+
+**Windows (PowerShell / cmd):**
 ```powershell
-# from this repo checkout:
-Copy-Item -Recurse comfyui-bridge\ComfyUI-DSH-Canvas <ComfyUI>\custom_nodes\ComfyUI-DSH-Canvas
+Copy-Item -Recurse (npm root -g)\dsh-comfyui-canvas\comfyui-bridge\ComfyUI-DSH-Canvas <ComfyUI>\custom_nodes\ComfyUI-DSH-Canvas
 ```
 
 **macOS / Linux (bash):**
-
 ```bash
-# from this repo checkout:
-cp -r comfyui-bridge/ComfyUI-DSH-Canvas <ComfyUI>/custom_nodes/ComfyUI-DSH-Canvas
+cp -r $(npm root -g)/dsh-comfyui-canvas/comfyui-bridge/ComfyUI-DSH-Canvas <ComfyUI>/custom_nodes/ComfyUI-DSH-Canvas
 ```
 
-Or, after `dsh plugin add`, the installed package carries it too:
+Then restart ComfyUI and load the canvas page once (the injected `bridge.js` reports the graph and listens for commands).
 
-```bash
-# Windows (PowerShell)
-Copy-Item -Recurse (npm root -g)\dsh-comfyui-canvas\comfyui-bridge\ComfyUI-DSH-Canvas <ComfyUI>\custom_nodes\ComfyUI-DSH-Canvas
+### 3. Cloud ComfyUI (deploy the bridge on the machine that RUNS ComfyUI)
 
-# macOS / Linux
-cp -r $(npm root -g)/dsh-comfyui-canvas/comfyui-bridge/ComfyUI-DSH-Canvas <ComfyUI>/custom_nodes/ComfyUI-DSH-Canvas
+`comfyui_setup_bridge` manages a **local** install (`comfyuiDir` is a local path). For a cloud / remote ComfyUI, install the bridge on the **cloud machine** — pick one:
+
+**A. SSH / console access (self-hosted cloud GPU box)** — on the cloud machine:
+```bash
+# option 1: pull the npm package and copy the bridge out of it
+npm pack dsh-comfyui-canvas && tar -xzf dsh-comfyui-canvas-*.tgz && cp -r package/comfyui-bridge/ComfyUI-DSH-Canvas <ComfyUI>/custom_nodes/
+
+# option 2: sparse-checkout just the bridge from the GitHub repo
+cd <ComfyUI>/custom_nodes
+git clone --depth 1 --filter=blob:none --sparse https://github.com/wbin0001/dsh-comfyui-canvas.git
+cd dsh-comfyui-canvas && git sparse-checkout set comfyui-bridge/ComfyUI-DSH-Canvas
+mv comfyui-bridge/ComfyUI-DSH-Canvas ../ComfyUI-DSH-Canvas && cd .. && rm -rf dsh-comfyui-canvas
 ```
+Then restart the cloud ComfyUI, point the plugin's `baseUrl` at the cloud address, and (recommended) set a matching `DSH_BRIDGE_TOKEN` on both sides (see Security).
 
-Then restart ComfyUI and load the canvas page once (the injected `bridge.js` reports the graph and listens for commands).
+**B. Hosted SaaS (API only, no shell)** — if the provider does not allow installing custom nodes, the bridge (and the visual canvas) is unavailable; use the pure API/MCP path instead (`comfyui_export_api` → comfy-cli / an MCP server) for headless runs. `comfyui_config` will report `bridgeInstalled: false` in this case.
 
-### 3. Configure
+### 4. Configure
 
 Open **Settings → ComfyUI Canvas** and set the ComfyUI base URL (default `http://127.0.0.1:8188`), port, network mode, optional bridge token, launch command, and the right-side rail width.
 
@@ -134,32 +150,43 @@ Content the agent generates in the chat — images and text — can become Comfy
 
 > Architecture boundary: file transfer (image → `input/`) goes through the host + native API; canvas node ops go through bridge commands; reading results goes through native `/history` + `/view` — three layers that never mix.
 
-### Canvas vs MCP — two ways to drive ComfyUI
+### Canvas + MCP — two driving modes of the same ComfyUI
 
-This plugin is the **canvas driver**: it sees and edits the *live canvas* the user is looking at (add nodes, wire links, tweak widgets, run, fetch the run's output images via `comfyui_get_outputs`, sweep parameters via `comfyui_batch_run`). It never needs a saved workflow file.
+The plugin is the **canvas driver**: it sees and edits the *live canvas* the user is looking at (add nodes, wire links, tweak widgets, run, fetch the run's output images via `comfyui_get_outputs`, sweep parameters via `comfyui_batch_run`). It never needs a saved workflow file.
 
-For **pipeline-style / headless workloads**, ComfyUI's official **Comfy CLI** (`comfy-cli`) is a complementary tool. It is a standalone Python CLI (installed via `pip install comfy-cli`, and can also expose an MCP server) — **not** a DSH plugin, so it is used separately from this plugin rather than mounted into the DSH profile. It covers capabilities this canvas plugin deliberately does **not** re-implement:
+For **pipeline-style / headless workloads**, ComfyUI's official **Comfy CLI** (`comfy-cli`, a standalone Python CLI that can also expose an **MCP server**) is the complementary executor. The two are not alternatives — they are two driving modes of the **same** ComfyUI instance, covering the full workflow lifecycle:
 
-| Capability | This plugin (canvas) | ComfyUI CLI (comfy-cli) |
+| Workflow stage | Driving mode | Capability |
 |---|---|---|
-| Operate the live canvas the user sees | ✅ | — |
-| Run a saved / API-format workflow file | ✅ (via canvas) | ✅ (directly) |
-| Batch-queue runs + fetch output images | ✅ (`batch_run` + `get_outputs`) | ✅ (`run_workflow` + `fetch_outputs`) |
-| Official workflow templates | — | ✅ (`templates`) |
-| Model download / management | — | ✅ (`models`) |
-| Hosted/paid models (Flux, Veo, …) | — | ✅ (`partner`) |
-| Pre-flight graph validation (`validate` / deps) | ✅ (`debug`, local) | ✅ (`validate`, server) |
+| Build / tune | **Canvas plugin** (bridge) | Live canvas edits, run, `debug` validation, `get_outputs` fetch |
+| Freeze / export | **Canvas plugin** | `comfyui_export_api` — export the tuned graph as API-format JSON |
+| Batch / headless at scale | **MCP / comfy-cli** | Run the same graph headlessly: batch queues, official templates, model management, hosted models |
+| Results back in the chat | **Canvas plugin** | `comfyui_get_outputs` pulls the run's outputs into the conversation |
 
-**Recommended split**: use this plugin while you are *building/tuning* a workflow on the canvas; use the Comfy CLI once you want to *run the same graph headlessly at scale* (batch pipelines, templates, model management, hosted models). They talk to the same ComfyUI instance and can be used side by side. Install the Comfy CLI with:
+**The loop**: tune on the canvas → `export_api` → hand the API workflow to MCP / comfy-cli for unattended scale → bring results back via `get_outputs`. Nothing leaves DSH; the canvas and headless modes complement rather than replace each other.
 
+Install the Comfy CLI with:
 ```bash
 pip install comfy-cli   # standalone CLI, not a DSH plugin — see https://github.com/Comfy-Org/comfy-cli
 ```
 
+### Workflow operating modes (how the agent works the canvas)
+
+The built-in `comfyui-canvas-ops` skill instructs the agent to pick the right operating mode per scenario:
+
+| Scenario | Mode |
+|---|---|
+| **Edit an existing workflow** | Incremental edits on the current canvas (`set_param` / `connect` / `add_node` / `remove_node` / `inject_text`) — never a whole-graph `load_workflow` that would wipe the unsaved state |
+| **Start a new workflow** | `comfyui_clear` (blank canvas, guarded by a `confirm` flag) then build up |
+| **Build a complex workflow** | `comfyui_group` — organize into named groups (prompt / sampler / output areas) |
+| **Quick validation / batch / unattended** | **API/MCP path** — submit an API-format workflow directly (or via an MCP server), no need to visualize on the canvas |
+
+The agent decides the path up front: visual canvas mode when the user is watching / tuning, API/MCP mode for fast validation, batch sweeps and unattended runs.
+
 ## Requirements
 
 - DeepSeek Harness Web (DSH), Node `^22.19.0 || >=24`
-- ComfyUI running (local by default at `127.0.0.1:8188`; for a cloud instance, deploy the bridge node there and make sure DSH can reach it) with the bridge node installed
+- ComfyUI running (local by default at `127.0.0.1:8188`; for a cloud instance, deploy the bridge node on the machine that runs ComfyUI and make sure DSH can reach it) with the bridge node installed (`comfyui_setup_bridge` does this in one step)
 - A browser tab with the ComfyUI page open (the canvas tab loads it automatically)
 
 ## Development
@@ -180,7 +207,7 @@ dsh-comfyui-canvas/
 │       ├── __init__.py       # /dsh-bridge/* HTTP routes on the ComfyUI server
 │       └── entry/bridge.js   # injected frontend: reports graph + runs commands
 ├── lib/
-│   ├── index.js              # DSH host: 19 canvas tools + 4 built-in skills
+│   ├── index.js              # DSH host: 21 canvas tools + 4 built-in skills
 │   └── client.js             # DSH web: split canvas (left) + chat rail (right) / settings
 ├── LICENSE
 ├── README.md

package/README.zh.md

@@ -3,12 +3,14 @@
 > 中文 · [English](README.md)
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.1.5-brightgreen.svg)](https://github.com/wbin0001/dsh-comfyui-canvas/releases)
+[![Version](https://img.shields.io/badge/version-0.1.7-brightgreen.svg)](https://github.com/wbin0001/dsh-comfyui-canvas/releases)
 [![GitHub Stars](https://img.shields.io/github/stars/wbin0001/dsh-comfyui-canvas.svg?style=social)](https://github.com/wbin0001/dsh-comfyui-canvas)
 [![DSH](https://img.shields.io/badge/DSH-v0.1.x-blueviolet.svg)](https://github.com/DeepSeek-Harness/DSH)
 [![ComfyUI](https://img.shields.io/badge/ComfyUI-0.34+-orange.svg)](https://github.com/comfyanonymous/ComfyUI)
 [![Canvas](https://img.shields.io/badge/canvas-split--screen-teal.svg)](docs/architecture.html)
 
+**关键词**：ComfyUI · Stable Diffusion · 文生图 · 图生图 · AI 绘画 · 工作流 workflow · 音乐 music · 视频 video · 3D · DeepSeek Harness · DSH
+
 > **✅ DSH 版本兼容（v0.1.4 起）**：分屏布局已完全**自包含**在插件内——只用官方 DSH 插槽（`conversation.session.header.utilities`）与 DOM `data-*` 锚点，**零核心改动**。任何官方 DSH **v0.1.x**（含带破坏性 client 更新的 v0.1.2+）都开箱即用、无需补丁。此前分屏 rail 依赖 DSH 私有核心补丁，v0.1.4 已彻底移除该依赖。
 > - ❌ **非官方桌面封装**（如 `dsh-desktop` 社区版）不保证兼容——它内部跑的上游版本可能超前/滞后于本插件基线，请以官方 DSH 为准。
 
@@ -20,7 +22,7 @@
 - **生产任务**：批量扫参（`batch_run`）、自动取回出图（`get_outputs`）带回对话，实现图像、音乐、视频、3D 等多任务智能创作与批量生产
 - **环境维护**：一键启动 ComfyUI、一键升级核心与全部自定义节点（`upgrade`），省心维护不间断
 
-本仓库集成了 **DSH 侧插件（画布副驾）+ ComfyUI 侧桥接节点**。需要无人值守 / 规模化执行时，可配合官方 ComfyUI MCP 服务器使用——见[「画布驱动 vs MCP」](#画布驱动-vs-mcp两种操控-comfyui-的方式)。
+本仓库集成了 **DSH 侧插件（画布副驾）+ ComfyUI 侧桥接节点**。需要无人值守 / 规模化执行时，可配合官方 ComfyUI MCP 服务器使用——见[「画布 + MCP」](#画布--mcp同一个-comfyui-的两种驾驶方式)。
 
 ---
 
@@ -31,8 +33,9 @@
 | **画布分屏入口** | 点会话标头右侧的 **ComfyUI** 按钮进入**画布左 + 对话 rail 右**的分屏形态——画布内嵌 ComfyUI 前端（本地/云端），右侧是官方对话 rail，边看画布边发消息让 agent 操控。iframe 常驻不重载，再点按钮即关闭分屏。 |
 | **分屏布局（自包含）** | ComfyUI 按钮 = 画布左 + 对话右，状态按会话隔离。只用官方插槽（`conversation.session.header.utilities`）+ DOM `data-*` 锚点与 CSS 变量，**零核心改动**，上游样式变化也不受影响。 |
 | **可视化画布副驾** | agent 操作**你正在看的画布**——节点出现、连线接上、参数变化、运行触发，全部实时显示在屏幕上，每一步都看得见，而不是黑盒改 JSON。出图经 `comfyui_get_outputs` 直接带回对话。 |
-| **画布操作工具** | `comfyui_read_workflow` / `add_node` / `connect` / `set_param` / `remove_node` / `inject_text` / `load_workflow` / `run` / `debug`——在活画布上搭建与修复工作流；`inject_text` 把对话文本一步注入为可连线节点。 |
-| **生产工具** | `comfyui_batch_run` 一次扫参数矩阵（seed / prompt / 强度）；`comfyui_get_outputs` 把产物直接带回对话——图像、视频、GIF、音频都支持，可传 `outputStem` 自动编号（`stem.01.png`，永不覆盖）；`comfyui_attach_file` 把本机任意文件（图片/音频/视频/3D/**文本**）上传进 ComfyUI `input/` 供对应 Load 节点使用；`comfyui_export_api` 把当前画布导出为 API 格式工作流，供 comfy-cli 无人值守批量。 |
+| **画布操作工具** | `comfyui_read_workflow` / `add_node` / `connect` / `set_param` / `remove_node` / `inject_text` / `load_workflow` / `run` / `debug` / `clear` / `group`——在活画布上搭建与修复工作流；`clear` 清出空白画布新建工作流，`group` 把复杂工作流分成具名组（提示词区 / 采样区 / 输出区），`inject_text` 把对话文本一步注入为可连线节点。 |
+| **生产工具** | `comfyui_batch_run` 一次扫参数矩阵（seed / prompt / 强度）——支持显式 `runs` 或声明式 `matrix`（`zip` 并行槽位 / `product` 笛卡尔展开）；`comfyui_get_outputs` 把产物直接带回对话——图像、视频、GIF、音频都支持，可传 `outputStem` 自动编号（`stem.01.png`，永不覆盖）；`comfyui_attach_file` 把本机任意文件（图片/音频/视频/3D/**文本**）上传进 ComfyUI `input/` 供对应 Load 节点使用；`comfyui_export_api` 把当前画布导出为 API 格式工作流，供 comfy-cli 无人值守批量。 |
+| **桥接节点一键安装** | `comfyui_setup_bridge` 检测 / 安装 / 更新 ComfyUI 侧桥接节点到 `custom_nodes/`（幂等、校验文件、提示何时重启）——不再需要手动复制；`comfyui_config` 一眼报告 `bridgeInstalled` / `bridgeVersion` / `bridgeUpToDate`。 |
 | **项目目录与溯源** | 下载默认落「项目目录」（设置页可改，默认 `<工作区>/projects`）；每次下载把 `runs.json`（promptId / overrides / 时间戳 / 文件）追加进项目目录，任意一张图都能追溯回它的生成参数。运行失败返回结构化 `executionError`（节点 id / 节点类型 / 异常类型 / 信息），不再是一堵 JSON 墙。 |
 | **技能包（SOP）** | 内置技能教 agent 按正确顺序操作：`comfyui-canvas-ops`（读→确认→改→跑→取回→自检）、`comfyui-admin-ops`（配置/启动/升级/节点管理）、`comfyui-video-audio-ops`（视频+配音/音轨）、`comfyui-dev-ops`（开发/调试自定义节点）。装插件即自带技能，无需额外配置。 |
 | **维护工具** | `comfyui_upgrade` 一键升级 ComfyUI 核心与全部 git 自定义节点（并发、跳过本地改过的仓库）；`comfyui_config` 报告当前连接、画布专注状态、项目目录，以及**桥接鉴权握手检查**（`bridgeAuthEffective`）。 |
@@ -67,37 +70,50 @@ pnpm add <本仓库路径>
 
 插件自带 `cordis.patch.yml`（通过 `dsh.bundle.patch` 声明），装完自动挂载，无需手改配置。
 
-### 2. 安装 ComfyUI 桥接节点
+### 2. 安装 ComfyUI 桥接节点（一键）
 
-agent 工具通过 `/dsh-bridge/*` 与 ComfyUI 页面通信。桥接节点**已内嵌在仓库** `comfyui-bridge/ComfyUI-DSH-Canvas`，把它复制进 ComfyUI 的 `custom_nodes`：
+agent 工具通过 `/dsh-bridge/*` 与 ComfyUI 页面通信。装完插件后，让 agent **「安装 ComfyUI 桥接节点」**（或自己调用 `comfyui_setup_bridge`）：它会检测 `custom_nodes/` 里是否已有桥接节点、把本包内嵌的版本复制过去（幂等——已装同版本或更新则保留）、校验文件、并提示何时重启 ComfyUI。
 
-**Windows（PowerShell / cmd）：**
+```text
+Agent: comfyui_setup_bridge → { installed, version, upToDate, restartNote }
+```
 
+需要先在 **设置 → ComfyUI 画布** 填好 **ComfyUI 安装目录**（或设 `COMFYUI_DIR` 环境变量）。没填时 `comfyui_config` 会报告 `bridgeInstalled: false`——填一次再重跑即可。
+
+手动复制仍然支持（如离线机器）——桥接节点**内嵌在本包** `comfyui-bridge/ComfyUI-DSH-Canvas`：
+
+**Windows（PowerShell / cmd）：**
 ```powershell
-# 方式一：从仓库 checkout 复制
-Copy-Item -Recurse comfyui-bridge\ComfyUI-DSH-Canvas <ComfyUI>\custom_nodes\ComfyUI-DSH-Canvas
+Copy-Item -Recurse (npm root -g)\dsh-comfyui-canvas\comfyui-bridge\ComfyUI-DSH-Canvas <ComfyUI>\custom_nodes\ComfyUI-DSH-Canvas
 ```
 
 **macOS / Linux（bash）：**
-
 ```bash
-# 方式一：从仓库 checkout 复制
-cp -r comfyui-bridge/ComfyUI-DSH-Canvas <ComfyUI>/custom_nodes/ComfyUI-DSH-Canvas
+cp -r $(npm root -g)/dsh-comfyui-canvas/comfyui-bridge/ComfyUI-DSH-Canvas <ComfyUI>/custom_nodes/ComfyUI-DSH-Canvas
 ```
 
-`dsh plugin add` 安装后，已安装的插件里也带这份桥接节点：
+然后重启 ComfyUI 并打开一次画布页面（注入的 `bridge.js` 会上报画布状态并监听命令）。
 
-```bash
-# Windows（PowerShell）
-Copy-Item -Recurse (npm root -g)\dsh-comfyui-canvas\comfyui-bridge\ComfyUI-DSH-Canvas <ComfyUI>\custom_nodes\ComfyUI-DSH-Canvas
+### 3. 云端 ComfyUI（桥接节点装在「跑 ComfyUI 的那台机器」上）
 
-# macOS / Linux
-cp -r $(npm root -g)/dsh-comfyui-canvas/comfyui-bridge/ComfyUI-DSH-Canvas <ComfyUI>/custom_nodes/ComfyUI-DSH-Canvas
+`comfyui_setup_bridge` 管理的是**本机**安装（`comfyuiDir` 是本机路径）。云端 / 远程 ComfyUI 请在**云端机器**上装桥接节点——二选一：
+
+**A. 有 SSH / 控制台（自建云 GPU 机）**——在云机上执行：
+```bash
+# 方式 1：拉取 npm 包，把其中的桥接节点解出来
+npm pack dsh-comfyui-canvas && tar -xzf dsh-comfyui-canvas-*.tgz && cp -r package/comfyui-bridge/ComfyUI-DSH-Canvas <ComfyUI>/custom_nodes/
+
+# 方式 2：从 GitHub 仓库稀疏检出桥接节点目录
+cd <ComfyUI>/custom_nodes
+git clone --depth 1 --filter=blob:none --sparse https://github.com/wbin0001/dsh-comfyui-canvas.git
+cd dsh-comfyui-canvas && git sparse-checkout set comfyui-bridge/ComfyUI-DSH-Canvas
+mv comfyui-bridge/ComfyUI-DSH-Canvas ../ComfyUI-DSH-Canvas && cd .. && rm -rf dsh-comfyui-canvas
 ```
+然后重启云端 ComfyUI，把插件 `baseUrl` 指向云端地址，并（推荐）两端设置一致的 `DSH_BRIDGE_TOKEN`（见安全章节）。
 
-然后重启 ComfyUI 并打开一次画布页面（注入的 `bridge.js` 会上报画布状态并监听命令）。
+**B. 托管 SaaS（只有 API、无 shell）**——若托管方不允许装自定义节点，桥接（以及可视化画布）不可用；请走纯 API/MCP 路径（`comfyui_export_api` → comfy-cli / MCP server）做无人值守运行。此时 `comfyui_config` 会报告 `bridgeInstalled: false`。
 
-### 3. 配置
+### 4. 配置
 
 打开 **设置 → ComfyUI 画布**，填写 ComfyUI 地址（默认 `http://127.0.0.1:8188`）、端口、网络模式、可选桥接 Token、启动命令和右侧面板宽度。
 
@@ -148,34 +164,44 @@ agent 在对话里生成的图片与文本，可直接作为 ComfyUI 工作流
 
 > 架构边界：文件传输（图片→`input/`）走 host + 原生 API；画布节点操作走桥接 command；读结果走原生 `/history`+`/view`，三层不混。
 
-### 画布驱动 vs MCP——两种操控 ComfyUI 的方式
+### 画布 + MCP——同一个 ComfyUI 的两种驾驶方式
 
 本插件是**画布驱动**：它看到并编辑用户**正在看的那张活画布**（加节点、连线、改参数、运行，并用 `comfyui_get_outputs` 取回本次出图、用 `comfyui_batch_run` 扫参），无需保存工作流文件。
 
-如果要做**流水线/无人值守**类的批量任务，ComfyUI 官方的 **Comfy CLI（comfy-cli）** 是与之互补的工具。它是一个独立的 Python CLI（通过 `pip install comfy-cli` 安装，也可对外暴露 MCP 服务器）——**不是** DSH 插件，因此与本插件分开使用，而非挂进 DSH profile。它覆盖本画布插件**刻意不重复实现**的能力：
+要做**流水线/无人值守**类批量任务时，ComfyUI 官方的 **Comfy CLI（comfy-cli，独立 Python CLI，也可对外暴露 MCP 服务器）** 是互补的执行端。两者不是二选一，而是**同一个 ComfyUI 实例的两种驾驶方式**，合起来覆盖工作流全生命周期：
 
-| 能力 | 本插件（画布） | ComfyUI CLI（comfy-cli） |
+| 工作流阶段 | 驾驶方式 | 能力 |
 |---|---|---|
-| 操作用户正在看的活画布 | ✅ | — |
-| 直接运行已保存 / API 格式工作流文件 | ✅（经画布） | ✅（直接） |
-| 批量排队 + 取回输出图 | ✅（`batch_run` + `get_outputs`） | ✅（`run_workflow` + `fetch_outputs`） |
-| 官方工作流模板 | — | ✅（`templates`） |
-| 模型下载 / 管理 | — | ✅（`models`） |
-| 托管 / 付费模型（Flux、Veo…） | — | ✅（`partner`） |
-| 图结构预检（validate / 依赖） | ✅（`debug`，本地） | ✅（`validate`，服务端） |
+| 搭建 / 调优 | **画布插件**（bridge） | 活画布编辑、运行、`debug` 校验、`get_outputs` 取图 |
+| 固化 / 导出 | **画布插件** | `comfyui_export_api`——把调好的图导出为 API 格式 JSON |
+| 批量 / 无人值守规模化 | **MCP / comfy-cli** | 跑同一张图：批量队列、官方模板、模型管理、托管模型 |
+| 结果带回对话 | **画布插件** | `comfyui_get_outputs` 把运行产物拉回对话 |
 
-**推荐分工**：在画布上**构建/调优**工作流时用本插件；需要**以相同图无人值守规模化执行**（批量流水线、模板、模型管理、托管模型）时用 Comfy CLI。两者连的是同一个 ComfyUI 实例，可并存使用。安装 Comfy CLI：
+**闭环**：画布上调优 → `export_api` 导出 → 交 MCP / comfy-cli 无人值守规模化跑 → `get_outputs` 取回结果。全程不离开 DSH，画布与无头两种模式互补而非替代。安装 Comfy CLI：
 
 ```bash
 pip install comfy-cli   # 独立 CLI，非 DSH 插件 —— 见 https://github.com/Comfy-Org/comfy-cli
 ```
 
+### 工作流操作模式（agent 如何驾驭画布）
+
+内置 `comfyui-canvas-ops` 技能会引导 agent 按场景选择操作模式：
+
+| 场景 | 模式 |
+|---|---|
+| **修改现有工作流** | 在当前画布上**增量编辑**（`set_param` / `connect` / `add_node` / `remove_node` / `inject_text`）——绝不用整图 `load_workflow` 冲掉未保存现场 |
+| **新建工作流** | `comfyui_clear`（清出空白画布，带 `confirm` 防误清）再逐步搭 |
+| **搭建复杂工作流** | `comfyui_group`——分成具名组（提示词区 / 采样区 / 输出区） |
+| **快速验证 / 批量 / 无人值守** | **API/MCP 路径**——直接提交 API 格式工作流（或经 MCP server），不必可视化画布 |
+
+agent 动手前先判断场景：用户在实时看画布 / 需要调优 → 画布路径；快速验证、批量扫参、无人值守 → API/MCP 路径。
+
 ---
 
 ## 环境要求
 
 - DeepSeek Harness Web（DSH），Node `^22.19.0 || >=24`
-- 运行中的 ComfyUI（默认本地 `127.0.0.1:8188`，云端需自行部署桥接节点并确保 DSH 可达），且已装桥接节点
+- 运行中的 ComfyUI（默认本地 `127.0.0.1:8188`；云端需在「跑 ComfyUI 的那台机器」上装桥接节点并确保 DSH 可达），且已装桥接节点（`comfyui_setup_bridge` 一键完成）
 - 浏览器打开过 ComfyUI 画布页（画布标签会自动加载）
 
 ---

package/comfyui-bridge/ComfyUI-DSH-Canvas/__init__.py

@@ -7,6 +7,10 @@
 # M3: optional shared-token auth (DSH_BRIDGE_TOKEN), report body size limit,
 #     and per-tab command targeting via the last-reported clientId.
 
+# Bridge release version. The DSH plugin compares this against its embedded
+# copy (see version.json) to decide whether an update is needed.
+__version__ = "0.1.7"
+
 import os
 import time
 import uuid

package/comfyui-bridge/ComfyUI-DSH-Canvas/entry/bridge.js

@@ -322,6 +322,82 @@ async function executeCommand(cmd, payload) {
       return { nodeId: String(nodeId), key: widgetKey, value: text };
     }
 
+    // v0.1.6: clear the canvas to a blank workflow (new-workflow semantics).
+    // graph.clear() is the LiteGraph-native reset; afterwards the canvas is
+    // empty and ready to be built up node by node.
+    case "clear": {
+      graph.clear?.();
+      scheduleReport();
+      return { cleared: true, nodes: 0 };
+    }
+
+    // v0.1.6: group nodes into named groups (complex-workflow organization).
+    // Uses LiteGraph's native group API (graph._groups). Availability varies
+    // across custom frontends, so `list` reports groupingAvailable so the
+    // agent can degrade gracefully instead of hard-failing.
+    case "group": {
+      const { action, title, id, nodeIds } = payload ?? {};
+      const groups = graph?._groups ?? null;
+      if (!Array.isArray(groups)) {
+        return {
+          groupingAvailable: false,
+          error: "this ComfyUI frontend does not expose LiteGraph groups",
+        };
+      }
+      switch (action) {
+        case "add": {
+          if (!title || typeof title !== "string") throw new Error("group add requires payload.title");
+          const nodeObjs = (Array.isArray(nodeIds) ? nodeIds : []).map((n) => graph.getNodeById(+n)).filter(Boolean);
+          const group = new LiteGraph.LGraphGroup(title);
+          for (const n of nodeObjs) group.addNode?.(n);
+          groups.push(group);
+          scheduleReport();
+          return { groupingAvailable: true, id: groups.indexOf(group), title: group.title, nodes: nodeObjs.map((n) => String(n.id)) };
+        }
+        case "rename": {
+          const g = groups[+id];
+          if (!g) throw new Error(`group not found: ${id}`);
+          g.title = String(title ?? g.title);
+          scheduleReport();
+          return { groupingAvailable: true, id: +id, title: g.title };
+        }
+        case "add_nodes": {
+          const g = groups[+id];
+          if (!g) throw new Error(`group not found: ${id}`);
+          const added = [];
+          for (const n of Array.isArray(nodeIds) ? nodeIds : []) {
+            const node = graph.getNodeById(+n);
+            if (node && !(g.nodes ?? []).includes(node)) { g.addNode?.(node); added.push(String(n)); }
+          }
+          scheduleReport();
+          return { groupingAvailable: true, id: +id, added };
+        }
+        case "remove_nodes": {
+          const g = groups[+id];
+          if (!g) throw new Error(`group not found: ${id}`);
+          const removed = [];
+          for (const n of Array.isArray(nodeIds) ? nodeIds : []) {
+            const node = graph.getNodeById(+n);
+            if (node && (g.nodes ?? []).includes(node)) { g.removeNode?.(node); removed.push(String(n)); }
+          }
+          scheduleReport();
+          return { groupingAvailable: true, id: +id, removed };
+        }
+        case "list": {
+          return {
+            groupingAvailable: true,
+            groups: groups.map((g, i) => ({
+              id: i,
+              title: g.title ?? "",
+              nodes: (g.nodes ?? []).map((n) => String(n.id)),
+            })),
+          };
+        }
+        default:
+          throw new Error(`group action must be add|rename|add_nodes|remove_nodes|list, got ${String(action)}`);
+      }
+    }
+
     // v0.1.1: export the current canvas as API-format workflow JSON — the
     // format /prompt and comfy-cli run_workflow consume. Bridges the live
     // canvas to headless/MCP batch runs.

package/comfyui-bridge/ComfyUI-DSH-Canvas/version.json

@@ -0,0 +1,4 @@
+{
+  "name": "ComfyUI-DSH-Canvas",
+  "version": "0.1.7"
+}