dsh-comfyui-canvas 0.1.2 → 0.1.3

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.2-brightgreen.svg)](https://github.com/wbin0001/dsh-comfyui-canvas/releases)
+[![Version](https://img.shields.io/badge/version-0.1.3-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,11 +28,13 @@ 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 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. |
+| **Production tools** | `comfyui_batch_run` sweeps a parameter matrix (seeds/prompts/strengths) in one go; `comfyui_get_outputs` pulls the resulting files back into the chat — images, videos, gifs, and audio — with optional `outputStem` auto-incrementing names (`stem.01.png`, never overwrites); `comfyui_attach_file` uploads any local file (image/audio/video/3D/text) into ComfyUI's input/ for the matching Load node; `comfyui_export_api` exports the live canvas as API-format workflow JSON for comfy-cli headless batch runs. |
+| **Projects & traceability** | Downloads default to the project directory (Settings → 项目目录, default `<workspace>/projects`); every downloaded run appends `runs.json` (promptId / overrides / timestamp / files) so any output can be traced back to its parameters. Failed runs return a structured `executionError` (node id / node type / exception / message) instead of a raw JSON wall. |
+| **Skills (SOPs)** | Built-in skills teach the agent the right order of operations: `comfyui-canvas-ops` (read → confirm → edit → run → fetch → self-check), `comfyui-admin-ops` (configure/launch/upgrade/node management), `comfyui-video-audio-ops` (video + voiceover/audio track), and `comfyui-dev-ops` (develop/debug custom nodes). Install the plugin and the skills ship with it — no extra setup. |
+| **Upkeep tool** | `comfyui_upgrade` one-click updates the ComfyUI core and every git-backed custom node (concurrent, dirty-safe); `comfyui_config` reports the active connection, canvas focus, project directory, and a bridge-auth handshake check (`bridgeAuthEffective`). |
+| **Node dev tools** | `comfyui_read_source` / `comfyui_edit_source` / `comfyui_reload` — read and edit custom-node source under custom_nodes/ and restart ComfyUI from the conversation, then verify on the canvas. |
 | **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. |
+| **Settings page** | ComfyUI base URL / port / network mode / bridge token / launch command / project directory / 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
@@ -186,7 +188,8 @@ The **bridge** is the only ComfyUI-side dependency. It exposes `/dsh-bridge/work
 
 ## 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.)_
+- `comfyui_reload` currently supports **Windows only** (uses `netstat`/`taskkill`); on macOS/Linux it fails loud instead of pretending, restart ComfyUI manually there.
+- 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
 

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.2-brightgreen.svg)](https://github.com/wbin0001/dsh-comfyui-canvas/releases)
+[![Version](https://img.shields.io/badge/version-0.1.3-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,12 +28,14 @@
 | **画布标签页** | 对话里新增 `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` 把产物直接带回对话——图像、视频、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` 报告当前连接与画布专注状态。 |
+| **生产工具** | `comfyui_batch_run` 一次扫参数矩阵（seed / prompt / 强度）；`comfyui_get_outputs` 把产物直接带回对话——图像、视频、GIF、音频都支持，可传 `outputStem` 自动编号（`stem.01.png`，永不覆盖）；`comfyui_attach_file` 把本机任意文件（图片/音频/视频/3D/**文本**）上传进 ComfyUI `input/` 供对应 Load 节点使用；`comfyui_export_api` 把当前画布导出为 API 格式工作流，供 comfy-cli 无人值守批量。 |
+| **项目目录与溯源** | 下载默认落「项目目录」（设置页可改，默认 `<工作区>/projects`）；每次下载把 `runs.json`（promptId / overrides / 时间戳 / 文件）追加进项目目录，任意一张图都能追溯回它的生成参数。运行失败返回结构化 `executionError`（节点 id / 节点类型 / 异常类型 / 信息），不再是一堵 JSON 墙。 |
+| **技能包（SOP）** | 内置技能教 agent 按正确顺序操作：`comfyui-canvas-ops`（读→确认→改→跑→取回→自检）、`comfyui-admin-ops`（配置/启动/升级/节点管理）、`comfyui-video-audio-ops`（视频+配音/音轨）、`comfyui-dev-ops`（开发/调试自定义节点）。装插件即自带技能，无需额外配置。 |
+| **维护工具** | `comfyui_upgrade` 一键升级 ComfyUI 核心与全部 git 自定义节点（并发、跳过本地改过的仓库）；`comfyui_config` 报告当前连接、画布专注状态、项目目录，以及**桥接鉴权握手检查**（`bridgeAuthEffective`）。 |
+| **节点开发工具** | `comfyui_read_source` / `comfyui_edit_source` / `comfyui_reload`——对话里直接读写 `custom_nodes/` 下的节点源码并重启 ComfyUI，再到画布上验证。 |
 | **画布专注模式（会话隔离）** | agent 通过 `comfyui_config` 感知当前会话是否在画布标签，只在画布场景专注画布操作，且**按会话隔离**——多个会话互不干扰。 |
 | **ComfyUI 报错处理** | `debug` 校验工作流并高亮报错节点（纯校验，不触发执行），agent 帮你定位/修复画布错误。 |
-| **设置页** | ComfyUI 地址 / 端口 / 网络模式 / 桥接 Token / 启动命令 / 右侧面板宽度，实时生效。导航栏已自定义为 ComfyUI logo 图标。 |
+| **设置页** | ComfyUI 地址 / 端口 / 网络模式 / 桥接 Token / 启动命令 / 项目目录 / 右侧面板宽度，实时生效。导航栏已自定义为 ComfyUI logo 图标。 |
 | **对话栏增强** | 图片预览并入输入框、`+` 号上传本地图片（走 DSH 官方附件通道）、画布上的授权弹窗、发送按钮贴右下角。 |
 
 ---
@@ -208,7 +210,8 @@ dsh-comfyui-canvas/
 
 ## 已知问题
 
-_（当前无已知未决问题。此前"画布运行后节点预览不显示"已在 v0.1.1 修复：移除 iframe 的 `referrerpolicy="no-referrer"` 消除环境差异，并在 `bridge.js` 监听 ComfyUI `executed` 事件强制重绘画布。）_
+- `comfyui_reload` 目前**仅支持 Windows**（依赖 `netstat`/`taskkill`）；macOS/Linux 上会明确报错而非假装成功，需手动重启 ComfyUI。
+- 此前"画布运行后节点预览不显示"已在 v0.1.1 修复：移除 iframe 的 `referrerpolicy="no-referrer"` 消除环境差异，并在 `bridge.js` 监听 ComfyUI `executed` 事件强制重绘画布。
 
 ---
 

package/docs/PLAN-v0.1.3.md

@@ -0,0 +1,101 @@
+# dsh-comfyui-canvas v0.1.3 方案
+
+> 目标：从「画布遥控器」进化为「可复现的创作工作台」——补齐运行溯源、输出不覆盖、项目目录三大能力（P0），加画布文件上传通道（A3，v0.1.2 搁置项）与失败结构化诊断（P1）。
+> 依据：第三方评估报告（2026-09-02）的 6 项优化建议 + v0.1.2 收尾时搁置的 A3。
+
+## 1. P0-1：运行溯源 `.runs.json`（~30 行）
+
+**问题**：`comfyui_run` 返回 promptId 后，批量跑多个 seed/prompt 变体，无法追溯「哪张图对应什么参数」。
+
+**方案**：host 端在每次 run/batch_run 时记录 `{ promptId, overrides, timestamp, status }` 到内存；`get_outputs` 下载时把记录 append 到 `downloadDir/<workflow_name>.runs.json`（无则新建）。
+
+```json
+[
+  { "run": 1, "promptId": "abc123", "overrides": [{"nodeId":6,"key":"seed","value":42}],
+    "timestamp": "2026-09-02T22:00:00Z", "status": "success", "files": ["char_ref.01.png"] }
+]
+```
+
+**价值**：可复现是创作的命脉。agent 读 `.runs.json` 对比历史运行，用户追溯任意一张图的来源参数。
+
+## 2. P0-2：输出不覆盖命名（~20 行）
+
+**问题**：ComfyUI `output/` 用自带命名规则，批量跑后文件混乱、可能互相覆盖。
+
+**方案**：`get_outputs` 下载时新增 `outputStem` 参数（可选）。扫描 `downloadDir` 已有 `<stem>.NN.<ext>` 文件，NN 自增不覆盖。
+
+**价值**：批量跑 20 个变体后文件名直接反映顺序，永不覆盖。
+
+## 3. P0-3：项目目录概念（~15 行）
+
+**问题**：导出的 API JSON、下载的图片、溯源文件散落各处。
+
+**方案**：ConfigSchema 新增 `projectDir` 字段。`get_outputs` 下载、`export_api` 导出、`.runs.json` 默认落在 `projectDir/<workflow_name>/`；未设时回退现有行为（不破坏兼容）。
+
+**价值**：一个创作项目的所有资产（工作流/输出/溯源）聚在一起，agent 用文件工具管理整个项目。
+
+## 4. A3：画布会话框「+ 文件」通道 —— 已砍（2026-09-03 决策）
+
+**原内容**：画布会话框加「+ 文件」按钮，直接传本地文件进 ComfyUI `input/`。
+
+**硬前置**：浏览器 `<input type="file">` 给的是 File 对象、不是绝对路径，而 `attach_file` 收 `path`——需先确认 client → host 传参通道（v0.1.2 方案开放问题 #1）。
+
+**砍的原因**：A1（host 侧 `attach_file`）已让 agent 能传任意文件（含文本/提示词），A3 只是「手动点按钮直传」的锦上添花，浏览器路径传递是硬前置、收益边际低。**留 v0.2+ 或不做**。若有需要，降级方案：agent 引导用户给路径，无需 UI。
+
+## 5. P1：运行失败结构化诊断（~40 行）
+
+**问题**：`run` 失败只返回 HTTP 错误或 `node_errors`，无法定位具体节点异常。
+
+**方案**：`run` 的 sendCommand 返回后，若 nodeErrors 非空，自动 GET `/history/{promptId}` 提取 `execution_error`，结构化返回：
+
+```json
+{
+  "promptId": "abc123", "success": false,
+  "nodeErrors": {"7": ["missing required input 'model'"]},
+  "executionError": { "nodeId": 7, "nodeType": "CheckpointLoaderSimple",
+    "exception": "FileNotFoundError", "message": "Checkpoint file not found: sd_xl_base.safetensors" }
+}
+```
+
+**价值**：agent 直接定位「节点 7 缺 checkpoint」并修复，不用看一堆 JSON。
+
+## 6. 本版顺手修复
+
+- ✅ `get_outputs` 无限超时（已修）：history fetch 15s、文件下载 fetch 30s 超时（`AbortSignal.any([exec.signal, timeout])`）
+- 桥接鉴权告警（设置页 + 画布激活，host 代理探测）——已实现（v0.1.2 后补，随 v0.1.3 发布）
+- ✅ `attach_file` 文本/提示词上传（`d58d302`）：mediaType 映射新增 txt/md/json/csv/yaml/yml/srt——提示词/批量提示词 JSON 等文本可直接进 ComfyUI `input/` 供文本类 Load 节点消费
+
+### 文件上传支持矩阵（`attach_file`，2026-09-03）
+
+| 类别 | 扩展名 | mediaType |
+|---|---|---|
+| 图片 | png / jpg / jpeg / webp / gif | image/* |
+| 音频（含音乐） | wav / mp3 / ogg / flac / m4a / aac | audio/* |
+| 视频 | mp4 / webm / mov / mkv / avi | video/* |
+| 3D | glb / gltf / obj / fbx / stl | model/* |
+| **文本/提示词** | txt / md / json / csv / yaml / yml / srt | text/plain、application/json、text/markdown、text/csv、application/yaml、application/x-subrip |
+| 其他 | 任意 | application/octet-stream 透传 |
+
+## 不做清单（范围控制）
+
+- ❌ WebSocket 推送替代轮询（P2，改动大，收益中等，留 v0.2）
+- ❌ 工作流链式组合（P1，单链封装 set_param+run，可用性待验证）
+- ❌ src/ + 构建管线、CI、DOM 选择器集中管理（工程化，独立排期）
+- ❌ `/dsh-bridge/report` 鉴权（localhost-only 已可接受，远期选项）
+
+## 实施步骤
+
+```
+step 1  P0-1 `.runs.json`：host 记录 run/batch_run 元数据 → get_outputs 下载时 flush
+step 2  P0-2 输出不覆盖命名：get_outputs 加 outputStem，NN 自增
+step 3  P0-3 项目目录：ConfigSchema 加 projectDir → get_outputs/export_api 默认路径
+step 4  P1 失败诊断：run 失败自动拉 /history/{pid} execution_error
+step 5  A3 画布上传通道：探 client→host 传参通道；不可行则降级/砍
+step 6  README 更新（P0 三项 + 新工具/参数说明）+ 版本号 0.1.2 → 0.1.3
+step 7  npm run check → 同步三处 → 提交推送 → npm publish → GitHub Release
+```
+
+## 参考
+
+- 第三方评估报告（2026-09-02）：6 项优化建议，P0 三项 ~65 行
+- v0.1.2 方案 `docs/PLAN-v0.1.2.md` §4.5「剩余」：A3 移入 v0.1.3

package/lib/client.js

@@ -40,7 +40,6 @@ function setSessionView(sc, sessionId, mode) {
   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;
@@ -657,6 +656,34 @@ function ComfyUICanvasView(props) {
     });
   };
 
+  // 桥接鉴权握手（画布激活时按需触发，非启动路径）：浏览器跨域读不到
+  // ComfyUI 状态码（CORS），所以向 host 请求一次代理探测——写
+  // probeRequested=true，host watcher 后台探测并把结果写回 bridgeProbe。
+  // 这里只负责发起 + 订阅展示，全程异步，不影响任何启动流程。
+  var probeState = React.useState(null); // {bridgeAuthEffective, bridgeAuthProbe, checkedAt}
+  var bridgeProbe = probeState[0];
+  var setBridgeProbe = probeState[1];
+  var tokenSetState = React.useState(false);
+  var tokenSet = tokenSetState[0];
+  var setTokenSet = tokenSetState[1];
+  React.useEffect(function () {
+    var sc = props.scope;
+    if (!sc) return;
+    if (typeof sc.set === "function") {
+      sc.set("probeRequested", true).catch(function () {});
+    }
+    if (typeof sc.subscribe !== "function" || typeof sc.getSnapshot !== "function") return;
+    var sync = function () {
+      var snap = sc.getSnapshot();
+      var v = snap && snap.value ? snap.value : {};
+      setBridgeProbe(v.bridgeProbe || null);
+      setTokenSet(!!(v.bridgeToken));
+    };
+    sync();
+    var unsub = sc.subscribe(sync);
+    return function () { if (typeof unsub === "function") unsub(); };
+  }, [sessionId]);
+
   // 启动超时：host 用 launchCommand 拉起 ComfyUI 通常几十秒内完成；超过
   // 45 秒仍未探测到在线就复位"正在启动…"，允许用户重试，避免永久卡死。
   React.useEffect(function () {
@@ -677,6 +704,20 @@ function ComfyUICanvasView(props) {
   // 授权弹窗渲染在 host 内部（与控制条同级），absolute 定位锚定 host 的
   // relative 边界 → 只盖画布视图区，不会挡住顶栏/右侧 rail。
   var hostChildren = [control];
+  // 桥接鉴权告警（非启动路径，画布激活时按需展示）：只有当 DSH 侧配了
+  // token、但桥接握手显示"错误 token 也能通过"时才亮红字——这是真正的
+  // 配置错位（ComfyUI 端没设 DSH_BRIDGE_TOKEN）。正常/未配 token 不打扰。
+  if (bridgeProbe && bridgeProbe.bridgeAuthEffective === false && tokenSet) {
+    hostChildren.push(React.createElement("div", {
+      style: {
+        position: "absolute", top: "8px", left: "50%", transform: "translateX(-50%)",
+        zIndex: 45, maxWidth: "86%",
+        background: "rgba(248,81,73,.12)", color: "#f85149",
+        border: "1px solid rgba(248,81,73,.4)", borderRadius: "6px",
+        padding: "6px 12px", fontSize: "12px", lineHeight: "1.5", textAlign: "center",
+      },
+    }, "⚠️ 桥接鉴权未生效：ComfyUI 端可能没设 DSH_BRIDGE_TOKEN。打开设置页 → ComfyUI 画布 查看详情。"));
+  }
   if (approval) {
     hostChildren.push(React.createElement(ComfyUIApprovalOverlay, { wait: approval }));
   }
@@ -702,6 +743,7 @@ function ComfyUISettingsRow(props) {
   var launchCommand = typeof value.launchCommand === "string" ? value.launchCommand : "";
   var comfyuiDir = typeof value.comfyuiDir === "string" ? value.comfyuiDir : "";
   var railWidth = value.railWidth != null ? Number(value.railWidth) : DEFAULT_RAIL;
+  var projectDir = typeof value.projectDir === "string" ? value.projectDir : "";
   var writable = !snapshot || snapshot.writable !== false;
 
   var inputStyle = {
@@ -719,6 +761,33 @@ function ComfyUISettingsRow(props) {
     scope.set(field, next).catch(function () { /* recover handled by scope */ });
   }
 
