前言¶

DeepSeek Harness（DSH）的桌面 Web UI 左侧栏，导航项和工作区列表挂在同一列里。条目一多，窗口高度不够时，靠下的导航点不到，工作区也只能看到上半截。原生布局里，各段往往各自滚动或固定高度裁切，没法把「整列」当成一个可读区域来用。

dsh-sidebar-groups 是社区客户端插件，由 2797218091 维护，归入 DSH 插件目录的「客户端」分类。它把导航与工作区合成一个可滚动区域，顶部 logo 与底部按钮保持固定，并为导航项、工作区分别提供可折叠分组；布局状态在重启后保留。下文按安装、用法、配置与边界说明，事实以 GitHub 仓库 README 为准。

这是什么¶

插件全称 dsh-sidebar-groups，当前版本 0.1.0，许可证 MIT。它只改造侧栏 DOM 与客户端 bundle，不修改 DSH 本体 app.asar，也不动 profile 里第三方包的源码。依赖 DSH >= 0.2.1-rc.1 的公开 slot、settings 与 Web 路由；不发网络请求、不注入远程脚本、不使用 eval。

一句话：解决左侧栏「内容被裁切」和「条目多时难以收纳」两类问题，用整列滚动 + 分组折叠，并通过配置持久化保留你的布局选择。

核心功能¶

README 将能力归纳为六点，此处只列已在文档中核实的内容。

整列滚动（F1）
导航项与工作区落在同一滚动容器内；鼠标停在列内任意位置（含工作区条目）即可滚动。顶部区与底部按钮不参与滚动；overscroll-behavior: contain，滚到顶或底不会把滚动传给页面。滚动条较细、悬停才更明显，出现与消失尽量不引起横向抖动；内容不足一屏时不显示滚动条。

导航分组（F2）
每个导航项有稳定 id（来自 slot 注册表），不按显示文字匹配。项可放顶层或收进任意分组，分组可折叠；组间与组内顺序在面板里用上移 / 下移调整。折叠态、归属与顺序在重启后保留。

工作区分组（F3）
工作区段落同样支持分组折叠，配置与导航分组相互独立。不足两个分组时不绘制分组头，避免空组头占位。

配置入口（F4）
侧栏底部「分组」按钮打开面板，改动立即生效，无需刷新浏览器。配置写入 profile 相关机制（见下文「配置存哪儿」）；旧的独立文件 sidebar-groups.json 可一次性回迁，且不会覆盖你已用面板写过的值。

行为不回归（F5）
原导航的点击、跳转、激活态、图标与 tooltip 保持原样；侧栏收成图标条、窄屏抽屉态下插件整体不接管（表现与原生一致）。不出现横向滚动条、不会出现两个侧栏。

安全（F6）
除 host 侧为旧配置回迁而读取 profile 目录下 sidebar-groups.json（存在才读）外，无额外文件读取与远程行为。

对比截图见仓库 docs/screenshots/before.png 与 after.png。

安装与启用¶

推荐从 GitHub 安装；仓库已提交构建产物 lib/，package.json 无 prepare / postinstall，因此安装命令不会触发本地编译，也不会牵扯 pnpm 的 allowBuilds 构建授权。

dsh plugin add github:2797218091/dsh-sidebar-groups

README 还提到可选路径：自行 npm publish 后可用包名安装 dsh plugin add dsh-sidebar-groups，该形式在仓库说明中标注为沿用他插件写法、本仓库未实测。

装完之后需要两步，否则 bundle 不会挂载或浏览器仍用旧缓存：

1. 重启 DSH —— bundle 在启动时装配，不重启不会加载新插件。
2. 在浏览器中按 Ctrl+Shift+R 硬刷新 —— 客户端 bundle 响应带 immutable 缓存头，普通 F5 可能继续用旧副本。

卸载顺序（README 原文）：

dsh plugin remove dsh-sidebar-groups

若本地 cordis.patch.yml 里仍有手动添加的 link: 安装行，应先删掉；再执行 remove、重启 DSH 并 Ctrl+Shift+R。teardown() 会还原被隐藏的节点并移除插件容器与样式。

