dsh-comfyui-canvas 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-comfyui-canvas contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# dsh-comfyui-canvas
+
+> [中文](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.1-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/DeepSeek_Harness-compatible-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)
+
+![dsh-comfyui-canvas demo — agent drives a live ComfyUI workflow and fetches the output grid back into the chat](docs/screenshots/03-workflow-output.png)
+
+Embed your **ComfyUI** (local or cloud) as a split-screen canvas tab inside [DeepSeek Harness](https://github.com/DeepSeek-Harness/DSH) Web, and merge DSH's LLM power with ComfyUI's generation into **one visual creation platform** — the agent sparks ideas, writes prompts and scripts right in the chat, applies them live to the canvas in front of you, and produces images, music, video, and 3D. From idea to finished output without ever leaving the conversation or switching front-ends:
+
+- **Canvas ops** — compose and arrange pipelines, read/write workflows, edit nodes, wire links, run, tune parameters, and debug errors, all live and WYSIWYG on the exact canvas you are looking at
+- **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).
+
+## What you get
+
+| Surface | Description |
+|---|---|
+| **ComfyUI canvas tab** | A `ComfyUI` conversation view that embeds the ComfyUI frontend (local or cloud) side by side with the Chat rail. The iframe stays alive across tab switches (no reload). |
+| **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 images back into the chat; `comfyui_attach_image` uploads a local image into ComfyUI's input/ for a LoadImage node; `comfyui_export_api` exports the live canvas as API-format workflow JSON for comfy-cli headless batch runs. |
+| **Upkeep tool** | `comfyui_upgrade` one-click updates the ComfyUI core and every git-backed custom node; `comfyui_config` reports the active connection and canvas focus. |
+| **Canvas focus mode** | The agent can tell (via `comfyui_config`) whether the browser is on the canvas tab for the current session, and focus on canvas work only then. Session-isolated. |
+| **Settings page** | ComfyUI base URL / port / network mode / bridge token / launch command / rail width. Changes apply live. Customized nav icon with ComfyUI logo. |
+| **Rail polish** | Image previews inside the input box, a `+` button to attach local images (DSH's official attachment path), approval popup over the canvas (split layout), send button pinned to the panel corner. |
+
+## Install
+
+### 1. Install the DSH plugin
+
+```bash
+dsh plugin add github:<your-name>/dsh-comfyui-canvas
+```
+
+or from a local checkout:
+
+```bash
+# in your DSH profile
+pnpm add <path-to-this-package>
+```
+
+The bundled `cordis.patch.yml` mounts the plugin automatically (`dsh.bundle.patch`).
+
+### 2. Install the ComfyUI bridge node
+
+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`:
+
+**Windows (PowerShell / cmd):**
+
+```powershell
+# from this repo checkout:
+Copy-Item -Recurse 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
+```
+
+Or, after `dsh plugin add`, the installed package carries it too:
+
+```bash
+# Windows (PowerShell)
+Copy-Item -Recurse (npm root -g)\dsh-comfyui-canvas\comfyui-bridge\ComfyUI-DSH-Canvas <ComfyUI>\custom_nodes\ComfyUI-DSH-Canvas
+
+# macOS / Linux
+cp -r $(npm root -g)/dsh-comfyui-canvas/comfyui-bridge/ComfyUI-DSH-Canvas <ComfyUI>/custom_nodes/ComfyUI-DSH-Canvas
+```
+
+Then restart ComfyUI and load the canvas page once (the injected `bridge.js` reports the graph and listens for commands).
+
+### 3. Configure
+
+Open **Settings → ComfyUI 画布** 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.
+
+The **launch command** differs by platform:
+
+| Platform | Example |
+|---|---|
+| Windows | `ComfyUI启动器.bat` (or `python main.py`) |
+| macOS | `python main.py` or `./start.sh` |
+| Linux | `python main.py` or `./start.sh` |
+
+## Security
+
+The bridge (`/dsh-bridge/*`) is the only network surface this plugin adds to ComfyUI. Read this before exposing ComfyUI beyond loopback.
+
+- **Trust model.** By default the bridge is unauthenticated, matching ComfyUI's own `/prompt` trust model — anyone who can reach the ComfyUI port can read the canvas, report state, and dispatch commands (`load_workflow`/`run` consume GPU). Commands are whitelisted on the frontend, so no arbitrary code execution is possible, but the surface is real.
+- **Bind to loopback.** Keep ComfyUI on `127.0.0.1` unless you explicitly need LAN/cloud access. `networkMode` is informational; the actual bind is whatever ComfyUI was launched with (`--listen`).
+- **Optional shared token.** Set a token in **Settings → ComfyUI 画布 → 桥接 Token** AND launch ComfyUI with the same value in its own environment (`DSH_BRIDGE_TOKEN=...`). When the token is set, every agent-initiated request — reading the canvas, dispatching a command, polling its result — must present `Authorization: Bearer <token>`; the host side sends it automatically and the bridge rejects requests without it. The frontend's own status reporting (`/report`, result callbacks) stays open, since the injected page cannot hold the token; those endpoints only mutate the in-memory snapshot and never dispatch execution. Leave it empty on both sides for the default open behavior.
+- **Multiple tabs are safe.** Commands are targeted at the last-reporting frontend (`clientId`), so several open ComfyUI tabs do not each execute a command.
+
+## Platform support
+
+Works on **Windows**, **macOS** and **Linux**. The agent tools talk to ComfyUI over plain HTTP (`/dsh-bridge/*`), so nothing platform-specific lives in the plugin itself — only the copy command and the ComfyUI launch command differ, and both are documented above.
+
+## Usage
+
+1. Open a conversation, switch to the **ComfyUI** tab — the canvas splits on the left, chat on the right.
+2. Ask the agent to do canvas work: *"读取当前工作流"*, *"给 KSampler 设 seed 为 42"*, *"检查画布有没有报错"*, *"运行一次"*.
+3. The agent reads `comfyui_config` first, so it knows it's on the canvas and stays focused on canvas operations.
+
+### Conversation → canvas
+
+Content the agent generates in the chat — images and text — can become ComfyUI workflow node inputs directly, closing the loop from conversation idea to canvas output:
+
+- `comfyui_attach_image`: upload a local image into ComfyUI's `input/` and optionally point a LoadImage node at it. Uses ComfyUI's native `/upload/image` (not the bridge) — the host reads and uploads the file from the agent's own machine, which matters when the DSH machine and the ComfyUI machine differ (cloud deployments).
+- `comfyui_inject_text`: write text to a node's widget; or create a new source node, set its value, and connect it to a target input — "conversation text as a wirable source". A one-step wrapper over `add_node + set_param + connect`; `set_param` alone suffices when only an existing widget changes, and `inject_text` is for "create a new source and wire it".
+- `comfyui_export_api`: export the live canvas as API-format workflow JSON (the format `/prompt` and comfy-cli `run_workflow` consume), bridging canvas → MCP headless runs.
+
+> 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
+
+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.
+
+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:
+
+| Capability | This plugin (canvas) | ComfyUI CLI (comfy-cli) |
+|---|---|---|
+| 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) |
+
+**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:
+
+```bash
+pip install comfy-cli   # standalone CLI, not a DSH plugin — see https://github.com/Comfy-Org/comfy-cli
+```
+
+## 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
+- A browser tab with the ComfyUI page open (the canvas tab loads it automatically)
+
+## Development
+
+```bash
+npm run check   # node --check both lib files
+```
+
+The plugin lives in the DSH profile under `node_modules/dsh-comfyui-canvas`; edit `lib/index.js` (host tools) and `lib/client.js` (web client), then restart DSH.
+
+## Repository layout
+
+```
+dsh-comfyui-canvas/
+├── cordis.patch.yml          # DSH bundle layer (auto-mount)
+├── comfyui-bridge/           # ComfyUI-side bridge node (self-contained)
+│   └── ComfyUI-DSH-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: 15 canvas tools + session-isolated mode
+│   └── client.js             # DSH web: canvas tab / settings / rail polish
+├── LICENSE
+├── README.md
+└── package.json
+```
+
+The **bridge** is the only ComfyUI-side dependency. It exposes `/dsh-bridge/workflow|report|command|result` and is injected into the ComfyUI page via `app.registerExtension`; without it the agent tools cannot reach the canvas.
+
+## Known issues
+
+_(None pending. The former "node previews missing after a run" is fixed in v0.1.1: removed the iframe's `referrerpolicy="no-referrer"` to match the native tab environment, and `bridge.js` now listens to ComfyUI's `executed` event to force a canvas redraw.)_
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,210 @@
+# dsh-comfyui-canvas（DSH 画布插件）
+
+> 中文 · [English](README.md)
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.1.1-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/DeepSeek_Harness-compatible-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)
+
+![dsh-comfyui-canvas 演示 —— agent 驱动实时 ComfyUI 工作流，把出图网格直接带回对话](docs/screenshots/03-workflow-output.png)
+
+把 **ComfyUI**（本地或云端）以分屏画布标签嵌入 [DeepSeek Harness](https://github.com/DeepSeek-Harness/DSH) Web，把 DSH 的 LLM 能力与 ComfyUI 的生成能力合成**一个可视化创作平台**——agent 在对话里激发创意、书写提示词与脚本，实时落到你眼前的画布上，产出图像、音乐、视频、3D。从灵感到成品，全程不离开对话，不用切换任何前端工具：
+
+- **画布操作**：搭建编排、读写工作流、修改节点、连线、运行、调整参数、工作流查错——所见即所得，实时落在你眼前的画布上
+- **生产任务**：批量扫参（`batch_run`）、自动取回出图（`get_outputs`）带回对话，实现图像、音乐、视频、3D 等多任务智能创作与批量生产
+- **环境维护**：一键启动 ComfyUI、一键升级核心与全部自定义节点（`upgrade`），省心维护不间断
+
+本仓库集成了 **DSH 侧插件（画布副驾）+ ComfyUI 侧桥接节点**。需要无人值守 / 规模化执行时，可配合官方 ComfyUI MCP 服务器使用——见[「画布驱动 vs MCP」](#画布驱动-vs-mcp两种操控-comfyui-的方式)。
+
+---
+
+## 功能特性
+
+| 能力 | 说明 |
+|---|---|
+| **画布标签页** | 对话里新增 `ComfyUI` 标签，左边画布、右边对话 rail 分屏。iframe 常驻不重载，切标签秒回。 |
+| **可视化画布副驾** | 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` 把出图直接带回对话；`comfyui_attach_image` 把对话里的图片送进画布 LoadImage；`comfyui_export_api` 把当前画布导出为 API 格式工作流，供 comfy-cli 无人值守批量。 |
+| **维护工具** | `comfyui_upgrade` 一键升级 ComfyUI 核心与全部 git 自定义节点；`comfyui_config` 报告当前连接与画布专注状态。 |
+| **画布专注模式（会话隔离）** | agent 通过 `comfyui_config` 感知当前会话是否在画布标签，只在画布场景专注画布操作，且**按会话隔离**——多个会话互不干扰。 |
+| **ComfyUI 报错处理** | `debug` 校验工作流并高亮报错节点（纯校验，不触发执行），agent 帮你定位/修复画布错误。 |
+| **设置页** | ComfyUI 地址 / 端口 / 网络模式 / 桥接 Token / 启动命令 / 右侧面板宽度，实时生效。导航栏已自定义为 ComfyUI logo 图标。 |
+| **对话栏增强** | 图片预览并入输入框、`+` 号上传本地图片（走 DSH 官方附件通道）、画布上的授权弹窗、发送按钮贴右下角。 |
+
+---
+
+## 安装
+
+### 1. 安装 DSH 插件
+
+```bash
+dsh plugin add github:<你的用户名>/dsh-comfyui-canvas
+```
+
+或本地安装：
+
+```bash
+# 在 DSH profile 目录下
+pnpm add <本仓库路径>
+```
+
+插件自带 `cordis.patch.yml`（通过 `dsh.bundle.patch` 声明），装完自动挂载，无需手改配置。
+
+### 2. 安装 ComfyUI 桥接节点
+
+agent 工具通过 `/dsh-bridge/*` 与 ComfyUI 页面通信。桥接节点**已内嵌在仓库** `comfyui-bridge/ComfyUI-DSH-Canvas`，把它复制进 ComfyUI 的 `custom_nodes`：
+
+**Windows（PowerShell / cmd）：**
+
+```powershell
+# 方式一：从仓库 checkout 复制
+Copy-Item -Recurse 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
+```
+
+`dsh plugin add` 安装后，已安装的插件里也带这份桥接节点：
+
+```bash
+# Windows（PowerShell）
+Copy-Item -Recurse (npm root -g)\dsh-comfyui-canvas\comfyui-bridge\ComfyUI-DSH-Canvas <ComfyUI>\custom_nodes\ComfyUI-DSH-Canvas
+
+# macOS / Linux
+cp -r $(npm root -g)/dsh-comfyui-canvas/comfyui-bridge/ComfyUI-DSH-Canvas <ComfyUI>/custom_nodes/ComfyUI-DSH-Canvas
+```
+
+然后重启 ComfyUI 并打开一次画布页面（注入的 `bridge.js` 会上报画布状态并监听命令）。
+
+### 3. 配置
+
+打开 **设置 → ComfyUI 画布**，填写 ComfyUI 地址（默认 `http://127.0.0.1:8188`）、端口、网络模式、可选桥接 Token、启动命令和右侧面板宽度。
+
+**启动命令**按平台不同：
+
+| 平台 | 示例 |
+|---|---|
+| Windows | `ComfyUI启动器.bat`（或 `python main.py`） |
+| macOS | `python main.py` 或 `./start.sh` |
+| Linux | `python main.py` 或 `./start.sh` |
+
+---
+
+## 安全
+
+桥接（`/dsh-bridge/*`）是本插件给 ComfyUI 新增的唯一网络面。把 ComfyUI 暴露到回环地址之外之前请先读这里。
+
+- **信任模型**。默认桥接无鉴权，与 ComfyUI 自身 `/prompt` 的信任模型一致——任何能访问 ComfyUI 端口的人都能读画布、上报状态、下发命令（`load_workflow`/`run` 会消耗 GPU）。前端有命令白名单，**无法**执行任意代码，但这个面是真实存在的。
+- **绑定回环**。除非确有局域网/云端需求，请让 ComfyUI 保持 `127.0.0.1`。`networkMode` 只是信息性字段；实际绑定取决于 ComfyUI 启动时的 `--listen`。
+- **可选共享 Token**。在 **设置 → ComfyUI 画布 → 桥接 Token** 里填一个 Token，同时用相同值启动 ComfyUI（给它自己的环境变量 `DSH_BRIDGE_TOKEN=...`）。启用后，每个**由 agent 发起**的请求——读画布、下发命令、轮询结果——都必须携带 `Authorization: Bearer <token>`；host 端自动带上，bridge 端拒绝没有 Token 的请求。前端自身的状态上报（`/report`、结果回传）保持开放，因为注入页面无法持有 Token；这些端点只改动内存快照、从不触发执行。两端都留空则保持默认开放行为。
+- **多标签页安全**。命令会定向到「最近上报的前端」（`clientId`），所以同时开着多个 ComfyUI 标签页不会各自执行一次命令。
+
+---
+
+## 平台支持
+
+支持 **Windows / macOS / Linux**。agent 工具通过纯 HTTP（`/dsh-bridge/*`）与 ComfyUI 通信，插件本身不依赖任何平台特性——只有**复制命令**和 **ComfyUI 启动命令**因平台而异，上面都已分别说明。
+
+---
+
+## 使用
+
+1. 打开一个会话，切换到 **ComfyUI** 标签——左边是画布，右边是对话。
+2. 直接让 agent 干画布活：
+   - *“读取当前工作流”*
+   - *“给 KSampler 设 seed 为 42”*
+   - *“检查画布有没有报错”*
+   - *“运行一次”*
+3. agent 会先读 `comfyui_config` 确认当前在画布模式，然后专注画布操作。
+
+### 对话产物 → 画布
+
+agent 在对话里生成的图片与文本，可直接作为 ComfyUI 工作流的节点输入，形成「对话创意 → 画布产出」闭环：
+
+- `comfyui_attach_image`：把本机一张图片上传进 ComfyUI `input/`，并可选指向某个 LoadImage 节点。走 ComfyUI 原生 `/upload/image`，不经桥接——文件读取与上传由 host 从本机发起（云端 ComfyUI 场景下 DSH 机器与 ComfyUI 机器可能不同机，必须由 host 发起）。
+- `comfyui_inject_text`：把一段文本写入某节点 widget；或新建一个源节点、填值、再连到目标输入——「对话文本作为独立可连线源」。是 `add_node + set_param + connect` 的一步封装；只改已有 widget 时 `set_param` 已够，`inject_text` 用于「新建源并连线」。
+- `comfyui_export_api`：把当前画布导出为 API 格式工作流 JSON（`/prompt` 与 comfy-cli `run_workflow` 所需格式），打通「画布 ↔ MCP」衔接——画布上调好图，导出后交 comfy-cli 无人值守批量跑。
+
+> 架构边界：文件传输（图片→`input/`）走 host + 原生 API；画布节点操作走桥接 command；读结果走原生 `/history`+`/view`，三层不混。
+
+### 画布驱动 vs MCP——两种操控 ComfyUI 的方式
+
+本插件是**画布驱动**：它看到并编辑用户**正在看的那张活画布**（加节点、连线、改参数、运行，并用 `comfyui_get_outputs` 取回本次出图、用 `comfyui_batch_run` 扫参），无需保存工作流文件。
+
+如果要做**流水线/无人值守**类的批量任务，ComfyUI 官方的 **Comfy CLI（comfy-cli）** 是与之互补的工具。它是一个独立的 Python CLI（通过 `pip install comfy-cli` 安装，也可对外暴露 MCP 服务器）——**不是** DSH 插件，因此与本插件分开使用，而非挂进 DSH profile。它覆盖本画布插件**刻意不重复实现**的能力：
+
+| 能力 | 本插件（画布） | ComfyUI CLI（comfy-cli） |
+|---|---|---|
+| 操作用户正在看的活画布 | ✅ | — |
+| 直接运行已保存 / API 格式工作流文件 | ✅（经画布） | ✅（直接） |
+| 批量排队 + 取回输出图 | ✅（`batch_run` + `get_outputs`） | ✅（`run_workflow` + `fetch_outputs`） |
+| 官方工作流模板 | — | ✅（`templates`） |
+| 模型下载 / 管理 | — | ✅（`models`） |
+| 托管 / 付费模型（Flux、Veo…） | — | ✅（`partner`） |
+| 图结构预检（validate / 依赖） | ✅（`debug`，本地） | ✅（`validate`，服务端） |
+
+**推荐分工**：在画布上**构建/调优**工作流时用本插件；需要**以相同图无人值守规模化执行**（批量流水线、模板、模型管理、托管模型）时用 Comfy CLI。两者连的是同一个 ComfyUI 实例，可并存使用。安装 Comfy CLI：
+
+```bash
+pip install comfy-cli   # 独立 CLI，非 DSH 插件 —— 见 https://github.com/Comfy-Org/comfy-cli
+```
+
+---
+
+## 环境要求
+
+- DeepSeek Harness Web（DSH），Node `^22.19.0 || >=24`
+- 运行中的 ComfyUI（默认本地 `127.0.0.1:8188`，云端需自行部署桥接节点并确保 DSH 可达），且已装桥接节点
+- 浏览器打开过 ComfyUI 画布页（画布标签会自动加载）
+
+---
+
+## 开发
+
+```bash
+npm run check   # node --check 校验 lib 两个文件
+```
+
+插件位于 DSH profile 的 `node_modules/dsh-comfyui-canvas`；`lib/index.js` 是 host 端工具、`lib/client.js` 是 web 端，改完重启 DSH 生效。
+
+---
+
+## 仓库结构
+
+```
+dsh-comfyui-canvas/
+├── cordis.patch.yml          # DSH bundle 加载层（自动挂载）
+├── comfyui-bridge/           # ComfyUI 侧桥接节点（随仓库发布）
+│   └── ComfyUI-DSH-Canvas/
+│       ├── __init__.py       # ComfyUI 服务端 /dsh-bridge/* 路由
+│       └── entry/bridge.js   # 注入画布前端：上报画布 + 执行命令
+├── lib/
+│   ├── index.js              # DSH host：15 个画布工具 + 会话隔离模式
+│   └── client.js             # DSH web：画布标签 / 设置页 / 对话栏增强
+├── LICENSE
+├── README.md
+├── README.zh.md              # 本文档
+└── package.json
+```
+
+**桥接节点**是唯一的 ComfyUI 侧依赖：它暴露 `/dsh-bridge/workflow | report | command | result`，并通过 `app.registerExtension` 注入画布页面；没有它 agent 工具就够不到画布。
+
+---
+
+## 已知问题
+
+_（当前无已知未决问题。此前"画布运行后节点预览不显示"已在 v0.1.1 修复：移除 iframe 的 `referrerpolicy="no-referrer"` 消除环境差异，并在 `bridge.js` 监听 ComfyUI `executed` 事件强制重绘画布。）_
+
+---
+
+## 许可证
+
+MIT

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

@@ -0,0 +1,174 @@
+# ComfyUI-DSH-Canvas bridge backend
+# Exposes the live ComfyUI canvas state to the DSH-ComfyUI-Canvas plugin.
+#
+# M0: read path — the injected frontend passively reports graph changes.
+# M1: write path — /dsh-bridge/command pushes LiteGraph commands to the
+#     frontend over the ComfyUI WebSocket, results are stored for the caller.
+# M3: optional shared-token auth (DSH_BRIDGE_TOKEN), report body size limit,
+#     and per-tab command targeting via the last-reported clientId.
+
+import os
+import time
+import uuid
+
+import server
+from aiohttp import web
+
+WEB_DIRECTORY = "entry"
+NODE_CLASS_MAPPINGS = {}
+__all__ = ["NODE_CLASS_MAPPINGS"]
+
+# Largest accepted /dsh-bridge/report body (bytes). A hostile or broken
+# reporter must not be able to balloon ComfyUI's memory with one upload.
+MAX_REPORT_BYTES = 8 * 1024 * 1024
+
+# Optional shared secret. When set, every /dsh-bridge/* request must carry
+# `Authorization: Bearer <token>`. When unset (the default), the bridge stays
+# open for backward compatibility — same trust model as ComfyUI's own /prompt.
+_BRIDGE_TOKEN = os.environ.get("DSH_BRIDGE_TOKEN", "").strip()
+
+# Latest graph-change report from the injected frontend (M0 in-memory only).
+_latest = {"nodes": [], "workflow": None, "prompt": None, "updated_at": None}
+
+# Completed command results, keyed by command id (M1). Short-lived: the DSH
+# tool polls a result, then this dict is trimmed opportunistically.
+_command_results: dict[str, dict] = {}
+
+
+def _authorized(request) -> bool:
+    """True when no token is configured, or the request carries it."""
+    if not _BRIDGE_TOKEN:
+        return True
+    header = request.headers.get("Authorization", "")
+    return header == f"Bearer {_BRIDGE_TOKEN}"
+
+
+def _reject_unauthorized(request) -> web.Response | None:
+    if _authorized(request):
+        return None
+    return web.json_response({"ok": False, "error": "unauthorized"}, status=401)
+
+
+@server.PromptServer.instance.routes.get("/dsh-bridge/workflow")
+async def get_workflow(request):
+    """DSH reads the last reported canvas state (nodes summary + workflow JSON)."""
+    denied = _reject_unauthorized(request)
+    if denied:
+        return denied
+    return web.json_response(_latest)
+
+
+@server.PromptServer.instance.routes.post("/dsh-bridge/report")
+async def report(request):
+    """The injected frontend posts graph changes here.
+
+    This endpoint is called by the injected bridge.js inside the ComfyUI page,
+    which cannot hold the optional token, so it is intentionally NOT gated by
+    `_reject_unauthorized`. It only mutates the in-memory `_latest` snapshot
+    and never triggers execution, so it adds no execution surface beyond what
+    ComfyUI's own unauthenticated /prompt already exposes.
+    """
+    try:
+        raw = await request.read()
+    except Exception:
+        return web.Response(status=400, text="read failed")
+    if len(raw) > MAX_REPORT_BYTES:
+        return web.Response(status=413, text=f"report body exceeds {MAX_REPORT_BYTES} bytes")
+    try:
+        import json
+
+        data = json.loads(raw)
+    except Exception:
+        return web.Response(status=400, text="invalid json")
+    if not isinstance(data, dict):
+        return web.Response(status=400, text="expected a json object")
+    _latest["nodes"] = data.get("nodes") or []
+    _latest["workflow"] = data.get("workflow")
+    _latest["prompt"] = data.get("prompt")
+    _latest["client_id"] = data.get("clientId")
+    _latest["updated_at"] = time.time()
+    return web.json_response({"accepted": True})
+
+
+@server.PromptServer.instance.routes.post("/dsh-bridge/command")
+async def command(request):
+    """DSH tool dispatches a LiteGraph command to the canvas frontend.
+
+    The command is forwarded to every connected ComfyUI frontend over the
+    native WebSocket (`send_sync`); the injected bridge.js listens for the
+    `dsh-bridge-command` event, executes it, and POSTs the result back to
+    /dsh-bridge/result. M3 targets the command at the last-reported frontend
+    (its `clientId`) so multiple open tabs do not each execute the command.
+    """
+    denied = _reject_unauthorized(request)
+    if denied:
+        return denied
+    try:
+        data = await request.json()
+    except Exception:
+        return web.Response(status=400, text="invalid json")
+    if not isinstance(data, dict) or "cmd" not in data:
+        return web.Response(status=400, text="expected { cmd, ... }")
+
+    cmd_id = data.get("id") or uuid.uuid4().hex
+    target = _latest.get("client_id")
+    if not target:
+        # No frontend has reported yet, so there is no safe single executor.
+        # Broadcasting would make every open tab run the command (duplicates).
+        # Refuse with a diagnostic instead — the caller should read the canvas
+        # first (comfyui_read_workflow triggers a refresh_report), which
+        # establishes the target clientId.
+        return web.json_response({
+            "ok": False,
+            "accepted": False,
+            "id": cmd_id,
+            "error": "no ComfyUI frontend has reported yet — read the canvas once (or open the ComfyUI page) so the bridge can target a single tab",
+        })
+    payload = {
+        "id": cmd_id,
+        "cmd": data.get("cmd"),
+        "payload": data.get("payload", {}),
+        # Only the frontend that last reported should act on the command.
+        "target": target,
+    }
+    try:
+        server.PromptServer.instance.send_sync("dsh-bridge-command", payload)
+    except Exception as exc:
+        return web.json_response({"ok": False, "error": f"ws send failed: {exc}"})
+    return web.json_response({"accepted": True, "id": cmd_id})
+
+
+@server.PromptServer.instance.routes.post("/dsh-bridge/result")
+async def result(request):
+    """The injected frontend reports a command's outcome.
+
+    Frontend-originated like /report, so not token-gated. A spoofed POST would
+    need to guess the random command id, and it only records an in-memory
+    outcome — it never dispatches execution.
+    """
+    try:
+        data = await request.json()
+    except Exception:
+        return web.Response(status=400, text="invalid json")
+    cmd_id = data.get("id")
+    if not cmd_id:
+        return web.Response(status=400, text="missing id")
+    _command_results[cmd_id] = data
+    # Opportunistic trim: keep only the newest 200 results.
+    if len(_command_results) > 200:
+        for stale in list(_command_results)[: len(_command_results) - 200]:
+            _command_results.pop(stale, None)
+    return web.json_response({"accepted": True})
+
+
+@server.PromptServer.instance.routes.get("/dsh-bridge/result/{cmd_id}")
+async def get_result(request):
+    """DSH tool polls a command result by id."""
+    denied = _reject_unauthorized(request)
+    if denied:
+        return denied
+    cmd_id = request.match_info.get("cmd_id", "")
+    item = _command_results.get(cmd_id)
+    if item is None:
+        return web.json_response({"ok": False, "error": "not_found"})
+    return web.json_response(item)