dsh-sidebar-row-menu 0.0.0-stage → 1.3.2

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.en.md ADDED
@@ -0,0 +1,339 @@
1
+ # dsh-sidebar-row-menu
2
+
3
+ <img src="assets/icon-180.png" width="96" align="right" alt="Plugin icon" />
4
+
5
+ [![CI](https://github.com/TLEWA/dsh-sidebar-row-menu/actions/workflows/ci.yml/badge.svg)](https://github.com/TLEWA/dsh-sidebar-row-menu/actions/workflows/ci.yml)
6
+ [![Release](https://github.com/TLEWA/dsh-sidebar-row-menu/actions/workflows/release.yml/badge.svg)](https://github.com/TLEWA/dsh-sidebar-row-menu/releases)
7
+
8
+ [简体中文](README.md) · [English](README.en.md)
9
+
10
+ Right-click menus for the sidebar of [DeepSeek Harness](https://github.com/deepseek-ai) (DSH):
11
+
12
+ - **Workspace rows** — right-click opens a menu (a reimplementation of
13
+ `dsh-sidebar-context-menu`'s capabilities);
14
+ - **Session rows nested under a workspace** — right-click opens that row's native
15
+ "…" menu at the pointer, with the plugin's own entries appended.
16
+
17
+ Menus are rendered with DSH's official `Menu` component, so visuals, positioning,
18
+ keyboard navigation and click-outside dismissal match the built-in "…" menus.
19
+ The workspace menu is composed by this plugin. Session menu content comes from the
20
+ `sidebar.workspaces.session.menu.item` slot — built-in actions and other plugins'
21
+ actions are all there. This plugin only appends its own entries; it does not copy
22
+ or hardcode any built-in action.
23
+
24
+ > The "…" button menu stays exactly as DSH ships it. The plugin's three entries
25
+ > appear only when the menu is opened by right-click. A right-click menu does not
26
+ > close when the pointer leaves it (same as the workspace menu); it closes only on
27
+ > an outside click, an item selection, or Escape.
28
+
29
+ ## Features
30
+
31
+ ### Workspace row
32
+
33
+ | Item | Behavior |
34
+ | --- | --- |
35
+ | New session | Expands the workspace and starts a session (same as the row's `+`) |
36
+ | Rename | Opens the official "Rename workspace" dialog |
37
+ | Open in VS Code | Host opens the workspace directory in a new window |
38
+ | Open in Explorer | Host opens the system file manager |
39
+ | Copy workspace path | Copies the directory path |
40
+ | Open in new tab | Only when `dsh-project-tabs` (exposing `openWorkspaceInTab`) is installed |
41
+ | Delete workspace | Opens the official delete confirmation |
42
+
43
+ ### Session row
44
+
45
+ Right-click does not build a second menu; it opens the row's own "…" menu:
46
+
47
+ | Source | Entries |
48
+ | --- | --- |
49
+ | DSH built-ins | Rename, Fork session, Pin / Unpin, Archive / Unarchive, Copy Session ID |
50
+ | Other plugins | Whatever they register into `sidebar.workspaces.session.menu.item` |
51
+ | This plugin | Open in VS Code, Open in Explorer, Copy session link |
52
+
53
+ The three entries added by this plugin:
54
+
55
+ | Item | Behavior |
56
+ | --- | --- |
57
+ | Open in VS Code | Uses the session's `cwd`, falling back to its workspace directory |
58
+ | Open in Explorer | Same as above |
59
+ | Copy session link | Copies the `?session=<id>` deep link |
60
+
61
+ These three are **right-click only**: they do not mount when the "…" button opens
62
+ the menu. A short-lived window flag is set before opening; outside that window the
63
+ entries render `null`.
64
+
65
+ Blank draft sessions have no native "…" menu and are left alone. Rows that are
66
+ neither a workspace nor a session (e.g. "Show more") are not intercepted.
67
+
68
+ ## Install
69
+
70
+ Requirements:
71
+
72
+ - DSH Desktop (or `dsh web`) has been started at least once, so the profile exists;
73
+ - Windows PowerShell 5.1+;
74
+ - Row components from the `0.2.1-rc.5` generation (see [Compatibility](#compatibility)).
75
+
76
+ ### Install from GitHub (recommended)
77
+
78
+ DSH Desktop installs Git dependencies through pnpm. The `lib/` directory in this
79
+ repository is already runnable, so **no local build is required**.
80
+
81
+ 1. Open **Plugins** in the sidebar → **Install plugin**;
82
+ 2. Paste the repository URL and confirm:
83
+
84
+ ```
85
+ https://github.com/TLEWA/dsh-sidebar-row-menu
86
+ ```
87
+
88
+ 3. Hard-refresh (`Ctrl+Shift+R`); restart the desktop app if the host half is not active.
89
+
90
+ That URL tracks the latest commit on `main`. Pin a tag for a stable version:
91
+
92
+ ```
93
+ https://github.com/TLEWA/dsh-sidebar-row-menu#v1.3.2
94
+ ```
95
+
96
+ Or install the tarball built by Actions directly, without Git:
97
+
98
+ ```
99
+ https://github.com/TLEWA/dsh-sidebar-row-menu/releases/download/v1.3.2/dsh-sidebar-row-menu-1.3.2.tgz
100
+ ```
101
+
102
+ Equivalent command line:
103
+
104
+ ```powershell
105
+ dsh plugin --profile desktop add github:TLEWA/dsh-sidebar-row-menu
106
+ ```
107
+
108
+ Automation: every push / pull request runs syntax checks, the full test suite and a
109
+ package verification in GitHub Actions; pushing a `v*` tag builds the tarball and
110
+ creates a GitHub Release with `dsh-sidebar-row-menu-<version>.tgz` and
111
+ `SHA256SUMS.txt`.
112
+
113
+ ### Plugin marketplace
114
+
115
+ The submission material for the
116
+ [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
117
+ listing (entry YAML and preflight script) is kept locally and is git-ignored; it
118
+ is not part of this repository. Submitting only requires the entry file in one
119
+ pull request against the upstream catalogue. Until the plugin is listed, install
120
+ via the GitHub URL above.
121
+
122
+ ### Manual install (clone the repository)
123
+
124
+ ```powershell
125
+ git clone https://github.com/TLEWA/dsh-sidebar-row-menu.git dsh-sidebar-row-menu
126
+ cd dsh-sidebar-row-menu
127
+ powershell -NoProfile -File .\scripts\install.ps1
128
+ ```
129
+
130
+ The script performs four steps and does not need pnpm:
131
+
132
+ 1. junction `%DSH_HOME%\plugins\dsh-sidebar-row-menu` → this repository
133
+ (the publish point; sources stay editable);
134
+ 2. write `link:../../plugins/dsh-sidebar-row-menu` into the profile's `dependencies`;
135
+ 3. junction `%DSH_HOME%\profiles\<profile>\node_modules\dsh-sidebar-row-menu` → publish point;
136
+ 4. verify the junction resolves to this package's `package.json` and that it has
137
+ `dsh.bundle.patch`, then append the package name to `dsh.profile.bundles`
138
+ (backing up `package.json` first).
139
+
140
+ The default profile is `desktop`; other targets:
141
+
142
+ ```powershell
143
+ powershell -NoProfile -File .\scripts\install.ps1 -Profile both
144
+ powershell -NoProfile -File .\scripts\install.ps1 -Profile 'C:\Users\<you>\.dsh\profiles\web'
145
+ ```
146
+
147
+ After installing:
148
+
149
+ - hard-refresh the UI (`Ctrl+Shift+R`); the console prints
150
+ `[dsh-sidebar-row-menu] installed` from the client half;
151
+ - if right-click still does nothing, restart the desktop app so the host half and
152
+ bundle tree are reloaded together.
153
+
154
+ Self-check (the host route should answer `400 bad-target`):
155
+
156
+ ```powershell
157
+ curl.exe -X POST http://127.0.0.1:10102/dsh-sidebar-row-menu/open `
158
+ -H 'content-type: application/json' -d '{"target":"nope","path":"x"}'
159
+ ```
160
+
161
+ Then right-click a workspace row and a session row beneath it: the menu should
162
+ open at the pointer and look identical to the built-in "…" menu. `Esc` and
163
+ clicking elsewhere close it.
164
+
165
+ Uninstall:
166
+
167
+ ```powershell
168
+ powershell -NoProfile -File .\scripts\install.ps1 -Uninstall
169
+ ```
170
+
171
+ This removes the two junctions, the dependency entry and the bundle entry; the
172
+ repository itself is untouched.
173
+
174
+ > Do not use `dsh plugin add link:<absolute path>`: on Windows pnpm treats `link:`
175
+ > as relative to the profile, and cross-drive paths produce broken links. The
176
+ > script exists to avoid exactly that.
177
+
178
+ ### Switching from the script install to the GitHub install
179
+
180
+ If you installed the development copy with `scripts/install.ps1` and then paste
181
+ the GitHub URL into the Plugins page, pnpm may fail with:
182
+
183
+ ```
184
+ [ERR_PNPM_EPERM] [importPackage ...\node_modules\dsh-sidebar-row-menu]
185
+ EPERM: operation not permitted, rename
186
+ '...\dsh-sidebar-row-menu_tmp_27508_27' -> '...\dsh-sidebar-row-menu'
187
+ ```
188
+
189
+ The script leaves a directory junction inside `node_modules`, and pnpm imports a
190
+ new package by renaming a temporary directory over the target; Windows will not
191
+ replace an existing junction that way. Uninstall the script install first, then
192
+ retry:
193
+
194
+ ```powershell
195
+ powershell -NoProfile -File .\scripts\install.ps1 -Uninstall
196
+ ```
197
+
198
+ If the directory is still there (or a failed attempt left `*_tmp_*` entries),
199
+ remove it manually and retry:
200
+
201
+ ```powershell
202
+ cmd /c rmdir "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-sidebar-row-menu"
203
+ ```
204
+
205
+ A fresh profile never hits this; it only affects the "script install, then
206
+ GitHub install" transition.
207
+
208
+ ## Development
209
+
210
+ ```powershell
211
+ npm run test # normal: node --test, one child process per file
212
+ npm run test:local # restricted terminals / sandboxes: --test-isolation=none
213
+ npm run build # npm pack (prepack runs check first), writes the .tgz
214
+ ```
215
+
216
+ The suite covers host pure functions (path validation, `vscode://file` encoding,
217
+ loopback checks, route status codes) and the client module (module id, exports,
218
+ dependency whitelist, listener install/uninstall, slot registry). Integration
219
+ tests use a fake `__reactFiber$`, DOM and `Menu` host to assert workspace menu
220
+ ordering, session right-click delegating to the native menu, blank rows being
221
+ skipped, and clipboard content for copy-link. Real fibers and services still need
222
+ a manual check in a running GUI.
223
+
224
+ Layout:
225
+
226
+ ```
227
+ lib/index.js host entry: name / inject / apply plus re-exported helpers
228
+ lib/host/security.js loopback request fence
229
+ lib/host/paths.js path validation, vscode://file encoding
230
+ lib/host/launch.js VS Code / Explorer launching
231
+ lib/host/route.js /open route and HTTP status codes
232
+ lib/client.js browser half: fiber lookup, slot registration, menu mount
233
+ cordis.patch.yml bundle patch inserting the plugin into the profile tree
234
+ scripts/install.ps1 pnpm-free install / uninstall
235
+ test/*.test.mjs node:test
236
+ ```
237
+
238
+ ## How it works
239
+
240
+ ### Why fiber props
241
+
242
+ Sidebar rows only expose `data-row-key` (`workspace:<key>` / `session:<id>`); the
243
+ workspace directory, session object and action callbacks are not in the DOM. The
244
+ row components are:
245
+
246
+ - `ProjectRowItem({ group, actions, onCreate, ... })` — `actions` exists only on
247
+ real workspace rows;
248
+ - `SessionNodeItem({ node, onRenameRequest, onOpen, ... })` — `node` looks like
249
+ `{ id, title, blank, running, archived, pinned, updatedAt }`.
250
+
251
+ The plugin reads `__reactFiber$` from the event target during the capture phase of
252
+ `contextmenu`, then walks up to 60 `return` links looking for matching
253
+ `memoizedProps`. If nothing matches it does not intercept at all.
254
+
255
+ ### Why session actions are not hardcoded
256
+
257
+ The native "…" menu is not a hardcoded button list: it is
258
+ `renderSlot('sidebar.workspaces.session.menu.item', ...)`. Fork, pin, archive and
259
+ third-party actions are all slot entries. Slot ownership is enforced by the
260
+ renderer: an entry may only render child slots it declared itself, so a third
261
+ party cannot re-layout someone else's slot.
262
+
263
+ Therefore a session right-click does exactly one thing: find the `Menu` in the
264
+ row's fiber subtree and trigger its anchor (the ellipsis button). The same slot
265
+ content opens. The plugin's own three actions are registered through
266
+ `ctx.slots.inject` + `ctx.slots.register`, so:
267
+
268
+ - they do not depend on built-in fork/pin entries existing;
269
+ - new entries from DSH or other plugins show up automatically;
270
+ - no built-in action is copied or hardcoded.
271
+
272
+ Workspace rows have no such slot, so their menu is still composed by this plugin.
273
+
274
+ ### Why the session menu appears at the pointer
275
+
276
+ The official `Menu` anchors to the ellipsis button, i.e. to the right of it. On
277
+ right-click the plugin temporarily points that button's (and two ancestors')
278
+ `getBoundingClientRect` at the pointer as a `0×0` rect. `Menu` re-reads the anchor
279
+ rect every frame, so the panel lands next to the cursor. The original methods are
280
+ restored as soon as the panel leaves `body`, so the button menu keeps its normal
281
+ position.
282
+
283
+ The "…" menu and the right-click menu share one `Menu` instance and one slot
284
+ content; the only difference is the `rightClickMenuUntil` window — the plugin's
285
+ three entries mount only inside it, and the window is cleared when the menu closes.
286
+
287
+ ### Why the workspace menu is mounted imperatively
288
+
289
+ A contextmenu event is not part of React's render flow. The workspace menu creates
290
+ a `0×0`, `z-index:2147483647` host on demand, `createRoot`s the official `Menu`
291
+ (`portal` plus an explicit `getAnchorRect` pinned to the pointer), and unmounts and
292
+ removes the host on close. The session menu mounts nothing new; it only opens the
293
+ row's existing menu.
294
+
295
+ ### Host route
296
+
297
+ `POST /dsh-sidebar-row-menu/open`, body `{ target: 'vscode' | 'explorer', path }`.
298
+
299
+ - loopback only (socket, Host, `Sec-Fetch-Site` and Origin are all checked);
300
+ - POST only, exact path, body ≤ 64 KB;
301
+ - `path` must be an **existing absolute directory** (relative paths, NUL, files and
302
+ missing paths are rejected) so the host never becomes a generic command runner;
303
+ - VS Code resolution order: `DSH_SCM_VSCODE` → registry
304
+ `HKCR\vscode\shell\open\command` → `%LOCALAPPDATA%` / `%ProgramFiles%`
305
+ `bin\code.cmd` → `PATH`; if none is found it falls back to `rundll32` with
306
+ `vscode://file/...`;
307
+ - spawn uses `detached + stdio:'ignore'` and deliberately does **not** set
308
+ `windowsHide` (otherwise Explorer windows would be hidden).
309
+
310
+ ## Compatibility
311
+
312
+ Built against DSH client `0.2.1-rc.5` (`ProjectRowItem`, `SessionNodeItem`,
313
+ `Menu`). If a DSH upgrade changes those row components or the menu positioning:
314
+
315
+ - workspace right-click silently stops appearing (no error, no UI breakage);
316
+ - session right-click falls back to opening next to the "…" button, with correct content.
317
+
318
+ ## Known limitations
319
+
320
+ - Depends on the props shape of the built-in row components. If DSH changes them,
321
+ right-click silently does nothing.
322
+ - Session right-click depends on the row's `Menu` staying in the fiber subtree. If
323
+ it is not found, the plugin clicks the row-actions ellipsis button; failing that
324
+ it gives up — it never builds a competing menu and never triggers row open.
325
+ - Session "delete" is not offered: DSH officially supports archive (recoverable).
326
+ Deleting records by force tends to leave orphan data. Archive/unarchive is
327
+ handled by the built-in menu entry.
328
+ - The VS Code / Explorer directory for a session comes from `sessions.list`'s
329
+ `cwd`, falling back to the workspace directory. Ungrouped sessions may have no
330
+ directory; in that case a "no directory available" toast is shown.
331
+
332
+ ## License and notices
333
+
334
+ - Code: [MIT](LICENSE).
335
+ - Third-party code and full license texts: [NOTICE.md](NOTICE.md) · [English](NOTICE.en.md).
336
+ - AI usage and code provenance: [AI_USAGE.md](AI_USAGE.md) · [English](AI_USAGE.en.md).
337
+
338
+ Commercial and non-commercial use are both allowed, but the project comes with
339
+ **no warranty** under the MIT terms; review AI-assisted code before relying on it.
package/README.md CHANGED
@@ -1,3 +1,300 @@
1
- # Temporary Holding Version
1
+ # dsh-sidebar-row-menu
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <img src="assets/icon-180.png" width="96" align="right" alt="插件图标" />
4
+
5
+ [![CI](https://github.com/TLEWA/dsh-sidebar-row-menu/actions/workflows/ci.yml/badge.svg)](https://github.com/TLEWA/dsh-sidebar-row-menu/actions/workflows/ci.yml)
6
+ [![Release](https://github.com/TLEWA/dsh-sidebar-row-menu/actions/workflows/release.yml/badge.svg)](https://github.com/TLEWA/dsh-sidebar-row-menu/releases)
7
+
8
+ [简体中文](README.md) · [English](README.en.md)
9
+
10
+ 给 [DeepSeek Harness](https://github.com/deepseek-ai)(DSH)左侧边栏加右键菜单:
11
+
12
+ - **工作区行**:右键弹出菜单(复刻 `dsh-sidebar-context-menu` 的能力);
13
+ - **工作区下层的会话行**:右键在指针处展开该行内置的「…」菜单,并追加本插件的条目。
14
+
15
+ 菜单使用 DSH 官方的 `Menu` 组件渲染,视觉、定位、键盘导航和“点外部关闭”都与内置
16
+ 「…」菜单一致。工作区菜单由本插件组项;会话菜单的内容来自
17
+ `sidebar.workspaces.session.menu.item` slot —— 内置动作和其他插件的动作都在里面,
18
+ 本插件只追加自己的条目,不复制、不硬编码任何内置动作。
19
+
20
+ > 点行尾「…」按钮看到的菜单保持 DSH 原样;本插件自己的三个条目只在右键展开时出现。
21
+ > 右键展开的菜单不会因为鼠标移出而关闭(与工作区右键一致),只有点击外部、选中条目或按 Esc 才关闭。
22
+
23
+ ## 功能
24
+
25
+ ### 工作区行右键
26
+
27
+ | 菜单项 | 行为 |
28
+ | --- | --- |
29
+ | 新会话 | 展开该工作区并新建会话(等价于行尾 `+`) |
30
+ | 重命名 | 打开官方“重命名工作区”对话框 |
31
+ | 使用 VS Code 打开 | 宿主在新窗口打开该工作区目录 |
32
+ | 在资源管理器中打开 | 宿主打开系统文件管理器 |
33
+ | 复制工作区路径 | 复制目录路径到剪贴板 |
34
+ | 在新标签中打开 | 仅在装有 `dsh-project-tabs`(暴露 `openWorkspaceInTab`)时出现 |
35
+ | 删除工作区 | 打开官方删除确认对话框 |
36
+
37
+ ### 会话行右键
38
+
39
+ 右键会话行不会另起一套菜单,而是展开该行自己的「…」菜单:
40
+
41
+ | 来源 | 条目 |
42
+ | --- | --- |
43
+ | DSH 内置 | 重命名、分叉会话、置顶 / 取消置顶、归档 / 取消归档、复制 Session ID |
44
+ | 其他插件 | 它们注册进 `sidebar.workspaces.session.menu.item` 的条目 |
45
+ | 本插件 | 使用 VS Code 打开、在资源管理器中打开、复制会话链接 |
46
+
47
+ 本插件追加的三个条目:
48
+
49
+ | 菜单项 | 行为 |
50
+ | --- | --- |
51
+ | 使用 VS Code 打开 | 优先用会话自己的 `cwd`,取不到则用所属工作区目录 |
52
+ | 在资源管理器中打开 | 同上 |
53
+ | 复制会话链接 | 复制 `?session=<id>` 深链接 |
54
+
55
+ 这三条是**右键专属**:点行尾「…」按钮时它们不挂载。实现上使用一个只在右键展开瞬间
56
+ 有效的窗口标记,窗口外的渲染直接返回 `null`。
57
+
58
+ 草稿会话(还没有任何消息的空白会话)没有内置「…」菜单,本插件同样不接管。
59
+ 非工作区 / 非会话的侧边栏行(如“显示更多”)也不会被拦截。
60
+
61
+ ## 安装
62
+
63
+ 要求:
64
+
65
+ - DSH 桌面版(或 `dsh web`)已经至少启动过一次,profile 目录存在;
66
+ - Windows PowerShell 5.1+;
67
+ - 与 DSH 客户端内置包 `0.2.1-rc.5` 同代的行组件(见[兼容性](#兼容性))。
68
+
69
+ ### 从 GitHub 直接安装(推荐)
70
+
71
+ DSH 桌面端通过 pnpm 安装 Git 依赖;本仓库的 `lib/` 已是可直接运行的产物,安装时
72
+ **不需要本地构建**。
73
+
74
+ 1. 打开侧边栏 **插件** 页 → **安装插件**;
75
+ 2. 粘贴仓库地址并确认:
76
+
77
+ ```
78
+ https://github.com/TLEWA/dsh-sidebar-row-menu
79
+ ```
80
+
81
+ 3. 安装完成后硬刷新(`Ctrl+Shift+R`);宿主半边未生效时重启桌面端。
82
+
83
+ 该地址跟随 `main` 的最新提交。要固定版本,在地址后加标签:
84
+
85
+ ```
86
+ https://github.com/TLEWA/dsh-sidebar-row-menu#v1.3.2
87
+ ```
88
+
89
+ 也可以直接安装 Actions 打出的压缩包(不经过 Git):
90
+
91
+ ```
92
+ https://github.com/TLEWA/dsh-sidebar-row-menu/releases/download/v1.3.2/dsh-sidebar-row-menu-1.3.2.tgz
93
+ ```
94
+
95
+ 命令行等价写法:
96
+
97
+ ```powershell
98
+ dsh plugin --profile desktop add github:TLEWA/dsh-sidebar-row-menu
99
+ ```
100
+
101
+ 自动化:每次 push / PR 由 GitHub Actions 执行语法检查、完整测试和打包校验;推送
102
+ `v*` 标签时自动创建 Release,附带 `dsh-sidebar-row-menu-<version>.tgz` 与
103
+ `SHA256SUMS.txt`。
104
+
105
+ ### 插件市场
106
+
107
+ 面向 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 的
108
+ 提交材料(条目 YAML、预检脚本)只保留在本地,已加入 `.gitignore`,不随本仓库发布;
109
+ 正式提交时只需把条目文件放进上游仓库的一个 PR。收录前请继续使用上面的 GitHub 地址安装。
110
+
111
+ ### 手动安装(克隆仓库)
112
+
113
+ ```powershell
114
+ git clone https://github.com/TLEWA/dsh-sidebar-row-menu.git dsh-sidebar-row-menu
115
+ cd dsh-sidebar-row-menu
116
+ powershell -NoProfile -File .\scripts\install.ps1
117
+ ```
118
+
119
+ 脚本做四件事(不依赖 pnpm):
120
+
121
+ 1. `%DSH_HOME%\plugins\dsh-sidebar-row-menu` → 本仓库(发布点目录联接,源码保持可编辑);
122
+ 2. 在 profile 的 `dependencies` 写 `link:../../plugins/dsh-sidebar-row-menu`;
123
+ 3. `%DSH_HOME%\profiles\<profile>\node_modules\dsh-sidebar-row-menu` → 发布点;
124
+ 4. 校验链接确实解析到本包的 `package.json` 且带 `dsh.bundle.patch`,才把包名追加到
125
+ `dsh.profile.bundles`;写回前备份 `package.json`。
126
+
127
+ 默认安装到 `desktop`,也可以:
128
+
129
+ ```powershell
130
+ powershell -NoProfile -File .\scripts\install.ps1 -Profile both
131
+ powershell -NoProfile -File .\scripts\install.ps1 -Profile 'C:\Users\<you>\.dsh\profiles\web'
132
+ ```
133
+
134
+ 安装完:
135
+
136
+ - 先硬刷新界面(`Ctrl+Shift+R`);客户端半边会在控制台打印
137
+ `[dsh-sidebar-row-menu] installed`;
138
+ - 若右键没有任何反应,再重启桌面应用,让宿主半边和 bundle 树一起重新装载。
139
+
140
+ 自检(宿主路由应返回 `400 bad-target`):
141
+
142
+ ```powershell
143
+ curl.exe -X POST http://127.0.0.1:10102/dsh-sidebar-row-menu/open `
144
+ -H 'content-type: application/json' -d '{"target":"nope","path":"x"}'
145
+ ```
146
+
147
+ 然后在侧边栏分别右键一个工作区行和它下面的会话行:菜单应贴着鼠标弹出,样式与
148
+ 内置「…」菜单一致;`Esc`、点空白处都能关闭。
149
+
150
+ 卸载:
151
+
152
+ ```powershell
153
+ powershell -NoProfile -File .\scripts\install.ps1 -Uninstall
154
+ ```
155
+
156
+ 只移除两个目录联接、依赖项和 bundle 条目,不碰仓库本身。
157
+
158
+ > 不要用 `dsh plugin add link:<绝对路径>`:pnpm 在 Windows 上把 `link:` 当成相对
159
+ > profile 的路径,跨盘时会生成坏链接;脚本正是为了绕开这一点。
160
+
161
+ ### 从脚本安装切换到 GitHub 安装
162
+
163
+ 如果你先用 `scripts/install.ps1` 装过开发版,再在插件页输入 GitHub 地址,pnpm 可能报:
164
+
165
+ ```
166
+ [ERR_PNPM_EPERM] [importPackage ...\node_modules\dsh-sidebar-row-menu]
167
+ EPERM: operation not permitted, rename
168
+ '...\dsh-sidebar-row-menu_tmp_27508_27' -> '...\dsh-sidebar-row-menu'
169
+ ```
170
+
171
+ 原因是脚本在 `node_modules` 里留了一个目录联接,而 pnpm 导入新包时用 rename 覆盖目标;
172
+ Windows 不允许这样替换一个已存在的联接目录。先卸载脚本安装,再重试:
173
+
174
+ ```powershell
175
+ powershell -NoProfile -File .\scripts\install.ps1 -Uninstall
176
+ ```
177
+
178
+ 如果卸载后目录仍在(或安装失败留下了 `*_tmp_*` 目录),手动删除后重试:
179
+
180
+ ```powershell
181
+ cmd /c rmdir "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-sidebar-row-menu"
182
+ ```
183
+
184
+ 全新 profile 不会遇到这个问题;它只影响“先脚本安装、后 GitHub 安装”的切换场景。
185
+
186
+ ## 开发
187
+
188
+ ```powershell
189
+ npm run test # 常规:node --test,逐文件子进程
190
+ npm run test:local # 受限终端 / 沙箱:--test-isolation=none,同进程跑
191
+ npm run build # npm pack(prepack 会先跑 check),产出 .tgz
192
+ ```
193
+
194
+ 测试覆盖宿主侧纯函数(路径校验、`vscode://file` 编码、loopback 判定、路由状态码)
195
+ 和客户端模块(模块 id、导出、依赖白名单、监听器安装/卸载、slot 注册表),并用伪造的
196
+ `__reactFiber$`、DOM 与 `Menu` 宿主做集成测试:工作区右键的菜单项顺序、会话右键是否
197
+ 展开内置菜单而不是自建菜单、草稿行是否被放过、复制链接的剪贴板内容都在断言里。
198
+ 真实 fiber 与服务仍需在运行中的 GUI 里做人工验证。
199
+
200
+ 目录:
201
+
202
+ ```
203
+ lib/index.js 宿主入口:name / inject / apply,再导出可测试的纯函数
204
+ lib/host/security.js loopback 请求围栏
205
+ lib/host/paths.js 路径校验、vscode://file 编码
206
+ lib/host/launch.js VS Code / 资源管理器启动
207
+ lib/host/route.js /open 路由与 HTTP 状态码
208
+ lib/client.js 客户端半边:fiber 解析、slot 注册、菜单挂载
209
+ cordis.patch.yml bundle patch:把插件插进 profile 插件树
210
+ scripts/install.ps1 无 pnpm 的安装 / 卸载脚本
211
+ test/*.test.mjs node:test
212
+ ```
213
+
214
+ ## 实现说明
215
+
216
+ ### 为什么从 fiber 取数据
217
+
218
+ 侧边栏行只暴露 `data-row-key`(`workspace:<key>` / `session:<id>`),工作区目录、
219
+ 会话对象和动作回调都不在 DOM 上。行组件是:
220
+
221
+ - `ProjectRowItem({ group, actions, onCreate, ... })`,`actions` 仅在真实工作区行存在;
222
+ - `SessionNodeItem({ node, onRenameRequest, onOpen, ... })`,`node` 形如
223
+ `{ id, title, blank, running, archived, pinned, updatedAt }`。
224
+
225
+ 插件在 `contextmenu` 捕获阶段从目标节点拿 `__reactFiber$`,向上最多 60 层找匹配的
226
+ `memoizedProps`。找不到就完全不拦截,避免影响其他行和其他插件。
227
+
228
+ ### 会话行为什么不硬编码
229
+
230
+ 内置「…」菜单不是硬编码的按钮列表,而是
231
+ `renderSlot('sidebar.workspaces.session.menu.item', ...)` 的结果;内置的分叉、置顶、
232
+ 归档,以及第三方插件的能力,都以 slot 条目形式注册。slot 的所有权由渲染器校验:
233
+ 每个条目只能渲染自己声明过的子 slot,第三方无法直接把手伸进别人的 slot 重新排版。
234
+
235
+ 因此会话行右键只做一件事:在行组件的 fiber 子树里找到那个 `Menu`,触发它 anchor
236
+ (省略号按钮)的点击,展开的自然是同一份 slot 内容。本插件自己的三个动作也通过
237
+ `ctx.slots.inject` + `ctx.slots.register` 注册进去,所以:
238
+
239
+ - 不依赖「分叉」「置顶」这些内置条目是否存在;
240
+ - 内置或别的插件以后新增条目,右键菜单自动出现;
241
+ - 不复制、不硬编码任何内置动作。
242
+
243
+ 工作区行没有这样的 slot,所以工作区菜单仍由本插件自己组项。
244
+
245
+ ### 为什么会话菜单能贴着鼠标
246
+
247
+ 官方 `Menu` 的 `anchor` 是那个省略号按钮,默认位置就在按钮右侧。右键时插件临时把
248
+ 该按钮及其两层祖先的 `getBoundingClientRect` 指到指针位置(`0×0` 矩形),官方 `Menu`
249
+ 每帧读取锚点 rect 重新定位,于是面板出现在鼠标旁;面板从 `body` 移除时立即还原原始
250
+ 方法,不影响按钮菜单的默认位置。
251
+
252
+ 「…」按钮菜单与右键菜单共用同一个 `Menu` 实例和同一份 slot 内容,区别只在
253
+ `rightClickMenuUntil` 窗口:本插件三条只在窗口内挂载,窗口随菜单关闭一并清零。
254
+
255
+ ### 为什么菜单是命令式挂载
256
+
257
+ 右键事件不是 React 渲染流的一部分。工作区菜单按需创建一个 `0×0`、
258
+ `z-index:2147483647` 的容器,`createRoot` 渲染官方 `Menu`(`portal` + 显式
259
+ `getAnchorRect` 钉在鼠标位置),关闭时 `unmount()` 并移除容器。会话菜单不挂载任何
260
+ 新容器,只是打开行内已有的官方菜单。
261
+
262
+ ### 宿主路由
263
+
264
+ `POST /dsh-sidebar-row-menu/open`,body `{ target: 'vscode' | 'explorer', path }`。
265
+
266
+ - 只接受 loopback 请求(socket、Host、`Sec-Fetch-Site`、Origin 四重校验);
267
+ - 只接受 POST,路径必须精确匹配,body ≤ 64 KB;
268
+ - `path` 必须是**已存在的绝对目录**(拒绝相对路径、NUL、文件、不存在的路径),
269
+ 避免把任意命令交给宿主;
270
+ - VS Code 解析顺序:`DSH_SCM_VSCODE` → 注册表 `HKCR\vscode\shell\open\command`
271
+ → `%LOCALAPPDATA%` / `%ProgramFiles%` 下的 `bin\code.cmd` → `PATH`;
272
+ 都找不到时退回 `rundll32` 打开 `vscode://file/...`;
273
+ - spawn 用 `detached + stdio:'ignore'`,不设 `windowsHide`(否则资源管理器窗口会被隐藏)。
274
+
275
+ ## 兼容性
276
+
277
+ 按 DSH 客户端 `0.2.1-rc.5` 的 `ProjectRowItem` / `SessionNodeItem` / `Menu` 实现。
278
+ DSH 升级若改动行组件或菜单定位实现:
279
+
280
+ - 工作区右键会静默不弹(不会报错、不影响原界面);
281
+ - 会话右键会退回行尾「…」按钮旁,内容仍然正确。
282
+
283
+ ## 已知限制
284
+
285
+ - 依赖 DSH 内置行组件的 props 形状。DSH 升级若改了这两个组件,右键会静默不弹。
286
+ - 会话右键依赖行内 `Menu` 组件仍在 fiber 子树里。找不到时退回点击行内操作区的
287
+ 省略号按钮,再找不到就放弃 —— 不会自建菜单,也不会误触行的打开动作。
288
+ - 本插件不提供会话“删除”:DSH 官方只支持归档,归档后可恢复;强行删记录容易留下
289
+ 孤儿数据。会话的归档 / 取消归档由内置菜单条目负责。
290
+ - 会话行右键的 VS Code / 资源管理器目录来自 `sessions.list` 的 `cwd`,取不到时退回
291
+ 所属工作区目录;未分组会话可能没有目录,此时会提示“没有可用的目录路径”。
292
+
293
+ ## 许可与声明
294
+
295
+ - 代码:[MIT](LICENSE)。
296
+ - 第三方代码引用与许可证全文:[NOTICE.md](NOTICE.md) · [English](NOTICE.en.md)。
297
+ - AI 使用与代码来源声明:[AI_USAGE.md](AI_USAGE.md) · [English](AI_USAGE.en.md)。
298
+
299
+ 本项目允许用于商业与非商业场景,但按 MIT 条款**不提供任何担保**;AI 辅助生成的
300
+ 代码请在采用前自行审查。
Binary file
@@ -0,0 +1,5 @@
1
+ # 作为 profile bundle patch 层,把本插件插进插件清单。
2
+ # 安装方式见 README.md / scripts/install.ps1。
3
+ - insert:
4
+ - id: sidebar-row-menu
5
+ name: 'dsh-sidebar-row-menu'