+  // 桥接鉴权握手（非启动路径）：设置页打开 / token 变化时向 host 请求一次
+  // 探测（probeRequested=true → host 后台探测 → 结果写回 bridgeProbe）。
+  // host 代理是因为浏览器跨域读不到 ComfyUI 的状态码（CORS），而 host 端
+  // fetch 没有此限制。这里只负责"发起请求 + 展示结果"，不阻塞任何启动流程。
+  // 输入 token 时防抖 600ms，避免每个字符触发一次探测。
+  React.useEffect(function () {
+    if (!bridgeToken) return;
+    var timer = setTimeout(function () {
+      if (scope && typeof scope.set === "function") {
+        scope.set("probeRequested", true).catch(function () {});
+      }
+    }, 600);
+    return function () { clearTimeout(timer); };
+  }, [bridgeToken]);
+  var probe = value.bridgeProbe || {};
+  var probeText = "";
+  var probeColor = "#9a9aa2";
+  if (probe.bridgeAuthEffective === true) {
+    probeText = "✅ 桥接鉴权已生效（错误 Token 会被拒绝）";
+    probeColor = "#3fb950";
+  } else if (probe.bridgeAuthEffective === false) {
+    probeText = bridgeToken
+      ? "⚠️ 桥接鉴权未生效：ComfyUI 端可能没设 DSH_BRIDGE_TOKEN（检查启动器）"
+      : "ℹ️ 未配置桥接 Token —— 桥接不鉴权（ComfyUI 默认信任模型）";
+    probeColor = bridgeToken ? "#f85149" : "#d29922";
+  }
+
   return React.createElement("div", { style: rowStyle },
     React.createElement("div", { style: titleStyle }, "ComfyUI 画布"),
     React.createElement("label", { style: labelStyle }, "ComfyUI 地址"),
@@ -762,12 +831,21 @@ function ComfyUISettingsRow(props) {
       spellCheck: false, placeholder: "例如 C:\\path\\to\\ComfyUI",
       onChange: function (e) { setField("comfyuiDir", e.target.value); },
     }),
