dsh-comfyui-canvas 0.1.3 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +18 -15
- package/README.zh.md +14 -10
- package/docs/NEXT-VERSION-PLAN.md +10 -13
- package/docs/PLAN-v0.1.4.md +199 -0
- package/docs/screenshots/02-workflow-dunhuang.png +0 -0
- package/docs/screenshots/04-gallery.png +0 -0
- package/docs/screenshots/05-batch-portraits.png +0 -0
- package/docs/screenshots/06-template-library.png +0 -0
- package/lib/client.js +609 -362
- package/lib/index.js +223 -76
- package/lib/utils.js +99 -0
- package/package.json +3 -2
- package/screenshots.json +6 -3
- package/docs/screenshots/01-startup-prompt.png +0 -0
- /package/docs/screenshots/{02-canvas-ready.png → 01-split-canvas-chat.png} +0 -0
- /package/docs/screenshots/{03-workflow-output.png → 03-output-grid.png} +0 -0
package/README.md
CHANGED
|
@@ -3,15 +3,18 @@
|
|
|
3
3
|
> [中文](README.zh.md) · English
|
|
4
4
|
|
|
5
5
|
[](LICENSE)
|
|
6
|
-
[](https://github.com/wbin0001/dsh-comfyui-canvas/releases)
|
|
7
7
|
[](https://github.com/wbin0001/dsh-comfyui-canvas)
|
|
8
|
-
[](https://github.com/DeepSeek-Harness/DSH)
|
|
9
9
|
[](https://github.com/comfyanonymous/ComfyUI)
|
|
10
10
|
[](docs/architecture.html)
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
> **✅ DSH version compatibility (since v0.1.4)**: the split-screen layout is **fully self-contained** in the plugin — it uses only official DSH slots (`conversation.session.header.utilities`) and DOM `data-*` anchors, with **zero core modifications**. Works on any official DSH **v0.1.x** (including v0.1.2+ with the breaking client refresh) without patches. The earlier split-rail implementation depended on private core patches; v0.1.4 removes that dependency entirely.
|
|
13
|
+
> - ❌ **Non-official desktop wrappers** (e.g. the community `dsh-desktop`) are not guaranteed compatible — they bundle an upstream version that may be ahead of or behind this plugin's baseline; rely on official DSH.
|
|
13
14
|
|
|
14
|
-
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
**From chat to canvas to artwork — drive ComfyUI as a visual workflow IDE inside DSH.** Embed **ComfyUI** (local or cloud) as a split-screen canvas in [DeepSeek Harness](https://github.com/DeepSeek-Harness/DSH) Web: the agent sparks ideas, writes prompts and scripts right in the chat, applies them live to the canvas in front of you, and produces images, music, video, and 3D. From idea to finished output without ever leaving the conversation or switching front-ends:
|
|
15
18
|
|
|
16
19
|
- **Canvas ops** — compose and arrange pipelines, read/write workflows, edit nodes, wire links, run, tune parameters, and debug errors, all live and WYSIWYG on the exact canvas you are looking at
|
|
17
20
|
- **Production tasks** — batch parameter sweeps (`batch_run`) and automatic output-image retrieval back into the chat (`get_outputs`), powering multi-modal creative and batch generation across images, music, video, and 3D
|
|
@@ -25,17 +28,17 @@ This package is the DSH-side plugin, and it ships the ComfyUI-side bridge node t
|
|
|
25
28
|
|
|
26
29
|
| Surface | Description |
|
|
27
30
|
|---|---|
|
|
28
|
-
| **ComfyUI canvas
|
|
31
|
+
| **ComfyUI canvas split** | Clicking the **ComfyUI** button in the session header drops you straight into **canvas-on-the-left + chat-rail-on-the-right** split mode — the canvas embeds the ComfyUI frontend (local or cloud) alongside the official conversation rail, so you can chat with the agent while watching it drive the canvas. The iframe stays alive (no reload); click the button again to exit split. |
|
|
29
32
|
| **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`. |
|
|
30
33
|
| **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. |
|
|
31
34
|
| **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. |
|
|
32
|
-
| **Projects & traceability** | Downloads default to the project directory (Settings →
|
|
35
|
+
| **Projects & traceability** | Downloads default to the project directory (Settings → Project directory, default `<workspace>/projects`); every downloaded run appends `runs.json` (promptId / overrides / timestamp / files) so any output can be traced back to its parameters. Failed runs return a structured `executionError` (node id / node type / exception / message) instead of a raw JSON wall. |
|
|
33
36
|
| **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. |
|
|
34
37
|
| **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`). |
|
|
35
38
|
| **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. |
|
|
36
|
-
| **Canvas focus mode** | The agent can tell (via `comfyui_config`) whether
|
|
37
|
-
| **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. |
|
|
38
|
-
| **
|
|
39
|
+
| **Canvas focus mode** | The agent can tell (via `comfyui_config`) whether canvas split mode is active for the current session, and focus on canvas work only then. Session-isolated. |
|
|
40
|
+
| **Settings page** | ComfyUI base URL / port / network mode / bridge token / launch command / project directory / rail width. Changes apply live. Shows the plugin version and supports check / one-click update (installs the latest npm release; a DSH restart is required). Customized nav icon with ComfyUI logo. |
|
|
41
|
+
| **Split layout** | The **ComfyUI** button in the session header opens canvas-on-the-left + official chat rail on the right (state is session-isolated). Only data-* anchors and CSS variables are used — no DSH core class names, so the layout survives upstream styling changes. |
|
|
39
42
|
|
|
40
43
|
## Install
|
|
41
44
|
|
|
@@ -92,13 +95,13 @@ Then restart ComfyUI and load the canvas page once (the injected `bridge.js` rep
|
|
|
92
95
|
|
|
93
96
|
### 3. Configure
|
|
94
97
|
|
|
95
|
-
Open **Settings → ComfyUI
|
|
98
|
+
Open **Settings → ComfyUI Canvas** and set the ComfyUI base URL (default `http://127.0.0.1:8188`), port, network mode, optional bridge token, launch command, and the right-side rail width.
|
|
96
99
|
|
|
97
100
|
The **launch command** differs by platform:
|
|
98
101
|
|
|
99
102
|
| Platform | Example |
|
|
100
103
|
|---|---|
|
|
101
|
-
| Windows | `ComfyUI启动器.bat` (or `python main.py`) |
|
|
104
|
+
| Windows | `ComfyUI启动器.bat` (the launcher script; or `python main.py`) |
|
|
102
105
|
| macOS | `python main.py` or `./start.sh` |
|
|
103
106
|
| Linux | `python main.py` or `./start.sh` |
|
|
104
107
|
|
|
@@ -108,7 +111,7 @@ The bridge (`/dsh-bridge/*`) is the only network surface this plugin adds to Com
|
|
|
108
111
|
|
|
109
112
|
- **Trust model.** By default the bridge is unauthenticated, matching ComfyUI's own `/prompt` trust model — anyone who can reach the ComfyUI port can read the canvas, report state, and dispatch commands (`load_workflow`/`run` consume GPU). Commands are whitelisted on the frontend, so no arbitrary code execution is possible, but the surface is real.
|
|
110
113
|
- **Bind to loopback.** Keep ComfyUI on `127.0.0.1` unless you explicitly need LAN/cloud access. `networkMode` is informational; the actual bind is whatever ComfyUI was launched with (`--listen`).
|
|
111
|
-
- **Optional shared token.** Set a token in **Settings → ComfyUI
|
|
114
|
+
- **Optional shared token.** Set a token in **Settings → ComfyUI Canvas → Bridge Token** AND launch ComfyUI with the same value in its own environment (`DSH_BRIDGE_TOKEN=...`). When the token is set, every agent-initiated request — reading the canvas, dispatching a command, polling its result — must present `Authorization: Bearer <token>`; the host side sends it automatically and the bridge rejects requests without it. The frontend's own status reporting (`/report`, result callbacks) stays open, since the injected page cannot hold the token; those endpoints only mutate the in-memory snapshot and never dispatch execution. Leave it empty on both sides for the default open behavior.
|
|
112
115
|
- **Multiple tabs are safe.** Commands are targeted at the last-reporting frontend (`clientId`), so several open ComfyUI tabs do not each execute a command.
|
|
113
116
|
|
|
114
117
|
## Platform support
|
|
@@ -117,8 +120,8 @@ Works on **Windows**, **macOS** and **Linux**. The agent tools talk to ComfyUI o
|
|
|
117
120
|
|
|
118
121
|
## Usage
|
|
119
122
|
|
|
120
|
-
1. Open a conversation
|
|
121
|
-
2. Ask the agent to do canvas work: *"
|
|
123
|
+
1. Open a conversation and click the **ComfyUI** button in the session header — the canvas appears on the left with the Chat rail (messages + input) on the right, so you can instruct the agent while watching it work the canvas. Click the button again to exit split mode.
|
|
124
|
+
2. Ask the agent to do canvas work: *"read the current workflow"*, *"set KSampler seed to 42"*, *"check the canvas for errors"*, *"run it"*.
|
|
122
125
|
3. The agent reads `comfyui_config` first, so it knows it's on the canvas and stays focused on canvas operations.
|
|
123
126
|
|
|
124
127
|
### Conversation → canvas
|
|
@@ -178,7 +181,7 @@ dsh-comfyui-canvas/
|
|
|
178
181
|
│ └── entry/bridge.js # injected frontend: reports graph + runs commands
|
|
179
182
|
├── lib/
|
|
180
183
|
│ ├── index.js # DSH host: 19 canvas tools + 4 built-in skills
|
|
181
|
-
│ └── client.js # DSH web: canvas
|
|
184
|
+
│ └── client.js # DSH web: split canvas (left) + chat rail (right) / settings
|
|
182
185
|
├── LICENSE
|
|
183
186
|
├── README.md
|
|
184
187
|
└── package.json
|
package/README.zh.md
CHANGED
|
@@ -3,15 +3,18 @@
|
|
|
3
3
|
> 中文 · [English](README.md)
|
|
4
4
|
|
|
5
5
|
[](LICENSE)
|
|
6
|
-
[](https://github.com/wbin0001/dsh-comfyui-canvas/releases)
|
|
7
7
|
[](https://github.com/wbin0001/dsh-comfyui-canvas)
|
|
8
|
-
[](https://github.com/DeepSeek-Harness/DSH)
|
|
9
9
|
[](https://github.com/comfyanonymous/ComfyUI)
|
|
10
10
|
[](docs/architecture.html)
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
> **✅ DSH 版本兼容（v0.1.4 起）**：分屏布局已完全**自包含**在插件内——只用官方 DSH 插槽（`conversation.session.header.utilities`）与 DOM `data-*` 锚点，**零核心改动**。任何官方 DSH **v0.1.x**（含带破坏性 client 更新的 v0.1.2+）都开箱即用、无需补丁。此前分屏 rail 依赖 DSH 私有核心补丁，v0.1.4 已彻底移除该依赖。
|
|
13
|
+
> - ❌ **非官方桌面封装**（如 `dsh-desktop` 社区版）不保证兼容——它内部跑的上游版本可能超前/滞后于本插件基线，请以官方 DSH 为准。
|
|
13
14
|
|
|
14
|
-
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
**从对话到画布再到作品——DSH 里驾驭 ComfyUI 的可视化工作流 IDE。** 把 **ComfyUI**（本地或云端）以画布分屏嵌入 [DeepSeek Harness](https://github.com/DeepSeek-Harness/DSH) Web，agent 在对话里激发创意、书写提示词与脚本，实时落到你眼前的画布上，产出图像、音乐、视频、3D。从灵感到成品，全程不离开对话，不用切换任何前端工具：
|
|
15
18
|
|
|
16
19
|
- **画布操作**：搭建编排、读写工作流、修改节点、连线、运行、调整参数、工作流查错——所见即所得，实时落在你眼前的画布上
|
|
17
20
|
- **生产任务**：批量扫参（`batch_run`）、自动取回出图（`get_outputs`）带回对话，实现图像、音乐、视频、3D 等多任务智能创作与批量生产
|
|
@@ -25,7 +28,8 @@
|
|
|
25
28
|
|
|
26
29
|
| 能力 | 说明 |
|
|
27
30
|
|---|---|
|
|
28
|
-
|
|
|
31
|
+
| **画布分屏入口** | 点会话标头右侧的 **ComfyUI** 按钮进入**画布左 + 对话 rail 右**的分屏形态——画布内嵌 ComfyUI 前端（本地/云端），右侧是官方对话 rail，边看画布边发消息让 agent 操控。iframe 常驻不重载，再点按钮即关闭分屏。 |
|
|
32
|
+
| **分屏布局（自包含）** | ComfyUI 按钮 = 画布左 + 对话右，状态按会话隔离。只用官方插槽（`conversation.session.header.utilities`）+ DOM `data-*` 锚点与 CSS 变量，**零核心改动**，上游样式变化也不受影响。 |
|
|
29
33
|
| **可视化画布副驾** | agent 操作**你正在看的画布**——节点出现、连线接上、参数变化、运行触发，全部实时显示在屏幕上，每一步都看得见，而不是黑盒改 JSON。出图经 `comfyui_get_outputs` 直接带回对话。 |
|
|
30
34
|
| **画布操作工具** | `comfyui_read_workflow` / `add_node` / `connect` / `set_param` / `remove_node` / `inject_text` / `load_workflow` / `run` / `debug`——在活画布上搭建与修复工作流；`inject_text` 把对话文本一步注入为可连线节点。 |
|
|
31
35
|
| **生产工具** | `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 无人值守批量。 |
|
|
@@ -33,10 +37,10 @@
|
|
|
33
37
|
| **技能包（SOP）** | 内置技能教 agent 按正确顺序操作：`comfyui-canvas-ops`（读→确认→改→跑→取回→自检）、`comfyui-admin-ops`（配置/启动/升级/节点管理）、`comfyui-video-audio-ops`（视频+配音/音轨）、`comfyui-dev-ops`（开发/调试自定义节点）。装插件即自带技能，无需额外配置。 |
|
|
34
38
|
| **维护工具** | `comfyui_upgrade` 一键升级 ComfyUI 核心与全部 git 自定义节点（并发、跳过本地改过的仓库）；`comfyui_config` 报告当前连接、画布专注状态、项目目录，以及**桥接鉴权握手检查**（`bridgeAuthEffective`）。 |
|
|
35
39
|
| **节点开发工具** | `comfyui_read_source` / `comfyui_edit_source` / `comfyui_reload`——对话里直接读写 `custom_nodes/` 下的节点源码并重启 ComfyUI，再到画布上验证。 |
|
|
36
|
-
| **画布专注模式（会话隔离）** | agent 通过 `comfyui_config`
|
|
40
|
+
| **画布专注模式（会话隔离）** | agent 通过 `comfyui_config` 感知当前会话是否开启画布分屏，只在画布场景专注画布操作，且**按会话隔离**——多个会话互不干扰。 |
|
|
37
41
|
| **ComfyUI 报错处理** | `debug` 校验工作流并高亮报错节点（纯校验，不触发执行），agent 帮你定位/修复画布错误。 |
|
|
38
|
-
| **设置页** | ComfyUI 地址 / 端口 / 网络模式 / 桥接 Token / 启动命令 / 项目目录 /
|
|
39
|
-
|
|
|
42
|
+
| **设置页** | ComfyUI 地址 / 端口 / 网络模式 / 桥接 Token / 启动命令 / 项目目录 / 右侧面板宽度，实时生效；显示插件版本号并支持检查 / 一键更新（更新到 npm 最新版后需重启 DSH）。导航栏已自定义为 ComfyUI logo 图标。 |
|
|
43
|
+
| **对话栏** | 分屏 rail 复用官方完整对话（消息、输入、发送、贴图、授权弹窗全在），不再需要插件自绘迷你输入框与授权 overlay。 |
|
|
40
44
|
|
|
41
45
|
---
|
|
42
46
|
|
|
@@ -126,7 +130,7 @@ cp -r $(npm root -g)/dsh-comfyui-canvas/comfyui-bridge/ComfyUI-DSH-Canvas <Comfy
|
|
|
126
130
|
|
|
127
131
|
## 使用
|
|
128
132
|
|
|
129
|
-
1.
|
|
133
|
+
1. 打开一个会话，点会话标头右侧的 **ComfyUI** 按钮——进入**画布左 + 对话 rail 右**的分屏形态（再点一次即关闭分屏，回到纯对话）。
|
|
130
134
|
2. 直接让 agent 干画布活：
|
|
131
135
|
- *“读取当前工作流”*
|
|
132
136
|
- *“给 KSampler 设 seed 为 42”*
|
|
@@ -197,7 +201,7 @@ dsh-comfyui-canvas/
|
|
|
197
201
|
│ └── entry/bridge.js # 注入画布前端：上报画布 + 执行命令
|
|
198
202
|
├── lib/
|
|
199
203
|
│ ├── index.js # DSH host：15 个画布工具 + 会话隔离模式
|
|
200
|
-
│ └── client.js # DSH web
|
|
204
|
+
│ └── client.js # DSH web：分屏画布（画布左+对话右）/ 设置页
|
|
201
205
|
├── LICENSE
|
|
202
206
|
├── README.md
|
|
203
207
|
├── README.zh.md # 本文档
|
|
@@ -1,19 +1,16 @@
|
|
|
1
1
|
# dsh-comfyui-canvas — 下个版本开发规划（v0.1.1）
|
|
2
2
|
|
|
3
3
|
> **本文档是「新会话接手说明书」**：下个版本开发请新开一个会话，先读本文件 + `docs/architecture.html`（分层架构）+ `docs/architecture-flow.html`（流程图），即可接续全部开发意图。
|
|
4
|
-
> 最后更新：2026-09-
|
|
5
|
-
|
|
6
|
-
>
|
|
7
|
-
> -
|
|
8
|
-
> -
|
|
9
|
-
>
|
|
10
|
-
> -
|
|
11
|
-
> -
|
|
12
|
-
>
|
|
13
|
-
> -
|
|
14
|
-
> - 修复：① `lib/index.js` 启动时显式传 `sandboxPolicy: { mode: 'danger-full-access', workspaceRoot }`（外部服务启动不受工作区沙箱限制），并把启动失败写入新增的 `launchError` 配置字段；② `lib/client.js` 启动卡片读取并展示 `launchError`，加 45s 启动超时（超时未在线则复位"正在启动…"允许重试）
|
|
15
|
-
> - 已同步：源码 → node_modules 副本；**需重启 DSH（host 改动生效）+ 刷新页面（client 改动生效）**
|
|
16
|
-
> - 涉及文件：`lib/client.js` + `lib/index.js` + `comfyui-bridge/ComfyUI-DSH-Canvas/entry/bridge.js`（本仓库）+ DSH 核心 `packages/client/ui-settings-general`（navIcon 映射，不在本仓库 git 内）
|
|
4
|
+
> 最后更新：2026-09-03
|
|
5
|
+
|
|
6
|
+
> **最新状态备忘（2026-09-03，v0.1.3 已发布版之后）**：
|
|
7
|
+
> - ✅ **v0.1.3 已发布**（npm `dsh-comfyui-canvas@0.1.3` + GitHub Release v0.1.3）：项目目录 / `.runs.json` 溯源 / `outputStem` NN 命名 / 失败结构化诊断 / 文本·提示词上传 / 鉴权告警；A3（画布「+文件」按钮）已砍。
|
|
8
|
+
> - ✅ **测试 + CI 已补**：`lib/utils.js` 抽取纯逻辑（mediaTypeOf / extractExecutionError / nextStemNumber / upsertRun），`test/utils.test.js` 16 个用例（`node:test`，`npm test`），`.github/workflows/test.yml`（check + test + pack，GitHub Actions 已验证绿）。
|
|
9
|
+
> - ⚠️ **待办（v0.1.4）：适配官方上游破坏性更新** ——
|
|
10
|
+
> - 现象：DSH Desktop v2.0.4（社区封装版 anywhere-labs/dsh-desktop，内部跑上游 **v0.1.2-alpha.1**）用户反映「装插件后右侧面板不显示」。
|
|
11
|
+
> - 根因：插件 client 基于官方 **v0.1.1-rc.2** 开发（`conversation.view` 注入 / splitRail 分屏 / client module 契约），上游 v0.1.2 系列有**破坏性更新**（官方 release note 自述"会导致很多插件不可用"）→ 分屏视图挂不上，只剩全屏 ComfyUI 标签。
|
|
12
|
+
> - 计划：把本地 DSH 从 `0.1.1-rc.2` 升到官方最新 **`v0.1.2-rc.1`**，在最新上游上验证并修复插件兼容性，发 v0.1.4；同时解决 DSH Desktop 用户兼容。
|
|
13
|
+
> - 事实记录：DSH Desktop ≠ 官方产品（社区封装，Electron 套壳，官方 Web UI 原样加载）；其 v2.x 是桌面壳自己的版本号，上游仍跟随 0.1.x。
|
|
17
14
|
|
|
18
15
|
---
|
|
19
16
|
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
# dsh-comfyui-canvas v0.1.4 方案
|
|
2
|
+
|
|
3
|
+
> **本文档是新会话接手说明书**：开发请新开会话，先读本文件 + `docs/NEXT-VERSION-PLAN.md`（接手说明）+ `docs/PLAN-v0.1.3.md`（上一版方案）。
|
|
4
|
+
> 状态：**已定稿**（2026-09-03；根因已重新定位，方向从「适配 v0.1.2」修正为「分屏能力插件自包含」）
|
|
5
|
+
> 2026-09-04 更新：**并入《SPLIT-LAYOUT-ZERO-DIFF-PLAN.md》实现细节**——明确 rail 聊天内容的来源（覆盖层挤压方案），并把「必须在原生核心上开发/验证」定为执行前提。原独立文档已合并删除。
|
|
6
|
+
> 范围：**只列与本插件有关的处理事项**（DSH 核心的无关本地定制不在本版处理范围）
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## 1. 一句话目标
|
|
11
|
+
|
|
12
|
+
**把「画布 + 对话 rail 分屏」从 DSH 核心私有补丁依赖中解放出来，改成插件自包含渲染**——让插件在任何干净官方 DSH（0.1.1 / 0.1.2）上开箱即用，同时解决 DSH Desktop 用户「右侧面板不显示」的问题。
|
|
13
|
+
|
|
14
|
+
**实现形态**：不切视图、不建插件自绘聊天——**chat 保持激活（核心渲染完整聊天 + composer），画布以覆盖层形式贴左侧，对话区用 CSS 从右侧挤压**。聊天内容 100% 来自核心，插件只负责画布覆盖层与布局挤压。
|
|
15
|
+
|
|
16
|
+
## 2. 根因（已重新定位，必读）
|
|
17
|
+
|
|
18
|
+
### 2.1 现象
|
|
19
|
+
- DSH Desktop v2.0.4（社区封装，上游 v0.1.2-alpha.1）用户反映：「装插件后右侧面板不显示」——只剩全屏 ComfyUI 标签，没有右侧对话 rail。
|
|
20
|
+
|
|
21
|
+
### 2.2 真正根因（非 v0.1.2 破坏性更新）
|
|
22
|
+
- 插件 `lib/client.js` **大量直接依赖 DSH 核心的 splitRail 结构**：
|
|
23
|
+
- `document.querySelectorAll('[class*="splitRail"]')`（rail 宽度）
|
|
24
|
+
- `[class*="splitRailComposer"]` / `[class*="splitRailInputWrap"]` 等 CSS（rail 编辑器样式）
|
|
25
|
+
- `ctx.slots.inject("conversation.view")` + plugin-declared split-screen（meta passthrough）
|
|
26
|
+
- 这些 splitRail 类名与 split-screen 通道**只存在于本地 DSH 的三个私有补丁**（`3926146` / `31131ffc` / `aa6c600`，已在 0.1.2-rc.1 上重 port 为 `90e8271363` / `b4436075da`），**官方任何版本都没有**。
|
|
27
|
+
- 因此：**任何装干净官方 DSH 的用户，右侧 rail 天生不存在**，与版本号无关。本地正常只是因为本机 DSH 打了私有补丁。
|
|
28
|
+
|
|
29
|
+
### 2.3 关键判断
|
|
30
|
+
- 「导航图标」已做非侵入式（插件自绘），**分屏 rail 是另一套核心依赖，从未处理**。
|
|
31
|
+
- v0.1.4 的目标 = 把导航图标那套「插件自包含」思路复制到分屏 rail 上。
|
|
32
|
+
|
|
33
|
+
### 2.4 为什么分屏必须由插件接管（单活视图约束，必读）
|
|
34
|
+
|
|
35
|
+
0.1.2-rc.1 官方（无补丁）契约下，插件**无法**让核心同时渲染画布与聊天，原因有三：
|
|
36
|
+
|
|
37
|
+
1. **`conversation.view` 是单活 list 槽**：`ConversationSession` 只渲染 `renderSlot('conversation.view', props, { only: active.id })`（`skeleton/ConversationSession.tsx` 第 302 行）——画布激活时 chat 根本不在 DOM 里。补丁的 split 分支（同时渲染 active + `{ only: 'chat' }`）是核心内部能力，官方没有。
|
|
38
|
+
2. **插件拿不到 chat 视图的渲染**：`chat` 条目由独立包 `ui-chat` 注册（`ui-chat/src/client/apply.ts` 第 94~105 行），带自己的 store / children（`conversation.chat.node`、`conversation.message.images`）/ 注入面。槽条目组件收到的是 `PropsRuntime<'conversation.view'>`——**没有 PropsRenderSlots**；client 规则也禁止 feature 插件 import 另一 feature 插件的值。组件内无法再渲染 chat。
|
|
39
|
+
3. **meta 透传不存在**：`StoredEntry.options.meta` 是补丁加的，官方 `register({ meta: {...} })` 静默丢失。
|
|
40
|
+
|
|
41
|
+
> 推论：**「画布 + 聊天并排」在官方核心上只有一条路——不切换视图，让 chat 保持激活，画布覆盖层贴左，对话区 CSS 右移。** 这就是本版方案。
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## 3. 本版处理事项（只列与插件有关的）
|
|
46
|
+
|
|
47
|
+
### 3.1 核心：分屏 rail 插件自包含（P0）
|
|
48
|
+
|
|
49
|
+
**现状盘点**：client.js 所有依赖核心 splitRail / split-screen 通道的位置：
|
|
50
|
+
|
|
51
|
+
| 位置（lib/client.js） | 依赖的补丁行为 | 官方核心上的下场 |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| `meta: { split: true }` 注册（约 L903） | ui-slots meta 透传 + `isSplitView` | meta 静默丢失 → 退回普通 tab |
|
|
54
|
+
| `[class*="splitRail"]`（`applyRailWidth`，L166-177） | 核心 split 分支渲染的 `aside.splitRail` | 无匹配 → rail 宽度失效 |
|
|
55
|
+
| `[class*="splitRailComposer"]` / `InputWrap` / `Send` 等样式（`injectRailComposerStyles`，L184-227） | splitRail 编辑器 DOM | 无匹配 → 样式失效 |
|
|
56
|
+
| `[class*="splitRailComposer"]`（`injectRailComposerPlus`，L234-327） | splitRail 图片区 | 无匹配 →「+」号失效 |
|
|
57
|
+
| `ComfyUIApprovalOverlay`（L397-479，挂载 L721-723） | 前提是「分屏下核心不渲染 composer 链」（补丁行为） | 官方下核心自有审批 → 双弹窗，**删除** |
|
|
58
|
+
|
|
59
|
+
**自包含方案（覆盖层挤压，主实现）**：
|
|
60
|
+
|
|
61
|
+
| 项 | 当前补丁方案（淘汰） | v0.1.4 方案 |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| 进入分屏 | ComfyUI view tab | header `utilities` 按钮（官方 0.1.2 原生插槽 `conversation.session.header.utilities`，`slots.ts` 第 111~115 行） |
|
|
64
|
+
| 画布 | 核心 splitStage | 插件 fixed iframe 覆盖层（复用现有 `buildCanvas`/`positionAt`），贴对话区左侧 |
|
|
65
|
+
| 聊天 | 核心 rail 里 `{ only: 'chat' }` | **核心正常渲染的完整 chat**（active 不切走）——含全部气泡、工具卡片、附件 |
|
|
66
|
+
| 输入 | 插件自绘迷你 composer | **核心完整 composer**：模型选择、计划、命令菜单、审批弹窗、附件拖放全保留 |
|
|
67
|
+
| 画布宽度 | railWidth 设置（已存在） | 同设置；覆盖层宽度 = 视口 − railWidth，对话列右移 railWidth |
|
|
68
|
+
| 审批弹窗 | 插件自绘 `ComfyUIApprovalOverlay` | 核心 composer 链自带 → **删除 overlay hack** |
|
|
69
|
+
|
|
70
|
+
**布局挤压的锚点**（全部是官方核心已存在的稳定设施，不改核心）：
|
|
71
|
+
|
|
72
|
+
| 锚点 | 位置 | 用途 |
|
|
73
|
+
|---|---|---|
|
|
74
|
+
| `data-conversation-scroll` | `ConversationRoot.tsx` 第 376 行 | 滚动容器；分屏时右移的目标盒 |
|
|
75
|
+
| `data-composer-seat` | 同上第 367 行 | composer 座；跟随 scrollBody 右移 |
|
|
76
|
+
| `data-phase` | 同上第 373 行 | `active/hero/settling`；只在 active 时挤压 |
|
|
77
|
+
| `--dsh-conversation-column-width` | `ConversationRoot` 第 189 行发布 | 对话列宽度；挤压后让核心宽度轴自适应 |
|
|
78
|
+
| `--dsh-composer-height` / `--dsh-conversation-viewport-height` | 第 170~174 行 | 浮动控制避让参数 |
|
|
79
|
+
| `conversation.session.header.utilities` | `slots.ts` 第 111~115 行，官方原生 | 分屏开关按钮的注册点（list 槽，空 owner，session 级） |
|
|
80
|
+
| `settings.section` / `settingsScope` | 插件已有 | rail 宽度、开关状态、会话隔离 map 的持久化 |
|
|
81
|
+
|
|
82
|
+
**会话隔离（保留现有机制）**：`activeViewBySession` 上报逻辑继续用，分屏开启/关闭时写 `settingsScope`，`comfyui_config` 工具仍能感知会话在画布专注模式。
|
|
83
|
+
|
|
84
|
+
### 3.2 配套：执行前提 —— 插件必须在原生核心上开发与验证（P0 前置，最重要）
|
|
85
|
+
|
|
86
|
+
**推论**：只要开发/验证环境的核心带补丁，写出的插件就必然依赖补丁行为（rail 可 hack、meta 可用、overlay 有存在理由）。因此「适配官方」不是重写完成后顺带验证的事，而是**整个开发过程的环境基线**。
|
|
87
|
+
|
|
88
|
+
**依赖度账本（哪些会写不出来）**：
|
|
89
|
+
|
|
90
|
+
| 依赖点 | 补丁核心（现状） | 官方核心 |
|
|
91
|
+
|---|---|---|
|
|
92
|
+
| `meta: { split: true }` | ui-slots 透传 + `isSplitView` 生效 | meta 静默丢失 → 退回普通 tab |
|
|
93
|
+
| `[class*="splitRail"]` 系列 | rail DOM 存在可 hack | 核心不渲染 rail，选择器全落空 |
|
|
94
|
+
| `ComfyUIApprovalOverlay` | 前提成立 | 前提消失、核心自带审批 → 双弹窗 |
|
|
95
|
+
|
|
96
|
+
**环境安排（二选一，动手时定）**：
|
|
97
|
+
|
|
98
|
+
- **A. 主仓库直接回滚核心（推荐）**：打标签/分支保留当前分屏可用态 → `git reset --hard 76fda72979`（远程官方 master）→ 按维护手册第二节步骤 5 重建 `lib/` + `build:web` → 之后插件的一切开发/验证都在官方核心上做。过渡期分屏退化为全屏画布 tab（0.1.1 时代行为），可接受则选此路。
|
|
99
|
+
- **B. 独立验证场 + 主仓保留现状**：`git worktree add <dir> 76fda72979` 建官方实例，插件改动先在验证场跑通再合回 `projects/`；主目录日常继续用分屏。代价是两份依赖/两套构建，且容易在补丁核心上顺手改坏。
|
|
100
|
+
|
|
101
|
+
两条路验收标准相同：**在未打任何补丁的 `76fda72979` 核心上，插件分屏全功能可用**。
|
|
102
|
+
|
|
103
|
+
### 3.3 插件侧改造清单（`projects/dsh-comfyui-canvas`，仅此一处）
|
|
104
|
+
|
|
105
|
+
- **a. 入口**：注册 `conversation.session.header.utilities`，渲染 ComfyUI 状态圆点 + 开/关按钮；状态存 `settingsScope`（`splitEnabledBySession` 沿用 `activeViewBySession` 的写裁剪手法）。
|
|
106
|
+
- **b. 布局挤压**：分屏开启时给 `[data-conversation-scroll]` / `[data-composer-seat]` 的祖先（按 `data-phase="active"` 选 root）加挤压，并设置 `--dsh-conversation-column-width`，让核心宽度轴整体收敛到右侧 railWidth 区间。用插件注入 `<style>` + MutationObserver（沿用 `injectRailComposerStyles` 手法），选择器只认 data 属性与 CSS 变量——**不认任何 hash 类名**。
|
|
107
|
+
- **c. 画布覆盖层**：`buildCanvas`/`positionAt` 改为「分屏模式下贴对话区 left:0、宽 = 视口−railWidth」；卸载时 `visibility:hidden`、iframe 文档常驻不变。
|
|
108
|
+
- **d. 删除**：`ComfyUIApprovalOverlay`、`injectRailComposerStyles`/`injectRailComposerPlus` 的 rail 专用 hack、全部 `[class*="splitRail"]` 选择器。
|
|
109
|
+
- **e. 保留**：`ComfyUIControl` 启动卡、桥接鉴权告警、设置页全部字段、`DEFAULT_RAIL` 语义、`activeBase` 配置同步、可达性探测。
|
|
110
|
+
|
|
111
|
+
### 3.4 核心补丁的处置
|
|
112
|
+
|
|
113
|
+
- 本地补丁提交（`90e8271363` + `b4436075da`，即旧三补丁的 0.1.2 port）**留在本地、不推送**，作为功能基线。
|
|
114
|
+
- 验收通过后回滚核心验证插件独立可跑（见 3.2 环境安排 A）；回滚后 `lib/` 按维护手册重建，snapshot 测试同步回原始期望。
|
|
115
|
+
|
|
116
|
+
### 3.5 配套：验证基座升级（P0 前置）
|
|
117
|
+
|
|
118
|
+
- 本地 DSH 升级 `0.1.1-rc.2` → `v0.1.2-rc.1`（官方正式候选版），作为自包含改造的验证环境（当前仓库已在 0.1.2-rc.1，见 2.2 补丁 port 记录）。
|
|
119
|
+
- 升级/回滚时丢弃 3 个 rail 本地补丁——插件自包含后不再需要；**与插件无关的本地定制（子代理目录等）不涉及、不保留判断**。
|
|
120
|
+
- 升级前确认 DSH 本体回退方案（git checkout 旧 tag + 重装依赖）。
|
|
121
|
+
|
|
122
|
+
### 3.6 版本声明更新（P1）
|
|
123
|
+
|
|
124
|
+
- README 中英：DSH 兼容声明从「v0.1.2+ 未适配」改为「v0.1.x 全系可用（分屏自包含）」+ DSH 徽章版本范围更新
|
|
125
|
+
- 版本号 `0.1.3` → `0.1.4`
|
|
126
|
+
|
|
127
|
+
### 3.7 质量保持（P1）
|
|
128
|
+
|
|
129
|
+
- `npm run check` + `npm test`（16 用例应原样保持绿——utils.js 与 client 改动无关）
|
|
130
|
+
- 三副本同步（源码 → node_modules → E 盘 bridge 如涉及）
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## 4. 验收（替换完成后，在官方核心上跑）
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
1. 启动 dsh web（官方核心源码），打开会话 → 点 header 分屏按钮
|
|
138
|
+
2. 左侧画布加载 ComfyUI，右侧完整聊天可见（历史消息、工具卡片）
|
|
139
|
+
3. 右侧 composer 完整：模型选择、计划入口、命令菜单、粘贴/拖入图片、发送
|
|
140
|
+
4. 工具请求越权 → 出现核心审批弹窗（不再有插件 overlay）
|
|
141
|
+
5. 折叠/展开 rail、拖动宽度、切会话 → 布局正确、宽度偏好保留
|
|
142
|
+
6. 窄视口（<1200px）→ 分屏自动退出或隐藏画布（别挤死聊天）
|
|
143
|
+
7. comfyui_config 工具读到的模式与会话隔离正确
|
|
144
|
+
8. 插件卸载/HMR 重载不残留全局样式、iframe 不重建
|
|
145
|
+
9. 普通视图/全部功能不因挤压 CSS 受影响
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## 5. 实施步骤
|
|
151
|
+
|
|
152
|
+
```
|
|
153
|
+
step 0 搭好「官方核心」开发环境（3.2 的 A 或 B）；确认回退方案
|
|
154
|
+
step 1 盘点 client.js 对核心 splitRail / split-screen 通道的全部依赖点（3.1 表已列，动手时复核行号）
|
|
155
|
+
step 2 client.js 覆盖层改造：header utilities 入口 + 画布覆盖层 + data-* 挤压 CSS（3.3 a/b/c）
|
|
156
|
+
step 3 删除 rail hack 与 overlay（3.3 d）；保留项核对（3.3 e）
|
|
157
|
+
step 4 验证（官方核心，按第 4 节验收 1-9 项）
|
|
158
|
+
step 5 npm run check + npm test（16 用例绿）→ 三副本同步
|
|
159
|
+
step 6 README 版本声明更新 + 版本号 0.1.4（3.6）
|
|
160
|
+
step 7 git commit → 推送 → npm publish → GitHub Release v0.1.4
|
|
161
|
+
step 8 cnb 镜像同步（平台流水线自动，或 @CodeBuddy 拉取更新）
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## 6. 风险与开放问题
|
|
167
|
+
|
|
168
|
+
- **挤压宽度轴的正确性**（最高风险）：核心宽度轴（`resolveContentWidth`、宽度手柄、`--dsh-chat-user-width` clamp）基于真实列宽计算。手动改 `--dsh-conversation-column-width` 可能与手柄/拖宽打架——实施时先浏览器实测拖宽 + 手柄位置，必要时只改 `margin-left` 不改变量（右移而不收窄，画布盖左侧空白）。两种策略都列进验收第 5、9 条。
|
|
169
|
+
- **交互模型变化**：分屏从 tab 变 header 按钮。若同时要「全屏画布 tab」与「分屏」，可在 `conversation.view` 注册普通 `comfyui-canvas` 条目（不带 meta，官方合法），tab = 全屏画布（0.1.1 时代行为）；分屏走 header 按钮。两入口并存不冲突，是否要 tab 入口需产品拍板。
|
|
170
|
+
- **iframe 与 DSH 的 z-index/遮挡**：现有覆盖层 z-index=40 与 overlay rail 的关系需重测（rail 删除后更简单）。
|
|
171
|
+
- **`data-phase` 选择器在 hero/settling 相位**：分屏按钮只在 active 相位可用（header 在非 blank 才渲染，天然满足）。
|
|
172
|
+
- **升级 DSH 本身是重操作**：影响整个开发环境；升级前确认回退方案（维护手册全套流程）。
|
|
173
|
+
- **上游 v0.1.2 其它 client 变更**：除分屏外，`conversation.view` / settings 契约如有变化一并适配（step 2 时核对）。
|
|
174
|
+
- **DSH Desktop 兼容**：自包含后不依赖上游结构，理论上官方与社区封装都可恢复；但社区版可能滞后/超前，仍不保证 100%。
|
|
175
|
+
- **升级姿态**：若上游未来把 `meta` 透传 / 多视图并排做成正式特性，本方案可无痛迁移回「核心声明式 split」，插件只删 hacks。
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## 7. 证据索引（2026-09-04 调查所读）
|
|
180
|
+
|
|
181
|
+
- `packages/client/ui-conversation/src/client/skeleton/ConversationSession.tsx`（单活视图 + 补丁 split 分支）
|
|
182
|
+
- `packages/client/ui-conversation/src/client/apply.ts`（viewTabs/激活/注入面）
|
|
183
|
+
- `packages/client/ui-conversation/src/client/contract/slots.ts`（`conversation.view` 声明、header utilities、ConvViewProps 无 render slots）
|
|
184
|
+
- `packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx`（data-* 锚点、宽度轴、composer seat）
|
|
185
|
+
- `packages/client/ui-slots/src/index.ts`（PropsRuntime 无 PropsRenderSlots、RenderOpts.only、meta 为补丁新增）
|
|
186
|
+
- `packages/client/ui-chat/src/client/apply.ts`（chat 条目、store、注入面、children）
|
|
187
|
+
- `packages/client/ui-layout/src/client/AppFrame.tsx`（固定三列）
|
|
188
|
+
- `projects/dsh-comfyui-canvas/lib/client.js`（现有覆盖层/rail hack/设置页）
|
|
189
|
+
|
|
190
|
+
---
|
|
191
|
+
|
|
192
|
+
## 8. 参考
|
|
193
|
+
|
|
194
|
+
- `docs/NEXT-VERSION-PLAN.md` 顶部备忘（2026-09-03）
|
|
195
|
+
- `docs/PLAN-v0.1.3.md`（v0.1.3 已交付）
|
|
196
|
+
- 本地 DSH 私有补丁：`3926146`（split-rail composer）/ `31131ffc`（plugin split-screen）/ `aa6c600`（rail 改名对齐）；0.1.2-rc.1 重 port：`90e8271363` / `b4436075da`
|
|
197
|
+
- 官方 DSH release：`dsh-v0.1.2-rc.1`（2026-09-03）
|
|
198
|
+
- cnb 镜像：`https://cnb.cool/Loxi009/dsh-comfyui-canvas`（定时同步流水线）
|
|
199
|
+
- 维护手册：`F:\Deepseek-harness\DSH依赖故障修复手册.md` 第二节（lib 重建）/ 第三节（插件更新）
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|