workspace-groups-remote/DEVELOPMENT.md

9.5 KiB
Raw Blame History

开发说明(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-tabs.ts 会话标签条的宿主侧持久化。放在宿主是因为浏览器存储按 origin 隔离,而 origin 含端口,dsh web/测试/桌面壳端口各不相同
src/context-types.ts 本插件消费的 cordis 服务结构类型(第三方插件拿不到 monorepo 内的 declare module 合并)

共享纯逻辑(浏览器 / node 两半都编译):

文件 职责
src/core/types.ts 规则配置类型,零运行时依赖
src/core/matcher.ts 归类与排序的纯函数:工作区归哪个分类、分类/工作区怎么排。宿主校验与客户端建树共用,语义不会漂移

浏览器半边(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 纯派生:分类文件夹 → 项目文件夹 → 会话行;可见性规则对齐官方树
locales.ts workspaceGroups 命名空间词典(zh/en + key 联合类型)
styles.css 全部样式,?inline 导入后由构建期 lightningcss 压缩内联
branch.ts / FlowerBranch.tsx 侧栏「花枝」SVG 曲线(移植自 RewampUI Flower Sidebar)
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),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 做真机验证:

  1. pnpm build
  2. 把 lib\(index.js、client.js、client.js.map、types\)覆盖到 C:\Users\qyh15\.dsh\profiles\desktop\node_modules\@dsh-xhl\workspace-groups\lib\
  3. 重启 DSH(Web GUI 在 http://127.0.0.1:1282)

lib/ 是入库的(上游仓库也这么干),改完源码要记得重新 build 再提交, 否则安装方拿到的还是旧产物。

4. 扩展时必须知道的三条约束

  1. 平台模块表外置,其它一律内联。 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。 单纯类型导入没问题(会被擦除)。
  2. CSS 走 ?inline 虚拟模块,前缀名不能改。 CSS_VIRTUAL_PREFIX 是 \0dsh-workspace-groups-inline-css:,styles.css 里的类名会被 lightningcss 压成哈希。加样式直接写 styles.css,组件里 import css from './styles.css?inline' 即可。
  3. 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 注释。
  • 新增平台依赖:先确认 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/ 是按早期版本写的,0.4.2 的标签条/快切没有覆盖, 改到这些区域时补测试。
  • package 版本号语义混乱:仓库 HEAD 里是 0.1.0,但提交里写 feat(v0.7); 重建树统一对齐到安装版的 0.4.2。发布前自己定一版号。