+    React.createElement("label", { style: labelStyle }, "项目目录（输出/导出/溯源默认落此；留空用 <工作区>/projects）"),
+    React.createElement("input", {
+      style: inputStyle, value: projectDir, disabled: !writable,
+      spellCheck: false, placeholder: "例如 D:\\AI-Projects（留空 = 工作区 projects/）",
+      onChange: function (e) { setField("projectDir", e.target.value); },
+    }),
     React.createElement("label", { style: labelStyle }, "右侧面板宽度 (px)（画布宽度 = 总宽 − 右侧面板）"),
     React.createElement("input", {
       style: inputStyle, value: String(railWidth), disabled: !writable,
       type: "number", min: 120, max: 1200, step: 10,
       onChange: function (e) { setField("railWidth", Number(e.target.value)); },
     }),
+    probeText ? React.createElement("div", {
+      style: { fontSize: "12px", color: probeColor, marginTop: "10px", lineHeight: "1.5" },
+    }, probeText) : null,
   );
 }
 

package/lib/index.js

@@ -15,6 +15,7 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import z from '@deepseek-ai/schemastery'
 import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import path from 'node:path'
 
 export const name = 'dsh-comfyui-canvas'
 export const inject = ['tools', 'settings', 'shell', 'skills']
@@ -44,6 +45,12 @@ const ConfigSchema = z.object({
   canvasScale: z.number().default(80),
   /** Last active view across sessions (legacy echo of activeViewBySession). */
   activeView: z.string().default('chat'),
+  /**
+   * Project directory for outputs/export/traceability. When empty, downloads
+   * and exports default to `<DSH workspace>/projects/<workflow_name>/`.
+   * Users with their own organization may point it anywhere (e.g. D:\AI-Projects).
+   */
+  projectDir: z.string().default(''),
   /**
    * Optional shared secret for the ComfyUI bridge. When set, every agent
    * request carries `Authorization: Bearer <token>`, and the bridge only
@@ -72,6 +79,20 @@ const ConfigSchema = z.object({
    * current session's value so the agent knows whether to focus on canvas work.
    */
   activeViewBySession: z.dict(z.union([z.const('canvas'), z.const('chat')])).default({}),
+  /**
+   * One-shot probe request: the client settings page / canvas tab sets this
+   * true when it wants a fresh bridge-auth handshake; the host watcher runs
+   * the probe (host side has no CORS problem) and writes the result into
+   * `bridgeProbe`, then clears this flag. Kept out of the startup path —
+   * probing is on-demand, async, and never blocks DSH boot.
+   */
+  probeRequested: z.boolean().default(false),
+  /** Last bridge-auth probe result, written by the host watcher. */
+  bridgeProbe: z.object({
+    bridgeAuthEffective: z.union([z.boolean(), z.const(null)]),
+    bridgeAuthProbe: z.string(),
+    checkedAt: z.number(),
+  }).default({ bridgeAuthEffective: null, bridgeAuthProbe: 'not-probed', checkedAt: 0 }),
 })
 
 function renderJSON(_args, value) {
@@ -88,6 +109,9 @@ const MEDIA_TYPE_BY_EXT = {
   mp4: 'video/mp4', webm: 'video/webm', mov: 'video/quicktime', mkv: 'video/x-matroska', avi: 'video/x-msvideo',
   // 3D
   glb: 'model/gltf-binary', gltf: 'model/gltf+json', obj: 'model/obj', fbx: 'model/fbx', stl: 'model/stl',
+  // text / prompts / structured inputs
+  txt: 'text/plain', md: 'text/markdown', srt: 'application/x-subrip',
+  json: 'application/json', csv: 'text/csv', yaml: 'application/yaml', yml: 'application/yaml',
 }
 function mediaTypeOf(ext) {
   return MEDIA_TYPE_BY_EXT[ext] ?? null
@@ -100,6 +124,86 @@ function bridgeHeaders(token) {
     : { 'Content-Type': 'application/json' }
 }
 
+/**
+ * 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. Shared by comfyui_config and the
+ * settings watcher (the client cannot probe cross-origin, so the host probes
+ * on the client's behalf).
+ */
+async function probeBridgeAuth(base, token) {
+  const result = {
+    bridgeAuthEffective: null,
+    bridgeAuthProbe: 'not-probed',
+    checkedAt: Date.now(),
+  }
+  try {
+    const good = await fetch(`${base}/dsh-bridge/workflow`, {
+      headers: token ? { Authorization: `Bearer ${token}` } : {},
+      signal: AbortSignal.timeout(4000),
+    })
+    const bad = token
+      ? await fetch(`${base}/dsh-bridge/workflow`, {
+        headers: { Authorization: 'Bearer dsh-bt-__wrong-probe__' },
+        signal: AbortSignal.timeout(4000),
+      })
+      : good
+    if (!good.ok) {
+      result.bridgeAuthProbe = `unreachable-or-error: HTTP ${good.status}`
+    } else if (!token) {
+      // No token configured on either side — open by design but flag it.
+      result.bridgeAuthEffective = false
+      result.bridgeAuthProbe = 'no token configured on DSH side'
+    } else {
+      result.bridgeAuthEffective = bad.status === 401
+      result.bridgeAuthProbe = bad.status === 401
+        ? 'bridge rejects bad token (auth effective)'
+        : 'bridge accepted a WRONG token — auth NOT effective on the ComfyUI side'
+    }
+  } catch (e) {
+    result.bridgeAuthProbe = `probe failed: ${e instanceof Error ? e.message : String(e)}`
+  }
+  return result
+}
+
+/**
+ * P1: extract a structured execution error from a ComfyUI history item, so a
+ * failed run reports "node 7 CheckpointLoaderSimple → FileNotFoundError" instead
+ * of a raw JSON wall. ComfyUI stores it under status.execution_error (newer) or
+ * status.messages[] entries of type "execution_error" (classic). Returns null
+ * when the run had no execution error.
+ */
+function extractExecutionError(item) {
+  const status = item?.status
+  if (!status) return null
+  if (status.execution_error && typeof status.execution_error === 'object') {
+    const e = status.execution_error
+    return {
+      nodeId: e.node_id ?? null,
+      nodeType: e.node_type ?? null,
+      exceptionType: e.exception_type ?? null,
+      message: e.exception_message ?? null,
+      traceback: Array.isArray(e.traceback) ? e.traceback.join('\n').slice(0, 2000) : (e.traceback ?? null),
+    }
+  }
+  if (Array.isArray(status.messages)) {
+    for (const [type, payload] of status.messages) {
+      if (type === 'execution_error' && payload && typeof payload === 'object') {
+        return {
+          nodeId: payload.node_id ?? null,
+          nodeType: payload.node_type ?? null,
+          exceptionType: payload.exception_type ?? null,
+          message: payload.exception_message ?? null,
+          traceback: Array.isArray(payload.traceback) ? payload.traceback.join('\n').slice(0, 2000) : (payload.traceback ?? null),
+        }
+      }
+    }
+  }
+  return null
+}
+
 /** POST a write command to the bridge and poll for the frontend result. */
 async function sendCommand(baseUrl, token, cmd, payload, signal, { pollMs = 400, timeoutMs = 8000 } = {}) {
   const started = Date.now()
@@ -134,6 +238,36 @@ export function apply(ctx) {
   // activeView read); undefined when the settings service is unavailable.
   let settingsScope = undefined
 
+  // v0.1.3: in-memory run ledger for `.runs.json` traceability — keyed by
+  // prompt_id, recording the overrides each run was started with so downloads
+  // can answer "which parameters produced this image". Bounded: DSH runs are
+  // long-lived and every run adds an entry, so cap it and drop the oldest
+  // (Map preserves insertion order).
+  const runLedger = new Map()
+  const RUN_LEDGER_MAX = 500
+  const recordRun = (promptId, overrides, status) => {
+    runLedger.set(String(promptId), {
+      overrides: Array.isArray(overrides) ? overrides : [],
+      timestamp: new Date().toISOString(),
+      status,
+    })
+    if (runLedger.size > RUN_LEDGER_MAX) {
+      const oldest = runLedger.keys().next().value
+      if (oldest !== undefined) runLedger.delete(oldest)
+    }
+  }
+
+  // v0.1.3: resolve the project directory — explicit setting wins, otherwise
+  // default to `<DSH workspace>/projects`. This is where get_outputs downloads
+  // land and `.runs.json` is written, so one project's assets stay together
+  // (outputs, export JSON, trace) without touching ComfyUI's own output/.
+  const resolveProjectDir = () => {
+    const value = settingsScope?.get?.()
+    const explicit = (value?.projectDir || '').trim()
+    if (explicit) return explicit
+    return path.join(process.cwd(), 'projects')
+  }
+
   // M3: prefer the settings namespace when the settings service is present.
   // Registration is optional so missing settings never blocks startup.
   const settings = ctx.settings ?? ctx.get?.('settings')
@@ -205,6 +339,30 @@ export function apply(ctx) {
           }
         })()
       })
