@codeasier/dsh-plugin-orca-projects 0.0.0-stage → 0.1.1

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 codeasier
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,291 @@
1
- # Temporary Holding Version
1
+ # @codeasier/dsh-plugin-orca-projects
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
+ An Orca-like project sidebar for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
4
+ (`dsh`) Web and Desktop client. It adds a fourth **Orca-like** grouping mode to
5
+ the sidebar view options: projects are the top-level rows, a pinned session
6
+ shelf sits above them, projects can be moved into custom groups, and a Git
7
+ repository's main checkout plus its linked worktrees collapse into one project.
8
+
9
+ This is a community plugin for
10
+ [codeasier/dsh-plugins](https://github.com/codeasier/dsh-plugins). It ships a
11
+ bundle patch, localized display metadata, an original icon, and an
12
+ [`engines.dsh`](https://github.com/codeasier/dsh-plugins/blob/main/docs/manifest-reference.md#compatibility)
13
+ compatibility range, so it installs, updates, and is versioned independently of
14
+ every other plugin in this repository.
15
+
16
+ ## What it does
17
+
18
+ Open the sidebar view options (the sliders button next to **项目**), choose
19
+ **Orca-like**, then click a project row to reveal its sessions.
20
+
21
+ - **Project-first grouping.** The sidebar lists projects (Git repositories),
22
+ not directory levels. The main checkout and every linked worktree, including
23
+ Orca's `~/orca/workspaces/<project>/<name>` layout and nested
24
+ `.worktrees/<name>` directories, appear under one project row. A layers badge
25
+ shows how many worktrees feed that project, and the project menu can start a
26
+ session in any one of them. The Host also discovers worktrees from
27
+ `.git/worktrees` even when DSH has no workspace for them; starting a session
28
+ in one registers its directory. A project's `...` menu also renames the
29
+ project label locally and deletes every workspace registration that belongs
30
+ to it.
31
+ - **Pinned shelf.** Pin a session from its hover pin button or its `...` menu.
32
+ It moves into the **已置顶** group at the very top. Under its project the same
33
+ session stays in place, grayed, with a **置顶** badge. Opening a pinned session
34
+ does not expand its project; use the pinned row's `...` menu → **在项目中显示**
35
+ to expand the project and scroll to the original row. Unpin it and it is an
36
+ ordinary project session again. A long shelf scrolls inside a bounded area so
37
+ it cannot push every project below the fold.
38
+ - **Compact session cards.** Cross-project sessions use two lines: a title,
39
+ then worktree and project chips. Project, pinned, flat, and search rows share
40
+ the same geometry, with the project chip only where the project is not already
41
+ the surrounding header. Rows without metadata collapse to one line. Pinned,
42
+ project, loose-workspace, flat, and search sessions share one raised container
43
+ per section with internal hairline separators, rather than one bordered card
44
+ per session; group and project headers are lightweight folding cards. Reduced
45
+ indentation and full-width titles keep the sidebar readable at narrow widths;
46
+ hover actions overlay the row instead of permanently reserving title space.
47
+ - **Worktree labels.** Session chips use the Host-resolved checkout identity,
48
+ including worktrees in arbitrary directories. Ordinary subdirectories inherit
49
+ their checkout's label. Without a resolved identity, the client recognizes
50
+ paths such as `.worktrees/feature-a` or Orca's `workspaces/<project>/2.0-review`.
51
+ Cross-project, pinned, and flat cards always show the label; project cards
52
+ show a named worktree when it is not already the project title, and omit the
53
+ implicit `main`. Unlike a path-only heuristic, the Host half reads the
54
+ workspace root's `.git` file and its `commondir` pointer, so a worktree in an
55
+ arbitrary directory still joins the repository it belongs to.
56
+ - **Live status and active filter.** Running sessions show an animated yellow
57
+ spinner, waiting-for-user interactions an amber dot, finished-but-unviewed
58
+ completions a green dot, and inactive sessions a gray dot. In Orca-like mode,
59
+ View options → **仅活跃会话** hides every non-active session and project; the
60
+ resulting empty state offers **查看全部会话** to switch the filter off. Waiting
61
+ takes precedence over running. Filtering never changes a visible project's
62
+ worktree membership, main workspace, or action targets. Status glyphs expose
63
+ localized labels and tooltips; disclosure controls expose `aria-expanded`, and
64
+ the current session exposes `aria-current` for keyboard and assistive-technology
65
+ navigation.
66
+ - **Custom groups.** Use a project's `...` menu → **移动到分组** to create a group
67
+ or move the project into one. You can also drag a project onto a group. Group
68
+ headers can be renamed, deleted, and used to add projects; deleting a group
69
+ returns its projects to **未分组**.
70
+ - **The other grouping modes remain available** in the same menu: **按工作区**,
71
+ **按工作区树**, **单列表**, plus **Orca-like**. Sort by recent updates or manual
72
+ order; filter archived sessions; search project and session titles. Orca-like
73
+ sorting and dragging work before any custom group is created. Sessions outside
74
+ registered workspaces remain accessible in grouped and workspace-tree views.
75
+ In the **Unassigned sessions** section they are grouped by workspace (or by
76
+ `cwd` when no workspace matches). Rows inside a group show only their checkout
77
+ label because the group already names the workspace. A pinned row stays in
78
+ its group, grayed with an **已置顶** badge and its project chip, and also
79
+ appears in the pinned shelf — the same treatment as pinned sessions under a
80
+ registered project.
81
+ - **External session migration.** In Orca-like mode, **Migrate unassigned
82
+ sessions…** matches those sessions to projects by `cwd` (longest project or
83
+ worktree path) and previews the matched and unmatched counts. It writes only a
84
+ browser-local `sessionId → projectId` mapping; DSH workspaces, `sessionIds`,
85
+ and session ownership stay unchanged. **Undo session migration** clears the
86
+ mapping.
87
+ - **Session actions** include pin/unpin, archive/unarchive, open, and copy the
88
+ Session ID. Project actions include a new session (per worktree), open the
89
+ main workspace, rename the project label, delete the project, and move it to
90
+ a group.
91
+ - **Persistence.** Custom groups, assignments, manual project/session order,
92
+ external session-to-project mappings, collapse state, and view options are
93
+ saved in the browser's `localStorage`
94
+ under `dsh.orca-projects.v1` for the current DSH origin. Pins and archived
95
+ state are Host-owned and shared with every sidebar surface.
96
+
97
+ ### How it fits
98
+
99
+ DSH exposes the sidebar's browsing region as a replaceable slot but has no
100
+ public "add a grouping mode" hook. The plugin therefore registers an alternative
101
+ occupant of `sidebar.workspaces` at priority `-1`, shadowing the shipped browser,
102
+ and re-creates the view-options menu with the extra mode. If this plugin crashes,
103
+ the slot renderer falls back to the shipped browser. The shipped browser's
104
+ per-row extension slots are not rendered by this sidebar in this version.
105
+ The plugin observes the shipped browser's injected shortcut source, so DSH's
106
+ `session.search` command opens and focuses this search field without replacing
107
+ its default or user-configured key bindings.
108
+
109
+ The browser cannot read `.git` directly. A small Host half registers one
110
+ authenticated fetch route, `/api/orca-projects/resolve`, through the existing
111
+ Connection service. It resolves each registered workspace path by reading
112
+ `.git` and `commondir` with Node's filesystem APIs, then returns the canonical
113
+ main-checkout path, title, and worktree name. The browser groups workspaces by
114
+ that key. The browser uses a document-relative URL so subpath deployments keep
115
+ DSH's mount prefix. The Host distinguishes confirmed non-repositories from
116
+ missing paths and resolution errors: existing non-Git directories stay separate,
117
+ while missing paths, errors, and an unavailable route retain the path-based
118
+ fallback for nested `.worktrees` directories and Orca workspace folders.
119
+
120
+ The migration tool is another overlay: it keeps `sessionId → projectId` in
121
+ `localStorage`, so an unassigned session can appear under a project without
122
+ being attached to that project's DSH workspace. Other clients and DSH's
123
+ workspace registry keep their original state.
124
+
125
+ ## Install
126
+
127
+ ### DeepSeek Harness CLI
128
+
129
+ ```sh
130
+ dsh plugin --profile web add @codeasier/dsh-plugin-orca-projects
131
+ ```
132
+
133
+ Restart the app when the profile does not run with HMR.
134
+
135
+ ### DeepSeek Harness Desktop
136
+
137
+ Open **Plugins** in the Desktop window and install
138
+ `@codeasier/dsh-plugin-orca-projects`, or use the command runtime bundled with
139
+ the app. The npm `dsh` CLI cannot manage the Electron-owned `desktop` profile.
140
+ See [Install on Desktop](https://github.com/codeasier/dsh-plugins/blob/main/docs/install/desktop.md).
141
+
142
+ ### From this checkout
143
+
144
+ ```sh
145
+ pnpm install && pnpm build
146
+ pnpm install:local dsh-plugin-orca-projects --profile web
147
+ ```
148
+
149
+ ## Configuration
150
+
151
+ The plugin has no Host `Config` schema and no tool. Its user state is
152
+ client-local:
153
+
154
+ | Storage | Key | Contents |
155
+ |---|---|---|
156
+ | `localStorage` | `dsh.orca-projects.v1` | Grouping mode, sort/filter, custom groups, project assignments, project names, external session mappings, project and session order, collapse state |
157
+
158
+ Pins and archived sessions are not stored here; they live in the workspace
159
+ controller and apply to every sidebar surface.
160
+
161
+ Disable the bundle row in the profile's `cordis.patch.yml` to return to the
162
+ shipped sidebar:
163
+
164
+ ```yaml
165
+ - id: orca-projects
166
+ name: '@codeasier/dsh-plugin-orca-projects'
167
+ disabled: true
168
+ ```
169
+
170
+ ## Compatibility
171
+
172
+ | Plugin | DeepSeek Harness | Node.js |
173
+ |---|---|---|
174
+ | `0.1.x` | `>=0.2.2-rc.1 <0.3.0` | `>=22.18.0` |
175
+
176
+ The plugin has a Web client half plus a small Host half that resolves repository
177
+ identity. DeepSeek Harness Desktop serves the same Web client and Host services,
178
+ so a Desktop window gets the same sidebar. Verified in the Web client at DSH
179
+ 0.2.2-rc.1; see [Verification](#verification).
180
+
181
+ ## Verification
182
+
183
+ - `pnpm check` passes (lint, typecheck, tests, build, conventions, docs, packs).
184
+ - The client bundle registers the loader id, locale namespace, and
185
+ `sidebar.workspaces` occupant; behavior tests cover the grouping model,
186
+ pin-shelf duplication, custom-group move/delete, archived filters, blank
187
+ sessions, search, manual order, persisted-state sanitization, worktree
188
+ consolidation, group assignment through a member path, the path-based
189
+ fallback, and project names. `src/repo.ts` is tested against temporary main
190
+ checkouts and linked worktrees, including an Orca-style path.
191
+ - Review-follow-up regressions cover simultaneous running/waiting status, loose
192
+ sessions in grouped/tree views, sorting/dragging without groups, stable active
193
+ project membership, resolved checkout labels in all modes, explicit negative
194
+ repository probes, subpath URLs, the shipped search-command bridge with the
195
+ real slot-entry shape, and stale worktree records with missing or foreign
196
+ checkout backlinks. These use server-rendered markup and fake service/shortcut
197
+ sources; the final build was also reinstalled in a scratch Web profile to
198
+ check the results in a real page. Expansion, current-session, and live-status
199
+ accessibility semantics have server-rendered regressions.
200
+ - The visual refinement was rendered at a 264px sidebar width in light and dark
201
+ themes with 22 projects and seven pinned sessions. The shelf remained bounded
202
+ and scrollable, ordinary loose-session rows showed no redundant project chip,
203
+ project/group/session nesting stayed within the narrow column, and no slot
204
+ errors appeared. Hover actions, keyboard disclosure with Enter, search and
205
+ Escape, current-project/current-session markers, and loose workspace groups
206
+ were exercised in the page.
207
+ - Earlier manual checks in a scratch Web profile at DSH 0.2.2-rc.1: Orca-like mode in the
208
+ view-options menu; project expansion; pin → shelf and gray project row; unpin
209
+ → restored row; create/rename/delete group; move project by menu and by drag;
210
+ reload persistence; search; archive/unarchive; flat, workspace, and tree modes;
211
+ light and dark themes; sidebar collapse/expand. Also checked: a pinned row
212
+ opens without expanding its project, **在项目中显示** expands and scrolls to
213
+ the original row, worktree badges resolve to `main`, `v0.16.1-patch`, and
214
+ `2.0-review`, and the type scale matches the shipped sidebar's 14px project
215
+ and session titles.
216
+ - Worktree consolidation was rendered with the real registered workspaces in a
217
+ scratch profile: the `msinsight` main checkout and its four Orca worktrees
218
+ formed one project with a `5` worktree badge, and `dsh-TUI` plus its four
219
+ `.worktrees` entries formed another with a `5` badge. The `dsh-plugins`
220
+ project had only its main workspace registered; the Host found its three
221
+ additional `.git/worktrees` checkouts and the row showed a `4` badge with all
222
+ four choices in the project menu, without creating workspaces just to list
223
+ them. Sessions outside every registered workspace appeared in a separate,
224
+ collapsed **Unassigned sessions** section, not as an unassignable project;
225
+ expanding it showed 18 collapsible workspace groups (for example
226
+ `cc-workspace` with 58 sessions) rather than one flat list, and expanding a
227
+ group showed its checkout label with the project chip omitted; pinning one
228
+ kept it in the group, grayed with an **已置顶** badge and its project chip, and
229
+ added it to the pinned shelf. The migration dialog
230
+ detected 183 of those 193 sessions across 10 projects, applied the external
231
+ mapping (leaving 10 unmatched), and the Undo action restored all 193. The
232
+ project menu listed
233
+ each worktree, renaming the project label persisted, and moving the project
234
+ into a custom group kept it as one row. The two stale `.worktrees` entries
235
+ whose directories no longer exist still grouped through the fallback.
236
+ - The Desktop window was not driven separately in this checkout; it uses the
237
+ same client artifact. Installing into the Electron-owned `desktop` profile is
238
+ a separate user action.
239
+
240
+ ## Limitations
241
+
242
+ - The plugin shadows the shipped workspace browser. The shipped browser's
243
+ session-row action extension slot (`sidebar.workspaces.session.row.action`)
244
+ and its hover cards are not rendered here.
245
+ - Search is local to the loaded session summaries (title, project path, and
246
+ working directory). It does not query message content on the Host.
247
+ - Custom groups are browser-local and do not sync across devices or profiles.
248
+ - Worktree identity is read from a `.git` entry at the workspace root; the Host
249
+ does not scan parent directories. A workspace without its own `.git` entry
250
+ stays a separate project, and a submodule is not merged into its enclosing
251
+ repository. Discovery of unregistered checkouts reads `.git/worktrees`; a
252
+ checkout is listed only while its directory exists and its `.git` file points
253
+ back to the same worktree record. Stale records are omitted even when their
254
+ old path has been reused by an ordinary directory or another repository. If the
255
+ Host route is unavailable, only the path patterns `.worktrees/`,
256
+ `.worktree/`, `worktrees/`, and Orca's `workspaces/<project>/<worktree>`
257
+ consolidate.
258
+ - Worktree consolidation and the external session migration apply to Orca-like
259
+ mode. The workspace and workspace-tree modes intentionally keep DSH's
260
+ directory-based grouping and ignore the migration mapping.
261
+ - The migration tool matches by `cwd` and only covers currently visible
262
+ sessions; it is a browser-local overlay, not a change to DSH's
263
+ `workspace.sessionIds`. It cannot attach an arbitrary session to a workspace
264
+ whose path differs from the session's `cwd`.
265
+ - Deleting a consolidated project removes every workspace registration that
266
+ belongs to it; files and sessions are kept. There is no per-worktree removal
267
+ action in this version.
268
+ - Green marks a finished-but-unviewed completion; an idle session whose
269
+ completion was already viewed returns to gray. **Active** for the filter means
270
+ running or waiting for a user interaction, not merely completed.
271
+ - Adding a project requires a working `ctx.uiWorkspace.pickDirectory()`. A
272
+ remote browser without the host directory picker cannot add projects.
273
+ - This version does not offer session rename, fork, or delete; use the
274
+ conversation surface or re-enable the shipped sidebar for those actions.
275
+
276
+ ## Develop
277
+
278
+ ```sh
279
+ pnpm --filter @codeasier/dsh-plugin-orca-projects build
280
+ pnpm --filter @codeasier/dsh-plugin-orca-projects test
281
+ pnpm --filter @codeasier/dsh-plugin-orca-projects typecheck
282
+ ```
283
+
284
+ Read [Plugin anatomy](https://github.com/codeasier/dsh-plugins/blob/main/docs/plugin-anatomy.md)
285
+ and [Client UI](https://github.com/codeasier/dsh-plugins/blob/main/docs/client-ui.md)
286
+ before extending the plugin. `client.js` is hand-written loader code; keep the
287
+ loader factory self-contained and run `node --check client.js` after editing it.
288
+
289
+ ## License
290
+
291
+ MIT
package/README.zh.md ADDED
@@ -0,0 +1,109 @@
1
+ # @codeasier/dsh-plugin-orca-projects
2
+
3
+ 面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(`dsh`)Web 与 Desktop 客户端的 Orca 风格项目侧栏。它在侧栏的视图选项中增加第四个 **Orca-like** 分组模式:项目是最上层的行,顶部有置顶会话架,项目可以移动到自定义分组;同一个 Git 仓库的主检出和所有 linked worktree 会收拢为一个项目。
4
+
5
+ 这是 [codeasier/dsh-plugins](https://github.com/codeasier/dsh-plugins) 的社区插件。它包含 bundle patch、本地化显示元数据、原创图标和 [`engines.dsh`](https://github.com/codeasier/dsh-plugins/blob/main/docs/manifest-reference.md#compatibility) 兼容范围,可以独立安装、更新和发布。
6
+
7
+ ## 功能
8
+
9
+ 打开侧栏视图选项(**项目**旁的滑块按钮),选择 **Orca-like**,然后点击项目行展开会话。
10
+
11
+ - **按项目分组。**侧栏以项目(Git 仓库)为单位,而不是目录层级。主检出和每个 linked worktree 都归入同一个项目行,包括 Orca 的 `~/orca/workspaces/<project>/<name>` 布局和嵌套的 `.worktrees/<name>` 目录。layers 徽标显示该项目包含多少个 worktree;项目菜单可以在指定 worktree 中新建会话。Host 还会从 `.git/worktrees` 发现 DSH 尚未注册的 worktree;在其中新建会话时会注册该目录。项目的 `...` 菜单还可以本地重命名项目,或删除该项目名下的全部 workspace 注册。
12
+ - **置顶会话架。**在会话悬浮按钮或 `...` 菜单中选择置顶。会话会移动到最顶部的 **已置顶**分组;在所属项目中,原会话仍然保留,但显示为灰色并带有 **置顶**标记。打开置顶会话不会展开其所在项目;使用置顶行 `...` 菜单中的 **在项目中显示**才会展开项目并滚动到原位置。取消置顶后,它恢复为普通项目会话。置顶较多时,会话架在限高区域内独立滚动,不会把全部项目挤出首屏。
13
+ - **紧凑会话卡片。**跨项目会话使用两行卡片:标题行,以及 worktree 和项目标签。项目、置顶、单列表和搜索结果使用同一套卡片布局;当项目已经是周围标题时,不再重复显示项目标签;没有元信息的行自动压缩为单行。置顶、项目、未归属 workspace、单列表和搜索结果的会话共享各自区域的统一容器,内部使用细分隔线,而不是每条会话一个边框卡片;分组和项目标题使用轻量折叠卡片。更浅的缩进和完整标题宽度提升窄侧栏的可读性;悬浮操作覆盖在行上,不再永久占用标题空间。
14
+ - **Worktree 标签。**会话标签优先使用 Host 解析的 checkout 身份,包括位于任意目录的 worktree;普通子目录继承所属 checkout 的标签。没有身份信息时,才使用 `.worktrees/feature-a` 或 Orca 的 `workspaces/<project>/2.0-review` 等路径规则兜底。跨项目、置顶和单列表卡片始终显示该标签;项目卡片只在 worktree 名称与项目标题不同时显示,并省略隐含的 `main`。与纯路径推断不同,Host 半会读取工作区根目录的 `.git` 文件及其 `commondir` 指针,因此位于任意目录的 worktree 仍然会归入它所属的仓库。
15
+ - **实时状态与活跃过滤。**运行中的会话显示黄色动画 spinner,等待用户交互的会话显示琥珀色圆点,已完成但未查看的会话显示绿色圆点,未活跃会话显示灰色圆点。在 Orca-like 模式下,视图选项 → **仅活跃会话**会隐藏所有非活跃会话和项目;空状态提供 **查看全部会话**以关闭过滤。等待用户交互的状态优先于运行中;过滤不会改变可见项目的 worktree 成员、主工作区或操作目标。状态图标提供中文标签和提示;折叠控件提供 `aria-expanded`,当前会话提供 `aria-current`,便于键盘和辅助技术导航。
16
+ - **自定义分组。**使用项目 `...` 菜单 → **移动到分组**创建分组或移动项目;也可以把项目拖到分组上。分组标题可以重命名、删除和用于添加项目;删除分组会把项目移回 **未分组**。
17
+ - **其他分组模式仍然可用。**同一菜单中还有 **按工作区**、**按工作区树**、**单列表** 和 **Orca-like**。可以按最近更新或手动排序、过滤已归档会话,以及搜索项目和会话标题。Orca-like 无需先创建自定义组即可排序和拖动;未归属已注册工作区的会话显示在独立的 **未归属会话** 区域,而不是一个合成项目;区域内部按 workspace/目录分组(没有匹配 workspace 时按 `cwd`),每个分组可折叠,而不是一个平铺列表;分组内的会话行只显示 checkout 标签,因为分组标题已经写明 workspace;置顶的行仍留在分组内,灰色显示并带 **已置顶** 标记和项目标签,同时出现在已置顶区域,与已注册项目下会话的置顶表现一致。Orca-like 模式下可使用 **迁移未归属会话…**:按 `cwd` 匹配最近的项目/worktree 路径,预览可迁移和无法匹配的数量,然后写入浏览器本地的 `sessionId → projectId` 外挂映射;可在视图菜单中用 **撤销会话迁移** 回退。该操作不会修改 DSH workspace 或 `sessionIds`。
18
+ - **会话操作。**置顶/取消置顶、归档/取消归档、打开、复制 Session ID。项目操作包括在指定 worktree 新建会话、打开主工作区、重命名项目标签、删除项目和移动到分组。
19
+ - **持久化。**自定义分组、分配、项目/会话手动顺序、未归属会话的外挂项目映射、折叠状态和视图选项保存在当前 DSH origin 的浏览器 `localStorage` 中,键为 `dsh.orca-projects.v1`。置顶和归档状态由 Host 管理,并在所有侧栏界面之间共享。
20
+
21
+ ### 工作原理
22
+
23
+ DSH 把侧栏的浏览区域暴露为可替换 slot,但没有公开的“新增分组模式”钩子。插件因此在 `sidebar.workspaces` 上注册一个优先级为 `-1` 的替代占用者,遮蔽内置浏览器,并重新创建带额外模式的视图选项菜单。如果插件崩溃,slot 渲染器会回退到内置浏览器。内置浏览器的逐行操作扩展 slot 不会在这个版本中渲染。插件观察内置浏览器注入的快捷键状态源,让 DSH 的 `session.search` 命令展开并聚焦此搜索框,不替换默认或用户自定义的按键绑定。
24
+
25
+ 浏览器无法直接读取 `.git`。一个很小的 Host 半通过现有 Connection 服务注册认证路由`/api/orca-projects/resolve`,使用 Node 文件系统 API 读取每个 workspace 路径的`.git` 和 `commondir`,返回规范的主检出路径、标题、worktree 名称,以及 `.git/worktrees` 下的全部 checkout。浏览器按该 key 合并 workspace,把未注册的 checkout 加入项目的 worktree 数量和菜单;迁移工具把 `sessionId → projectId` 写入 `localStorage`,不会把会话附加到 DSH workspace,因此其他客户端和 DSH 注册表保持原状。请求使用相对 document base 的 URL 保留子路径部署前缀。Host 区分已确认的非仓库、路径不存在和解析失败:已存在的非 Git 目录保持独立,路径不存在、解析失败或路由不可用时才保留针对嵌套 `.worktrees` 目录和 Orca 工作区目录的路径兜底。
26
+
27
+ ## 安装
28
+
29
+ ### DeepSeek Harness CLI
30
+
31
+ ```sh
32
+ dsh plugin --profile web add @codeasier/dsh-plugin-orca-projects
33
+ ```
34
+
35
+ 如果 profile 没有启用 HMR,安装后请重启应用。
36
+
37
+ ### DeepSeek Harness Desktop
38
+
39
+ 在 Desktop 窗口中打开 **插件**并安装`@codeasier/dsh-plugin-orca-projects`,或使用应用内置的命令运行时。npm 的 `dsh` CLI 不能管理由 Electron 持有的 `desktop` profile。参见[安装到 Desktop](https://github.com/codeasier/dsh-plugins/blob/main/docs/install/desktop.md)。
40
+
41
+ ### 从当前 checkout 安装
42
+
43
+ ```sh
44
+ pnpm install && pnpm build
45
+ pnpm install:local dsh-plugin-orca-projects --profile web
46
+ ```
47
+
48
+ ## 配置
49
+
50
+ 插件没有 Host `Config` schema,也没有工具。用户状态保存在客户端:
51
+
52
+ | 存储 | Key | 内容 |
53
+ |---|---|---|
54
+ | `localStorage` | `dsh.orca-projects.v1` | 分组模式、排序/过滤、自定义分组、项目分配、项目名称、未归属会话的外挂项目映射、项目/会话顺序、折叠状态 |
55
+
56
+ 置顶和归档会话不保存在这里;它们位于 workspace controller,并作用于所有侧栏界面。
57
+
58
+ 在 profile 的 `cordis.patch.yml` 中禁用 bundle 行即可回到内置侧栏:
59
+
60
+ ```yaml
61
+ - id: orca-projects
62
+ name: '@codeasier/dsh-plugin-orca-projects'
63
+ disabled: true
64
+ ```
65
+
66
+ ## 兼容性
67
+
68
+ | 插件 | DeepSeek Harness | Node.js |
69
+ |---|---|---|
70
+ | `0.1.x` | `>=0.2.2-rc.1 <0.3.0` | `>=22.18.0` |
71
+
72
+ 插件包含 Web 客户端半和一个小型 Host 半,用于解析仓库身份。DeepSeek Harness Desktop 提供相同的 Web 客户端和 Host 服务,因此 Desktop 窗口获得相同的侧栏。已在DSH 0.2.2-rc.1 的 Web 客户端验证;见 [验证](#验证)。
73
+
74
+ ## 验证
75
+
76
+ - `pnpm check` 通过(lint、类型检查、测试、构建、约定、文档和打包检查)。
77
+ - 客户端 bundle 注册了 loader id、locale namespace 和 `sidebar.workspaces` 占用者;行为测试覆盖分组模型、置顶架重复显示、自定义分组移动/删除、归档过滤、空白会话、搜索、手动顺序、持久化状态清洗、worktree 合并、通过成员路径分组、路径兜底和项目名称。`src/repo.ts` 使用临时主检出和 linked worktree(包括 Orca 风格路径)测试。
78
+ - 评审跟进回归覆盖同时运行与等待交互、分组/树模式中的未归属会话、无自定义组时的排序与拖动、活跃过滤下完整的项目成员、各模式的 checkout 标签、明确的非仓库/不存在/失败结果、子路径 URL、使用真实 slot 条目形状的内置搜索命令桥接,以及 checkout 回链缺失或指向其他仓库的陈旧 worktree 记录。这些检查使用服务端渲染及假的服务/快捷键状态源;最终构建也已在临时 Web profile 中重新安装并在真实页面检查。折叠、当前会话和实时状态的可访问性语义也有服务端渲染回归。
79
+ - 视觉优化已在 264px 侧栏宽度下用 22 个项目和 7 条置顶会话验证浅色、深色主题。置顶架保持限高且可滚动,普通未归属会话不重复显示项目标签,分组/项目/会话嵌套没有溢出窄栏,页面无 slot 错误。另在真实页面检查了悬浮操作、Enter 键折叠、搜索与 Escape、当前项目/会话标记,以及未归属 workspace 分组。
80
+ - 此前在 DSH 0.2.2-rc.1 的临时 Web profile 中手动检查:视图选项中的 Orca-like 模式;项目展开;置顶 → 置顶架及原项目中的灰色行;取消置顶 → 恢复;创建/重命名/删除分组;通过菜单和拖拽移动项目;刷新后持久化;搜索;归档/取消归档;单列表、工作区和工作区树模式;浅色和深色主题;侧栏折叠/展开。另检查了置顶行打开时不展开项目、 **在项目中显示**会展开并滚动到原行、worktree 标签解析为 `main`、 `v0.16.1-patch` 和 `2.0-review`,以及字号与内置侧栏的 14px 项目和会话标题一致。
81
+ - 使用真实注册的 workspace 在临时 profile 中渲染 worktree 合并:`msinsight` 主检出加四个 Orca worktree 形成一个项目,显示 `5` 个 worktree;`dsh-TUI` 加四个 `.worktrees` 条目形成另一个,显示 `5` 个。`dsh-plugins` 只注册了主 workspace,Host 找到了另外三个 `.git/worktrees` checkout,项目行显示 `4` 个 worktree,项目菜单列出全部四项,且没有为了展示而创建 workspace。不属于任何已注册工作区的会话显示在独立的、默认折叠的 **未归属会话** 区域,而不是一个无法移动的合成项目;展开后可以看到 18 个可折叠的 workspace 分组(例如 `cc-workspace` 的 58 条),而不是一个平铺列表;展开分组后只显示 checkout 标签;置顶的那一行仍留在分组内,灰色显示并带 **已置顶** 标记和项目标签,同时也出现在已置顶区域。迁移对话框从 193 条中识别出 183 条、覆盖 10 个项目;应用外挂映射后剩余 10 条,撤销后恢复 193 条。项目菜单列出每个 worktree,重命名项目标签可持久化,把项目移入自定义分组后仍保持一行。两个目录已不存在的旧 `.worktrees` 条目仍通过兜底归入项目。
82
+ - 本次 checkout 没有单独驱动 Desktop 窗口;它使用同一个客户端 artifact。安装到 Electron 持有的 `desktop` profile 是单独的用户操作。
83
+
84
+ ## 限制
85
+
86
+ - 插件遮蔽内置 workspace 浏览器。内置浏览器的会话行操作扩展 slot (`sidebar.workspaces.session.row.action`)和悬浮卡片不会在这里渲染。
87
+ - 搜索只针对已加载的会话摘要(标题、项目路径和工作目录),不会查询 Host 上的消息内容。
88
+ - 自定义分组保存在浏览器本地,不会跨设备或 profile 同步。
89
+ - worktree 身份只从 workspace 根目录的 `.git` 条目读取;Host 不会向上扫描父目录。没有自己 `.git` 条目的 workspace 仍然是独立项目,submodule 不会并入外层仓库。未注册 checkout 从 `.git/worktrees` 发现;只有目录存在且 `.git` 文件回链到同一条 worktree 管理记录时才会列出。陈旧记录会被省略,即使原路径已被普通目录或其他仓库复用。如果 Host 路由不可用,只有 `.worktrees/`、`.worktree/`、`worktrees/` 和 Orca 的 `workspaces/<project>/<worktree>` 路径模式会合并。
90
+ - worktree 合并和会话迁移只适用于 Orca-like 模式。工作区模式和工作区树模式仍然保留 DSH 的目录分组语义,并忽略迁移映射。
91
+ - 迁移工具只按 `cwd` 匹配当前可见会话,是浏览器本地外挂映射,不会修改 DSH 的 `workspace.sessionIds`;无法把任意会话附加到路径与其 `cwd` 不同的 workspace。
92
+ - 删除合并后的项目会移除它名下的全部 workspace 注册,文件和会话会保留。这个版本没有单独移除某个 worktree 的操作。
93
+ - 绿色表示已完成但未查看;已经查看过的 idle 会话会恢复为灰色。过滤中的 **活跃**指正在运行或等待用户交互,而不仅仅是已完成。
94
+ - 添加项目需要可用的 `ctx.uiWorkspace.pickDirectory()`。没有 Host 目录选择器的远程浏览器无法添加项目。
95
+ - 这个版本不提供会话重命名、fork 或删除;请使用对话界面,或重新启用内置侧栏。
96
+
97
+ ## 开发
98
+
99
+ ```sh
100
+ pnpm --filter @codeasier/dsh-plugin-orca-projects build
101
+ pnpm --filter @codeasier/dsh-plugin-orca-projects test
102
+ pnpm --filter @codeasier/dsh-plugin-orca-projects typecheck
103
+ ```
104
+
105
+ 扩展插件前请阅读 [Plugin anatomy](https://github.com/codeasier/dsh-plugins/blob/main/docs/plugin-anatomy.md)和 [Client UI](https://github.com/codeasier/dsh-plugins/blob/main/docs/client-ui.md)。`client.js` 是手写的 loader 代码;保持 loader factory 自包含,并在修改后运行`node --check client.js`。
106
+
107
+ ## License
108
+
109
+ MIT