dsh-sansheng-liubu/docs/p0/navigation.md

266 lines
26 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# P0 · 导航与扩展点调研(navigation)
- 调研对象:`dsh-better-sidebar@0.28.2`、`workspace-groups-local@1.3.0`(来源 `github:newbieQQ/dsh-better-workspace-group`)、现有 `dsh-sansheng-liubu-panel` / `dsh-sansheng-liubu-workbench`,以及宿主客户端(`app.asar` 内 `@deepseek-ai/dsh-client-*`)。
- 结论只用于 P5 选型;本文件是本次任务唯一写入,未改任何代码/配置,未运行构建。
- 证据约定:profile 包相对 `C:\Users\qyh15\.dsh\profiles\desktop\node_modules\`;宿主包写作 `asar:dsh/node_modules/@deepseek-ai/<pkg>/...`(在安装目录 `resources\app.asar` 内,需解包读取)。
- DS Bot 未安装,第 4 节依据上游仓库 `Fei2411/DS-Bot`(main,包版本 0.3.2)源码与方案文档 `docs/DSBot-三省六部开发方案.md` 推断,逐条标注"已证 / 待运行验证"。
## 结论摘要
1. 宿主**没有 page/route 概念,也没有前端 URL 路由**;"一个页面"= `sidebar.panellist` 上的一个条目 + `main` 里同 id 的 keyed 组件(`asar:.../dsh-client-ui-sidebar/README.md:37`)。全仓 grep `pushState|hashchange|location.hash` 无页面级命中。
2. 左列只有三块可挂:`sidebar.panellist`(图标行,list)、`sidebar.workspaces`(项目树,single)、`sidebar.settings`(single,底栏);项目树目前由 workspace-groups 独占。
3. 右列是 `rightbar`(single, root)+ 每 session 一个 pane;**卡片列没有专门 slot**,但右栏 tab 体是完全自由的 React 组件,宽度/收起/全屏/窄屏由宿主实现(`asar:.../dsh-client-ui-sidebar-right/README.md:38`)。
4. better-sidebar 只暴露 `registerTab` / `registerFileViewer`,自身就是宿主右栏的 tab 宿主;**给它打补丁不会多出第四列**,它只是把 tab 适配到 `sidebar.right.pane.tab`(`dsh-better-sidebar/src/client/native/index.ts:313-345`)。
5. workspace-groups **不发布服务、不发事件**(`lib/client.js` 无 `ctx.provide` / `reflect.provide` / `emit`);"当前项目"是各消费方用宿主 `ui-workspace` 的 selection store + session→workspace 反查自行推导的。
6. DS Bot 不是"一页":bot 模式下它整体接管 `shell` + `conversation` 两组 slot,自绘左列/中列/右抽屉(`ds-bot/src/client/surface.js`、`frame-layout.js`),**无 URL、无 `sidebar.panellist` 条目、无"嵌入指定 bot/群聊"参数**,只认 `POST api/bot` 与 localStorage。
7. 因此 P5 三块的最省事落点:左 = workspace-groups 原样;中 = DS Bot 的 bot surface;右 = **DSH 自己的 rightbar**(新伴侣插件注册一个 page 型 tab)。这条路零补丁、可调宽/收起/深色/窄屏全部复用宿主。
8. 但"右列常驻同屏"做不到纯伴侣:DS Bot 的右抽屉与 DSH 右栏**互斥**(`ds-bot/src/client/right-panel.js` 文件头注释),且它会以更低 priority 覆盖 `main.conversation`。要常驻必须在固定 SHA 的 ds-bot 上做最小补丁(方案 B)。
## 1. 侧栏页面如何注册
### 1.1 package.json 的 `dsh` 字段(三份真实样本)
| 字段 | better-sidebar 0.28.2 | workspace-groups-local 1.3.0 | sansheng-panel 0.9.2 |
| --- | --- | --- | --- |
| `main` | `lib/index.js`(Host 半) | `lib/index.js` | `index.js` |
| `exports["./client"]` | `./lib/client.js` | `./lib/client.js` | `./lib/client.js` |
| `dsh.manifestVersion` | `1` | 有 | 有 |
| `dsh.client.platform` | `"web"` | `"web"` | `"web"` |
| `dsh.client.inject` | `["@deepseek-ai/dsh-client-locale","...ui-slots","...ui-conversation","...ui-sidebar-right","...dsh-client-modules"]` | 10 项,含 `dsh-api-workspace-controller`、`dsh-client-ui-sidebar`、`dsh-client-ui-workspace` | 无(改在运行时 `get`,见 1.3) |
| `dsh.bundle.patch` | `./cordis.patch.yml` | `./cordis.patch.yml` | 无 |
要点:
- `exports["./client"]` 是**客户端入口**,宿主按 `dsh.client.platform === "web"` 加载;`main`/`lib/index.js` 是 Node 侧(Host)插件,可注册 HTTP 路由(workspace-groups 就是这么暴露数据的)。
- `dsh.bundle.patch` 指向的 `cordis.patch.yml` 决定该插件是否默认插入到 profile 的 bundle 行;workspace-groups 的 patch 只 `insert` 一行 `workspace-groups-local`,没有依赖声明。
- `dsh.client.inject` 是**软依赖**:写进去的服务若不存在,插件会被 park(`panel/lib/client.js` 注释原话:"better-sidebar 是可选的:没装时不要写进 inject,否则插件会被 park")。因此可选依赖(如 `betterSidebar`、`sidebarRightTabs`)用运行时 `ctx.get(...)` 探测。
### 1.2 宿主提供的 web 扩展面(seat 全清单)
`root` 之下只有三列 + 两个 shell 位(`asar:dsh/node_modules/@deepseek-ai/dsh-client-ui-layout/lib/client.js:623-653`):
```
root
├─ sidebar (single, root) ← ui-sidebar 注册的子 seat
├─ main (keyed, root) ← 全页插件在这里按 key 注册
├─ rightbar (single, root) ← ui-sidebar-right 接管
├─ shell.bottom (single, root)
├─ shell.overlay (list, root)
└─ shell.leading (single, root)
```
`sidebar` 的子 seat(`asar:.../dsh-client-ui-sidebar/lib/client.js:611-649`,渲染点 `:226` / `:277` / `:504`):
| seat | kind | 用途 |
| --- | --- | --- |
| `sidebar.brand.mark` / `sidebar.brand.name` | single | 顶栏品牌 |
| `sidebar.toggle.badge` | single | 折叠按钮角标 |
| `sidebar.panellist` | **list** | 页面图标行("全页插件"入口) |
| `sidebar.panellist.actions` | list | 页面上方工具条 |
| `sidebar.workspaces` | **single** | 项目/会话树(workspace-groups 占位) |
| `sidebar.settings` | single | 底栏设置入口 |
| `sidebar.footer.action` | list | 底栏动作 |
`rightbar` 的层级(`asar:.../dsh-client-ui-sidebar-right/lib/client.js:5030-5077`):
```
rightbar (single, root)
└─ rightbar.session (single, session)
└─ sidebar.right.pane.tab (keyed, session) ← 插件页体
sidebar.right.pane.tab.title (keyed, session) ← 标题
sidebar.right.tab.menu.item (list, session) ← tab 右键项
```
其他本次用得到的 seat:`conversation.header`、`conversation.content`(工厂 slot)、`conversation.session.header.actions` / `.utilities`、`settings.section`、`shell.overlay`、`sidebar.workspaces.directoryFlow`(目录选择洞,single)。
### 1.3 两种页面形状与真实注册代码
**A. 全页(左侧图标 + 中间整页)** —— `@linxin666/dsh-client-ui-task-board@0.4.13` 只用了两个 seat:`slots.inject("main")` 与 `slots.inject("sidebar.panellist")`。宿主自带的 `dsh-client-ui-schedule`(`lib/client.js:7484-7485`)与 `dsh-client-ui-plugin-manager`(`:4484-4485`)同款。
规则(`asar:.../dsh-client-ui-sidebar/README.md:37`):往 `sidebar.panellist` 注册 `{ id, order?, label }`,**同一个 id 就是 `main` 里的 key**;`main` 里查不到该 key 会抛错。`main` 的 keyed 语义允许"同 key 多注册、priority 低者渲染"(workbench 用 `priority: -1` 抢在宿主 0 之前)。
**B. 右栏 tab(面板式)** —— 两段式注册,两个包都这么做:
```js
// 1) 声明 tab 类型(右栏的"页签种类")
ctx.sidebarRightTabs.register({ id, kind, priority: 'builtin', title: () => '...' })
// 2) 挂页体 + 标题
ctx.slots.register({ name: 'sidebar.right.pane.tab', key: id }, Body)
ctx.slots.register({ name: 'sidebar.right.pane.tab.title', key: id }, Title)
```
- `sidebarRightTabs.register` 的完整签名与优先级规则见 `asar:.../dsh-client-ui-sidebar-right/README.md:82`:`{ id, kind, patterns?, priority?, canOpen?, title, guide?, keepMounted? }`;id 全局唯一,重复注册同 id 抛错;kind 最多一个 builtin + 一个 extension,extension 生效;priority 依次为 extension(第三方默认最高)→ builtin → fallback,再比 `patterns` 匹配长度、注册顺序。
- body 通过框架注入的 `useTabInfo()` 拿 `{ sidebar, panel, tab }`,`tab` 含 record、`visible`、`navigation`(含 `params`)、`signal`、`actions`(`README.md:83`)。
- 打开:`ctx.sidebarRight.openTab(kind, { params })` / `openResource(address, options?)`;`params` 原样进 `navigation.params`,运行时不校验形状;未知 kind 或非 `dsh-resource://` 地址抛错;options 有 `replaceTab / paneId / revealIfOpened / preferNewPane`(`README.md:92-94`)。
- 可用的 pane 动作:`close/active/isExpanded/toggleExpanded/toggleFullscreen/focus/split/float/dock`(`README.md:96`)。**没有 pane 级 toolbar slot,也没有"收起态"插槽**(`README.md:87` 明确"尚未提供")。
**C. better-sidebar 的注册面**(它自己也是插件,对外只开两个口):
```js
export const inject = ['betterSidebar']
ctx.effect(() => ctx.betterSidebar.registerTab({ id, title, order, single, component }))
```
`README.md:125-140`;`BetterSidebarService` 面见 `dsh-better-sidebar/src/client/service.ts`(`registerTab` / `registerFileViewer` / `registerFileIcon` / `openTab` / `closeTab` / `activateTab` / `subscribe` / `getSnapshot` / `hostRouteUrl` / `setSurface` …)。`TabDescriptor` 字段:`id, title, component, order, single, dedupeKey, createTab, urlTarget, settings, badge, rightActions, onOpen, onActivate, onClose, bottomOnly, hidden, available`。
它内部把每个 tab 适配成宿主右栏的 tab(`src/client/native/index.ts:313-345`):先 `ctx.inject(['sidebarRightTabs'])`,再 `tabs.register({ id, kind, keepMounted: true, priority: 'extension', patterns, canOpen, title, guide })`,然后注册 `sidebar.right.pane.tab` / `.title`。**没有"独立右列"或"卡片容器"API**,它的 `openTab({ target: 'right' })` 就是宿主 rightbar。
## 2. better-workspace-group 的项目树
### 2.1 数据来源(三层)
1. **宿主注册表**(运行时真相):`@deepseek-ai/dsh-api-workspace-controller` 的 WorkspaceSnapshot:
`{ items: [{ workspaceId, path, sessionIds: [...], ... }], archivedSessionIds: [...] }`(`asar:.../dsh-api-workspace-controller/lib/types/feed.js:14,25`)。会话列表同源。
2. **侧车文件**(分组/多 folder 的私有状态):`~/.dsh/workspace-groups.manual.json`、`workspace-groups.folders.json`、`workspace-groups.tabs.json`、`workspace-groups.yaml`(规则分组,示例 `workspace-groups.example.yaml`)。README 口号:"Sidecar YAML + runtime overlays, zero core-storage intrusion" —— 不改宿主 core storage。
3. **Host 路由**(侧车给浏览器端读写的通道,`workspace-groups-local/lib/index.js`):
`ctx.effect(() => ctx.webServer.register({ kind: "exact", path }))` 注册 `/workspace-groups/config`(`:3802-3804`)、`/workspace-groups/tabs`(`:3830-3832`)、`/workspace-groups/manual`(`:3882-3884`)、`/workspace-groups/remote-hint`(`:3921-3923`),另有一组自 `:3952` 起。**未文档化契约**,第三方可 fetch 但不保证稳定。
### 2.2 数据结构
- 树上三层:**category(组,纯展示/拖拽容器)→ project(= 宿主 workspace,可含多 folder 的 multi-root)→ session(= 宿主 session)**。
- 视图状态在 `createGroupsViewStore()`(本地 store,`PropsStore<ReturnType<typeof createGroupsViewStore>>`,`lib/types/client/contract.d.ts`),组件 `GroupsBrowserProps = PropsRuntime<'sidebar.workspaces'> & PropsStore<...> & InjectFace<GroupsBrowserInjected> & PropsLocale<'workspaceGroups'>`。
- 注入面 `GroupsBrowserInjected`:`hooks.directoryFlow: HostObservable<boolean>`、`startSession`、`createSessionIn`、`open`、`searchSessions`、`searchResultLimit`、`renameSession`、`forkSession`、`renameWorkspace`、`deleteWorkspace`、`insertWorkspaceBefore`、`archiveSession`、`insertSessionBefore`、`createWorkspace({path})`、`pickDirectory()`、`getDirectoryFlow()`、`createDirectory`、`openTab(sessionId, status)`、`useTabs`、`tabActions`。
- 它只调用宿主已有面:`ctx.uiWorkspace.openSession/startSession/forkSession/pickDirectory/createDirectory/archiveSession`、`ctx.workspaces.create/delete/rename/insertBefore/insertSessionBefore`、`ctx.sessions.list/search/create/binding`、`ctx.locale.register`。**未新增任何服务。**
### 2.3 当前选中项目:不对外暴露,靠推导
- 注册处:`ctx.slots.inject("sidebar.workspaces", () => ctx.slots.register({...}))`;并 `entriesOfSlot("sidebar.workspaces.directoryFlow")[0]` 占住官方目录选择洞(避免 "Add workspace…" 出现两份)。
- "当前项目"在它内部是每次推导的(`workspace-groups-local/lib/client.js`):
- `:1533` / `:1588`:`const currentWorkspaceId = current === void 0 ? void 0 : workspaces.find(w => !members.absorbed.has(w.workspaceId) && projectHoldsSession(w, members.byOwner.get(w.workspaceId) ?? [], current))?.workspaceId`
- `:5154`:`const currentWorkspaceId = useMemo(() => activeWorkspaceId(workspaces, currentSessionId), [workspaces, currentSessionId])`
- 权威来源仍是宿主 `dsh-client-ui-workspace`:`selection = createSnapshotStore({}, { persist: { name: "dsh.sessions.current" } })`(`asar:.../dsh-client-ui-workspace/lib/client.js:1369`,持久化 localStorage 键 `dsh.sessions.current`),写入 `{ sessionId, ...(subagentAddress ? { subagentAddress } : {}) }`(`:1663`),由 session 反查 workspace 是 `workspaces.items.find(item => item.sessionIds.includes(summary.id))`(`:1613`)。**"选中项目"实际是"当前 session 所属 workspace"**,`archivedSessionIds` 在 `:1641` 使用。
### 2.4 切换项目有没有事件?
**没有第三方可订阅的插件事件。** `workspace-groups-local/lib/client.js` 全文 grep `ctx.emit` / `ctx.provide` / `ctx.reflect.provide` / 具名 event 均无命中;宿主侧也没有"workspace 切换"事件总线(`layout`/`sidebarRight` 都是服务,不是 emitter)。
可用的替代订阅(都是 store 的 observable,HostObservable/HostSnapshot 同族):
```js
ctx.get('workspaces').list.subscribe(reconcile) // 项目/会话增删改,见 ui-workspace client.js:1597-1598
ctx.get('sessions').list.subscribe(reconcile)
ctx.get('workspaces').selection.subscribe(...) // 当前 session(= 当前项目线索)
```
已装插件里 `ui-workspace` 自己就是这样 reconcile 的(`:1597-1598`),workspace-groups 与 workbench 则用框架 hook `useWorkspaces` / `useSessions` / `useSessionStatus`(`contract.d.ts` 的 `SessionsTabsStandardProps` 注释)。
**给第三方的三种读法**(按推荐度):
1. **Hook/Store 读**(推荐):`useWorkspaces()` 拿 snapshot,`useSessions()` 拿当前 session,按 `sessionIds.includes(current)` 反查 workspace id。
2. `ctx.uiWorkspace` 已有动作(`README.md:73`:`openSession` / `openWorkspace` / `forkSession` / `startSession` / `connectWorkspace`、`workspaceDisplayTitle`),可用来"切到某项目/会话"。
3. 直接 fetch 它的 `/workspace-groups/*` 路由取分组结构(能拿到 category 分组名,但依赖未文档化 HTTP 契约)。
## 3. 右侧栏 / 面板 / 卡片插槽
**有右栏,没有"卡片列"。** 结构见 1.2:`rightbar` → `rightbar.session` → `sidebar.right.pane.tab`(每 session 一个 pane,可 split 成多 pane)。
宿主已实现的、P5 需要的交互(`asar:.../dsh-client-ui-sidebar-right/README.md`):
- `:38` 两种呈现 normal / fullscreen;**<768px 自动 fullscreen(即"窄屏抽屉"效果)**;normal 有拖动宽度手柄;支持 float/dock/split。
- `:49` 面板无 header,控件放在右上 pane 的 tab strip。
- `:105` `keepMounted: true` 让 body 跨 tab/session 切换、收起、停靠保活(三卡片里如果有轮询/订阅,务必打开)。
- `:114-122` 默认页:恰好一个 guide entry 时直接打开该页,0 或多个打开 guide;同 pane 最多一个 guide。
- `:143` 无 session 时右栏什么都不画(hero 屏)。
深色:宿主用 `theme` 服务(DS Bot 的 `inject` 里就含 `'theme'`),组件应读主题 token 而不是硬编码;现有 panel/workbench 通过 `style[data-plugin-css=<id>]` 注入自己的 CSS(`workbench/panel/lib/client.js:688`)。
### 3.1 第三方注册 React 组件的真实写法
这个框架的 slot occupant 就是"返回 VNode 的函数",用 `h(...)`(panel/workbench 都是 `h`,没有 JSX 构建步骤):
```js
// 右栏 tab 页体(最接近的例子:panel/lib/client.js 的 SanshengTabBody)
ctx.slots.register({ name: 'sidebar.right.pane.tab', key: TAB_ID }, (props) => {
const info = useTabInfo() // { sidebar, panel, tab }
return h(CardColumn, { ...props, info })
})
```
**最接近 P5 三卡片的现成实现**:`workbench/panel/lib/client.js:2044-2140` 的 `createConversationMain` ——
`div.wb-main-split`(原生内容 + `div.wb-main-resizer` + `div.wb-main-rail`),resizer 是 `role="separator"`、`aria-orientation="vertical"`、`aria-valuenow/min/max`、`tabIndex: 0`,键盘支持方向键 / Shift / Home / End;宽度存 `localStorage["sansheng.workbench.railWidth"]`,`clamp(width, RAIL_MIN, RAIL_MAX)`(`:19`、`:710-720`)。这套"拖宽 + 持久化 + 无障碍"的代码可以整段搬到卡片列。
另外两种写法(都可选):
- **portal / 自绘 DOM**:`shell.overlay`(list, root)可以挂不参与三列布局的浮层(better-sidebar 的 `context-diagnostics-ui.tsx:222` 就是);适合"浮动的第三列"或窄屏抽屉遮罩,但不管布局宽度。
- **包装某个已有 seat**:workbench 用 `slots.inject("main.conversation")` + `priority: -1` 包装原生会话(见 5.2),是"在别人的页面里加一列"的先例。
## 4. DS Bot 的加载约定(未安装,按上游源码推断)
### 4.1 包形态
`ds-bot/package.json`:`name: ds-bot` 0.3.2、`main: index.js`、`exports["./client"] → ./client.js`、`license: Apache-2.0`、`dsh.client = { platform: "web" }`(**无 inject 列表** —— 它全部用 `ctx.get()` 运行时探测)、`dsh.bundle.patch = ./cordis.patch.yml`;peerDeps `@deepseek-ai/cordis`、`dsh-llm`、`dsh-scope`、`dsh-tools`、`dsh-web`;客户端由 `scripts/build-client.mjs`(esbuild)打成根 `client.js`。
客户端入口 `ds-bot/src/client/index.js`(约 70 KB)首部:`export const inject = ['sessions', 'uiWorkspace', 'uiConversation', 'slots', 'theme', 'layout']`,与宿主 UI 包一一对应。
### 4.2 它如何"出现":接管 shell,而不是加页
- `ds-bot/src/client/surface.js`:`groupsFor({ mode, plain })` → `{ shell: mode === 'bot', conversation: mode === 'bot' && !plain }`;`GROUPS = ['shell', 'conversation']`;`surfaceGroups(install, {onError})` 提供 `reconcile/remount/dispose`,**整组要么全挂、要么全撤**;`freePriority(entries, {priority, key, id})` 给同 cell 的已有 entry 各减 1 取最小,注释 "lowest renders",并警告"同 cell 同 priority 的另一插件注册会抛错"。
- 模式持久化:`readMode/writeMode` 读写 `localStorage['ds-bot:surface']`,值 `'bot' | 'agent'`(`ds-bot/src/client/surface.js`、`storage.js`)。
- 布局:`ds-bot/src/client/frame-layout.js` 自己算整个 frame —— `MIN_CHAT=420`、`RAIL_WIDTH=88`、`PANEL_MIN={details:320,browser:360,side:320}`、`DSH_NARROW=1024`(注释:"The shell collapses its own sidebar below this width")、`SIDEBAR_MIN/MAX=264/420`、`readSidebar/writeSidebar` 存 `{pref:'open'|'rail'|'hidden', shown, width}` 到 `ds-bot:sidebar`;`frameLayout()` 返回 `{left, panel, column, room}`。**bot 模式下不依赖 DSH 的 sidebar/rightbar 布局控制器**,左列 open/rail/drawer/hidden 由它自己画。
- 与 DSH 右栏的关系:`ds-bot/src/client/right-panel.js` 读 frame 上的 `data-rightbar-collapsed` / `data-rightbar-fullscreen` / `[data-rightbar-col]`,文件头注释原话:"One right-side panel at a time: the Bot drawer and DSH's right column never share the window (public#456: both open squeezed the conversation). Whichever the user asked for last wins."
### 4.3 URL / 路由 / 侧栏条目
- **没有 URL 路由**:宿主全仓(8437 文件)grep `pushState|hashchange|location.hash` 只命中 devtools/vendor 与 account/browser 包,没有 page 级路由;DS Bot 也没有路由文件。它的"页面"是客户端内存状态:`createSource` 的 `ui.details`(SessionId)、`ui.tab`、`ui.side` 等(`ds-bot/src/client/index.js` 的 apply 内),配合 localStorage 键(`storage.js`:`ds-bot:seen / prefs / surface / sidebar / browser-width / ds-bot.browser.v2`)。
- **没有 `sidebar.panellist` 条目**:它不是"左侧图标 → main 页"那种全页插件(对比 task-board 只注册这两个 seat)。切换靠它自己左列(`sidebar.js`,84 KB)与 header(`header.js` / `header-navigation.js`)。
- **没有"嵌入指定 bot / 群聊"的路由参数**:客户端与 Host 的唯一约定是 `POST api/bot`,body `{ endpoint, payload }`(`ds-bot/src/client/api.js`,`const ROUTE = 'api/bot'`;document-relative,"so the Web UI keeps working under a mounted base path")。错误码 `bot/refused|invalid|read-only|not-found|browser-off`。要"打开某群/某 bot",现有手段只有 `call('state', ...)` 拉数据 + 客户端状态,**没有 URL 深链**。
- 唯一类似"深链"的机制是宿主右栏的 `ctx.sidebarRight.openTab(kind, { params })`(params → `navigation.params`),但 DS Bot 不使用它。
### 4.4 与两个已装插件的兼容风险(待验证)
- better-sidebar 也改 shell 的左列;workspace-groups 占 `sidebar.workspaces`。DS Bot 的 `shell` 组会替换 shell 上的许多 cell,两插件是否仍渲染 **未验证**(需在安装 DS Bot 的桌面 profile 里看)。
- 右栏:DS Bot 的 drawer 与 DSH 右栏互斥(4.2 注释),这是 P5 方案 A 的硬限制。
## 5. 最小接入方案
### 5.1 三块分别挂哪里
| P5 需求 | 落点 | 需要改谁 |
| --- | --- | --- |
| 左侧复用项目树 | `sidebar.workspaces`(single,workspace-groups 已占) | **不改**。伴侣插件不要去 shadow 它(single + 同 priority 冲突;且它的 `GroupsBrowser` 未导出,shadow 即丢树) |
| 中间 DS Bot 聊天 | DS Bot 自己的 `conversation` 组(bot surface) | 不改;若要"角色点击切中央会话",调 `ctx.uiWorkspace.openSession` / `sessions` 切换即可 |
| 右侧三张纵向卡片 | `sidebarRightTabs.register` + `sidebar.right.pane.tab`(宿主 rightbar) | **新伴侣插件**;三卡片在 body 内纵向排布 |
### 5.2 方案 A:纯伴侣插件(零补丁)
新增一个包(如 `dsh-sansheng-liubu-roles`),`dsh.client.platform = "web"`,`inject` 至少 `["slots","sessions","uiWorkspace","uiConversation","sidebarRightTabs","sidebarRight"]`(可选 `betterSidebar` 用 `ctx.get` 探测):
1. `ctx.sidebarRightTabs.register({ id: 'sansheng-roles', kind: 'sansheng-roles', priority: 'builtin', title: () => '三省六部 · 角色', guide: [...] })`。
2. `ctx.slots.register({ name: 'sidebar.right.pane.tab', key: 'sansheng-roles' }, RolesColumn)`,`keepMounted: true`。
3. `RolesColumn` 内部:纵向三张卡(丞相 / 尚书 / 工部),复用 workbench 的 resizer 代码做"整列宽度"(或直接用宿主宽度手柄),收起用 `ctx.sidebarRight.toggleExpanded()`,深色读 `theme` token,窄屏交给宿主(<768px 自动 fullscreen)。
4. 当前项目/角色状态:`useWorkspaces()` + `useSessions()` 反查 workspace,再读 roles 数据(companion 自己的 store / Host 路由)。
5. 打开方式:左侧 `sidebar.panellist` 加一个图标(id 与 `main` 页配对)或 tab 菜单入口,让用户一键到"角色列"。
优点:零补丁、不动上游、不改 better-sidebar/workspace-groups;宽度/收起/全屏/窄屏/主题全部宿主提供(`README.md:38`)。
缺点:① 卡片列是右栏的一个 **tab**,不是常驻列,用户需点开;② DS Bot 打开自己的右抽屉时会收起 DSH 右栏(`right-panel.js` 的互斥规则)。
### 5.3 方案 B:A + 固定 SHA 的 ds-bot 最小补丁
在 A 的基础上给 `Fei2411/DS-Bot@84c3cb8`(方案文档候选基线)打补丁:在 `surface.js` 的 `conversation` 组里、DS Bot 自己的中列右侧,加一个可调宽/可收起的卡片列(新组件传 `workspaceId` / `roles`,数据同 A 的 store)。改动面:`surface.js`(多挂一个 cell)、新增 `role-column.jsx`、`frame-layout.js`(`PANEL_MIN` 增加一档)、`styles.js`。
优点:卡片列**常驻同屏**、与聊天共享 frame,窄屏可复用它的 `frameLayout` 折叠规则(`left:'rail'`、`panel:'folded'|'overlay'`)。
缺点:维护补丁(升级需 rebase)、需要在上游允许的扩展点之外改代码;且必须先解决"DS Bot 与 better-sidebar/workspace-groups 的 shell 兼容"这个 P0 悬项。
### 5.4 推荐
**先 A,验证后再决定 B。** 理由:
1. A 的四个硬需求(可调宽、可收起、深色、窄屏)宿主已实现,`README.md:38` 明确 <768px 自动 fullscreen;A 不需要碰 `better-sidebar`(它没有列 API,打补丁也变不出新列)。
2. A 的唯一不可接受点是"右栏 tab 非常驻",而这恰好由 `right-panel.js` 的互斥规则决定 —— 这是**产品取舍**,应在 A 的可用版本上做一次真实体验再定,而不是先付补丁成本。
3. 若体验结论是"必须常驻",B 的补丁面很小(一个 cell + 一个组件 + 布局常量),符合方案文档"公开扩展点不足才在固定上游版本上做最小补丁"的约束。
4. 无论 A/B,都**不需要改 better-sidebar**;也不要 shadow `sidebar.workspaces`,左列保持 workspace-groups 原样即可。
## 6. 待运行验证清单(P0 未闭环)
1. DS Bot 装上后,bot 模式下 DSH 的 `rightbar` 是否仍渲染(`data-rightbar-col` 是否存在)——决定方案 A 是否可用。
2. DS Bot 的 `shell` 组接管后,better-sidebar 的 `sidebar.panellist` / workspace-groups 的 `sidebar.workspaces` 是否仍可见、可点。
3. `main.conversation` 包装(workbench 式 `priority:-1`)在 bot 模式下是否被 DS Bot 的 `freePriority` 覆盖(需看 `surface.js` 的实际 seat 清单)。
4. 右栏 `keepMounted` 的 body 在 DS Bot 抽屉开合时是否被卸载(会影响轮询/订阅)。
5. `<768px` 宿主把右栏切成 fullscreen 时,三卡片纵向布局的实际可用高度。
## 附录:证据索引
- 宿主包(只读解包):`C:\Users\qyh15\AppData\Local\Programs\DeepSeek Harness\resources\app.asar` → `dsh/node_modules/@deepseek-ai/dsh-client-ui-{layout,sidebar,sidebar-right,workspace,conversation}/`、`dsh-api-workspace-controller/lib/types/feed.js`。
- 插件:`~/.dsh/profiles/desktop/node_modules/{dsh-better-sidebar,workspace-groups-local}`;工作区 `panel/`、`workbench/panel/`。
- 上游:`Fei2411/DS-Bot`(main)`ds-bot/src/client/{index.js,surface.js,right-panel.js,frame-layout.js,api.js,storage.js}`、`ds-bot/package.json`、`ds-bot/README.md`;方案 `docs/DSBot-三省六部开发方案.md`。