+
+      // Bridge-auth probe watcher: the client settings page / canvas tab sets
+      // probeRequested=true when it wants a fresh handshake; the host probes
+      // (host-side fetch has no CORS issue — the browser cannot read ComfyUI's
+      // status cross-origin, which is why the client asks us to do it) and
+      // writes the verdict back into `bridgeProbe`, then clears the flag.
+      let probing = false
+      scope.watch(() => {
+        const value = scope.get()
+        if (!value?.probeRequested || probing) return
+        probing = true
+        void (async () => {
+          try {
+            const token = (value?.bridgeToken || '').trim()
+            const base = resolveBase()
+            const result = await probeBridgeAuth(base, token)
+            try {
+              scope.update({ bridgeProbe: result, probeRequested: false })
+            } catch { /* best effort */ }
+          } finally {
+            probing = false
+          }
+        })()
+      })
     } catch {
       // Duplicate registration or unavailable provider — keep defaults.
     }
@@ -370,7 +528,28 @@ export function apply(ctx) {
     },
     output: { schema: { type: 'object', additionalProperties: true }, render: renderJSON },
     async execute(args, exec) {
-      return sendCommand(baseUrl(), bridgeToken(), 'run', { overrides: args.overrides }, exec.signal, { timeoutMs: 20000 })
+      const result = await sendCommand(baseUrl(), bridgeToken(), 'run', { overrides: args.overrides }, exec.signal, { timeoutMs: 20000 })
+      // v0.1.3: record the run for .runs.json traceability.
+      if (result && result.promptId) {
+        recordRun(result.promptId, args.overrides, result.nodeErrors ? 'error' : 'queued')
+      }
+      // P1: a submission failure (nodeErrors) often hides a concrete execution
+      // error. Best-effort fetch /history right away to surface it structurally.
+      const hasNodeErrors = result && result.nodeErrors && Object.keys(result.nodeErrors).length > 0
+      if (result && result.promptId && hasNodeErrors) {
+        try {
+          const pid = encodeURIComponent(result.promptId)
+          const hr = await fetch(`${baseUrl()}/history/${pid}`, {
+            signal: AbortSignal.any([exec.signal, AbortSignal.timeout(8000)]),
+          })
+          if (hr.ok) {
+            const history = await hr.json()
+            const executionError = extractExecutionError(history?.[result.promptId])
+            if (executionError) result.executionError = executionError
+          }
+        } catch { /* best effort — nodeErrors alone is still actionable */ }
+      }
+      return result
     },
   }))
 
