266 lines
26 KiB
Markdown
266 lines
26 KiB
Markdown
# 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`。
|