dsh-comfyui-canvas 0.1.1

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

@@ -0,0 +1,414 @@
+// ComfyUI-DSH-Canvas bridge frontend.
+// Injected into the ComfyUI page via app.registerExtension. It watches the
+// LiteGraph canvas and posts graph changes to the bridge backend, so the DSH
+// plugin can read what is on the canvas without touching the iframe DOM.
+//
+// M0: passive reporting (read path).
+// M1: command listener (write path) — add_node / connect / set_param /
+//     remove_node executed directly on LiteGraph, results POSTed back.
+// M2: load_workflow (rewrite loop) / run (queuePrompt) / highlight (debug).
+// M3: validate (structural checks, no execution) + per-tab targeting.
+
+import { app } from "../../scripts/app.js";
+import { api } from "../../scripts/api.js";
+
+const REPORT_URL = "/dsh-bridge/report";
+const RESULT_URL = "/dsh-bridge/result";
+const COMMAND_EVENT = "dsh-bridge-command";
+const DEBOUNCE_MS = 300;
+
+// Stable per-tab identity: lets the backend route a command to one frontend
+// even when several tabs are open (DSH canvas tab + a native ComfyUI tab).
+// The backend echoes the last-reported clientId back as `target`, and only
+// that tab executes; the others skip the command.
+const CLIENT_ID = (crypto?.randomUUID?.() ?? String(Math.random()).slice(2));
+
+// ------- M0: passive reporting -------
+
+function summarize(graph) {
+  const nodes = graph?.nodes ?? [];
+  return nodes.map((node) => ({
+    id: String(node.id),
+    type: node.type ?? node.comfyClass ?? "unknown",
+    title: node.title || node.type || "",
+  }));
+}
+
+function serializeGraph(graph) {
+  try {
+    return graph?.serialize?.() ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function report() {
+  try {
+    const graph = app.graph;
+    if (!graph) return;
+    const body = {
+      clientId: CLIENT_ID,
+      nodes: summarize(graph),
+      workflow: serializeGraph(graph),
+      prompt: null, // API-format prompt lands with the run path (M2)
+    };
+    fetch(REPORT_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    }).catch(() => {
+      // Backend may not be up yet during startup; next change retries.
+    });
+  } catch {
+    // Never let a reporting error break the canvas.
+  }
+}
+
+let timer = null;
+function scheduleReport() {
+  clearTimeout(timer);
+  timer = setTimeout(report, DEBOUNCE_MS);
+}
+
+// ------- M1: write path -------
+
+async function resolveLiteGraph() {
+  if (window.LiteGraph) return window.LiteGraph;
+  try {
+    const mod = await import("../../scripts/litegraph.js");
+    return mod.LiteGraph ?? window.LiteGraph;
+  } catch {
+    return window.LiteGraph;
+  }
+}
+
+// Apply a widget value with combo validation + callback, shared by set_param
+// and inject_text. Throws on an unknown combo value so it fails loudly instead
+// of silently rendering empty, then lets the widget's own callback react.
+function applyWidgetValue(node, widget, value) {
+  widget.value = value;
+  if (widget.type === "combo" || Array.isArray(widget.options)) {
+    const labels = (Array.isArray(widget.options) ? widget.options : widget.options?.values ?? [])
+      .map((o) => (typeof o === "object" && o !== null ? (o.value ?? o[0]) : o));
+    if (labels.length > 0 && !labels.some((l) => String(l) === String(value))) {
+      throw new Error(`value ${JSON.stringify(value)} is not a valid option for ${widget.name} (${labels.join(", ")})`);
+    }
+  }
+  widget.callback?.(widget.value, widget);
+  node.onWidgetChanged?.(widget, widget.value, null, null);
+  node.setDirtyCanvas?.(true, true);
+}
+
+async function executeCommand(cmd, payload) {
+  const graph = app.graph;
+  const LiteGraph = await resolveLiteGraph();
+
+  switch (cmd) {
+    case "add_node": {
+      const type = payload.class ?? payload.type;
+      if (!type) throw new Error("add_node requires payload.class");
+      const node = LiteGraph?.createNode?.(type) ?? null;
+      if (!node) throw new Error(`unknown node class: ${type}`);
+      if (Array.isArray(payload.pos)) node.pos = [payload.pos[0], payload.pos[1]];
+      graph.add(node);
+      scheduleReport();
+      return { nodeId: String(node.id), type: node.type };
+    }
+
+    case "connect": {
+      const { srcId, srcSlot, dstId, dstSlot } = payload;
+      const src = graph.getNodeById(+srcId);
+      const dst = graph.getNodeById(+dstId);
+      if (!src) throw new Error(`source node not found: ${srcId}`);
+      if (!dst) throw new Error(`destination node not found: ${dstId}`);
+      const ok = src.connect(+srcSlot, dst, +dstSlot);
+      if (!ok) throw new Error("connection rejected by LiteGraph");
+      scheduleReport();
+      return { connected: `${srcId}:${srcSlot} -> ${dstId}:${dstSlot}` };
+    }
+
+    case "set_param": {
+      const { nodeId, key, value } = payload;
+      const node = graph.getNodeById(+nodeId);
+      if (!node) throw new Error(`node not found: ${nodeId}`);
+      const widget = (node.widgets ?? []).find((w) => w.name === key);
+      if (!widget) throw new Error(`widget not found: ${key}`);
+      applyWidgetValue(node, widget, value);
+      scheduleReport();
+      return { key, value };
+    }
+
+    case "remove_node": {
+      const { nodeId } = payload;
+      const node = graph.getNodeById(+nodeId);
+      if (!node) throw new Error(`node not found: ${nodeId}`);
+      graph.remove(node);
+      scheduleReport();
+      return { removed: String(nodeId) };
+    }
+
+    // M2: load a whole workflow back onto the canvas (rewrite loop).
+    case "load_workflow": {
+      const data = payload.workflow;
+      if (!data) throw new Error("load_workflow requires payload.workflow");
+      if (typeof data === "string") {
+        try { payload.workflow = JSON.parse(data); } catch {
+          throw new Error("payload.workflow is not valid JSON");
+        }
+      }
+      await app.loadGraphData(payload.workflow);
+      scheduleReport();
+      return { loaded: true };
+    }
+
+    // M2: run the current canvas graph (queuePrompt) and report the task id.
+    // `overrides` (optional) temporarily sets widget values before the graph
+    // is compiled, then restores them — the canvas is left untouched, so the
+    // same graph can be run repeatedly with different seeds/prompts.
+    case "run": {
+      if (typeof app.graphToPrompt !== "function") {
+        throw new Error("this ComfyUI frontend lacks app.graphToPrompt");
+      }
+      const overrides = Array.isArray(payload.overrides) ? payload.overrides : [];
+      // Snapshot the touched widgets so we can restore them afterwards.
+      const saved = [];
+      for (const o of overrides) {
+        const node = graph.getNodeById(+o.nodeId);
+        if (!node) throw new Error(`override node not found: ${o.nodeId}`);
+        const widget = (node.widgets ?? []).find((w) => w.name === o.key);
+        if (!widget) throw new Error(`override widget not found: ${o.nodeId}.${o.key}`);
+        saved.push({ node, widget, prev: widget.value });
+        widget.value = o.value;
+      }
+      try {
+        const { output } = await app.graphToPrompt();
+        const resp = await api.fetchApi("/prompt", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ prompt: output }),
+        });
+        const json = await resp.json().catch(() => null);
+        if (!resp.ok) throw new Error(json?.error?.message ?? `prompt HTTP ${resp.status}`);
+        return { promptId: json.prompt_id, nodeErrors: json.node_errors ?? null };
+      } finally {
+        // Restore regardless of outcome so the canvas is never left altered.
+        for (const s of saved) {
+          s.widget.value = s.prev;
+          s.node.setDirtyCanvas?.(true, true);
+        }
+      }
+    }
+
+    // M4: batch run — execute the graph once per override set (a parameter
+    // matrix), queueing each as its own prompt. Returns the prompt ids in the
+    // same order as the runs. ComfyUI executes the queue serially, so this is
+    // a convenient way to sweep seeds / prompts / strengths.
+    case "batch_run": {
+      if (typeof app.graphToPrompt !== "function") {
+        throw new Error("this ComfyUI frontend lacks app.graphToPrompt");
+      }
+      const runs = Array.isArray(payload.runs) ? payload.runs : [];
+      const results = [];
+      for (const run of runs ?? []) {
+        const overrides = Array.isArray(run.overrides) ? run.overrides : [];
+        const saved = [];
+        for (const o of overrides) {
+          const node = graph.getNodeById(+o.nodeId);
+          if (!node) throw new Error(`override node not found: ${o.nodeId}`);
+          const widget = (node.widgets ?? []).find((w) => w.name === o.key);
+          if (!widget) throw new Error(`override widget not found: ${o.nodeId}.${o.key}`);
+          saved.push({ node, widget, prev: widget.value });
+          widget.value = o.value;
+        }
+        try {
+          const { output } = await app.graphToPrompt();
+          const resp = await api.fetchApi("/prompt", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ prompt: output }),
+          });
+          const json = await resp.json().catch(() => null);
+          if (!resp.ok) throw new Error(json?.error?.message ?? `prompt HTTP ${resp.status}`);
+          results.push({ promptId: json.prompt_id, nodeErrors: json.node_errors ?? null });
+        } finally {
+          for (const s of saved) {
+            s.widget.value = s.prev;
+            s.node.setDirtyCanvas?.(true, true);
+          }
+        }
+      }
+      return { queued: results.length, runs: results };
+    }
+
+    // M2: flash/highlight nodes by id (debug output).
+    case "highlight": {
+      const ids = Array.isArray(payload.ids) ? payload.ids : [];
+      for (const id of ids) {
+        const node = graph.getNodeById(+id);
+        if (node && typeof node.flash === "function") node.flash();
+      }
+      return { highlighted: ids.map(String) };
+    }
+
+    // M3: validate — structural checks only, never submits /prompt, so a valid
+    // graph is NOT queued (unlike `run`). Flags nodes with unconnected required
+    // inputs so the agent can locate/fix errors without spending a generation.
+    // Dynamic-slot nodes (switch / index / selector, or numbered inputs like
+    // `image15`) intentionally leave trailing slots unconnected — those are
+    // reported as warnings, never as errors, so debug does not false-flag them.
+    case "validate": {
+      const nodeErrors = {};
+      const warnings = {};
+      for (const node of graph?.nodes ?? []) {
+        const missing = [];
+        const dynamic = [];
+        for (const input of node.inputs ?? []) {
+          if (input.link == null && !input.optional && !input.widget) {
+            const type = String(node.type ?? "");
+            const isDynamicSlot = /switch|index|selector|multi/i.test(type)
+              || /^(image|input|value|mask|opt|optional)\d+$/i.test(input.name);
+            (isDynamicSlot ? dynamic : missing).push(
+              isDynamicSlot
+                ? `dynamic slot "${input.name}" unconnected (switch/index node — expected)`
+                : `missing required input "${input.name}"`,
+            );
+          }
+        }
+        if (missing.length) nodeErrors[String(node.id)] = missing;
+        if (dynamic.length) warnings[String(node.id)] = dynamic;
+      }
+      const offendingIds = Object.keys(nodeErrors);
+      return { valid: offendingIds.length === 0, nodeErrors, warnings, offendingIds };
+    }
+
+    // M3: ask the frontend to re-report the current graph immediately, so
+    // comfyui_read_workflow does not serve a stale cache when the page is
+    // open but idle (no recent change to trigger a debounced report).
+    case "refresh_report": {
+      report();
+      return { reported: true };
+    }
+
+    // v0.1.1: inject text into the canvas. Mode 2 (newClass): create a source
+    // node, set its widget, optionally connect to a target input — a one-step
+    // "conversation text → canvas node". Mode 1 (nodeId): write an existing
+    // widget directly. Both reuse applyWidgetValue so combo validation + the
+    // widget callback fire identically to set_param.
+    case "inject_text": {
+      const { text, nodeId, widgetKey = "text", newClass, targetId, targetSlot, sourceSlot = 0 } = payload;
+      if (newClass) {
+        const node = LiteGraph?.createNode?.(newClass) ?? null;
+        if (!node) throw new Error(`unknown node class: ${newClass}`);
+        graph.add(node);
+        const widget = (node.widgets ?? []).find((w) => w.name === widgetKey);
+        if (widget) applyWidgetValue(node, widget, text);
+        const connected = targetId != null && targetSlot != null;
+        if (connected) {
+          const dst = graph.getNodeById(+targetId);
+          if (!dst) throw new Error(`target node not found: ${targetId}`);
+          const ok = node.connect(+sourceSlot, dst, +targetSlot);
+          if (!ok) throw new Error("connection rejected by LiteGraph");
+        }
+        scheduleReport();
+        return { nodeId: String(node.id), created: true, type: node.type, connected };
+      }
+      if (nodeId == null) throw new Error("inject_text requires nodeId or newClass");
+      const node = graph.getNodeById(+nodeId);
+      if (!node) throw new Error(`node not found: ${nodeId}`);
+      const widget = (node.widgets ?? []).find((w) => w.name === widgetKey);
+      if (!widget) throw new Error(`widget not found: ${widgetKey}`);
+      applyWidgetValue(node, widget, text);
+      scheduleReport();
+      return { nodeId: String(nodeId), key: widgetKey, value: text };
+    }
+
+    // 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.
+    case "export_api": {
+      if (typeof app.graphToPrompt !== "function") {
+        throw new Error("this ComfyUI frontend lacks app.graphToPrompt");
+      }
+      const { output } = await app.graphToPrompt();
+      return { workflow: output, nodeCount: Object.keys(output || {}).length };
+    }
+
+    default:
+      throw new Error(`unknown command: ${cmd}`);
+  }
+}
+
+function postResult(cmdId, ok, raw) {
+  const body = { id: cmdId, ok };
+  if (ok) {
+    body.result = raw;
+  } else {
+    body.error = raw?.message ?? String(raw ?? "unknown error");
+  }
+  fetch(RESULT_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  }).catch(() => {});
+}
+
+app.registerExtension({
+  name: "ComfyUI-DSH-Canvas",
+  setup() {
+    const graph = app.graph;
+    if (!graph) return;
+
+    // M0: report on canvas changes, preserving any existing handler.
+    // The arrow keeps `this` from the setup scope; forward the graph itself so
+    // a handler that relies on `this` still sees the graph.
+    const prevOnChange = graph.onChange;
+    graph.onChange = (...args) => {
+      if (typeof prevOnChange === "function") {
+        try { prevOnChange.apply(graph, args); } catch { /* ignore */ }
+      }
+      scheduleReport();
+    };
+    const prevGraphConfigure = graph.configure ?? null;
+    if (typeof graph.configure === "function") {
+      graph.configure = function (...args) {
+        const out = prevGraphConfigure.apply(this, args);
+        scheduleReport();
+        return out;
+      };
+    }
+
+    // M1: listen for write commands pushed over the WebSocket.
+    // Per-tab targeting (M3): when the backend names a target clientId (the
+    // last one that reported), only that tab executes — several open ComfyUI
+    // tabs must not each run the same command. No target = any tab may run.
+    api.addEventListener(COMMAND_EVENT, async (event) => {
+      const msg = event?.detail;
+      if (!msg || !msg.id || !msg.cmd) return;
+      if (msg.target && msg.target !== CLIENT_ID) return;
+      try {
+        const raw = await executeCommand(msg.cmd, msg.payload ?? {});
+        postResult(msg.id, true, raw);
+      } catch (err) {
+        console.error("[ComfyUI-DSH-Canvas] command failed", msg.cmd, err);
+        postResult(msg.id, false, err);
+      }
+    });
+
+    // v0.1.1 fix: node previews (SaveImage/PreviewImage thumbnails) sometimes
+    // do not appear after a manual run inside the DSH canvas iframe, even
+    // though the images land in output/. ComfyUI's own executed handler sets
+    // node.imgs, but inside the nested iframe the canvas redraw (driven by
+    // requestAnimationFrame) may not fire afterwards, so the preview stays
+    // empty. Forcing a redraw here on every executed event closes that gap —
+    // harmless when ComfyUI already redrew, and it is exactly the event the
+    // README previously noted the bridge did not touch.
+    api.addEventListener("executed", () => {
+      try {
+        app.canvas?.setDirty?.(true, true);
+      } catch { /* never break the canvas over a redraw */ }
+    });
+
+    // Initial report once the canvas is ready.
+    setTimeout(report, 1500);
+  },
+});

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-comfyui-canvas bundle layer: applied automatically when the package is
+# installed (package.json declares dsh.bundle.patch), i.e. a profile that runs
+# `dsh plugin add github:<you>/dsh-comfyui-canvas` gets this wiring without any
+# manual cordis.patch.yml edits. Later layers override these rows by id.
+
+# 挂载插件行：注册 host 端画布工具 + client 端画布标签页/设置页。
+- insert:
+    - id: comfyui-canvas
+      name: dsh-comfyui-canvas

