dsh-split-workspace 0.5.0 → 0.9.0
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 +324 -14
- package/lib/client.js +1286 -52
- package/lib/index.js +269 -6
- package/package.json +17 -5
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**中文(默认)** · [English](#english)
|
|
4
4
|
|
|
5
|
-
把 DeepSeek Harness 的对话区拆成原生多窗格工作区——左右分屏、上下分屏、田字 2×2 或自动网格,窗口放得下多少会话就开多少。每个窗格都是真实会话,拥有自己的输入框、流式输出、停止、队列、待办、附件、`/` 命令、`ask_user_question`、审批与视图页,桌面端(`dsh-app
|
|
5
|
+
把 DeepSeek Harness 的对话区拆成原生多窗格工作区——左右分屏、上下分屏、田字 2×2 或自动网格,窗口放得下多少会话就开多少。每个窗格都是真实会话,拥有自己的输入框、流式输出、停止、队列、待办、附件、`/` 命令、`ask_user_question`、审批与视图页,桌面端(`dsh-app://`)同样可用。还可以把任意会话变成可拖动、可缩放的**浮窗**,在分屏与浮窗两种模式之间来回切换。
|
|
6
6
|
|
|
7
7
|
## 快速开始
|
|
8
8
|
|
|
@@ -49,7 +49,7 @@ dsh --profile web
|
|
|
49
49
|
|
|
50
50
|
1. 打开 DSH Desktop,侧边栏 **插件市场**,搜索 `dsh-split-workspace` 并安装;或进入 **插件 → 添加插件 → 安装第三方插件**,填入包名。
|
|
51
51
|
2. 打开 **设置 → 插件**,启用 `dsh-split-workspace`。
|
|
52
|
-
3.
|
|
52
|
+
3. 安装完成后插件通常会被 DSH 的 HMR 立即加载,无需重启;如果几秒后侧边栏底部仍没有分屏图标,再完全退出并重开 DSH Desktop(插件加载后,菜单/更新提示也提供「重启 DSH」入口)。
|
|
53
53
|
|
|
54
54
|
> 桌面端的 `desktop` profile 由 Electron 应用独占管理。不要在终端执行 `dsh plugin --profile desktop add ...`,该命令会拒绝执行;桌面端请用上面的插件市场 / 添加插件界面。
|
|
55
55
|
|
|
@@ -59,15 +59,15 @@ dsh --profile web
|
|
|
59
59
|
2. DSH Desktop → **插件 → 添加插件 → 安装第三方插件**:
|
|
60
60
|
- 优先填 `.tgz` 的**绝对路径**(安装器会识别为「压缩包」);
|
|
61
61
|
- 如果当前版本只接受目录,先把 `.tgz` 解压,再填解压后的目录路径(目录根下要有 `package.json`)。
|
|
62
|
-
3. 在 **设置 → 插件**
|
|
62
|
+
3. 在 **设置 → 插件** 启用;通常会被 HMR 立即加载。若侧边栏底部没有出现分屏图标,完全退出并重开 DSH Desktop,或使用插件菜单里的「重启 DSH」。
|
|
63
63
|
4. 离线机器不需要网络;插件运行时不联网。
|
|
64
64
|
|
|
65
65
|
### 启用与验证
|
|
66
66
|
|
|
67
|
-
- 打开 **设置 → 插件**,确认 `dsh-split-workspace`
|
|
67
|
+
- 打开 **设置 → 插件**,确认 `dsh-split-workspace` 已启用。DSH 0.2.x 会通过 HMR 热加载新安装的插件;如果没有出现界面,见下方「更新、重载与重启」。
|
|
68
68
|
- 分屏入口:点击侧边栏底部(设置旁)的分屏图标,或把侧边栏里的会话拖到对话区。
|
|
69
69
|
- 打开浏览器/桌面端控制台执行 `window.__dshSplitWorkspace.health()`,可看到版本、窗格数和几何状态。
|
|
70
|
-
-
|
|
70
|
+
- 如果看不到分屏入口:确认插件已启用且没有报错;如果侧边栏底部的 footer 没有渲染,插件会在对话区左下角显示兜底的分屏按钮。
|
|
71
71
|
|
|
72
72
|
### 开始分屏
|
|
73
73
|
|
|
@@ -77,13 +77,80 @@ dsh --profile web
|
|
|
77
77
|
- 或者把侧边栏里的会话拖到对话区:放下的会话成为第二个窗格。
|
|
78
78
|
- 分屏后,把另一个会话拖到某个窗格即可替换;也可以用窗格标题栏的分屏按钮为新窗格选择会话。
|
|
79
79
|
- 拖动侧边栏会话经过窗格边缘时,窗格会预览放下后的布局,并用虚线占位标出即将加入的会话;松开即应用该布局。
|
|
80
|
-
- **重置分屏** 会清空本插件在 localStorage / sessionStorage
|
|
80
|
+
- **重置分屏** 会清空本插件在 localStorage / sessionStorage 里的分屏相关键、已保存布局、崩溃保护、最小化标记和窗格临时缓存(性能模式偏好会保留);当分屏因为缓存或异常状态怎么都起不来时,点它即可恢复到干净状态。
|
|
81
|
+
- 右键任意会话(或点行尾的「⋯」)→ **进入浮窗**,即可把该会话变成一个可自由摆放的浮窗;浮窗标题栏可以拖动、边缘可以缩放,点 **⇲ 回到分屏** 放回分屏,点 **✕** 直接关闭浮窗。同一会话不会同时出现在分屏和浮窗里:进入浮窗时会自动从分屏/待分屏中移出。
|
|
82
|
+
- 右键会话 → **在系统窗口打开**:在系统默认浏览器里打开一个只显示该会话的独立窗口,关闭 / 最小化 / 双击标题栏放大 / 全屏都由系统窗口原生提供。
|
|
83
|
+
- **关闭窗格(标题栏 ✕)或退出分屏时,只要剩余会话少于两个就整体退出分屏**:窗格树和所有会话的分屏状态会一起清空,不会留下「菜单里显示分屏中、却没有被选中」的残留状态。只剩一个窗格的分屏不成立,所以不保留隐藏的单窗格树。
|
|
84
|
+
|
|
85
|
+
## 浮窗模式(独立窗口)
|
|
86
|
+
|
|
87
|
+
分屏和浮窗是同一个工作区的两种形态,可以随时互相切换:
|
|
88
|
+
|
|
89
|
+
- **分屏 → 浮窗**:右键会话 → **进入浮窗**。该会话会从分屏(或待分屏)中移出,变成一个浮动窗口;窗口内仍然是这个会话的真实原生界面(输入框、流式输出、停止、队列、工具行、附件、审批、视图页都可用)。
|
|
90
|
+
- **浮窗 → 分屏**:右键浮窗里的会话 → **加入分屏**(或标题栏的 **⇲ 回到分屏**)。若当前已有分屏,会话直接追加为窗格;若还没有分屏,会先进入「待分屏」,再加一个会话即开始分屏;右键 → **退出浮窗** 只关闭浮窗,不放回分屏。
|
|
91
|
+
- **浮窗操作**:拖动标题栏移动窗口,拖动任意边缘/角落缩放,点击窗口自动置顶;位置、大小和层叠顺序会持久化,DSH 重启后浮窗仍在。窗口缩放或右侧栏开合后,浮窗会自动回到可见范围。
|
|
92
|
+
- **与分屏共存**:浮窗可以浮在分屏之上,每个浮窗独立占用一个真实会话;从 2 窗格分屏抽出一个会话会结束分屏并清除另一个会话的分屏状态(浮窗 ⇲ 回分屏时进入「待分屏」,再加一个会话即可重新分屏);3 个及以上窗格抽取时,分屏继续显示剩余窗格。
|
|
93
|
+
- 浮窗和分屏窗格互斥:一个会话只会存在一种形态,避免同一会话被两个输入框同时编辑。
|
|
94
|
+
|
|
95
|
+
### 为什么浮窗不是系统级独立窗口?
|
|
96
|
+
|
|
97
|
+
这不是偷懒,而是当前 DSH 宿主没有提供第二个原生窗口:
|
|
98
|
+
|
|
99
|
+
- DSH Desktop 的 Electron 主进程只创建一个主窗口;主窗口的 `setWindowOpenHandler` 对 `window.open` 一律返回 `{ action: "deny" }`(仅把 http/https 链接交给系统浏览器打开),也没有按会话开窗的 IPC 或菜单项。
|
|
100
|
+
- DSH Web 客户端是单页应用,没有 `?session=` 之类的会话深链路由;会话切换由 `uiWorkspace.openSession` 在页面内完成,不存在“打开一个只显示某会话的新窗口”的 URL。
|
|
101
|
+
- 插件运行在渲染层,无法创建 Electron `BrowserWindow`;因此浮窗实现为 `shell.overlay` 之上的**应用内窗口**:它可以移动、缩放、置顶、持久化,并且宿主是真实的 `ChatPane`,但与主窗口共享同一个客户端和页面。
|
|
102
|
+
|
|
103
|
+
如果 DSH 未来开放原生多窗口能力,浮窗层可以直接换成原生窗口,而“分屏 ⇄ 浮窗”的会话切换逻辑不需要改。
|
|
104
|
+
|
|
105
|
+
## 系统窗口(独立窗口)
|
|
106
|
+
|
|
107
|
+
- 右键会话 → **在系统窗口打开**:插件通过宿主生成已认证的 DSH Web 地址,并在**系统默认浏览器**中打开一个新窗口;窗口里只渲染这个会话(DSH 侧栏等界面被隐藏),关闭、最小化、双击标题栏放大、全屏都由系统窗口原生提供。
|
|
108
|
+
- 打开时该会话会从分屏 / 浮窗 / 待分屏中移出,避免同一会话同时被两个输入框编辑;关闭系统窗口不会删除会话,它仍在侧栏里,可随时重新加入分屏。
|
|
109
|
+
- 窗口页头双击可进入 / 退出页面全屏(页头的 ⛶ 按钮相同);窗口标题会同步会话标题。
|
|
110
|
+
- **为什么是浏览器窗口?** DSH Desktop 的 Electron 主进程只保留一个应用窗口,主窗口的 `setWindowOpenHandler` 拒绝用 `window.open` 创建第二个原生窗口(http/https 只交给系统浏览器);插件的 Host 进程是 Node 子进程,没有 Electron `BrowserWindow` API。因此当前 DSH 版本下,能真正位于 DSH 工作区之外、并具备系统窗口控制的方案就是由操作系统打开一个浏览器窗口。Web 版由 `window.open` 直接打开同样的独立窗口。
|
|
111
|
+
- 限制:窗口带浏览器地址栏 / 标签页 UI,不是 DSH 原生第二窗口;如果未来 DSH 开放原生多窗口,这一层可以替换。
|
|
112
|
+
|
|
113
|
+
## 性能模式与卡顿排查
|
|
114
|
+
|
|
115
|
+
**性能模式默认开启**(从 0.9.0 起;显式关过一次的保留关闭状态)。在侧边栏底部分屏按钮的菜单里点 **性能模式** 可切换(也可用 `window.__dshSplitWorkspace.setPerformanceMode(true/false)`,设置会持久化)。开启后:
|
|
116
|
+
|
|
117
|
+
- 关闭所有窗格 / 浮窗 / 菜单 / 提示的动画、过渡、卡片阴影和焦点光晕,并停掉工具行跑马灯动画。
|
|
118
|
+
- 关闭**每个窗格的 composer 几何测量 MutationObserver**。这是最可疑的开销之一:流式输出每个 token 都会改动窗格 DOM,旧逻辑会在每次改动时排队测量(`getBoundingClientRect` + 样式读取),窗格越多越明显;性能模式改为 ResizeObserver + 1.5s 轮询。
|
|
119
|
+
- 暂停 TOC 握把同步(`dsh-prompt-history` 的 ☰ 定位)、压缩结果监听、浮窗位置巡检、右侧栏 800ms 轮询(保留 resize 监听),几何测量从 1s 降到 3.5s,侧栏会话扫描从 200ms 降到 1s。
|
|
120
|
+
- 拖动会话/窗格时**完全不渲染缩略图预览**(不克隆对话 DOM,也没有逐帧移动的预览窗口);拖入目标、布局预览和放置反馈仍然保留。
|
|
121
|
+
- 真实会话、输入、停止、审批、分屏 / 浮窗 / 系统窗口功能全部保留。
|
|
122
|
+
|
|
123
|
+
**仍然可能卡的原因**:每个窗格都是一个完整的原生对话视图,N 个会话同时流式输出就是 N 份 React/DOM 渲染与滚动更新,这是 DSH 客户端本身的主要成本,插件无法消除(除非上游支持离屏暂停/虚拟化)。在 Windows + 低单核性能的机器上,建议同时保持 2–3 个活动窗格、少开浮窗、把不用的分屏最小化;输入框可切到紧凑 TUI 模式;如果装了 `dsh-prompt-history`,它的 TOC 同步在性能模式下会被暂停。
|
|
124
|
+
|
|
125
|
+
诊断入口:`window.__dshSplitWorkspace.health()` 查看 `performance`、`panes`、`geometry`、`active`;用 DevTools Performance 对比开启性能模式前后的长任务。
|
|
126
|
+
|
|
127
|
+
## 更新、重载与重启
|
|
128
|
+
|
|
129
|
+
DSH 0.2.x(含 Desktop 0.2.2-rc.3)带 HMR:新安装的插件会被热加载,重建后的客户端 bundle 也会自动替换,**大多数安装/更新不需要重启 DSH**。以下情况才需要重启:
|
|
130
|
+
|
|
131
|
+
- 插件管理器明确提示 `restart-required`(Host 半边、被链接包的宿主模块发生变化,或包目录被移动);
|
|
132
|
+
- 安装后侧边栏底部几秒内没有出现分屏图标(少数没有 HMR 的旧版 DSH)。
|
|
133
|
+
|
|
134
|
+
DSH **生产版没有内置的“重启”菜单项**(开发版才有 `Restart App and Host`)。从本插件的 0.9.0 起:
|
|
135
|
+
|
|
136
|
+
- 侧边栏底部 **分屏菜单 → 重启 DSH**:先确认(运行中的任务会中断),再由 Host 半调用系统级“退出并重新打开”(macOS 通过 AppleScript 正常退出,Windows 关闭窗口后终止进程并重启)。
|
|
137
|
+
- 检测到磁盘版本比页面新时,右下角的更新提示直接提供 **重启 DSH** 按钮;Web 版提供 **刷新页面**。
|
|
138
|
+
- 也可以用 `window.__dshSplitWorkspace.restartApp()`,或按老办法手动退出后重新打开:Windows 从托盘/开始菜单彻底退出,macOS 用 ⌘Q。
|
|
139
|
+
- 底部菜单的 **刷新界面** 只重新加载页面(适合浮层卡住、布局异常),不会应用需要重启的 Host 变化。
|
|
140
|
+
- 首次安装时插件客户端可能尚未加载,因此插件自身无法显示重启按钮;插件管理器会在安装结果里提示重启,按提示或手动退出重开即可。
|
|
141
|
+
- **安装后看不到分屏入口时,先尝试刷新页面而不是重启**:DSH Desktop 生产版没有页面刷新菜单,但自带 **开发者工具**(macOS `⌘⌥I`,Windows `Ctrl+Shift+I`,或菜单 View → Toggle Developer Tools);在开发者工具里点刷新按钮、按 `⌘R` / `F5`,或在 Console 执行 `location.reload()`,都会重新加载页面并取回最新的插件图,通常无需重启 DSH。仍不生效再完全退出重开。
|
|
81
142
|
|
|
82
143
|
## 功能
|
|
83
144
|
|
|
84
145
|
- **侧边栏分屏菜单**:底部分屏按钮弹出「添加分屏 / 退出分屏 / 最小化分屏 / 重置分屏」,其中退出和最小化与顶部工具栏完全一致。
|
|
85
146
|
- **多选添加分屏**:弹框可搜索、可多选;已分屏时默认勾选当前窗格,可取消或追加,按最终勾选结果分屏。
|
|
86
147
|
- **会话右键集成**:原生右键菜单新增「加入分屏 / 退出分屏」,未分屏时先进入待分屏,满两个才分屏;退出到只剩一个自动退出分屏。
|
|
148
|
+
- **浮窗模式**:右键会话 → 「进入浮窗」,把会话变成可拖动、可缩放的独立窗口;标题栏 ⇲ 放回分屏、✕ 关闭,浮窗位置/大小/层叠顺序持久化。
|
|
149
|
+
- **分屏 ⇄ 浮窗双向切换**:同一会话互斥存在于一种形态;进入浮窗自动移出分屏,回到分屏自动关闭浮窗。
|
|
150
|
+
- **系统窗口**:右键会话 → 「在系统窗口打开」,在系统默认浏览器中打开只含该会话的独立窗口;原生关闭 / 最小化 / 最大化 / 全屏,打开时自动从分屏和浮窗移出。
|
|
151
|
+
- **性能模式(默认开启)**:一键关闭动画、阴影、跑马灯和多个后台轮询/观察器,适合低配或 Windows 上多窗格卡顿的场景;设置持久化。性能模式下**不再渲染拖动会话时的缩略图预览**(拖入目标与放置反馈保留),可以再明显减少拖动时的 DOM/合成开销。
|
|
152
|
+
- **更新提示 / 重启 DSH / 刷新界面**:检测到磁盘上的新版本时右下角提示,并提供「重启 DSH」(桌面版)或「刷新页面」(Web 版);分屏菜单同时提供「刷新界面」与「重启 DSH」。
|
|
153
|
+
- **兜底分屏入口**:如果所在 DSH 布局没有渲染侧边栏 footer(或 footer 被隐藏),插件会在对话区左下角显示一个分屏按钮,保证菜单仍可打开。
|
|
87
154
|
- **一键重置**:清空插件相关的 localStorage / sessionStorage、布局、崩溃保护和临时缓存,避免异常状态卡住分屏。
|
|
88
155
|
- **不限数量的原生窗格**:没有四窗格上限,窗口放得下多少会话就能开多少。
|
|
89
156
|
- **自动布局**:2 个窗格左右分栏,3 个呈 L 形,4 个田字 2×2,5 个以上按行优先的均衡网格排列。
|
|
@@ -119,6 +186,15 @@ dsh --profile web
|
|
|
119
186
|
- `window.__dshSplitWorkspace.health()`:版本、宿主、窗格、几何、持久化树、崩溃保护。
|
|
120
187
|
- `window.__dshSplitWorkspace.split(sessionId)`:把会话加为窗格。
|
|
121
188
|
- `window.__dshSplitWorkspace.addToSplit(sessionId)` / `removeFromSplit(sessionId)`:加入 / 退出分屏(未分屏时先进入待分屏)。
|
|
189
|
+
- `window.__dshSplitWorkspace.float(sessionId)`:把会话变成浮窗(自动从分屏/待分屏移出)。
|
|
190
|
+
- `window.__dshSplitWorkspace.dockFloat(sessionId)`:把浮窗放回分屏(没有分屏时进入待分屏)。
|
|
191
|
+
- `window.__dshSplitWorkspace.closeFloat(sessionId)`:关闭浮窗(不放回分屏)。
|
|
192
|
+
- `window.__dshSplitWorkspace.floats()`:当前浮窗的会话 id 列表(按创建顺序)。
|
|
193
|
+
- `window.__dshSplitWorkspace.openSystemWindow(sessionId)`:在系统窗口打开该会话(宿主生成已认证 URL)。
|
|
194
|
+
- `window.__dshSplitWorkspace.setPerformanceMode(true/false)`:开关性能模式(持久化)。
|
|
195
|
+
- `window.__dshSplitWorkspace.performanceMode()`:当前是否处于性能模式。
|
|
196
|
+
- `window.__dshSplitWorkspace.reloadClient()`:刷新页面。
|
|
197
|
+
- `window.__dshSplitWorkspace.restartApp()`:退出并重新打开 DSH 桌面版(需要完整重启时使用)。
|
|
122
198
|
- `window.__dshSplitWorkspace.pending()`:当前待分屏的会话 id。
|
|
123
199
|
- `window.__dshSplitWorkspace.openAddSplitDialog()`:打开多选添加分屏弹框。
|
|
124
200
|
- `window.__dshSplitWorkspace.arrange("auto")`:重新适配自动布局(旧模式名会被接受并忽略)。
|
|
@@ -128,6 +204,34 @@ dsh --profile web
|
|
|
128
204
|
- `window.__dshSplitWorkspace.reset()`:清除已保存布局。
|
|
129
205
|
- `window.__dshSplitWorkspace.resetAll()`:连同 localStorage / sessionStorage 与临时缓存一起彻底重置(等同菜单里的「重置分屏」)。
|
|
130
206
|
|
|
207
|
+
## 工程结构(源码拆分)
|
|
208
|
+
|
|
209
|
+
`lib/client.js` 是**构建产物**,不要直接编辑;源码在 `src/client/`,按模块拆成 18 个有序片段,由 `scripts/build-client.mjs` 拼回单文件:
|
|
210
|
+
|
|
211
|
+
| 片段 | 内容 |
|
|
212
|
+
| --- | --- |
|
|
213
|
+
| `00-preamble` / `01-constants` | module-loader 入口、React/P、常量、存储、性能/版本键、独立窗口检测 |
|
|
214
|
+
| `02-styles` | 全部 `dsv-*` CSS(含性能模式与浮窗样式) |
|
|
215
|
+
| `03-runtime` | runtime store、健康诊断、会话列表源 |
|
|
216
|
+
| `04-tree` | 分屏树 store、布局算法、持久化 |
|
|
217
|
+
| `05-pending-float-store` | 待分屏状态、浮窗 store 与模式切换 |
|
|
218
|
+
| `06-drag-reflow` | 窗格拖动预览/reflow、拖拽工具 |
|
|
219
|
+
| `07-faces` | root standard faces、session bindings |
|
|
220
|
+
| `08-pane-kit` | slot 捕获与原生组件 re-host |
|
|
221
|
+
| `09-pane-renderers` | 原生/降级对话与输入框渲染器 |
|
|
222
|
+
| `10-pane-frame` | 窗格标题栏、关闭/浮窗按钮、composer 测量 |
|
|
223
|
+
| `11-canvas-navigation` | 画布/分隔条、会话选择器、键盘导航、公共 API 前置 |
|
|
224
|
+
| `12-chrome` | 安全模式/帮助/提示、性能模式提示、更新通知、座位 |
|
|
225
|
+
| `13-drag-bridge` | 未激活时的拖入分屏桥 |
|
|
226
|
+
| `14-launcher` | 底部菜单、多选添加分屏弹框、会话菜单集成 |
|
|
227
|
+
| `15-float-window` | 浮窗组件与图层 |
|
|
228
|
+
| `16-standalone` | 系统窗口独立页 |
|
|
229
|
+
| `17-api-apply` | `window.__dshSplitWorkspace` API、`apply()` 与导出 |
|
|
230
|
+
|
|
231
|
+
- `npm run build`:重新生成 `lib/client.js`;`npm test` 会先跑 `build:check`,源码/产物不一致会失败。
|
|
232
|
+
- 为什么不用打包器:DSH 客户端只加载一个 `<plugin>/client.js`,片段共享同一个 module-loader 闭包,按顺序拼接即可;这样发布包保持零依赖、无构建依赖。
|
|
233
|
+
- 修改代码时改 `src/client/` 对应片段,然后 `npm run build`;`lib/client.js` 顶部有一行 GENERATED 标记。
|
|
234
|
+
|
|
131
235
|
## 快捷键
|
|
132
236
|
|
|
133
237
|
- `Alt+T`:切换聚焦窗格里的紧凑 TUI 输入框。
|
|
@@ -148,6 +252,9 @@ will land:
|
|
|
148
252
|
## 限制
|
|
149
253
|
|
|
150
254
|
- 没有窗格数量上限;持久化树会校验(会话唯一、深度),损坏的树会被丢弃,而不是恢复一个坏掉的工作区。
|
|
255
|
+
- 「浮窗」是应用内窗口,不是 Electron 原生第二窗口:DSH Desktop 主窗口禁用了 `window.open`,Web 客户端也没有会话深链;浮窗复用真实会话组件、可拖动缩放,但仍在 DSH 主窗口内渲染(详见上面的「为什么浮窗不是系统级独立窗口?」)。
|
|
256
|
+
- 浮窗和分屏窗格互斥;同一会话不会同时以两种形态渲染,避免共享编辑器冲突。
|
|
257
|
+
- 「系统窗口」当前由系统默认浏览器承载(DSH Desktop 拒绝插件创建第二个原生窗口,Host 进程也没有 Electron 窗口 API),因此带浏览器地址栏;系统窗口内的会话同样互斥于分屏和浮窗。
|
|
151
258
|
- 持久化递归深度上限为 32 层,是为了手改数据时的栈安全,不是窗格上限。
|
|
152
259
|
- 隐藏的原生会话仍在遮罩下流式运行;窗格重新挂载原生输入框,所以每个窗格自己的输入框拥有该会话的编辑器。
|
|
153
260
|
- 窗格重命名拒绝空会话(原生重命名对话框同样如此)。
|
|
@@ -162,7 +269,9 @@ MIT。见 `THIRD-PARTY-NOTICES.md`。
|
|
|
162
269
|
## English
|
|
163
270
|
|
|
164
271
|
**Split screen for DeepSeek Harness (DSH) Desktop — open as many conversations
|
|
165
|
-
as you need, side by side, stacked, or in a 2×2 / automatic grid.**
|
|
272
|
+
as you need, side by side, stacked, or in a 2×2 / automatic grid.** Any
|
|
273
|
+
conversation can also become a movable, resizable **floating window**, and the
|
|
274
|
+
two modes switch back and forth at any time.
|
|
166
275
|
|
|
167
276
|
`dsh-split-workspace` turns the DeepSeek Harness conversation area into a native
|
|
168
277
|
multi-pane workspace, including in the **Desktop app** (`dsh-app://` shell). Each
|
|
@@ -224,7 +333,7 @@ dsh --profile web
|
|
|
224
333
|
|
|
225
334
|
1. Open DSH Desktop → **Plugin market** in the sidebar, search for `dsh-split-workspace`, and install it. Or use **Plugins → Add plugin → Install a third-party plugin** and enter the package name.
|
|
226
335
|
2. Open **Settings → Plugins** and enable `dsh-split-workspace`.
|
|
227
|
-
3.
|
|
336
|
+
3. DSH's HMR normally loads a newly installed plugin immediately, so no restart is needed. If the split icon still does not appear in the sidebar footer after a few seconds, quit and reopen DSH Desktop completely (the plugin menu and update chip also offer **Restart DSH**).
|
|
228
337
|
|
|
229
338
|
> The `desktop` profile is owned by the Electron app. Do **not** run `dsh plugin --profile desktop add ...` in a terminal; it is rejected. Use the in-app plugin market / Add plugin UI instead.
|
|
230
339
|
|
|
@@ -234,15 +343,15 @@ dsh --profile web
|
|
|
234
343
|
2. DSH Desktop → **Plugins → Add plugin → Install a third-party plugin**:
|
|
235
344
|
- prefer the **absolute path to the `.tgz`** (the installer recognises it as a tarball);
|
|
236
345
|
- if that build only accepts directories, extract the `.tgz` and enter the extracted directory (its root must contain `package.json`).
|
|
237
|
-
3. Enable it in **Settings → Plugins
|
|
346
|
+
3. Enable it in **Settings → Plugins**; HMR usually loads it immediately. If the footer split icon does not appear, quit and reopen DSH Desktop, or use **Restart DSH** in the plugin menu.
|
|
238
347
|
4. The offline machine needs no network access; the plugin makes no runtime requests.
|
|
239
348
|
|
|
240
349
|
**Enable and verify**
|
|
241
350
|
|
|
242
|
-
- **Settings → Plugins** must show `dsh-split-workspace` enabled.
|
|
351
|
+
- **Settings → Plugins** must show `dsh-split-workspace` enabled. DSH 0.2.x hot-loads newly installed plugins through HMR; if the UI still does not appear, see “Updates, reload and restart”.
|
|
243
352
|
- Entry points: the split icon in the sidebar footer (beside Settings), or drag a conversation from the sidebar onto the conversation column.
|
|
244
353
|
- Run `window.__dshSplitWorkspace.health()` in the browser/desktop console to see the version, pane count and geometry.
|
|
245
|
-
- If the split entry is missing: make sure
|
|
354
|
+
- If the split entry is missing: make sure the plugin is enabled and has no error. When the stock sidebar footer does not render this plugin's action, the plugin shows a fallback split button at the conversation area's bottom-left corner.
|
|
246
355
|
|
|
247
356
|
**Start splitting**
|
|
248
357
|
|
|
@@ -252,13 +361,156 @@ dsh --profile web
|
|
|
252
361
|
- Or drag a conversation from the sidebar onto the conversation column: the dropped conversation becomes the second pane.
|
|
253
362
|
- Once split, drag another conversation onto a pane to replace it, or use a pane header's split buttons to choose the session for a new pane.
|
|
254
363
|
- While a sidebar conversation is dragged over a pane edge, the panes lay themselves out as they will after the drop and a dashed placeholder names the incoming conversation — release to commit exactly that layout.
|
|
255
|
-
- **Reset split** clears
|
|
364
|
+
- **Reset split** clears the plugin's split-related localStorage / sessionStorage keys, the saved layout, the crash guard, the minimized flag and pane caches, so a split stuck by stale state can always start again (the performance-mode preference is kept).
|
|
365
|
+
- Closing a pane (header **✕**) or leaving the split via the context menu exits the split as soon as fewer than two conversations remain: the whole pane tree and every conversation's split membership are cleared, so nothing is left tagged “in split” while unselected.
|
|
366
|
+
- Right-click any conversation (or its row `⋯` button) → **Enter floating window** to detach it into a movable window. Drag its title bar to move it, drag any edge to resize, use **⇲ Dock to split** to put it back into a split, or **✕** to close the float. A conversation is never hosted in both modes: entering a float removes it from the split / pending split first.
|
|
367
|
+
- Right-click a conversation → **Open in system window** to open it alone in a separate system window (the default browser on Desktop), with the window's native close / minimize / maximize / fullscreen controls.
|
|
368
|
+
|
|
369
|
+
### Floating windows
|
|
370
|
+
|
|
371
|
+
Split panes and floating windows are two shapes of the same workspace, and a
|
|
372
|
+
conversation can switch between them without a reload:
|
|
373
|
+
|
|
374
|
+
- **Split → float**: right-click a conversation → **Enter floating window**. It
|
|
375
|
+
leaves the split (or the pending pick) and becomes a floating window that
|
|
376
|
+
hosts the session's real native UI — composer, streaming, Stop, queue, tool
|
|
377
|
+
rows, attachments, approvals and view tabs all keep working.
|
|
378
|
+
- **Float → split**: right-click the conversation inside the float → **Add to
|
|
379
|
+
split** (or use the header's **⇲ Dock to split**). With a split running, the
|
|
380
|
+
session is appended as a pane; with none, it is parked in the pending split
|
|
381
|
+
and the next pick starts the split. **Exit floating window** only closes the
|
|
382
|
+
float without docking it.
|
|
383
|
+
- **Window behaviour**: drag the title bar to move, drag any edge/corner to
|
|
384
|
+
resize, click to raise. Position, size and stacking order persist across DSH
|
|
385
|
+
restarts, and every float is clamped back into the conversation column after
|
|
386
|
+
a window resize or a right-sidebar open/close.
|
|
387
|
+
- **With a split**: floats sit above the split. Extracting one conversation
|
|
388
|
+
from a 2-pane split ends the split and clears the other conversation's split
|
|
389
|
+
membership (docking the float back parks it in the pending split, so the next
|
|
390
|
+
pick restarts the split); with 3+ panes the split keeps showing the remaining
|
|
391
|
+
panes.
|
|
392
|
+
- A session exists in exactly one mode at a time, so two composers can never
|
|
393
|
+
edit the same conversation at once.
|
|
394
|
+
|
|
395
|
+
#### Why not a real OS-level window?
|
|
396
|
+
|
|
397
|
+
This is a host limitation, not a shortcut:
|
|
398
|
+
|
|
399
|
+
- The DSH Desktop Electron main process creates a single main window; its
|
|
400
|
+
`setWindowOpenHandler` returns `{ action: "deny" }` for every `window.open`
|
|
401
|
+
(http/https links are handed to the system browser), and there is no
|
|
402
|
+
per-session window IPC or menu action.
|
|
403
|
+
- The DSH Web client is a single-page app with no per-session deep link such as
|
|
404
|
+
`?session=`; session switches happen in-page through `uiWorkspace.openSession`,
|
|
405
|
+
so there is no URL for "open one conversation in a new window".
|
|
406
|
+
- A renderer plugin cannot create an Electron `BrowserWindow`.
|
|
407
|
+
|
|
408
|
+
The float is therefore an **in-app window** rendered on the `shell.overlay`
|
|
409
|
+
layer: movable, resizable, persistent, and backed by the real `ChatPane`, but
|
|
410
|
+
inside the same DSH page. If DSH later exposes native multi-window support, the
|
|
411
|
+
float layer can be swapped for real windows while the split⇄float switching
|
|
412
|
+
logic stays unchanged.
|
|
413
|
+
|
|
414
|
+
### System window
|
|
415
|
+
|
|
416
|
+
- Right-click a conversation → **Open in system window**: the Host plugin mints
|
|
417
|
+
an authenticated DSH Web URL and opens it in a **separate system window**
|
|
418
|
+
(the OS default browser on Desktop). The page renders that one conversation
|
|
419
|
+
only; close / minimize / double-click-title-bar maximize / fullscreen are the
|
|
420
|
+
native window's own controls.
|
|
421
|
+
- Opening it detaches the conversation from the split / float / pending pick, so
|
|
422
|
+
one conversation is never edited through two composers. Closing the system
|
|
423
|
+
window keeps the conversation — it stays in the sidebar and can rejoin a split.
|
|
424
|
+
- Double-click the page header (or use its ⛶ button) to toggle page fullscreen;
|
|
425
|
+
the window title follows the conversation title.
|
|
426
|
+
- **Why a browser window?** The DSH Desktop Electron main process keeps a single
|
|
427
|
+
application window and its `setWindowOpenHandler` refuses `window.open`
|
|
428
|
+
(http/https is handed to the system browser); the plugin Host runs in a Node
|
|
429
|
+
child process with no Electron `BrowserWindow` API. A browser window is
|
|
430
|
+
therefore the only real OS window with native window controls that a plugin
|
|
431
|
+
can open today. In Web mode `window.open` opens the same standalone window.
|
|
432
|
+
- Limitation: the window carries browser chrome (address bar / tabs); it is not
|
|
433
|
+
a second DSH-native window. If DSH later exposes native multi-window support,
|
|
434
|
+
this layer can be replaced.
|
|
435
|
+
|
|
436
|
+
### Performance mode and lag analysis
|
|
437
|
+
|
|
438
|
+
**Performance mode is ON by default** since 0.9.0 (an explicit off choice is
|
|
439
|
+
kept). Open the sidebar-footer split menu and pick **Performance mode**, or run
|
|
440
|
+
`window.__dshSplitWorkspace.setPerformanceMode(true/false)`; it persists. It
|
|
441
|
+
turns off:
|
|
442
|
+
|
|
443
|
+
- every pane / float / menu / chip animation, transition, card shadow, focus
|
|
444
|
+
glow and running-row shimmer;
|
|
445
|
+
- the per-pane composer-geometry `MutationObserver`. This is the most suspicious
|
|
446
|
+
cost: streaming mutates a pane's DOM on every token and the old path queued a
|
|
447
|
+
measurement (`getBoundingClientRect` + style reads) for each change, multiplying
|
|
448
|
+
with pane count. Performance mode keeps ResizeObserver plus a 1.5 s poll;
|
|
449
|
+
- TOC-grip sync (`dsh-prompt-history` ☰ placement), compaction-watch, float
|
|
450
|
+
position polling and the 800 ms right-sidebar poll (resize listeners stay);
|
|
451
|
+
geometry polling drops from 1 s to 3.5 s and sidebar session scraping from
|
|
452
|
+
200 ms to 1 s;
|
|
453
|
+
- the floating drag-preview thumbnail for sessions and panes is not rendered at
|
|
454
|
+
all — no DOM clone, no per-frame thumbnail positioning; drop targets and the
|
|
455
|
+
layout reflow hole still work.
|
|
456
|
+
|
|
457
|
+
Real conversations, composers, approval flows, split/float/system-window
|
|
458
|
+
features all stay available.
|
|
459
|
+
|
|
460
|
+
**What can still lag**: every pane is a full native conversation view, so N panes
|
|
461
|
+
streaming at once means N independent React/DOM render and scroll pipelines —
|
|
462
|
+
the dominant upstream cost, which a renderer plugin cannot remove (that would
|
|
463
|
+
need upstream offscreen pausing/virtualization). On Windows machines with weak
|
|
464
|
+
single-core throughput, keep 2–3 active panes, close or minimize unused splits,
|
|
465
|
+
avoid stacking floats over a split, and use the compact TUI composer. Check
|
|
466
|
+
`window.__dshSplitWorkspace.health()` (`performance`, `panes`, `geometry`) and
|
|
467
|
+
compare DevTools Performance long tasks with the mode on/off.
|
|
468
|
+
|
|
469
|
+
### Updates, reload and restart
|
|
470
|
+
|
|
471
|
+
DSH 0.2.x (including Desktop 0.2.2-rc.3) ships HMR: a newly installed plugin is
|
|
472
|
+
hot-loaded, and a rebuilt client bundle is swapped into the open page. Most
|
|
473
|
+
installs/updates therefore need **no restart**. A restart is only needed when:
|
|
474
|
+
|
|
475
|
+
- the plugin manager reports `restart-required` (Host-half or linked-package
|
|
476
|
+
host modules changed, or the package directory moved);
|
|
477
|
+
- the footer split icon still has not appeared a few seconds after install (some
|
|
478
|
+
older DSH builds without HMR).
|
|
479
|
+
|
|
480
|
+
Production DSH has **no built-in Restart menu item** (development builds do).
|
|
481
|
+
Since dsh-split-workspace 0.9.0:
|
|
482
|
+
|
|
483
|
+
- **Split menu → Restart DSH** confirms first (running tasks are interrupted),
|
|
484
|
+
then the Host half closes and reopens the desktop app at the OS level (a
|
|
485
|
+
normal AppleScript quit on macOS; close-then-terminate and relaunch on
|
|
486
|
+
Windows).
|
|
487
|
+
- The update chip offers **Restart DSH** on Desktop and **Reload page** in the
|
|
488
|
+
Web GUI.
|
|
489
|
+
- `window.__dshSplitWorkspace.restartApp()` does the same. Manually: Windows —
|
|
490
|
+
quit from the tray/Start menu; macOS — ⌘Q; then open DSH again.
|
|
491
|
+
- **Refresh interface** only reloads the page (useful for a stuck overlay or a
|
|
492
|
+
layout glitch); it does not apply changes that need a full restart.
|
|
493
|
+
- On a first install the plugin client is not running yet, so it cannot show
|
|
494
|
+
its own restart button; follow the plugin manager's restart notice or quit
|
|
495
|
+
and reopen DSH manually.
|
|
496
|
+
- **If the split entry is missing after a hot install, try a page reload before a
|
|
497
|
+
restart**: production DSH has no Reload menu item, but it ships Developer
|
|
498
|
+
Tools (macOS `⌘⌥I`, Windows `Ctrl+Shift+I`, or View → Toggle Developer Tools).
|
|
499
|
+
Use the reload button in Developer Tools, press `⌘R` / `F5`, or run
|
|
500
|
+
`location.reload()` in its Console to reload the page and fetch the current
|
|
501
|
+
plugin graph — usually no DSH restart is needed. Quit and reopen only if that still fails.
|
|
256
502
|
|
|
257
503
|
### Features
|
|
258
504
|
|
|
259
505
|
- **Sidebar split menu** — the footer button opens Add / Exit / Minimize / Reset; Exit and Minimize are the same actions as the split toolbar.
|
|
260
506
|
- **Multi-select add** — searchable dialog; pre-selects current panes, lets you uncheck or extend, and rebuilds the split from the final selection.
|
|
261
507
|
- **Session-menu integration** — the stock right-click menu gains Add to split / Leave split. Outside split mode the first pick waits in a pending split until a second conversation is added; removing down to one pane exits the split.
|
|
508
|
+
- **Floating windows** — right-click a conversation → Enter floating window turns it into a movable, resizable window; Dock to split / ✕ in its header switch it back or close it, and geometry persists.
|
|
509
|
+
- **Split ⇄ float switching** — one conversation lives in exactly one mode; entering a float detaches it from the split, docking it back closes the float.
|
|
510
|
+
- **System window** — right-click → Open in system window opens the conversation alone in a separate OS window (the default browser on Desktop) with native close / minimize / maximize / fullscreen; it is detached from split and float first.
|
|
511
|
+
- **Performance mode (on by default)** — one switch drops animations, shadows, shimmer and several background observers/polls for low-power or laggy Windows machines; the setting persists. In this mode the floating drag-preview thumbnail is not rendered at all (drop targets and placement feedback stay).
|
|
512
|
+
- **Update chip / Restart DSH / Refresh interface** — a newer on-disk version shows a corner chip with **Restart DSH** on Desktop or **Reload page** in the Web GUI; the split menu also offers Restart DSH and Refresh interface.
|
|
513
|
+
- **Fallback split entry** — when the host layout does not render the sidebar footer action (or hides it), the plugin shows a split button at the conversation area's bottom-left corner so the menu stays reachable.
|
|
262
514
|
- **One-click reset** — wipes plugin localStorage/sessionStorage, layout, crash guard and temporary caches.
|
|
263
515
|
- **Unlimited native panes** — no four-pane cap; add as many conversations as
|
|
264
516
|
the window can show.
|
|
@@ -346,6 +598,21 @@ architecture the upstream plugin uses.
|
|
|
346
598
|
- `window.__dshSplitWorkspace.addToSplit(sessionId)` /
|
|
347
599
|
`removeFromSplit(sessionId)` — add to / leave the split (the first pick
|
|
348
600
|
outside split mode waits in the pending split).
|
|
601
|
+
- `window.__dshSplitWorkspace.float(sessionId)` — detach the conversation into
|
|
602
|
+
a floating window (removed from the split / pending split first).
|
|
603
|
+
- `window.__dshSplitWorkspace.dockFloat(sessionId)` — put a floating window
|
|
604
|
+
back into the split (or the pending split when no split is running).
|
|
605
|
+
- `window.__dshSplitWorkspace.closeFloat(sessionId)` — close a floating window
|
|
606
|
+
without docking it.
|
|
607
|
+
- `window.__dshSplitWorkspace.floats()` — current floating-window session ids,
|
|
608
|
+
in creation order.
|
|
609
|
+
- `window.__dshSplitWorkspace.openSystemWindow(sessionId)` — open the
|
|
610
|
+
conversation in a separate system window (Host-minted authenticated URL).
|
|
611
|
+
- `window.__dshSplitWorkspace.setPerformanceMode(true/false)` /
|
|
612
|
+
`performanceMode()` — toggle/inspect the persisted performance mode.
|
|
613
|
+
- `window.__dshSplitWorkspace.reloadClient()` — reload the page.
|
|
614
|
+
- `window.__dshSplitWorkspace.restartApp()` — close and reopen DSH Desktop
|
|
615
|
+
(for the rare changes that need a full restart).
|
|
349
616
|
- `window.__dshSplitWorkspace.pending()` — conversations waiting for a second
|
|
350
617
|
pick before the split starts.
|
|
351
618
|
- `window.__dshSplitWorkspace.openAddSplitDialog()` — open the multi-select add
|
|
@@ -357,9 +624,42 @@ architecture the upstream plugin uses.
|
|
|
357
624
|
(diagnostics for the hole/collapse behaviour).
|
|
358
625
|
- `window.__dshSplitWorkspace.setEnabled(false)` — kill switch.
|
|
359
626
|
- `window.__dshSplitWorkspace.reset()` — clear the saved layout.
|
|
360
|
-
- `window.__dshSplitWorkspace.resetAll()` — also wipe the plugin's
|
|
627
|
+
- `window.__dshSplitWorkspace.resetAll()` — also wipe the plugin's split
|
|
361
628
|
localStorage / sessionStorage keys and temporary caches (same as the menu's
|
|
362
|
-
Reset split).
|
|
629
|
+
Reset split; the performance-mode preference is preserved).
|
|
630
|
+
|
|
631
|
+
### Source layout and build
|
|
632
|
+
|
|
633
|
+
`lib/client.js` is a **generated artifact**; do not edit it. The source lives in
|
|
634
|
+
`src/client/` as 18 ordered sections, assembled by `scripts/build-client.mjs`:
|
|
635
|
+
|
|
636
|
+
| Section | Responsibility |
|
|
637
|
+
| --- | --- |
|
|
638
|
+
| `00-preamble` / `01-constants` | module-loader entry, React/P, constants, storage, perf/version keys, standalone detection |
|
|
639
|
+
| `02-styles` | all `dsv-*` CSS (including performance mode and floats) |
|
|
640
|
+
| `03-runtime` | runtime store, health diagnostics, session-list source |
|
|
641
|
+
| `04-tree` | split tree store, layouts, persistence |
|
|
642
|
+
| `05-pending-float-store` | pending split, float store, split⇄float helpers |
|
|
643
|
+
| `06-drag-reflow` | pane drag preview/reflow and drag utilities |
|
|
644
|
+
| `07-faces` | root standard faces and session bindings |
|
|
645
|
+
| `08-pane-kit` | slot capture and native component re-hosting |
|
|
646
|
+
| `09-pane-renderers` | native/fallback transcript + composer renderers |
|
|
647
|
+
| `10-pane-frame` | pane header, close/dock buttons, composer measurement |
|
|
648
|
+
| `11-canvas-navigation` | canvas/dividers, pickers, keyboard navigation, early API |
|
|
649
|
+
| `12-chrome` | safe mode/help/tips, performance notice, update notice, seat |
|
|
650
|
+
| `13-drag-bridge` | inactive drag-to-split bridge |
|
|
651
|
+
| `14-launcher` | footer menu, multi-select add dialog, session menu integration |
|
|
652
|
+
| `15-float-window` | floating window components/layer |
|
|
653
|
+
| `16-standalone` | system-window standalone page |
|
|
654
|
+
| `17-api-apply` | `window.__dshSplitWorkspace` API, `apply()` and exports |
|
|
655
|
+
|
|
656
|
+
- `npm run build` regenerates `lib/client.js`; `npm test` runs `build:check` first
|
|
657
|
+
and fails when the source and artifact disagree.
|
|
658
|
+
- No bundler: the DSH client loads exactly one `<plugin>/client.js`, the sections
|
|
659
|
+
share one module-loader closure, and ordered concatenation keeps the published
|
|
660
|
+
package dependency-free.
|
|
661
|
+
- Edit the matching `src/client/` section and run `npm run build`; the generated
|
|
662
|
+
file starts with a GENERATED marker.
|
|
363
663
|
|
|
364
664
|
### Keyboard
|
|
365
665
|
|
|
@@ -370,6 +670,16 @@ architecture the upstream plugin uses.
|
|
|
370
670
|
|
|
371
671
|
- No pane-count cap; the persisted tree is validated (unique sessions, depth)
|
|
372
672
|
and a corrupt tree is discarded instead of reactivating a broken workspace.
|
|
673
|
+
- A floating window is an **in-app** window, not a second Electron window: the
|
|
674
|
+
Desktop main window denies `window.open` and the Web client has no
|
|
675
|
+
per-session deep link, so the float re-hosts the real conversation inside the
|
|
676
|
+
same DSH page (see “Why not a real OS-level window?” above).
|
|
677
|
+
- A conversation is either a split pane or a floating window — never both — so
|
|
678
|
+
two composers can never share one session's editor.
|
|
679
|
+
- The **system window** is currently hosted by the OS default browser (DSH
|
|
680
|
+
Desktop refuses plugin-created native secondary windows and the Host process
|
|
681
|
+
has no Electron window API), so it carries browser chrome; a conversation in
|
|
682
|
+
a system window is likewise detached from split and float.
|
|
373
683
|
- The persisted recursion depth is capped at 32 levels as a stack-safety guard
|
|
374
684
|
for hand-edited payloads, not as a pane limit.
|
|
375
685
|
- The hidden stock conversation still streams under the overlay; panes re-host
|