@@ -391,7 +570,18 @@ export function apply(ctx) {
     },
     output: { schema: { type: 'object', additionalProperties: true }, render: renderJSON },
     async execute(args, exec) {
-      return sendCommand(baseUrl(), bridgeToken(), 'batch_run', { runs: args.runs }, exec.signal, { timeoutMs: 30000 })
+      const result = await sendCommand(baseUrl(), bridgeToken(), 'batch_run', { runs: args.runs }, exec.signal, { timeoutMs: 30000 })
+      // v0.1.3: record every queued run for .runs.json traceability.
+      if (result && Array.isArray(result.results)) {
+        for (let i = 0; i < result.results.length; i++) {
+          const r = result.results[i]
+          const overrides = Array.isArray(args.runs?.[i]?.overrides) ? args.runs[i].overrides : []
+          if (r && r.promptId) {
+            recordRun(r.promptId, overrides, r.nodeErrors ? 'error' : 'queued')
+          }
+        }
+      }
+      return result
     },
   }))
 
@@ -404,17 +594,25 @@ export function apply(ctx) {
     name: 'comfyui_get_outputs',
     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. ' +
+      'files (kind/filename/type/subfolder/URL), and downloads them into downloadDir — or the project directory ' +
+      '(Settings → 项目目录, default <workspace>/projects) when downloadDir is omitted. With outputStem, files are ' +
+      'saved as <stem>.<NN>.<ext> with an auto-incrementing number so sweep runs never overwrite each other; ' +
+      'each download also appends the run trace (promptId/overrides/timestamp/files) to runs.json. ' +
       '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 output files into. Omit to return URLs only.' },