安装插件会以当前 DSH 进程权限运行客户端注入逻辑；安装前宜自行查看 源码与 LICENSE。

典型用法¶

1. 点击侧栏底部 「分组」 按钮（与设置同一行；侧栏收成图标条时仅显示图标，悬停有原生 title）。
2. 在面板中自上而下操作：
   - 整列滚动（顶部/底部固定） —— 取消勾选即恢复 DSH 原生侧栏布局；
   - 导航项 —— 右上角「+ 分组」；每组一行，可折叠、上移、下移、删除（至少保留一个分组）；组内每项可上移、下移，并通过「移到分组」下拉调整归属；
   - 工作区 —— 同样结构；
   - 底部 恢复默认 与 完成。点遮罩或按 Esc 关闭。
3. 出厂预设：导航顶层保留 插件、插件市场、任务看板 三项（顶层分组不显示标题行），其余收入默认折叠的「更多」组；工作区出厂只有一个「工作区」分组，故不画分组头。首次安装若只有单分组，视觉上可能接近「零变化」，这是「不留空组头」的设计。
4. 修改立即生效并写回配置；重启 DSH 后布局仍保留。

若出厂把三项常用导航认错（例如 boot 时 slot 注册表尚未填满），README 建议：打开「分组」面板 → 底部 恢复默认，会按当前完整注册表重算并落盘。

配置结构简述¶

配置挂在 settings 命名空间，对应 cordis.patch.yml 中的 insert id：

- insert:
    - id: sidebar-groups
      name: dsh-sidebar-groups

宿主侧 Config 含 state（整份状态文档，默认未配置）与 legacyImported（旧独立配置是否已回迁）。客户端 SidebarGroupsState 形状包括：

• version：当前 STATE_VERSION = 1
• scrolling：是否整列滚动，出厂为 true
• nav / workspaces：各自独立的 groups 数组

每个 GroupSpec 含稳定 id、显示 label、collapsed、showHeader、成员 items（导航侧为 slot id，工作区侧为段落标题文本处理后作 key）。出厂分组 id 含 top、more、ws-all。

客户端通过 /sidebar-groups/api/state 读、/sidebar-groups/api/update（POST，带 expectedRevision 乐观锁）写。浏览器另有 localStorage 键 dsh-sidebar-groups:state，仅在宿主路由不可用时兜底。README「已知限制」第 13 条说明：在部分环境下 settings 服务可能拒绝覆盖 cordis 注入的 entry，此时状态以本机 localStorage 镜像为主，关开 DSH 仍可保留；与 profile 挂载行的关系以实现为准。

适用场景与注意¶

适合谁
长期在 DSH 桌面端使用、侧栏导航和工作区条目较多、希望一列滚到底且按项目习惯折叠分组的开发者。

兼容性
要求 DSH >= 0.2.1-rc.1，Node >= 20（构建侧）。插件依赖 DSH 侧栏 DOM 与 data-sidebar-* 等结构锚点；大版本升级后若侧栏异常，宜先怀疑 DOM 适配层。无静态 inject 时插件会静默闲置，不会拖垮整个 GUI。

务必知晓的限制（节选）

• 工作区行不能重排顺序，只能调整「属于哪一组」与分组折叠；原因是 React 18 根事件委托，克隆节点无法可靠点击。
• 工作区分组 key 是段落标题文本；改名会导致丢失原分组归属。
• 图标条态、窄屏抽屉态、宽度动画进行中：插件跳过适配，表现同原生。
• 侧栏底部内边距相对原生略大（6 px → 16 px）；scrollbar-gutter: stable 会常驻预留约 5 px，避免滚动条显隐时横向抖动。

完整列表见仓库 README「已知限制」一节。

结尾¶

dsh-sidebar-groups 针对 DSH 左侧栏「裁切」与「杂乱」两类痛点，用整列滚动和双轨分组折叠给出可持久化的布局方案，并在 README 中写清 DOM 边界与安全行为。插件归属社区生态，目录站 SkillHub 插件页 与 GitHub 仓库 为查阅安装命令、面板操作与配置的入口；与 DeepSeek / 幻方无官方从属关系，安装与使用请自行审阅源码与许可证。