package/docs/NEXT-VERSION-PLAN.md

@@ -0,0 +1,199 @@
+# dsh-comfyui-canvas — 下个版本开发规划（v0.1.1）
+
+> **本文档是「新会话接手说明书」**：下个版本开发请新开一个会话，先读本文件 + `docs/architecture.html`（分层架构）+ `docs/architecture-flow.html`（流程图），即可接续全部开发意图。
+> 最后更新：2026-09-01
+
+> **最近一次更新（2026-09-01）**：
+> - 设置面板导航图标改为**大写「C」字母**（此前为不美观的 C 形填充样式），并**移除 label 前的 🎨 emoji**——左侧导航只显示干净的「C + ComfyUI 画布」
+> - **修复 bug「画布运行后节点预览不显示」**（README 已知问题）：手动在 DSH 画布 iframe 内运行工作流后，SaveImage/PreviewImage 节点预览缩略图不出现
+>   - 根因（已诊断确认）：DSH 画布 iframe 设置了 `referrerpolicy="no-referrer"`，与原生 ComfyUI 标签页环境不一致；且 bridge 不触碰 `executed` 事件流，iframe 内画布重绘（rAF 驱动）在 executed 后未触发
+>   - 修复：① `lib/client.js` 移除 iframe 的 `referrerpolicy`（iframe 内请求 Referer 本来就是 ComfyUI 自己的 URL，不会泄漏 DSH URL）；② `comfyui-bridge/.../entry/bridge.js` 新增监听 ComfyUI `executed` 事件 → `app.canvas.setDirty(true, true)` 强制重绘
+>   - 三处已同步：源码 → node_modules 副本 → E 盘 custom_nodes；**需重启 ComfyUI 使 bridge 改动生效**
+> - **修复 bug「画布启动按钮点不动 / 卡在正在启动…」**：在 DSH 画布直接点「启动 ComfyUI」，host 收到 `launchRequested` 后静默失败、界面永远停在"正在启动…"
+>   - 根因（已诊断确认）：host 启动 watcher 调 `shell.start(shell.resolve({ command, workdir }))` 时**没传 `sandboxPolicy`**，Windows 上 `pwsh-sandbox` 按默认 `workspace-write`（root=F:\Deepseek-harness）执行启动器——而 `ComfyUI启动器.bat` 在 **E 盘**启动 python 并写 output/temp，受限 token 下被拒、进程立即退出；且错误被 `void proc.done.catch(() => {})` 吞掉，客户端无超时、永久卡死
+>   - 修复：① `lib/index.js` 启动时显式传 `sandboxPolicy: { mode: 'danger-full-access', workspaceRoot }`（外部服务启动不受工作区沙箱限制），并把启动失败写入新增的 `launchError` 配置字段；② `lib/client.js` 启动卡片读取并展示 `launchError`，加 45s 启动超时（超时未在线则复位"正在启动…"允许重试）
+>   - 已同步：源码 → node_modules 副本；**需重启 DSH（host 改动生效）+ 刷新页面（client 改动生效）**
+> - 涉及文件：`lib/client.js` + `lib/index.js` + `comfyui-bridge/ComfyUI-DSH-Canvas/entry/bridge.js`（本仓库）+ DSH 核心 `packages/client/ui-settings-general`（navIcon 映射，不在本仓库 git 内）
+
+---
+
+## 0. 如何接续（先读这里）
+
+下个会话请按此顺序恢复上下文：
+
+1. **读本文档** —— 理解下版本目标、技术边界、实施步骤
+2. **读 `docs/architecture.html` / `docs/architecture-flow.html`** —— 在浏览器打开这两张图，理解三侧（浏览器 / DSH Host / ComfyUI）架构
+3. **跑一次 `npm run check`** —— 确认当前代码语法可用
+4. **确认环境三副本可访问**（见 §1.3）
+
+---
+
+## 1. 项目现状快照
+
+### 1.1 基本信息
+- **包名/版本**：`dsh-comfyui-canvas` / `0.1.0`
+- **仓库（已开源 Public）**：https://github.com/wbin0001/dsh-comfyui-canvas
+- **许可证**：MIT；**语言**：host = JS（ESM），bridge 后端 = Python，bridge 前端 = JS
+- **README**：`README.md`（en）+ `README.zh.md`（zh），功能表已按「画布操作 / 生产任务 / 环境维护」三面组织
+
+### 1.2 当前 12 个 agent 工具（host `lib/index.js`）
+```
+comfyui_read_workflow     读画布（先 refresh_report 再读；无上报返回 ready:false 诊断）
+comfyui_add_node          加节点（class + 可选 pos，立即显示在画布）
+comfyui_connect           连线 srcId:srcSlot → dstId:dstSlot
+comfyui_set_param         改 widget 值（支持 combo 校验 + callback）
+comfyui_remove_node       删节点
+comfyui_load_workflow     整图替换（兼容 read 结果整对象回传的 unwrap）
+comfyui_run               运行（可选 overrides 临时覆盖 widget，跑完还原画布）
+comfyui_get_outputs       取回出图（读 /history/:id + /view，可选 downloadDir 落盘）
+comfyui_batch_run         参数矩阵批量（runs=[{overrides:[...]}]，逐组入队）
+comfyui_debug             纯校验（不触发执行；switch/index 动态槽归 warnings 不报错）
+comfyui_config            会话隔离的画布感知 + 连接配置
+comfyui_upgrade           git pull 核心 + 全部自定义节点
+```
+
+### 1.3 三副本位置（改代码必须三处同步）
+| 角色 | 路径 | 说明 |
+|---|---|---|
+| 源码主仓（权威源） | `F:\Deepseek-harness\projects\dsh-comfyui-canvas` | git 管理，这是改代码的地方 |
+| DSH 运行时副本 | `F:\Deepseek-harness\.dsh\profiles\web\node_modules\dsh-comfyui-canvas` | DSH 启动实际加载这份 —— 改完 host/client 要复制过来 |
+| ComfyUI 桥接节点 | `E:\AI-ComfyUI\ComfyUI_windows_portable\ComfyUI\custom_nodes\ComfyUI-DSH-Canvas` | 只同步 `comfyui-bridge/` 下的 `__init__.py` + `entry/bridge.js` —— 改 bridge 要复制过来并**重启 ComfyUI** |
+
+> 同步约定：host/client 改动 → 同步到 node_modules 副本；bridge 改动 → 同步到 node_modules 副本 + E 盘 custom_nodes。改完跑 `node --check` + `python -m py_compile`。
+
+### 1.4 关键机制速记
+- **bridge 三件套**：`__init__.py`（Python 路由 + 可选 `DSH_BRIDGE_TOKEN` 鉴权 + report 8MB 上限 + clientId 定向）+ `entry/bridge.js`（前端注入，执行白名单命令）
+- **命令白名单**（bridge.js `executeCommand`）：`add_node / connect / set_param / remove_node / load_workflow / run / batch_run / validate / highlight / refresh_report`（+ 下版本将加 `inject_text`）
+- **画布数据流**：host 工具 → HTTP `/dsh-bridge/command` → bridge 后端 → WebSocket `send_sync` → 前端执行 → POST `/dsh-bridge/result` → host 轮询
+- **出图取回**：`get_outputs` 直连 ComfyUI 原生 `/history/:id` + `/view`（不经过 bridge），区分 `output/`（SaveImage 永久）与 `temp/`（PreviewImage 临时）
+
+---
+
+## 2. 下版本目标：v0.1.1 ——「对话产物进画布」
+
+### 2.1 一句话目标
+让 **agent 在对话中生成的内容（文本 / 图片）直接作为 ComfyUI 工作流的节点输入**，形成「对话创意 → 画布产出」的闭环，无需手动切工具。
+
+### 2.2 核心新增项（本版本必做）
+
+#### A. 新增工具 `comfyui_attach_image` —— 把图片送进画布
+- **职责**：把 agent 本机的一张图片上传进 ComfyUI 的 `input/` 目录，并（可选）更新指定 `LoadImage` 节点的文件名，使其立刻生效
+- **实现位置**：**host 端（`lib/index.js`）** —— 走 ComfyUI **原生 `POST /upload/image`** 端点，**不经过 bridge**（源文件在 agent 本机，bridge 无本机路径概念）
+- **为什么在 host**：云端 ComfyUI 场景下「DSH 机器」与「ComfyUI 机器」不是同一台，文件读取与上传必须由 host 从本机发起；这正是 ComfyUI 官方 web UI 传图的同一条路
+- **接口草案**：
+  ```js
+  comfyui_attach_image({
+    image:   string  // 本机图片绝对路径（必填）
+    nodeId?: number  // 可选：指定 LoadImage 节点，上传后自动 set_param 指向新文件名
+  })
+  // 返回 { filename, subfolder, nodeId?, updated? }
+  ```
+- **要点**：上传后返回的文件名要与 `LoadImage` 节点 widget `image` 期望的值一致（ComfyUI `/upload/image` 返回的 `name` + `subfolder` 拼进 filename）；可组合 `set_param` 复用现有路径
+- **验收**：对话里生成/出现一张图 → `attach_image` → 画布上 LoadImage 显示该图 → `run` 能正常走通
+
+#### B. 新增工具 `comfyui_inject_text` —— 把文本注入节点（含建源连线）
+- **职责**：把一段文本写入某节点 widget（如 CLIPTextEncode 的 `text`）；或先 `add_node` 一个 text/primitive 源节点、填值、再 `connect` 到目标节点的输入——即「对话文本作为独立可连线源」
+- **实现位置**：**host 注册工具 + bridge 加 command 分支**（画布操作必须由前端 LiteGraph 执行）
+  - host `lib/index.js`：定义 `comfyui_inject_text`，拼 command 下发
+  - bridge.js `executeCommand` 新增 `inject_text` 分支：`add_node`（若给 class）→ `set_param` → `connect`
+- **本质**：现有 `add_node + set_param + connect` 的组合封装，提供「一步到位」的语义
+- **日常替代**：若只改已有节点 widget（多数文本场景），`set_param` 已够；`inject_text` 是「要新建源并连线」时的便捷入口
+- **接口草案**：
+  ```js
+  comfyui_inject_text({
+    text:      string  // 要注入的文本
+    nodeId?:   number  // 可选：目标节点，直接写其 widget（如 text/prompt）
+    widgetKey?:string  // 可选：目标 widget 名，默认 "text"
+    newClass?: string  // 可选：先新建此类型节点（如 "StringConcatenate"）作源
+    targetId?: number  // 可选：把新源节点 connect 到目标节点输入
+    targetSlot?:number // 可选：目标输入槽位
+  })
+  ```
+- **验收**：对话生成一段提示词 → `inject_text` → 画布出现新文本节点并接到 CLIP 类节点 → `run` 生效
+
+### 2.3 架构边界原则（重要，写死）
+| 操作类型 | 归属 | 执行路径 |
+|---|---|---|
+| 文件传输（上传图片到 input/） | **host** | 直连 ComfyUI 原生 `/upload/image`，不经过 bridge |
+| 画布节点操作（增删连改） | **host 注册 + bridge 分支** | `/dsh-bridge/command` → 前端 LiteGraph 执行 |
+| 读取执行结果 / 出图 | **host** | 直连 `/history/:id` + `/view` |
+
+> 一句话：**凡是「本机文件 ↔ ComfyUI 文件」走 host + 原生 API；凡是「动画布 / LiteGraph」走 bridge command；读结果走原生 API。** 不要跨层。
+
+### 2.4 其他候选（按优先级，时间允许再做）
+1. `comfyui_export_api` —— 把当前画布导出为 **API 格式 workflow JSON**（供 MCP comfy-cli `run_workflow` 无人值守批量用）—— 打通「画布 ↔ MCP」衔接
+2. `batch_run` 增强 —— 支持 zip 式参数矩阵（多字段同步扫）+ 返回每组的 `get_outputs` 摘要
+3. 授权审批增强 —— 越权高的命令（`load_workflow`/`run`/`upgrade`）走 pending 审批流（现有授权遮罩已就位，补命令级钩子）
+4. README 补「对话产物进画布」用法章节 + 录一段演示 GIF
+
+---
+
+## 3. 实施步骤（新会话照此执行）
+
+```text
+step 1  读本文档 + 两张架构图 → 跑 npm run check 确认基线
+step 2  实现 A：comfyui_attach_image（host lib/index.js）
+        - 复用 bridgeToken/bridgeHeaders 风格；用 fetch 打 /upload/image
+        - multipart 构造（FormData/Blob，Node 22 可用）
+        - 注意 ComfyUI /upload/image 的字段：image=file, type=input, overwrite=false
+        - 可选：返回后调 set_param 更新 LoadImage
+step 3  实现 B：comfyui_inject_text
+        - bridge.js executeCommand 加 inject_text 分支
+        - host 加 comfyui_inject_text 工具（含参数 schema）
+step 4  三处同步（源码 → node_modules → E 盘 custom_nodes）
+        - node --check（lib 两个 JS + bridge.js）
+        - python -m py_compile（__init__.py）
+step 5  真机验证（ComfyUI 运行中）
+        - attach_image：本机放一张图 → 上传 → 画布 LoadImage 可见 → run 走通
+        - inject_text：生成一段提示词 → 注入新节点并连线 → run 生效
+step 6  README（中/英）：
+        - What you get 表加新工具
+        - 新增「对话产物进画布」小节（含 attach_image / inject_text 用法）
+        - 12 → 14 工具计数
+step 7  npm run check + python -m py_compile → git commit → 三处同步
+step 8  发布（见 §4）
+```
+
+**新增/修改文件清单（预计）**
+- `lib/index.js`：+`comfyui_attach_image`，+`comfyui_inject_text`
+- `comfyui-bridge/ComfyUI-DSH-Canvas/entry/bridge.js`：+`inject_text` 分支
+- `README.md` / `README.zh.md`：工具表与用法
+- `docs/architecture-flow.html`：可选补「对话产物 → 画布」一段
+
+---
+
+## 4. 发布与生态（上版本遗留待办，可一并收尾）
+
+- **npm publish**（让 `dsh plugin add dsh-comfyui-canvas` 可装）
+  ```powershell
+  cd F:\Deepseek-harness\projects\dsh-comfyui-canvas   # 或新仓库本地路径
+  npm config set registry https://registry.npmjs.org   # 当前指向 npmmirror，必须切回官方
+  npm adduser                                          # 浏览器授权登录
+  npm whoami                                           # 确认用户名
+  npm publish                                          # 发布（tarball 已验证干净：无 pyc/缓存）
+  ```
+  - 已确认：包名 `dsh-comfyui-canvas` 在 npm **未被占用**；package.json `files` 已排除 `__pycache__`/`*.pyc`
+- **awesome-dsh-plugin 收录**（让 `dshmarket` 市场可见）
+  - 前置：仓库已加 `dsh-plugin` topic ✅；`dsh.bundle` manifest ✅；commit ≥10 ✅；需**仓库创建满 1 天**（CI 硬性检查，2026-09-01 后可提）
+  - 提交 PR：在 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 的 `data/plugins/` 加一个文件 `wbin0001__dsh-comfyui-canvas.yml`
+  - 条目草稿（description 必须属实，会被对照代码检查）：
+    ```yaml
+    url: https://github.com/wbin0001/dsh-comfyui-canvas
+    name: wbin0001/dsh-comfyui-canvas
+    category: tools
+    description:
+      en: 'Embed your ComfyUI as a split-screen canvas in DSH Web and let the agent operate it live: read/write workflows, edit nodes, wire links, run, fetch output images, and batch-sweep parameters straight from the chat.'
+      zh: '把 ComfyUI 作为分屏画布嵌入 DSH，agent 可视化操作：读写工作流、改节点、连线、运行、取回出图、批量扫参，全程不离开对话。'
+    ```
+    > 注意：description 含 `: `（冒号加空格）时必须加引号，详见该仓库 `contributing.md`
+
+---
+
+## 5. 已知事项 / 坑（写死，避免重踩）
+
+- **运行时副本版本号滞后**：node_modules 副本是 0.2.0、源码是 0.1.0——功能一致，仅版本号不同；`npm publish` 后如需统一可重装官方版。当前不处理
+- **DSH 侧工具热加载**：host 工具的 `name`/`description` 改动需**重启 DSH** 才注入 agent 工具列表；bridge 改动需**重启 ComfyUI/重开画布页**
+- **was-ns 依赖**：ComfyUI venv 的 NumPy 已固定 `<2.4`（启动器会自动校验降级），不要随意升级 numpy，否则 was-ns/numba 报错
+- **Cloud ComfyUI**：`networkMode` 支持 cloud-selfhosted/saas；云端需自行部署桥接节点 + DSH 可达 + token 两端一致
+- **安全基线**：`/dsh-bridge/*` 保护 host→bridge 通道（token）；前端上报（/report、result）不 gate；report ≤8MB；多标签 clientId 定向；命令无 client_id 时拒绝
+- **版本号策略**：v0.1.0 已发布；下版升 **0.1.1**（用户指定——新增工具作为小版本增量推进，不跨次版本号）