+      downloadDir: { type: 'string', description: 'Optional absolute local directory to save the output files into. Defaults to the project directory when omitted.' },
+      outputStem: { type: 'string', description: 'Optional filename stem; files are saved as <stem>.<NN>.<ext> (NN auto-increments, never overwrites).' },
     },
     output: { schema: { type: 'object', additionalProperties: true }, render: renderJSON },
     async execute(args, exec) {
       const base = baseUrl()
       const pid = encodeURIComponent(args.promptId)
-      const res = await fetch(`${base}/history/${pid}`, { signal: exec.signal })
+      // Timeout the history read so a hung ComfyUI endpoint can't strand the
+      // agent forever; keep exec.signal (agent cancel) in the same signal.
+      const res = await fetch(`${base}/history/${pid}`, {
+        signal: AbortSignal.any([exec.signal, AbortSignal.timeout(15000)]),
+      })
       if (!res.ok) throw new Error(`history HTTP ${res.status}`)
       const history = await res.json()
       const item = history?.[args.promptId]
@@ -446,19 +644,80 @@ export function apply(ctx) {
           }
         }
       }
+      // v0.1.3: downloads land in downloadDir, or the project directory
+      // (explicit setting, defaulting to <workspace>/projects). outputStem
+      // renames to <stem>.<NN>.<ext> so sweep runs never overwrite; the run
+      // ledger (promptId/overrides/timestamp from comfyui_run/batch_run) is
+      // appended to runs.json for traceability.
       let downloaded = []
