350 lines
20 KiB
Markdown
350 lines
20 KiB
Markdown
<p align="right">
|
||
<a href="./README.md">English</a> · <strong>简体中文</strong>
|
||
</p>
|
||
|
||
# dsh-workspace-groups
|
||
|
||

|
||

|
||
<img src="https://img.shields.io/badge/DeepSeek%20Harness-plugin-202724" alt="DeepSeek Harness plugin">
|
||
|
||
> **DeepSeek Harness(DSH)Web 客户端插件:完整的工作区分组管理工具。**
|
||
> 把 GUI 侧边栏的工作区列表从两层「项目 → 会话」升级为三层
|
||
> **「分类文件夹 → 项目文件夹 → 会话」**,并围绕它提供完整的分组管理能力——
|
||
> 手动建组、重命名/删除分组、拖拽归类、项目与分组的自由排序、规则自动归类、
|
||
> 树形搜索。所有操作**即时生效并持久化**,对官方数据**零侵入**。
|
||
|
||
典型场景:多个 DSH 插件项目(SkillsManagePlugins / Documentation-Driven AI Coding /
|
||
DeepSeek峰谷小组件 等)归入一个「DSH 插件」分类文件夹,点开是各项目,再点开是各自会话;
|
||
临时项目随手建个「临时」分组拖进去,用完删除分组,项目全部回归**顶层**。
|
||
|
||
## 截图
|
||
|
||
<img src="screenshot.png" alt="dsh-workspace-groups 工作区分组管理" width="280" />
|
||
|
||
## 特性
|
||
|
||
### 分组树浏览
|
||
- **分组文件夹 → 项目文件夹 → 会话行**,分组/项目均可折叠;展开状态独立持久化
|
||
(`dsh.workspace.groups.view.v1`,刷新/重启保留)
|
||
- **顶层项目行**:不归组的项目(不匹配任何规则、被移出分组、删除分组后回归的)
|
||
直接显示在分组列表之后,与分组平级——**没有「未分类」桶**
|
||
|
||
### 分组管理(完整生命周期)
|
||
- **手动新建分组**:区头「新建分组」按钮即建即显,空分组也渲染
|
||
- **重命名 / 删除任意分组**:每个分组行(**含规则分类**)悬停 `⋯` 菜单;
|
||
删除分组后组内所有项目回到**顶层**;规则分类的改名/删除经 overlay 生效
|
||
(`renamed` / `hidden`),**规则 YAML 原样保留**
|
||
- **规则自动归类**:sidecar YAML 声明分类规则(`pathPrefix` / `pathExact` /
|
||
`nameContains` / `basenameContains`),改配置即可调整归类,无需改代码
|
||
|
||
### 拖拽归类 + 排序
|
||
- **拖项目进分组**:拖到任意分组行 / 分组内项目行即移入(跨组移动 = 覆盖规则归类)
|
||
- **从分组拖出**:拖动时**整个顶层区域都是移出落点**,用**插入横线**指示(非高亮框)——
|
||
拖到任意顶层项目行(插到它前/后)、拖到最后一行下方空白(追加末尾)、顶层为空时
|
||
在最后一个分组行下方显示独立横线 = 移出分组;分组内项目行的菜单「移出分组」
|
||
(规则归类项目也有)
|
||
- **项目组内排序**:拖到项目行上半 = 插到它前面、下半 = 插到它后面
|
||
- **顶层项目排序**:顶层项目行也可拖拽排序(上半 = 插到它前、下半 = 插到它后),
|
||
顺序持久化在 `workspaceOrder["__topLevel__"]`
|
||
- **分组排序**:分组行可拖动,拖到另一分组行上半 = 移到它前面、下半 = 移到它后面
|
||
- **插入位置指示线**:拖动中实时显示 2px 指示线(行上/下方),松手落点所见即所得
|
||
- **按级别收起 + 结束后恢复**:拖项目只收起项目行(分组内 + 顶层,分组行不收);
|
||
拖分组只收起分组行(项目行不收);dragend 自动恢复拖动前的展开状态
|
||
- **行图标可区分**:分组行是文件夹图标、项目行是项目符号图标(官方同款),
|
||
分组与项目一眼可分
|
||
|
||
### 分组外观(颜色 / 图标 / 置顶)
|
||
|
||
- **分组配色**:10 种主题色,在分组行左侧画 2px 内嵌色条,并把文件夹图标染色
|
||
- **分组图标**:20 个内置图标(取自 DSH 图标集),或 1–4 个字符的自定义字形(emoji/拉丁);
|
||
未知值降级为默认文件夹图标而不是报错,数据与客户端版本因此可以各自演进
|
||
- **置顶分组**:置顶分组排到树的最前面;把分组拖过置顶边界时会在同一次写入里翻转
|
||
置顶状态,落点就是指示线显示的位置
|
||
- **折叠动画**:展开/收起分组或项目时行高与透明度过渡,动画期间隐藏花朵标记,
|
||
花不会滞后于所在行;大树、拖动折叠中、`prefers-reduced-motion` 下自动跳过动画
|
||
- 存放在 overlay 的 `appearance` 里,**绝不写进规则 YAML**
|
||
|
||
### 一个工作区多个文件夹(multi-root)
|
||
- **给项目挂多个文件夹**:项目行的 `⋯` 菜单里点 **文件夹…**,弹窗第一行是项目自带的
|
||
目录(**基础文件夹**,永远是 #0,不可移除),下面是你自己加的额外文件夹
|
||
- **每个项目一个根目录**:弹窗里的单选列,或文件夹行的 `⋯ → 设为根目录`,决定“新建会话”
|
||
默认落在哪个文件夹;根目录那一行会被提到最前面并带 ★ 标记
|
||
- **会话按自己的 cwd 归位**:项目一旦有额外文件夹,会话上方会多出文件夹行,每条会话按
|
||
自己记录的 cwd 落进所属文件夹(最具体的文件夹优先,Windows 下大小写不敏感);没有额外
|
||
文件夹的项目保持原来的两层扁平结构,行为完全不变
|
||
- **在指定文件夹里开会话**:文件夹行悬停的 `+` 会以该文件夹为 cwd 新建会话;基础文件夹
|
||
沿用平台自己的“新建会话”手势,连点两次会复用已打开的空白会话,而不是堆一堆空会话
|
||
- 文件夹默认展开,挂上新文件夹不会把本来能看到的会话藏起来;折叠状态只是当前视图状态,
|
||
故意不持久化
|
||
|
||
### 搜索与操作
|
||
- **树形搜索**:命中后仍保留三层树结构(分类 → 项目 → 命中会话),命中行高亮 +
|
||
内容摘要,防抖 250ms
|
||
- **工作区/会话操作不退化**:Add Workspace、项目重命名/删除、新建/打开/重命名/
|
||
派生/归档会话
|
||
|
||
### 持久化与零侵入
|
||
- 所有手动操作(分组、归类、排序、改名、隐藏)写入插件自有 overlay
|
||
(`~/.dsh/workspace-groups.manual.json`),host 校验后**原子写入**(写坏返回 400 并
|
||
保留原文件);标签栏同样处理,独立文件 `~/.dsh/workspace-groups.tabs.json`;项目的
|
||
额外文件夹与根目录选择也一样,独立文件 `~/.dsh/workspace-groups.folders.json`
|
||
(写时严格、读时宽容 —— 不认识的文件夹直接丢弃,不会把树弄坏)
|
||
- **零侵入**:不修改 `~/.dsh/storages/workspace.json`、不修改会话落盘结构、不修改官方
|
||
`@deepseek-ai/dsh-client-ui-workspace` 包;规则 YAML 永不改写
|
||
- **产物自包含**:`lib/` 已构建并随仓库分发,Git 安装无需执行任何依赖脚本
|
||
|
||
## 工作原理
|
||
|
||
- 本插件是 **client 插件**,注册进官方 sidebar shell 声明的 `sidebar.workspaces`
|
||
slot(`kind: 'single'`),以 `priority: -1` 顶替官方默认 WorkspaceBrowser
|
||
(官方以 priority 0 注册;single 槽位最低 priority 胜出)。
|
||
- 数据源全部复用运行时 API:`useWorkspaces` / `useSessions` 全局 hooks 与
|
||
`ctx.workspaces.*` / `ctx.sessions.*`,分类只是**展示层变换**。
|
||
- host 半做两件事:把 sidecar YAML 解析为 JSON 与运行时 overlay 合并,经
|
||
`GET /workspace-groups/config` 路由(`Cache-Control: no-cache`)供 client 获取;
|
||
`PUT /workspace-groups/manual` 接收整份 overlay(手动分组、每工作区归类覆盖、
|
||
分组/项目排序、规则分类改名与隐藏),校验后原子写入
|
||
`$DSH_HOME/workspace-groups.manual.json`。
|
||
- **归类优先级**:手动覆盖(拖拽/菜单写入;`null` = 强制顶层、规则匹配也无效)→
|
||
YAML 规则自动归类(被隐藏的规则分类失效)→ **顶层**(不归组的项目显示为顶层行)。
|
||
YAML 永不改写。
|
||
|
||
## 安装(GitHub 分发)
|
||
|
||
> 前置:已安装 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
|
||
> (`dsh` 命令可用),并已初始化好目标 profile(如内置 `web`)。
|
||
|
||
```sh
|
||
dsh plugin --profile web add github:z-col/dsh-workspace-groups
|
||
```
|
||
|
||
这会自动:
|
||
|
||
1. 在 `~/.dsh/profiles/web/package.json` 的 `dependencies` 加入
|
||
`"dsh-workspace-groups": "github:z-col/dsh-workspace-groups"`(含版本/commit)
|
||
2. 在 `dsh.profile.bundles` 末尾追加 `"dsh-workspace-groups"`
|
||
3. 运行 pnpm 安装并校验 bundle 层
|
||
|
||
**安装后重启 web profile**(bundle 与 host 半只有在重启后才会被加载):
|
||
|
||
```sh
|
||
# 停止现有 dsh web 进程后重新启动,例如:
|
||
dsh web
|
||
```
|
||
|
||
验证安装:
|
||
|
||
```sh
|
||
dsh --profile web --dump-config | grep -A3 workspace-groups
|
||
# 应出现 - id: workspace-groups / name: dsh-workspace-groups / config: {}
|
||
curl http://127.0.0.1:3080/workspace-groups/config
|
||
# 应返回 sidecar YAML 解析后的 JSON
|
||
```
|
||
|
||
## 卸载
|
||
|
||
```sh
|
||
dsh plugin --profile web remove dsh-workspace-groups
|
||
```
|
||
|
||
这会自动从 `dependencies` 删除该依赖并从 `dsh.profile.bundles` 移除对应行。
|
||
同样需要**重启 web profile** 后生效。
|
||
|
||
> 手动等价做法(任选其一,不要重复):编辑 `~/.dsh/profiles/web/package.json`,
|
||
> 从 `dependencies` 删除 `dsh-workspace-groups` 行、从 `dsh.profile.bundles`
|
||
> 删除 `"dsh-workspace-groups"`,然后在该目录 `pnpm install`。
|
||
|
||
## 分类配置(sidecar)
|
||
|
||
默认位置 `~/.dsh/workspace-groups.yaml`(也可用 `$DSH_HOME` 环境变量覆盖家目录)。
|
||
模板见仓库根目录 `workspace-groups.example.yaml`。
|
||
|
||
```yaml
|
||
categories:
|
||
- name: DSH 插件
|
||
rules:
|
||
- pathPrefix: /Users/zcol/Project/SkillsManagePlugins
|
||
- nameContains: 插件
|
||
- basenameContains: plugin
|
||
- name: 个人项目
|
||
rules:
|
||
- pathPrefix: /Users/zcol/Project/yeluzi
|
||
```
|
||
|
||
规则字段(每个 rule 是 OR 关系,任一命中即归类;分类按序匹配,先到先得):
|
||
|
||
| 字段 | 含义 |
|
||
|---|---|
|
||
| `pathPrefix` | 项目绝对路径前缀 |
|
||
| `pathExact` | 项目绝对路径精确匹配 |
|
||
| `nameContains` | 项目显示标题包含(忽略大小写) |
|
||
| `basenameContains` | 项目目录名包含(忽略大小写) |
|
||
|
||
未命中任何分类、或被移出分组的项目显示为**顶层项目行**(与分组平级),不会被隐藏。
|
||
|
||
## 手动分组与拖拽归类(runtime overlay)
|
||
|
||
规则 YAML 之外,还有一份插件自有的运行时 overlay,**只记录 UI 里的手动操作**,
|
||
默认位置 `$DSH_HOME/workspace-groups.manual.json`(例如 `~/.dsh/workspace-groups.manual.json`):
|
||
|
||
```json
|
||
{
|
||
"categories": ["临时", "归档"],
|
||
"assignments": {
|
||
"a1b2c3d4-e5f6-7890-abcd-ef1234567890": "临时",
|
||
"a1b2c3d4-e5f6-7890-abcd-ef1234567891": null
|
||
},
|
||
"categoryOrder": ["临时", "DSH 插件"],
|
||
"workspaceOrder": { "临时": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"] },
|
||
"renamed": { "DSH 插件": "插件集" },
|
||
"hidden": ["文档"],
|
||
"appearance": {
|
||
"插件集": { "color": "blue", "icon": "code", "pinned": true },
|
||
"临时": { "color": "amber" }
|
||
}
|
||
}
|
||
```
|
||
|
||
- `categories` —— 手动新建的分组名(无规则,空分组也渲染)。
|
||
- `assignments` —— 工作区 → 分组的归类覆盖,键是稳定的工作区 id(重命名不影响)。
|
||
**优先级高于 YAML 规则**;值为 `null` 表示**强制移到顶层**(即使规则能匹配)。
|
||
- `categoryOrder` —— 分组显示顺序(顶层项目不在此列,恒显示在分组之后)。
|
||
- `workspaceOrder` —— 每个分组内项目的手动排序(拖拽排序写入)。
|
||
- `renamed` / `hidden` —— 规则分类的 UI 改名/删除(隐藏后其规则失效,匹配项目
|
||
变顶层);规则 YAML 原样保留。
|
||
- `appearance` —— 按**显示名**(与 `categoryOrder` 同一键空间)记录分组外观:
|
||
`color`(`red`/`orange`/`amber`/`green`/`teal`/`blue`/`indigo`/`purple`/`pink`/`gray`)、
|
||
`icon`(内置图标 id 或 1–4 个字符的字形)、`pinned`(排到未置顶分组之前)。三个字段
|
||
都可选,写回时会把空值删掉,所以「取消设置」表现为字段消失,而不是存 `false`/`''`。
|
||
指向**已不存在分类**的键在读写两侧都被容忍——否则删掉一条 YAML 分类后每次保存都会
|
||
400。**颜色/图标只存在这里**:`parseGroupsConfig` 会丢弃 YAML 的未知键,所以在
|
||
sidecar 里写 `color:` 会被静默忽略。
|
||
- **降级提醒**:旧版本会整文件覆盖 overlay,下一次保存就会丢掉 `appearance`
|
||
(与 `categoryOrder` 同级别风险)。回退插件版本前请先备份
|
||
`workspace-groups.manual.json`。
|
||
- 文件由浏览器 UI 全量写入(`PUT /workspace-groups/manual`,原子替换),手工编辑
|
||
同样生效(下次加载时读取);写坏会返回 400 并保留原文件,不会破坏规则 YAML。
|
||
|
||
| 操作 | 入口 |
|
||
|---|---|
|
||
| 新建分组 | 区头「新建分组」按钮(文件夹图标),弹窗输入名称 |
|
||
| 重命名/删除分组 | **任意分组**(含规则分类)悬停 `⋯` 菜单;删除后组内项目回顶层 |
|
||
| 设置分组外观 | `⋯` 菜单「颜色与图标…」:色板、图标网格、自定义字形;每次点击立即写入(没有「确定」按钮) |
|
||
| 置顶分组 | `⋯` 菜单「置顶分组」/「取消置顶」;把分组拖过置顶边界时会在同一次写入里自动翻转 |
|
||
| 拖项目进分组 | 拖动项目行到目标分组行 / 分组内任意项目行,松手即移入 |
|
||
| 项目排序 | 拖动项目行到同组另一项目行:**上半 = 插到它前、下半 = 插到它后**(指示线显示落点);拖动时所有项目行收起、dragend 恢复 |
|
||
| 顶层排序 | 拖动顶层项目行到另一顶层行:**上半 = 插到它前、下半 = 插到它后**;顺序持久化 `workspaceOrder["__topLevel__"]` |
|
||
| 移出分组 | 拖到**顶层区域任意位置**(用插入横线指示落点——拖到顶层行前/后、最后一行下方追加、顶层为空时最后分组行下方独立横线),或项目行菜单「移出分组」(强制移到顶层) |
|
||
| 分组排序 | 拖动分组行到另一分组行:**上半 = 移到它前、下半 = 移到它后**(指示线显示落点;拖动时所有分组收起、dragend 恢复) |
|
||
|
||
## 会话标签栏(tab strip)
|
||
|
||
侧栏树上方常驻一条横向标签栏,每个「打开过的会话」对应一个标签,显示项目名 + 标签名:
|
||
|
||
- **打开 / 切换 / 关闭**:打开一个会话即在标签栏尾部新增一个标签;点击标签切换会话,
|
||
点击 `×` 关闭该标签。
|
||
- **中键单击**标签直接关闭;**拖动**标签可调整顺序。固定标签始终留在前部的固定区,
|
||
拖动不会跨越该边界。
|
||
- **重命名标签**:双击标签即可给标签单独起名(留空恢复为会话标题)。真正的会话改名
|
||
仍在右键菜单里,标签名不会改写会话标题。
|
||
- **右键菜单**:固定/取消固定、重命名标签、重命名会话、关闭、**关闭其他标签**、
|
||
**关闭右侧标签**。「关闭其他标签」始终保留已固定的标签。
|
||
- **持久化**:标签栏写入 `$DSH_HOME/workspace-groups.tabs.json`,走宿主路由
|
||
`GET/PUT /workspace-groups/tabs`;旧版本写下的标签栏(没有固定/自定义名
|
||
字段)可无缝升级——缺字段按「未固定、无自定义名」读取。
|
||
|
||
## 收录标签(topics)
|
||
|
||
本仓库面向 DSH 插件生态的自动收录(社区市场靠 GitHub topic 扫描发现),已设置:
|
||
|
||
- `dsh-plugin`(核心标签,[1024Store](https://github.com/imsai-sh/awesome-deepseek-harness-plugins)
|
||
等市场定时按此 topic 自动发现,并校验 `package.json` + 插件 bundle 清单
|
||
(`cordis.patch.yml`))
|
||
- `deepseek-harness` / `deepseek-harness-plugin` / `dsh`
|
||
- `sidebar` / `workspace` / `workspace-groups`
|
||
|
||
`package.json` 同时提供 `keywords` 便于 npm/搜索索引。
|
||
|
||
## 开发
|
||
|
||
```sh
|
||
pnpm install
|
||
pnpm typecheck # host + client 双 program 类型检查
|
||
pnpm test # 核心规则、overlay、树派生单测
|
||
pnpm build # 构建 lib/(node 半 + client bundle)
|
||
pnpm watch # tsdown 监听(client HMR)
|
||
node scripts/verify-groups.mjs # 真机 CDP 验证(host 已重启时;自启独立 headless Chrome,自动恢复现场)
|
||
```
|
||
|
||
产物契约(与官方 client 包一致):
|
||
|
||
- `lib/index.js` —— host 半(ESM;读取 sidecar + `/workspace-groups/config` 路由,
|
||
js-yaml 已内联,无运行时依赖)
|
||
- `lib/client.js` —— browser 半(`window.__ModuleLoader__.load({id, factory})`;
|
||
仅 require 平台 seed:react / react/jsx-runtime / @deepseek-ai/dsh-client-runtime/client /
|
||
@deepseek-ai/dsh-client-ui-primitives;跨插件值 import 在构建期被 purity 门拒绝)
|
||
- `lib/types/**` —— 声明文件
|
||
|
||
> 发布策略说明:`lib/` 构建产物随仓库提交(无 `prepare` 脚本),因此
|
||
> `dsh plugin add github:...` 全程无需执行第三方构建脚本,安装即用。
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
src/
|
||
index.ts # host 半:config 快照路由 + manual 写路由
|
||
host-config.ts # sidecar YAML 读取/校验
|
||
host-manual.ts # runtime overlay 读写/校验(原子发布)
|
||
context-types.ts # host 侧 cordis 服务结构类型
|
||
core/
|
||
types.ts # 配置类型(两半共享)
|
||
matcher.ts # 分类规则 + 手动覆盖优先级 + 排序纯函数(两半共享)
|
||
client/
|
||
index.ts # apply:注册 sidebar.workspaces(priority -1)
|
||
contract.ts # 注入面类型
|
||
stores.ts # 展开状态 store(persist: dsh.workspace.groups.view.v1)
|
||
tree.ts # 三层树派生 + 树形搜索派生
|
||
GroupsBrowser.tsx # 浏览区域组件(分组弹窗 + 拖拽归类/排序 + 插入指示线)
|
||
rows.tsx # 分类/项目/会话/搜索结果行(拖拽源/目标)
|
||
locales.ts # 中英文案
|
||
styles.css # 内联样式
|
||
tests/
|
||
core.test.ts # 分类规则 + 手动覆盖优先级 + moveBefore/moveAfter + 配置解析
|
||
manual.test.ts # overlay 校验 + 文件原子往返
|
||
tree.test.ts # 树派生渲染契约(手动分组空渲染/覆盖优先)
|
||
store.test.ts # 展开状态语义(折叠写 false 不删 key)
|
||
scripts/
|
||
verify-groups.mjs # 真机 CDP 验证(自启 headless Chrome,自动恢复现场)
|
||
```
|
||
|
||
> 开发文档(`docs/` 五级框架与 `AGENTS.md`)是开发用工程文件,**不随仓库分发**
|
||
> (已在 `.gitignore` 排除)。
|
||
|
||
## 验证记录
|
||
|
||
- v0.1/v0.2 真实组合验证(headless Chrome + CDP 实操):三层树顶替生效、分类正确、
|
||
展开持久化、搜索保留归属;`workspace.json` / 会话落盘 / 官方 store 零侵入。
|
||
- v0.3 真机验证 24/24(`scripts/verify-groups.mjs`:建组/拖拽/排序/收起/规则分类
|
||
菜单/重命名/删除回顶层/现场恢复,零侵入断言)。
|
||
- v0.4 真机验证 30/30(新增:插入指示线、项目/分组**向下拖**(行下半 → 插到目标
|
||
之后)、分组向上拖(行上半 → 移到目标之前);现场恢复通过)。
|
||
- v0.4.1 真机验证 34/34(新增:**从分组拖出**——顶层落点区/顶层行 drop =
|
||
强制顶层;分组内项目行菜单「移出分组」)。
|
||
- v0.5 真机验证 35/35(模型变更:**无「未分类」桶**——顶层项目行、删除分组成员
|
||
回顶层、拖拽/菜单移出到顶层、树中不存在未分类桶;现场恢复)。
|
||
- v0.6 真机验证 40/40(新增:**按级别收起**——拖项目只收起项目行(分组行不收)、
|
||
拖分组只收起分组行(项目行不收);dragend 还原拖动前展开快照)。
|
||
- v0.6.1 真机验证 42/42(新增:**整个顶层区域为移出落点**且拖拽中有可见高亮提示;
|
||
分组/项目行图标区分;现场恢复)。
|
||
- v0.7 真机验证 46/46(新增:顶层落点改用**插入横线**(非高亮框)——拖到顶层行前/后、
|
||
最后一行下方追加、顶层为空时独立横线;**顶层项目可排序**,顺序持久化
|
||
`workspaceOrder["__topLevel__"]`;并修复 host 校验拒绝 `__topLevel__` 与
|
||
「拖到两行之间却落在上一行上面」的落点定位 bug;现场恢复)。
|
||
- 单测 66 用例全绿(vitest:`core` / `manual` / `tree` / `store`)。
|
||
- 可复跑的自动化真机验证:`node scripts/verify-groups.mjs`(需 host 已重启)。
|
||
|
||
## License
|
||
|
||
MIT
|