12 KiB
12 KiB
开发说明(DEVELOPMENT)
面向「在这个仓库上做扩展」的人。仓库是 DeepSeek Harness 插件
@dsh-xhl/workspace-groups:侧栏三级工作区分组浏览器 + 顶部会话标签条
- Ctrl+R 快切面板。宿主半边(node)负责 sidecar 配置读写,浏览器半边负责 UI。
1. 这份工作树的来源
当前分支 feat/base-0.4.2 的工作树,是从用户机器上实际安装运行的那份 0.4.2 构建
反推重建的,而不是仓库 HEAD 的原样代码:
- 来源:
~/.dsh/profiles/desktop/node_modules/@dsh-xhl/workspace-groups/lib/client.js.map(内联sourcesContent,含全部src/client/*的 TypeScript 源码) - 仓库 HEAD(
942babe,package 版本仍写着0.1.0)里只有侧栏分组浏览器, 没有会话标签条 / 快切面板 / 分支视图这些模块,即上游 GitHub 的公开代码落后于 已发布构建。 - 因此重建树 = 安装版 0.4.2 的完整源码,并补齐宿主侧
src/host-tabs.ts与/workspace-groups/tabs路由。
重建后的对齐校验(可用下面第 3 节的命令复现):
| 产物 | 与安装版对比 |
|---|---|
lib/index.js(宿主) |
diff 行数 0(逐字节) |
lib/client.js(浏览器) |
仅 1 行差异:CSS 虚拟模块注释里的构建绝对路径 |
lib/types/**/*.d.ts |
27/27 完全一致 |
git 历史里 942babe 及更早的提交原样保留;重建工作作为 b30f771 一次提交落在
feat/base-0.4.2 分支上。合回 master / 推上游前请自行决定如何叙事。
2. 目录结构
宿主半边(node,平台 node,输出 ESM):
| 文件 | 职责 |
|---|---|
src/index.ts |
插件入口。inject = ['webServer'],注册 4 组路由:GET /workspace-groups/config、`GET |
src/host-config.ts |
读用户 YAML 分类规则(默认 ~/.dsh/workspace-groups.yaml),校验后以 JSON 下发 |
src/host-manual.ts |
运行期分组覆盖(手动分组 + 单工作区归类覆盖),落 $DSH_HOME/workspace-groups.manual.json |
src/host-folders.ts |
每个工作区的额外文件夹 + 根目录,落 $DSH_HOME/workspace-groups.folders.json(写时严格、读时宽容) |
src/host-tabs.ts |
会话标签条的宿主侧持久化。放在宿主是因为浏览器存储按 origin 隔离,而 origin 含端口,dsh web/测试/桌面壳端口各不相同 |
src/context-types.ts |
本插件消费的 cordis 服务结构类型(第三方插件拿不到 monorepo 内的 declare module 合并) |
共享纯逻辑(浏览器 / node 两半都编译):
| 文件 | 职责 |
|---|---|
src/core/types.ts |
规则配置类型,零运行时依赖 |
src/core/matcher.ts |
归类与排序的纯函数:工作区归哪个分类、分类/工作区怎么排。宿主校验与客户端建树共用,语义不会漂移 |
src/core/folders.ts |
多文件夹的纯函数:有效文件夹列表、根目录解析、cwd 归属(最具体优先)。宿主校验与客户端建树共用 |
浏览器半边(src/client/,输出 CJS 闭包工厂):
| 文件 | 职责 |
|---|---|
index.ts |
客户端入口:向 sidebar.workspaces 槽注册(priority -1,shadow 官方浏览器)、注册 i18n、绑定各视图 |
contract.ts |
注入共享契约(GroupsBrowserInjected),镜像官方 ui-workspace 的注入形状 |
GroupsBrowser.tsx |
主 UI:分区头(标题/搜索/新建分组/添加工作区)+ 三级树 + 分组/工作区/会话对话框 |
rows.tsx |
树的行组件(行内菜单、状态点、图标),对话框挂在 browser root 以免折叠时卸载 |
tree.ts |
纯派生:分类文件夹 → 项目文件夹 →(可选)文件夹行 → 会话行;可见性规则对齐官方树 |
folders-persist.ts |
文件夹 overlay 的客户端侧,读写宿主 /workspace-groups/folders |
locales.ts |
workspaceGroups 命名空间词典(zh/en + key 联合类型) |
styles.css |
全部样式,?inline 导入后由构建期 lightningcss 压缩内联 |
branch.ts / FlowerBranch.tsx |
侧栏当前行的「花朵」标记(几何计算在 branch.ts,仍由单测覆盖;连线与逐行圆点已移除,只画花朵) |
tabs.ts |
标签条纯状态:打开顺序、激活项、派生展示 |
tab-store.ts |
defineStore 绑定(只做绑定,变换留在 tabs.ts) |
tab-seat.ts |
DOM 挂载点:标签条要贴在会话列顶部(ui-layout AppFrame 的 .centerCol 是 pI_x6G_centerCol,没有对应 slot) |
tab-persist.ts |
标签条持久化的客户端侧,读写宿主 /workspace-groups/tabs |
SessionTabs.tsx |
标签条 UI:每个打开的会话一枚 chip |
quick.ts / QuickPanel.tsx |
Ctrl+R 快切面板(工作区 / 会话两个页签) |
open-folder.ts |
调 @deepseek-ai/dsh-host-open-in-app 的宿主路由,打开项目目录 |
subagent-lineage.ts |
子代理后代计数的本地投影(0.1.2 起 runtime 不再提供 indexSubagentDescendants) |
store-core.ts |
展开状态的纯变换(无运行时 import,便于单测) |
stores.ts |
视图 store 工厂(展开状态,独立持久化 key,不碰官方 dsh.workspace.view.v5) |
store-hook.ts |
面向 store 实例的框架形状选择器 hook(useSyncExternalStoreWithSelector) |
其它:tests/*.test.ts(vitest,覆盖 core matcher/tree/store/tabs/folders),
tools/verify-folders.mjs(沙箱内 vitest 起不来时的等价纯 node 断言),cordis.patch.yml
(cordis 插件补丁层),scripts/verify-groups.mjs,workspace-groups.example.yaml。
3. 构建 / 校验 / 装回去
本机的 DSH 沙箱里没有把 node/pnpm 放进 PATH,用下面这份绝对路径脚本跑(含备选写法说明):
$nodeDir = "C:\Users\qyh15\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin"
$pnpm = "C:\Users\qyh15\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\pnpm\bin\pnpm.cjs"
$env:Path = "$nodeDir;$PWD\node_modules\.bin;" + $env:Path
# 依赖(已装过可跳过)
& "$nodeDir\node.exe" $pnpm install
# 类型检查(tsc 两次:node 半边 + 浏览器半边)
& "$nodeDir\node.exe" $pnpm typecheck
# 构建:先 tsc 出 lib/types,再 tsdown 出 lib/index.js + lib/client.js
& "$nodeDir\node.exe" $pnpm build
# 单测(注意:DSH 沙箱内 vitest 起子进程会被 EPERM 拦掉,用普通终端跑)
& "$nodeDir\node.exe" .\node_modules\vitest\vitest.mjs run
对齐校验(重建时用过,改动后也可用来确认没伤到宿主半边):
$installed = "C:\Users\qyh15\.dsh\profiles\desktop\node_modules\@dsh-xhl\workspace-groups"
& "$nodeDir\node.exe" ..\tools\diff-text.mjs "$installed\lib\index.js" lib\index.js 3
& "$nodeDir\node.exe" ..\tools\compare-types.mjs "$installed\lib\types" lib\types
装回正在运行的 DSH 做真机验证:
pnpm build- 把
lib\(index.js、client.js、client.js.map、types\)覆盖到C:\Users\qyh15\.dsh\profiles\desktop\node_modules\@dsh-xhl\workspace-groups\lib\ - 重启 DSH(Web GUI 在
http://127.0.0.1:1282)
lib/是入库的(上游仓库也这么干),改完源码要记得重新 build 再提交, 否则安装方拿到的还是旧产物。
4. 扩展时必须知道的三条约束
- 平台模块表外置,其它一律内联。
tsdown.config.ts的CLIENT_EXTERNALS只允许react、react/jsx-runtime、react-dom*、@deepseek-ai/cordis、dsh-client-ui-slots、dsh-client-ui-primitives、dsh-client-store、dsh-client-runtime/client。任何其它@deepseek-ai/*值导入都会让构建失败 (dsh-workspace-groups-client-purity纯净门);跨插件协作只能走 cordis 服务或 slot。 单纯类型导入没问题(会被擦除)。 - CSS 走
?inline虚拟模块,前缀名不能改。CSS_VIRTUAL_PREFIX是\0dsh-workspace-groups-inline-css:,styles.css里的类名会被 lightningcss 压成哈希。加样式直接写styles.css,组件里import css from './styles.css?inline'即可。 - Node 内置模块不许进浏览器包(
NODE_BUILTINS参与判定)。需要 node 能力就往宿主半边加路由。
5. 常见扩展动作
- 加一块侧栏 UI / 一个按钮:
rows.tsx加行内动作 →GroupsBrowser.tsx接 handler;文案加进locales.ts的zh/en与WorkspaceGroupsKey联合类型(漏加会被 tsc 抓到)。 - 加一份视图状态:纯变换写
store-core.ts(或新开xxx.ts,保持零运行时 import) →stores.ts里defineStore绑定 → 组件用store-hook.ts的选择器 hook。 这样单测能直接测语义,不必起浏览器 module loader。 - 加宿主能力:新建
src/host-xxx.ts(读写 sidecar、做校验)→ 在src/index.ts里用ctx.effect(() => ctx.webServer.register({ kind: 'exact', path, handler }), '...')挂路由 → 客户端照tab-persist.ts的fetch封装去调,注意Cache-Control: no-store。 - 加标签条行为:状态变换进
tabs.ts(纯),store 绑定在tab-store.ts, 渲染在SessionTabs.tsx,落盘走tab-persist.ts;位置模型是「首次入列时定序」, 改动前先读tabs.ts顶部的 position model 注释。两条不变量:固定标签恒在未固定 之前(moveTab在固定区边界夹紧、togglePinTab插到固定区尾/未固定区头), 标签名与会话标题互不影响(renameTab只动title)。除order之外的标签状态 (固定、自定义名)也必须由restoreTabsImpl原样复原,否则每次重启都丢配置。 - 加一个分组展示元数据(颜色 / 图标 / 置顶等):字段进
types.ts(CategoryAppearance+GROUP_COLORS/GROUP_ICON_IDS白名单)→ 校验进host-manual.ts的parseAppearance(严格写、宽容读:不校验键对应的分类是否 还存在,否则删掉一条 YAML 分类就会让之后每次保存都 400)→ 派生进matcher.ts(要影响排序就必须放effectiveCategories,只在渲染层排会让拖拽落点与看到的顺序 不一致)→tree.ts节点带appearance→rows.tsx渲染 →styles.css配色/ 动画 →locales.ts双语文案。写路径统一走GroupsBrowser.tsx的updateCategoryAppearance;改名要重映射appearance的键、 删除要清掉(键空间是 display name,与categoryOrder一致)。 - 新增平台依赖:先确认 DSH shell 的 module table 真有那一行,再往
CLIENT_EXTERNALS里加,否则运行时require会拿不到模块。
6. 已知坑
- 沙箱内跑不了 vitest:
spawn被 DSH 沙箱拦(EPERM),在普通 PowerShell 终端里跑。 node_modules/.bin/*.CMD直调会挂:pnpm 里嵌套的 pnpm 脚本在 DSH 沙箱下会Could not determine executable,统一用node <pnpm.cjs> <script>形式。- 单测覆盖不齐:
tests/是早期版本写的,现已补tests/tabs.test.ts(标签条纯逻辑: 固定区不变量、拖动夹紧、关闭其他/右侧、持久化恢复);快切面板 (quick.ts/QuickPanel.tsx)与分组外观仍无单测,改到这些区域时补。 - 改持久化格式一律「严格写、宽容读」:新增字段必须是可选的,旧文件读不进来不算
错;悬挂键(如已删除的分类/会话)不得拒写,否则用户会卡在 400 上再也保存不了;
新字段在
restore*里必须原样带过去(pinned/title漏带就等于重启丢配置)。 - package 版本号语义混乱:仓库 HEAD 里是
0.1.0,但提交里写feat(v0.7); 重建树统一对齐到安装版的0.4.2。发布前自己定一版号。