-      if (args.downloadDir && files.length > 0) {
+      let runsFile = null
+      const targetDir = args.downloadDir || resolveProjectDir()
+      if (targetDir && files.length > 0) {
         const fs = await import('node:fs')
         const path = await import('node:path')
-        fs.mkdirSync(args.downloadDir, { recursive: true })
+        fs.mkdirSync(targetDir, { recursive: true })
+        // next NN for outputStem: scan existing <stem>.<NN>.<ext> in targetDir
+        const stem = (args.outputStem || '').trim()
+        let nextNum = 1
+        if (stem) {
+          const stemPrefix = stem + '.'
+          const nums = []
+          try {
+            for (const name of fs.readdirSync(targetDir)) {
+              if (!name.startsWith(stemPrefix)) continue
+              const rest = name.slice(stemPrefix.length)
+              const dot = rest.indexOf('.')
+              if (dot <= 0) continue
+              const numStr = rest.slice(0, dot)
+              if (/^\d+$/.test(numStr)) nums.push(Number(numStr))
+            }
+          } catch { /* dir may not exist yet */ }
+          if (nums.length > 0) nextNum = Math.max(...nums) + 1
+        }
+        const savedNames = []
         for (const f of files) {
-          const resp = await fetch(f.url, { signal: exec.signal })
+          const resp = await fetch(f.url, {
+            signal: AbortSignal.any([exec.signal, AbortSignal.timeout(30000)]),
+          })
           if (!resp.ok) throw new Error(`download ${f.filename} HTTP ${resp.status}`)
           const buf = Buffer.from(await resp.arrayBuffer())
-          const local = path.join(args.downloadDir, f.filename)
+          const ext = path.extname(f.filename) || '.bin'
+          const localName = stem
+            ? `${stem}.${String(nextNum).padStart(2, '0')}${ext}`
+            : f.filename
+          if (stem) nextNum++
+          const local = path.join(targetDir, localName)
           fs.writeFileSync(local, buf)
-          downloaded.push({ ...f, local })
+          downloaded.push({ ...f, local, localName })
+          savedNames.push(localName)
         }
+        // append this run's trace to runs.json (create if missing). Dedup by
+        // promptId: re-downloading the same run updates its entry instead of
+        // appending a duplicate; `run` numbers continue from the max seen.
+        const ledger = runLedger.get(String(args.promptId)) || {}
+        const runsPath = path.join(targetDir, 'runs.json')
+        let runs = []
+        try {
+          if (fs.existsSync(runsPath)) runs = JSON.parse(fs.readFileSync(runsPath, 'utf8'))
+          if (!Array.isArray(runs)) runs = []
+        } catch { runs = [] }
+        const existing = runs.findIndex((r) => r && r.promptId === args.promptId)
+        // Prefer the run's FINAL history status ('success'/'error') over the
+        // ledger's provisional 'queued' — the ledger is written at submit time,
+        // history reflects what actually happened.
+        const finalStatus = item.status?.status_str || ledger.status || 'success'
+        const entry = {
+          run: existing >= 0 ? runs[existing].run : (runs.reduce((m, r) => Math.max(m, r?.run || 0), 0) + 1),
+          promptId: args.promptId,
+          overrides: Array.isArray(ledger.overrides) ? ledger.overrides : [],
+          timestamp: ledger.timestamp || new Date().toISOString(),
+          status: finalStatus,
+          files: savedNames,
+        }
+        if (existing >= 0) runs[existing] = entry
+        else runs.push(entry)
+        fs.writeFileSync(runsPath, JSON.stringify(runs, null, 2))
+        runsFile = runsPath
       }
       return {
         promptId: args.promptId,
@@ -468,6 +727,10 @@ export function apply(ctx) {
         nodeCount: Object.keys(outputs).length,
         outputs: files,
         downloaded,
+        runsFile,
+        // P1: structured execution error when the run failed on a node, so the
+        // agent can name the failing node/exception instead of reading raw JSON.
+        executionError: extractExecutionError(item),
       }
     },
   }))
