dsh-comfyui-canvas 0.1.1 → 0.1.2

package/README.md

@@ -3,7 +3,7 @@
 > [中文](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)
+[![Version](https://img.shields.io/badge/version-0.1.2-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)
@@ -19,6 +19,8 @@ Embed your **ComfyUI** (local or cloud) as a split-screen canvas tab inside [Dee
 
 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).
 
+> **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.
+
 ## What you get
 
 | Surface | Description |
@@ -26,7 +28,8 @@ This package is the DSH-side plugin, and it ships the ComfyUI-side bridge node t
 | **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. |
+| **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; `comfyui_attach_file` uploads any local file (image/audio/video/3D) 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. |
+| **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), and `comfyui-video-audio-ops` (video + voiceover/audio track). 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; `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. |
@@ -37,10 +40,16 @@ This package is the DSH-side plugin, and it ships the ComfyUI-side bridge node t
 ### 1. Install the DSH plugin
 
 ```bash
-dsh plugin add github:<your-name>/dsh-comfyui-canvas
+dsh plugin add dsh-comfyui-canvas
+```
+
+Or from a GitHub checkout:
+
+```bash
+dsh plugin add github:wbin0001/dsh-comfyui-canvas
 ```
 
-or from a local checkout:
+Or from a local checkout:
 
 ```bash
 # in your DSH profile
@@ -166,7 +175,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: 15 canvas tools + session-isolated mode
+│   ├── index.js              # DSH host: 19 canvas tools + 4 built-in skills
 │   └── client.js             # DSH web: canvas tab / settings / rail polish
 ├── LICENSE
 ├── README.md

package/README.zh.md

@@ -3,7 +3,7 @@
 > 中文 · [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)
+[![Version](https://img.shields.io/badge/version-0.1.2-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)
@@ -28,7 +28,8 @@
 | **画布标签页** | 对话里新增 `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_batch_run` 一次扫参数矩阵（seed / prompt / 强度）；`comfyui_get_outputs` 把产物直接带回对话——图像、视频、GIF、音频都支持；`comfyui_attach_file` 把本机任意文件（图片/音频/视频/3D）上传进 ComfyUI `input/` 供对应 Load 节点使用；`comfyui_export_api` 把当前画布导出为 API 格式工作流，供 comfy-cli 无人值守批量。 |
+| **技能包（SOP）** | 内置技能教 agent 按正确顺序操作：`comfyui-canvas-ops`（读→确认→改→跑→取回→自检）、`comfyui-admin-ops`（配置/启动/升级/节点管理）、`comfyui-video-audio-ops`（视频+配音/音轨）。装插件即自带技能，无需额外配置。 |
 | **维护工具** | `comfyui_upgrade` 一键升级 ComfyUI 核心与全部 git 自定义节点；`comfyui_config` 报告当前连接与画布专注状态。 |
 | **画布专注模式（会话隔离）** | agent 通过 `comfyui_config` 感知当前会话是否在画布标签，只在画布场景专注画布操作，且**按会话隔离**——多个会话互不干扰。 |
 | **ComfyUI 报错处理** | `debug` 校验工作流并高亮报错节点（纯校验，不触发执行），agent 帮你定位/修复画布错误。 |
@@ -42,7 +43,13 @@
 ### 1. 安装 DSH 插件
 
 ```bash
-dsh plugin add github:<你的用户名>/dsh-comfyui-canvas
+dsh plugin add dsh-comfyui-canvas
+```
+
+或从 GitHub 安装：
+
+```bash
+dsh plugin add github:wbin0001/dsh-comfyui-canvas
 ```
 
 或本地安装：

package/docs/PLAN-v0.1.2.md

@@ -249,10 +249,29 @@ step 12 发布（npm publish + awesome-dsh-plugin 收录信息若有变更）
 ### 设置导航图标（核心改动 §5.5）已落地
 - 见 §5.5 完整记录；核心已还原、非侵入式图标生效、已推送
 
-### npm publish（待办，见 §4 step 12）
-- 包名 `dsh-comfyui-canvas` 在 npm **未被占用**（此前确认）
-- `package.json` `files` 已覆盖 LICENSE/README/lib/comfyui-bridge/screenshots.json/docs
-- 待执行：`npm config set registry https://registry.npmjs.org` → `npm publish`
+### npm publish 已完成（2026-09-02）
+- ✅ `dsh-comfyui-canvas@0.1.1` 已发布到官方 registry（https://www.npmjs.com/package/dsh-comfyui-canvas）
+- 包名未被占用；`files` 覆盖 LICENSE/README/lib/comfyui-bridge/screenshots.json/docs
+- 安装命令已更新为 `dsh plugin add dsh-comfyui-canvas`（npm 方式）
+- 发布 SOP：改版本号 → `npm config set registry https://registry.npmjs.org` → `npm publish`
+- ⚠️ 注意：账户已开 2FA（安全密钥/Passkey）；发布用 granular token（bypass 2FA，90 天有效，约 2026-12 到期）
+
+### 通用文件传输 A1 + A2 已实现（2026-09-02，`a73ffd4`）
+- ✅ `comfyui_attach_file`（host `lib/index.js`）：任意文件（image/audio/video/3D）上传进 ComfyUI `input/`，`mediaTypeOf` 按扩展名推断，可选 `nodeId`+`widgetKey` 指向 Load 节点
+- ✅ `comfyui_get_outputs` 泛化：扫描 `images/videos/gifs/audio` 四种 kind，每条带 `kind` + `/view` URL
+- 已同步 node_modules 副本、已推送 GitHub
+
+### 技能包 B 已实现（2026-09-02，`d1c3d07`）
+- ✅ `ctx.skills.register` 内嵌三个 runtime 技能（随插件分发、零步骤）：
+  - `comfyui-canvas-ops`（画布操作 SOP：读→确认→改→跑→取回→自检）
+  - `comfyui-admin-ops`（环境管理 SOP：配置/启动/升级/节点管理）
+  - `comfyui-video-audio-ops`（音画创作 SOP：视频+配音/音轨）
+- `inject` 加 `skills`；技能内容中英双语、含安全约定
+- 已同步 node_modules 副本、已推送 GitHub
+
+### 剩余（见 §4 实施步骤）
+- A3 画布会话框「+ 文件」通道（client 侧，硬前置：浏览器路径传递）
+- C 节点开发调试（`read_source` / `edit_source` / `reload` + `comfyui-dev-ops` 技能）
 
 ---
 

package/lib/client.js

@@ -24,6 +24,9 @@ function canvasState() {
 
 // 按会话更新 activeViewBySession 映射（读-改-写整张 map，settings 写入串行安全）。
 // 只改自己 sessionId 的键，其它会话不受影响 → 画布模式感知是会话隔离的。
+// 上限 MAX_SESSION_VIEWS：会话销毁时不会自动清理，若不封顶 map 会无限增长
+// （WKB review 实测已 7 条）。写时裁剪到「当前会话 + 最近的 N-1 条」。
+var MAX_SESSION_VIEWS = 50;
 function setSessionView(sc, sessionId, mode) {
   var snap = sc.getSnapshot ? sc.getSnapshot() : null;
   var value = snap && snap.value ? snap.value : {};
@@ -33,6 +36,23 @@ function setSessionView(sc, sessionId, mode) {
     for (var k in current) map[k] = current[k];
   }
   map[String(sessionId)] = mode;
+  var keys = Object.keys(map);
+  if (keys.length > MAX_SESSION_VIEWS) {
+    // Drop oldest keys (object string-key order = insertion order), always
+    // keeping the current session.
+    var drop = keys.length - MAX_SESSION_VIEWS;
+    var keep = {};
+    var currentKey = String(sessionId);
+    var kept = 0;
+    for (var i = 0; i < keys.length; i++) {
+      var k = keys[i];
+      if (k === currentKey || kept < MAX_SESSION_VIEWS - 1) {
+        keep[k] = map[k];
+        kept++;
+      }
+    }
+    map = keep;
+  }
   sc.set("activeViewBySession", map).catch(function () {});
 }
 
@@ -562,9 +582,10 @@ function ComfyUICanvasView(props) {
     };
   }, [sessionId]);
 
-  // ComfyUI 可达性检测：每隔几秒探一下。注意用 mode:'no-cors' —— DSH 页面
-  // (127.0.0.1:3080) 跨域探测 ComfyUI (127.0.0.1:8188) 会被 CORS 拦截，no-cors
-  // 只要服务可达就 resolve（opaque），不可达才 reject，适合纯可达性探测。
+  // ComfyUI 可达性检测：每隔几秒探一下。优先用正常 CORS 请求并检查 res.ok
+  // （能区分"在线"和"500 报错"）；若 DSH 页面 (127.0.0.1:3080) 跨域探测
+  // ComfyUI (127.0.0.1:8188) 被 CORS 拦截（抛 TypeError），回退到 mode:'no-cors'
+  // 的 opaque 可达性探测——服务可达即 resolve，不可达才 reject。
   var onlineState = React.useState(null); // null=检测中, true=在线, false=离线
   var online = onlineState[0];
   var setOnline = onlineState[1];
@@ -574,17 +595,28 @@ function ComfyUICanvasView(props) {
     // 同步顶栏状态圆点（初始检测中）。
     updateCanvasStatus(null);
     var probe = function () {
-      fetch(activeBase + "/system_stats", { method: "GET", mode: "no-cors", signal: AbortSignal.timeout(2500) })
-        .then(function () {
+      fetch(activeBase + "/system_stats", { method: "GET", signal: AbortSignal.timeout(2500) })
+        .then(function (res) {
           if (stopped) return;
-          setOnline(true);
-          setStarting(false); // 服务已可达，清掉"正在启动"态
-          updateCanvasStatus(true);
+          setOnline(res.ok); // 200-299 → 在线；4xx/5xx → 离线（服务在但报错）
+          setStarting(false);
+          updateCanvasStatus(res.ok);
         })
         .catch(function () {
           if (stopped) return;
-          setOnline(false);
-          updateCanvasStatus(false);
+          // CORS 拦截（TypeError）或网络错误 → 用 no-cors 回退判断端口是否可达
+          fetch(activeBase + "/system_stats", { method: "GET", mode: "no-cors", signal: AbortSignal.timeout(2500) })
+            .then(function () {
+              if (stopped) return;
+              setOnline(true);
+              setStarting(false);
+              updateCanvasStatus(true);
+            })
+            .catch(function () {
+              if (stopped) return;
+              setOnline(false);
+              updateCanvasStatus(false);
+            });
         });
     };
     probe();

package/lib/index.js

@@ -17,7 +17,7 @@ import z from '@deepseek-ai/schemastery'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 
 export const name = 'dsh-comfyui-canvas'
-export const inject = ['tools', 'settings', 'shell']
+export const inject = ['tools', 'settings', 'shell', 'skills']
 
 const NAMESPACE = settingsNamespace('dsh-comfyui-canvas')
 const DEFAULT_BASE = 'http://127.0.0.1:8188'
@@ -40,6 +40,10 @@ const ConfigSchema = z.object({
   comfyuiDir: z.string().default(''),
   /** Split-rail width in px. */
   railWidth: z.number().default(360),
+  /** Canvas scale percent (legacy UI field; kept in schema so settings don't drop it). */
+  canvasScale: z.number().default(80),
+  /** Last active view across sessions (legacy echo of activeViewBySession). */
+  activeView: z.string().default('chat'),
   /**
    * Optional shared secret for the ComfyUI bridge. When set, every agent
    * request carries `Authorization: Bearer <token>`, and the bridge only
@@ -236,7 +240,38 @@ export function apply(ctx) {
           updated_at: null,
         }
       }
-      return { ready: true, ...data }
+      // Normalize node/link ids to numbers. The frontend reports ids as
+      // strings; every write tool (connect srcId/dstId, set_param nodeId, …)
+      // declares `number`, so returning strings forces the model to convert.
+      // Coerce only numeric-looking ids; leave exotic ones untouched.
+      const normalized = {
+        ...data,
+        nodes: Array.isArray(data.nodes) ? data.nodes.map((n) => {
+          const id = Number(n?.id)
+          return { ...n, id: Number.isFinite(id) ? id : n?.id }
+        }) : data.nodes,
+        workflow: data.workflow && Array.isArray(data.workflow.nodes)
+          ? {
+            ...data.workflow,
+            nodes: data.workflow.nodes.map((n) => {
+              const id = Number(n?.id)
+              return { ...n, id: Number.isFinite(id) ? id : n?.id }
+            }),
+            links: Array.isArray(data.workflow.links) ? data.workflow.links.map((l) => {
+              const src = Number(l?.[1])
+              const dst = Number(l?.[3])
+              return [
+                l?.[0],
+                Number.isFinite(src) ? src : l?.[1],
+                l?.[2],
+                Number.isFinite(dst) ? dst : l?.[3],
+                ...(l?.slice ? l.slice(4) : []),
+              ]
+            }) : data.workflow.links,
+          }
+          : data.workflow,
+      }
+      return { ready: true, ...normalized }
     },
   }))
 
@@ -360,19 +395,20 @@ export function apply(ctx) {
     },
   }))
 
-  // M2: fetch the output images of a completed run. Reads ComfyUI's own
-  // /history/{promptId} (native endpoint, same trust model as /prompt) and
-  // lists every output node's images (filename / subfolder / type / view URL).
-  // With downloadDir, the images are also saved locally. `ready:false` means
-  // the id is not in history yet — the run may still be executing.
+  // M2: fetch the output files of a completed run (images, videos, gifs,
+  // audio). Reads ComfyUI's own /history/{promptId} (native endpoint, same
+  // trust model as /prompt) and lists every output node's files (kind /
+  // filename / subfolder / type / view URL). With downloadDir, the files are
+  // also saved locally. `ready:false` means the id is not in history yet.
   ctx.tools.register(defineTool({
     name: 'comfyui_get_outputs',
-    description: 'Fetch the output images produced by a completed ComfyUI run (comfyui_run returns prompt_id). ' +
-      'Reads ComfyUI /history/{promptId}, lists every output node with its images (filename/type/subfolder/URL), ' +
-      'and optionally downloads them into a local directory. Returns ready:false while the run is still executing.',
+    description: 'Fetch the output files produced by a completed ComfyUI run (comfyui_run returns prompt_id): ' +
+      'images, videos, gifs, and audio. Reads ComfyUI /history/{promptId}, lists every output node with its ' +
+      'files (kind/filename/type/subfolder/URL), and optionally downloads them into a local directory. ' +
+      'Returns ready:false while the run is still executing.',
     parameters: {
       promptId: { type: 'string', required: true, description: 'The prompt_id returned by comfyui_run.' },
-      downloadDir: { type: 'string', description: 'Optional absolute local directory to save the images into. Omit to return URLs only.' },
+      downloadDir: { type: 'string', description: 'Optional absolute local directory to save the output files into. Omit to return URLs only.' },
     },
     output: { schema: { type: 'object', additionalProperties: true }, render: renderJSON },
     async execute(args, exec) {
@@ -387,17 +423,27 @@ export function apply(ctx) {
       }
       const outputs = item.outputs ?? {}
       const files = []
+      // ComfyUI history outputs carry file arrays under per-kind keys:
+      // images / videos / gifs / audio (depends on the node). Scan them all so
+      // a run's video/audio/3D outputs come back like images do — each entry
+      // keeps its kind + a /view URL (the view endpoint serves any stored file).
+      const FILE_KINDS = ['images', 'videos', 'gifs', 'audio']
+      // Singular label per history key (images→image, videos→video, gifs→gif,
+      // audio→audio). A naive slice(0,-1) would corrupt "audio" into "audi".
+      const KIND_LABEL = { images: 'image', videos: 'video', gifs: 'gif', audio: 'audio' }
       for (const [nodeId, out] of Object.entries(outputs)) {
-        const images = Array.isArray(out?.images) ? out.images : []
-        for (const img of images) {
-          const filename = img?.filename
-          if (!filename) continue
-          const subfolder = img?.subfolder ?? ''
-          const type = img?.type ?? 'output'
-          const qs = `filename=${encodeURIComponent(filename)}` +
-            (subfolder ? `&subfolder=${encodeURIComponent(subfolder)}` : '') +
-            `&type=${encodeURIComponent(type)}`
-          files.push({ nodeId, filename, subfolder, type, url: `${base}/view?${qs}` })
+        for (const kind of FILE_KINDS) {
+          const list = Array.isArray(out?.[kind]) ? out[kind] : []
+          for (const file of list) {
+            const filename = file?.filename
+            if (!filename) continue
+            const subfolder = file?.subfolder ?? ''
+            const type = file?.type ?? 'output'
+            const qs = `filename=${encodeURIComponent(filename)}` +
+              (subfolder ? `&subfolder=${encodeURIComponent(subfolder)}` : '') +
+              `&type=${encodeURIComponent(type)}`
+            files.push({ nodeId, kind: KIND_LABEL[kind] ?? kind, filename, subfolder, type, url: `${base}/view?${qs}` })
+          }
         }
       }
       let downloaded = []
@@ -494,12 +540,48 @@ export function apply(ctx) {
         activeView = 'chat'
         activeViewKnown = true
       }
+      // P0 handshake: does the BRIDGE actually enforce the token? The DSH side
+      // setting alone proves nothing — if the ComfyUI side never got
+      // DSH_BRIDGE_TOKEN, _authorized() always passes and the bridge is open.
+      // Probe with the correct token and a deliberately wrong one: both
+      // succeeding means auth is NOT effective on the wire.
+      const token = (value?.bridgeToken || '').trim()
+      let bridgeAuthEffective = null
+      let bridgeAuthProbe = 'not-probed'
+      try {
+        const good = await fetch(`${baseUrl()}/dsh-bridge/workflow`, {
+          headers: token ? { Authorization: `Bearer ${token}` } : {},
+          signal: AbortSignal.timeout(4000),
+        })
+        const bad = token
+          ? await fetch(`${baseUrl()}/dsh-bridge/workflow`, {
+            headers: { Authorization: 'Bearer dsh-bt-__wrong-probe__' },
+            signal: AbortSignal.timeout(4000),
+          })
+          : good
+        if (!good.ok) {
+          bridgeAuthProbe = `unreachable-or-error: HTTP ${good.status}`
+        } else if (!token) {
+          // No token configured on either side — open by design but flag it.
+          bridgeAuthEffective = false
+          bridgeAuthProbe = 'no token configured on DSH side'
+        } else {
+          bridgeAuthEffective = bad.status === 401
+          bridgeAuthProbe = bad.status === 401
+            ? 'bridge rejects bad token (auth effective)'
+            : 'bridge accepted a WRONG token — auth NOT effective on the ComfyUI side'
+        }
+      } catch (e) {
+        bridgeAuthProbe = `probe failed: ${e instanceof Error ? e.message : String(e)}`
+      }
       return {
         baseUrl: baseUrl(),
         activeView,
         activeViewKnown,
         sessionSource,
-        bridgeTokenSet: Boolean(value?.bridgeToken),
+        bridgeTokenSet: Boolean(token),
+        bridgeAuthEffective,
+        bridgeAuthProbe,
         comfyuiDir: value?.comfyuiDir || '',
         launchCommand: value?.launchCommand || '',
       }
@@ -529,6 +611,12 @@ export function apply(ctx) {
       }
       const fs = await import('node:fs')
       const path = await import('node:path')
+      // WKB review: 69 sequential git pulls can take ~2.3h and hang the agent.
+      // Run concurrently (4 lanes), bound the whole batch, and skip dirty
+      // checkouts (locally-modified repos are exactly this plugin's own users)
+      // instead of hard-pulling into conflicts.
+      const CONCURRENCY = 4
+      const BATCH_TIMEOUT_MS = 300000 // 5 min total
       const run = async (label, command, workdir) => {
         try {
           const spec = shell.resolve({ command, workdir, timeoutMs: 120000 })
@@ -542,9 +630,10 @@ export function apply(ctx) {
       }
       const results = []
       const scopeArg = args?.scope ?? 'all'
+      const jobs = []
       // core: the ComfyUI root is itself a git checkout
       if (scopeArg !== 'nodes' && fs.existsSync(path.join(dir, '.git'))) {
-        results.push(await run('core', 'git pull', dir))
+        jobs.push({ label: 'core', workdir: dir })
       }
       // nodes: every git-backed custom node
       if (scopeArg !== 'core') {
@@ -557,12 +646,39 @@ export function apply(ctx) {
           for (const name of entries) {
             const nodeDir = path.join(nodesDir, name)
             if (fs.existsSync(path.join(nodeDir, '.git'))) {
-              results.push(await run(`node:${name}`, 'git pull', nodeDir))
+              jobs.push({ label: `node:${name}`, workdir: nodeDir })
             }
           }
         }
       }
-      return { upgraded: results.length, results }
+      // dirty probe: empty output = clean (pull safe); non-empty = skip + report
+      const skippedDirty = []
+      const pullJobs = []
+      for (const job of jobs) {
+        const probe = await run(job.label, 'git status --porcelain', job.workdir)
+        if (probe.ok && probe.out.trim().length > 0) {
+          skippedDirty.push({ label: job.label, changedFiles: probe.out.trim().split('\n').length })
+        } else {
+          pullJobs.push(job)
+        }
+      }
+      // bounded concurrency over the pull queue
+      const started = Date.now()
+      let cursor = 0
+      const worker = async () => {
+        while (cursor < pullJobs.length) {
+          if (Date.now() - started > BATCH_TIMEOUT_MS) {
+            results.push({ label: pullJobs[cursor].label, ok: false, error: 'batch timeout exceeded' })
+            cursor++
+            continue
+          }
+          const job = pullJobs[cursor++]
+          results.push(await run(job.label, 'git pull', job.workdir))
+        }
+      }
+      await Promise.all(Array.from({ length: Math.min(CONCURRENCY, pullJobs.length) }, worker))
+      results.sort((a, b) => a.label.localeCompare(b.label))
+      return { upgraded: results.length, skippedDirty, results }
     },
   }))
 
@@ -627,12 +743,14 @@ export function apply(ctx) {
   // the source file is on the agent's own machine, so the host reads and
   // uploads it — same trust model as get_outputs' /history + /view. The bridge
   // token does not apply (native endpoint, not /dsh-bridge/*).
+  // DEPRECATED (v0.1.2): superseded by comfyui_attach_file (image is a subset
+  // of its media types). Kept for back-compat; removed in a future version.
   ctx.tools.register(defineTool({
     name: 'comfyui_attach_image',
-    description: 'Upload a local image into ComfyUI\'s input/ directory and optionally point a LoadImage ' +
-      'node at it. Uses ComfyUI\'s native /upload/image (not the bridge), so the source file is read from ' +
-      'the agent\'s own machine. After upload, pass nodeId to update a LoadImage node\'s image widget to ' +
-      'the new filename so it takes effect immediately.',
+    description: '[DEPRECATED — use comfyui_attach_file instead] Upload a local image into ComfyUI\'s input/ ' +
+      'directory and optionally point a LoadImage node at it. Uses ComfyUI\'s native /upload/image (not the bridge), ' +
+      'so the source file is read from the agent\'s own machine. After upload, pass nodeId to update a LoadImage ' +
+      'node\'s image widget to the new filename so it takes effect immediately.',
     parameters: {
       image: { type: 'string', required: true, description: 'Absolute local path to the image file (png/jpeg/webp/gif).' },
       nodeId: { type: 'number', description: 'Optional LoadImage node id to point at the uploaded file.' },
@@ -723,4 +841,241 @@ export function apply(ctx) {
       return sendCommand(baseUrl(), bridgeToken(), 'export_api', {}, exec.signal, { timeoutMs: 10000 })
     },
   }))
+
+  // v0.1.2 C: node development/debug tools — read / edit custom-node source and
+  // reload ComfyUI so the change takes effect, all from the conversation. The
+  // canvas doubles as the observation window: edit → reload → run a minimal
+  // workflow on the canvas → see the result, without leaving the chat.
+  const requireComfyUIDir = async () => {
+    const value = settingsScope?.get?.()
+    const dir = (value?.comfyuiDir || process.env.COMFYUI_DIR || '').trim()
+    if (!dir) throw new Error('ComfyUI install directory not set. Set comfyuiDir in Settings → ComfyUI 画布, or env COMFYUI_DIR.')
+    return dir
+  }
+  const resolveNodeDir = async (root, nodeName) => {
+    const { join, resolve, sep } = await import('node:path')
+    const nodeDir = join(root, 'custom_nodes', nodeName)
+    // Anchor to the custom_nodes directory itself, not the ComfyUI root:
+    // a nodeName like "../x" would otherwise resolve inside root but outside
+    // custom_nodes and slip past a root-anchored prefix check.
+    const nodesReal = resolve(join(root, 'custom_nodes'))
+    const nodeReal = resolve(nodeDir)
+    if (!nodeReal.startsWith(nodesReal + sep)) throw new Error(`invalid node path: ${nodeName}`)
+    return nodeDir
+  }
+  // Shared helper: list source files under a node dir (top two levels, skipping
+  // .git / node_modules / __pycache__ / .venv), or read one file's content.
+  const inspectNodeSource = async (nodeDir, relPath) => {
+    const fs = await import('node:fs')
+    const path = await import('node:path')
+    if (relPath) {
+      const target = path.resolve(nodeDir, relPath)
+      if (!target.startsWith(path.resolve(nodeDir) + path.sep)) throw new Error('path escapes node dir')
+      if (!fs.existsSync(target) || !fs.statSync(target).isFile()) throw new Error(`file not found: ${relPath}`)
+      return { path: relPath, content: fs.readFileSync(target, 'utf8') }
+    }
+    const SKIP = new Set(['.git', 'node_modules', '__pycache__', '.venv', 'venv', 'dist', 'build'])
+    const tree = []
+    const walk = (dir, depth) => {
+      if (depth > 2) return
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (SKIP.has(entry.name)) continue
+        const full = path.join(dir, entry.name)
+        const rel = path.relative(nodeDir, full).replace(/\\/g, '/')
+        tree.push({ path: rel, type: entry.isDirectory() ? 'dir' : 'file', size: entry.isFile() ? fs.statSync(full).size : null })
+        if (entry.isDirectory()) walk(full, depth + 1)
+      }
+    }
+    walk(nodeDir, 0)
+    return { node: path.basename(nodeDir), tree }
+  }
+  ctx.tools.register(defineTool({
+    name: 'comfyui_read_source',
+    description: 'Read a ComfyUI custom node\'s source under custom_nodes/<name>/. Without path: list its source tree ' +
+      '(top two levels, skipping .git/node_modules/caches). With path: return that file\'s full content. ' +
+      'Use during node development to inspect or debug a custom node (including this plugin\'s own bridge node).',
+    parameters: {
+      node: { type: 'string', required: true, description: 'Custom node directory name under ComfyUI custom_nodes/ (e.g. ComfyUI-DSH-Canvas).' },
+      path: { type: 'string', description: 'Optional relative file path inside the node dir to read (omit to list the tree).' },
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderJSON },
+    async execute(args) {
+      const fs = await import('node:fs')
+      const dir = await requireComfyUIDir()
+      const nodeDir = await resolveNodeDir(dir, args.node)
+      if (!fs.existsSync(nodeDir)) throw new Error(`custom node not found: ${args.node}`)
+      return inspectNodeSource(nodeDir, args.path)
+    },
+  }))
+  ctx.tools.register(defineTool({
+    name: 'comfyui_edit_source',
+    description: 'Edit a file inside a ComfyUI custom node\'s source (custom_nodes/<name>/). Writes new content to the ' +
+      'given relative path; path is confined to the node dir. Pair with comfyui_reload to apply the change: ' +
+      'edit → reload → run a minimal workflow on the canvas to verify. This is how you develop/debug a custom node ' +
+      'from the conversation without touching the ComfyUI UI.',
+    parameters: {
+      node: { type: 'string', required: true, description: 'Custom node directory name under ComfyUI custom_nodes/.' },
+      path: { type: 'string', required: true, description: 'Relative file path inside the node dir to write (e.g. __init__.py or entry/bridge.js).' },
+      content: { type: 'string', required: true, description: 'Full new file content (replaces the file).' },
+    },
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderJSON },
+    async execute(args) {
+      const fs = await import('node:fs')
+      const path = await import('node:path')
+      const dir = await requireComfyUIDir()
+      const nodeDir = await resolveNodeDir(dir, args.node)
+      const target = path.resolve(nodeDir, args.path)
+      if (!target.startsWith(path.resolve(nodeDir) + path.sep)) throw new Error('path escapes node dir')
+      fs.mkdirSync(path.dirname(target), { recursive: true })
+      fs.writeFileSync(target, args.content, 'utf8')
+      return { node: args.node, path: args.path, bytes: Buffer.byteLength(args.content, 'utf8'), ok: true }
+    },
+  }))
+  ctx.tools.register(defineTool({
+    name: 'comfyui_reload',
+    description: 'Restart the local ComfyUI so custom-node source changes take effect: find the process listening on ' +
+      'the ComfyUI port, kill it, then relaunch via the configured launch command. Use after comfyui_edit_source, ' +
+      'then run a minimal workflow on the canvas to verify the change. Warns about running generations; cancels ' +
+      'pending work by restarting.',
+    parameters: {},
+    output: { schema: { type: 'object', additionalProperties: true }, render: renderJSON },
+    async execute(_args) {
+      const value = settingsScope?.get?.()
+      const base = baseUrl()
+      const port = (() => { try { return new URL(base).port || '8188' } catch { return '8188' } })()
+      const cmd = (value?.launchCommand || '').trim()
+      const workdir = (value?.comfyuiDir || process.env.COMFYUI_DIR || '').trim() || undefined
+      const shell = ctx.get?.('shell')
+      if (!shell || typeof shell.run !== 'function') throw new Error('shell service unavailable — cannot reload ComfyUI')
+      if (!cmd) throw new Error('launchCommand is empty — set it in Settings → ComfyUI 画布 to allow reload')
+      // netstat -ano / findstr / taskkill are Windows-specific; on other
+      // platforms the PID hunt and kill would silently no-op and the tool
+      // would report a false success. Fail loud instead of pretending.
+      if (process.platform !== 'win32') {
+        throw new Error('comfyui_reload currently supports Windows only (netstat/taskkill); on macOS/Linux restart ComfyUI manually')
+      }
+      // 1. find the PID on the ComfyUI port
+      const netstat = await shell.run(shell.resolve({ command: `netstat -ano | findstr :${port} | findstr LISTENING`, timeoutMs: 15000 }))
+      const out = (netstat.stdout?.text || netstat.stdout || '').toString()
+      const pids = [...new Set([...out.matchAll(/\s(\d+)\s*$/gm)].map(m => m[1]))]
+      // 2. kill those PIDs (best-effort; ignore failures so relaunch still runs).
+      //    taskkill is a host-level operation outside the session workspace, so
+      //    run it unconfined like the launch below — the default workspace-write
+      //    sandbox would deny it and the old process would survive, blocking the
+      //    port and making the reload look like a no-op.
+      const killed = []
+      for (const pid of pids) {
+        try {
+          await shell.run(shell.resolve({
+            command: `taskkill /PID ${pid} /F`,
+            timeoutMs: 10000,
+            sandboxPolicy: { mode: 'danger-full-access', workspaceRoot: process.cwd() },
+          }))
+          killed.push(pid)
+        } catch { /* already gone or denied — proceed */ }
+      }
+      // 3. relaunch via the same unconfined path the Start button uses
+      shell.start(shell.resolve({
+        command: cmd,
+        ...(workdir ? { workdir } : {}),
+        sandboxPolicy: { mode: 'danger-full-access', workspaceRoot: process.cwd() },
+      }))
+      // 4. wait for /system_stats to come back
+      const deadline = Date.now() + 45000
+      let up = false
+      let lastErr = ''
+      while (Date.now() < deadline) {
+        try {
+          const res = await fetch(`${base}/system_stats`, { signal: AbortSignal.timeout(3000) })
+          if (res.ok) { up = true; break }
+        } catch (e) { lastErr = e instanceof Error ? e.message : String(e) }
+        await new Promise((done) => setTimeout(done, 1500))
+      }
+      return { reloaded: up, killed, port, launched: cmd, error: up ? null : (lastErr || 'timed out waiting for ComfyUI to come back') }
+    },
+  }))
+
+  // v0.1.2: register the skills (SOPs) that teach the agent HOW to use the
+  // canvas/admin tools in the right order. Runtime skills ship inside the
+  // plugin, so `dsh plugin add` installs them with zero extra steps.
+  const skills = ctx.skills ?? ctx.get?.('skills')
+  if (skills && typeof skills.register === 'function') {
+    skills.register({
+      name: 'comfyui-canvas-ops',
+      source: 'runtime',
+      description: 'Operate the live ComfyUI canvas with the agent: read/edit/run workflows, fetch outputs.',
+      whenToUse: 'Use when the user asks to make an image, edit a workflow, adjust a node, run the canvas, or fetch its outputs.',
+      content: [
+        '# ComfyUI 画布操作 SOP',
+        '',
+        '当用户要求用画布作图 / 修改工作流 / 出图时，按此顺序执行：',
+        '',
+        '1. comfyui_config —— 确认画布在前台（activeView=canvas）、连接正常；不在画布视图时先提示用户切到 ComfyUI 标签',
+        '2. comfyui_read_workflow —— 读取当前图，向用户复述关键节点并确认要改什么',
+        '3. 按需修改：comfyui_set_param（改参数）、comfyui_connect（连线）、comfyui_add_node / comfyui_remove_node（增删节点）、comfyui_inject_text（注入文本）',
+        '4. 修改前说明改了哪些；运行前用 comfyui_debug 校验（不触发执行）',
+        '5. comfyui_run 运行（可传 overrides 临时覆盖参数，跑完还原画布）',
+        '6. comfyui_get_outputs 取回出图（支持 images/videos/gifs/audio）',
+        '7. 用 vision 工具自检出图质量 → 不达标回 step 3 迭代；达标再交付',
+        '',
+        '安全约定：读取永远只读；写操作（改节点/运行/替换图）先向用户确认；批量用 comfyui_batch_run。',
+      ].join('\n'),
+    })
+    skills.register({
+      name: 'comfyui-admin-ops',
+      source: 'runtime',
+      description: 'Manage the ComfyUI environment: configure, launch, upgrade, and list/install custom nodes.',
+      whenToUse: 'Use when the user asks to configure ComfyUI, start it, update it, upgrade its nodes, or manage installed custom nodes.',
+      content: [
+        '# ComfyUI 环境管理 SOP',
+        '',
+        '当用户要求配置 / 启动 / 更新 ComfyUI、管理已装节点时，按此顺序执行：',
+        '',
+        '1. 配置管理 —— comfyui_config 读/改连接（baseUrl / port / networkMode / 桥接 token / 启动命令 / rail 宽度）',
+        '2. 启动 / 状态 —— 用设置里的启动命令拉起 ComfyUI（launchRequested 机制），轮询 /system_stats 确认在线；读 launchError 排查启动失败',
+        '3. 更新 —— comfyui_upgrade：git pull 核心 + 全部节点（scope=core/nodes/all），失败不中断其余',
+        '4. 节点管理 —— 用文件系统工具列出 custom_nodes/、识别 git 托管与手工目录；安装/更新节点用 shell 走 git 或 pnpm',
+        '',
+        '安全约定：更新 / 重启 / 装节点是重操作 —— 先确认、讲清影响（如「更新 60+ 节点」「重启中断生成」）；更新前检查是否有运行中任务。',
+      ].join('\n'),
+    })
+    skills.register({
+      name: 'comfyui-video-audio-ops',
+      source: 'runtime',
+      description: 'Create video with audio/voiceover on ComfyUI: generate video, attach audio, fetch the merged file.',
+      whenToUse: 'Use when the user wants a video with sound / voiceover / music track produced through the ComfyUI canvas.',
+      content: [
+        '# ComfyUI 音画创作 SOP',
+        '',
+        '当用户要求「视频 + 配音 / 音轨 / 音乐」时，按此顺序执行：',
+        '',
+        '1. 生成视频 —— 读画布上的视频工作流（如 Wan / Kling / LTX），comfyui_run 运行',
+        '2. 生成音频 —— 用 comfyui_attach_file 把 TTS 生成的 wav / 音轨文件上传进 ComfyUI input/（供 LoadAudio 节点）',
+        '3. 音画合成 —— 走 VideoAddAudio 或对应音画工作流，comfyui_run 合并',
+        '4. comfyui_get_outputs 取回含音轨的视频文件（URL/路径）',
+        '5. 交付时给出文件路径/URL；DSH 不播放，用户本地打开',
+        '',
+        '提示：TTS 音频只是「传输的一类文件」，上传即用；播放能力由 DSH 生态负责，本插件只做传输。',
+      ].join('\n'),
+    })
+    skills.register({
+      name: 'comfyui-dev-ops',
+      source: 'runtime',
+      description: 'Develop or debug a ComfyUI custom node from the conversation: read its source, edit it, reload ComfyUI, and verify on the canvas.',
+      whenToUse: 'Use when the user wants to develop, modify, or debug a ComfyUI custom node (including this plugin\'s bridge node) — read/edit its source, restart ComfyUI, or verify a change on the canvas.',
+      content: [
+        '# ComfyUI 节点开发调试 SOP',
+        '',
+        '当用户要求开发 / 修改 / 调试 ComfyUI 自定义节点（含本插件的桥接节点）时，按此循环执行：',
+        '',
+        '1. comfyui_read_source —— 读目标节点源码（列出目录树或读单个文件，如 __init__.py / entry/bridge.js），先弄清结构与注册方式',
+        '2. comfyui_edit_source —— 修改源码（受控写文件，仅限该节点目录内）',
+        '3. comfyui_reload —— 重启 ComfyUI 使改动生效（会中断运行中任务，先确认）；等 /system_stats 恢复在线',
+        '4. 画布验证 —— 在画布上搭一个用到该节点的最小工作流，comfyui_run 运行',
+        '5. comfyui_get_outputs 看结果 → 不达标回 step 2 迭代',
+        '',
+        '安全约定：改的是 custom_nodes/ 下的本机源码 —— 写操作先确认、讲清改哪个文件；重启前检查是否有运行中任务；改坏了节点可能让 ComfyUI 起不来（保留备份 / 可回退）。',
+      ].join('\n'),
+    })
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-comfyui-canvas",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Give DeepSeek Harness agents live control of your ComfyUI canvas (local or cloud): embed it as a split-screen tab, then read/edit/run workflows, debug errors, fetch output images, and batch-sweep parameters straight from the chat. Ships the ComfyUI-side bridge node.",
   "type": "module",
   "main": "lib/index.js",