前言¶
用 DeepSeek Harness（DSH）做智能体或长会话开发时，官方侧栏按工作区组织会话：每个会话绑定一个工作区，日志和归属由宿主管理。实际任务往往跨多个工作区并行——例如同一项目在不同 repo 里各开一条会话——侧栏里只能按工作区切换，很难用「项目 / 阶段」这类维度一眼扫全相关会话。移动会话到别的工作区会动到底层归属，通常也不合适。
下面介绍社区客户端插件 dsh-session-groups（维护者 momijijin）：在官方工作区/会话侧栏之上加一层「自由分组」视图，只改插件自己的分组记录和展示位置，不改官方工作区成员关系、不写 workspace.json、不动会话日志。
这是什么¶
dsh-session-groups 是 DSH 的客户端插件（分类：客户端），当前版本 0.3.0-beta.76。它把侧栏扩展为可在「官方工作区视图」与「自由分组视图」之间切换；同一分组可以收纳来自不同工作区的会话，会话仍属于原工作区。
插件数据与官方数据分离：分组记录落在 <dshHome>/storages/dsh-session-groups.json，UI 偏好写在 localStorage（如 dsh-session-groups.view.v1 等）。卸载后官方侧栏恢复默认视图，分组文件和偏好会保留，重装可恢复。
目录页：skillhub.cn/plugins/momijijin/dsh-session-groups（社区插件目录，与 DeepSeek / 幻方无官方从属关系）。源码：github.com/momijijin/dsh-session-groups，许可证 MIT。
核心功能¶
视图与布局¶
- 自由分组视图与官方工作区视图切换。
- 侧栏宽度可拖（264px 起，默认 420px，最大视口宽度 80%）；双击把手恢复默认。
- 视图模式、宽度、折叠状态、归档筛选、弹窗几何会持久化；「视图选项」里可 恢复默认布局（不动分组数据）。
分组与会话¶
- 根分组与子分组最多 8 层；可重命名、换图标、预设色或自定义
#RRGGBB。 - 拖拽排序、改父级、子树跟随；空叶分组可直接删，非空分组删除前可选子会话/子组去向。
- 会话可拖入分组或拖回「未归组」；支持打开、重命名、归档/取消归档、菜单分叉（基于最后已完成轮次）、复制 Session ID。
- 搜索匹配标题、工作区名、分组路径（最多 20 条）；选中后展开祖先并高亮。归档三态：隐藏 / 全部 / 仅归档。
头部状态¶
三个互斥统计按钮：执行中、等待用户介入、未读；下拉按分组列会话，点击打开。不包含后台 job 计数。
可选 AI 控制¶
默认关闭。在 Plugins → dsh-session-groups 详情页第一层可开 controlApi 等开关（见下文配置）。开启后 Host 原生工具 session_groups_control 可规划/应用分组变更；改名、归档、破坏性删除分别受 controlSessions、controlDestructive 门禁。普通用手拖分组即可，不必开 AI 控制。
安装与启用¶
推荐通过 dshmarket 安装。在市场中搜索：
dsh-session-groups
资料说明：市场条目正在准备中；上架后应完全通过 dshmarket 安装与更新。若曾用本地 tarball 安装，上架后需从市场重装一次，让安装来源绑定目录。本地 tarball 与 CLI 仅维护者/调试用，见仓库 docs/RELEASE.md，不要自行拼接未在文档中出现的 dsh plugin add github:... 命令。
兼容性（安装前核对）：
- DSH core/API：
engines.dsh为>=0.2.0-rc.2 <0.3.0，主要对应@deepseek-ai/dsh0.2.1-rc.2 与 0.2.1-rc.5。 - 已验证桌面壳：社区 DSH Desktop Stable 2.0.18；官方 DeepSeek Harness 桌面版 0.2.1.0。
- 不官方支持：社区 DSH Desktop Beta、社区 DSH NEXT（
-next通道）。 - Linux 上 Node/构建经 GitHub Actions 验证，真实 DSH UI 在 Linux/macOS 上资料标注为未验证或 experimental；Windows 本地 UI 已验证。
安装后启用插件，在侧栏切换到自由分组视图；首次会有一次性说明卡（可 dismiss，状态存 localStorage）。
典型用法¶
手动编排（最常见）¶
- 在自由分组视图新建根分组（无分组且无会话时，空状态也可创建第一个分组）。
- 从「未归组」或其它分组把会话拖入目标组；需要跨工作区归类时，直接拖即可，官方工作区归属不变。
- 用搜索定位会话；需要时用归档筛选隐藏或只看归档项。
- 维护分组结构：拖拽改顺序或父级；删除非空组时按提示选择子项去向。
用 AI 批量建组（可选）¶
先开启 AI 控制接口（controlApi）。若还要 AI 改名，再开 会话操作（controlSessions）。在会话里发给 AI 的提示词示例（摘自 README，路径按你的项目名替换）：
用 session_groups_control 创建或复用以下分组层级：
〈项目名〉项目组 — 图标 server，颜色 blue
- 设计中 — 图标 book，颜色 purple
- 开发中 — 图标 play-circle，颜色 blue
- 已挂起 — 图标 clock，颜色 orange
- 已完成 — 图标 check-circle，颜色 green
- 已取消 — 图标 x-circle，颜色 red
已有分组复用，只补缺失的子组。先查 state/resolve；路径不存在或有歧义就停下来问我。再 plan，把 changes 和 planHash 给我看，最后用同一个 planHash 和 baseRevision 执行 apply。
AI 应通过 plan + apply（带 planHash 与 baseRevision）提交，避免盲目改组。
配置项¶
插件管理器 Plugins → dsh-session-groups 第一层有五个开关，默认均关闭：
| 配置 | 默认 | 作用 |
|---|---|---|
diagnostics |
关闭 | 拖拽 HUD 与本地 NDJSON trace；热生效 |
debugProbe |
关闭 | 弹窗布局探针；生产勿开 |
controlApi |
关闭 | 原生 session_groups_control 与调试 HTTP 路由总开关 |
controlDestructive |
关闭 | 允许 AI 控制执行删除等破坏性操作；开启需二次确认 |
controlSessions |
关闭 | 允许 AI 改会话名、归档；需同时开 controlApi |
诊断写入（仅 diagnostics 开启时）：
<dshHome>/storages/dsh-session-groups.diagnostics.ndjson
适用场景与注意¶
适合谁： 在 DSH Desktop 里同时维护多条跨工作区会话，希望用自定义树形分组做项目/阶段视图，又不想改动官方工作区结构的开发者。
运行与权限： 插件随当前 DSH 进程加载，读写 <dshHome>/storages/ 与浏览器 localStorage；开启 controlApi 后 AI 可在门禁内改分组乃至会话元数据。安装前应阅读源码与 MIT 许可证，确认接受数据路径与可选 AI 控制范围。
数据与多窗口： 分组是单窗口本地状态；多窗口并发写可能遇到 409，需按提示刷新。彻底移除痕迹需手动删除 dsh-session-groups.json、.bak 及上述 localStorage 键。
生态： DSH 主张「一切皆插件」；本插件是侧栏上的展示与分组层，官方工作区与会话管理仍是权威来源。
结尾¶
dsh-session-groups 解决的是「跨工作区、不动底层归属」的侧栏编排问题：自由嵌套分组、拖拽、搜索与归档筛选，数据本地持久化并带 .bak 恢复；AI 控制为可选项。需要详情与版本说明时，可看社区目录页与 GitHub README（含 docs/COMPATIBILITY.md）。
- 目录页：https://www.skillhub.cn/plugins/momijijin/dsh-session-groups
- GitHub：https://github.com/momijijin/dsh-session-groups