@@ -543,47 +806,21 @@ export function apply(ctx) {
       // 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.
+      // Shared probe (also used by the settings watcher) answers it.
       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)}`
-      }
+      const probe = await probeBridgeAuth(baseUrl(), token)
       return {
         baseUrl: baseUrl(),
         activeView,
         activeViewKnown,
         sessionSource,
         bridgeTokenSet: Boolean(token),
-        bridgeAuthEffective,
-        bridgeAuthProbe,
+        bridgeAuthEffective: probe.bridgeAuthEffective,
+        bridgeAuthProbe: probe.bridgeAuthProbe,
+        checkedAt: probe.checkedAt,
         comfyuiDir: value?.comfyuiDir || '',
         launchCommand: value?.launchCommand || '',
+        projectDir: resolveProjectDir(),
       }
     },
   }))
@@ -692,10 +929,11 @@ export function apply(ctx) {
   // Load node (LoadImage→image, LoadAudio→audio, LoadVideo→video, 3D→mesh…).
   ctx.tools.register(defineTool({
     name: 'comfyui_attach_file',
-    description: 'Upload a local file (image/audio/video/3D) into ComfyUI\'s input/ directory and optionally ' +
+    description: 'Upload a local file (image/audio/video/3D/text) into ComfyUI\'s input/ directory and optionally ' +
       'point a Load node at it. Uses ComfyUI\'s native upload endpoint (not the bridge); the source file is read ' +
-      'from the agent\'s own machine. mediaType is inferred from the extension when omitted. After upload, pass ' +
-      'nodeId (and widgetKey for non-image loads) to update the Load node so it takes effect immediately.',
+      'from the agent\'s own machine. mediaType is inferred from the extension when omitted (incl. text/prompts: ' +
+      'txt/md/json/csv/yaml/srt). After upload, pass nodeId (and widgetKey for non-image loads) to update the ' +
+      'Load node so it takes effect immediately.',
     parameters: {
       path: { type: 'string', required: true, description: 'Absolute local path to the file.' },
       mediaType: { type: 'string', description: 'Optional explicit media type (e.g. video/mp4, audio/wav, model/gltf-binary); defaults to a per-extension guess.' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-comfyui-canvas",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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",