前言¶
在 DeepSeek Harness（DSH）里把官方侧边栏收起来，往往意味着工作区与会话列表也跟着藏进窄条或图标里。社区里较早的浮动侧边栏方案（例如 dsh-floating-sidebar）通过复用官方侧边栏 DOM 并覆盖 grid，让鼠标贴边时能「浮出」列表，但中栏会在开合时整体重排，动画也只能动 left，每帧触发布局。
dsh-sidebar-overlay 换了一条路：不碰官方侧边栏列，也不改官方 grid，而是在官方 shell.overlay 浮层座位上自建一套工作区与会话浏览 UI。下面介绍它是什么、能做什么，以及如何安装与日常使用。
这是什么¶
dsh-sidebar-overlay 由维护者 blockman0321 发布，分类为客户端插件（npm 包名 dsh-sidebar-overlay，当前版本 0.1.0，MIT 许可证）。一句话定位：在侧边栏折叠时，鼠标移到窗口左侧对话区下方的一段热区，会浮出一张宽 280px 的卡片（工作区 + 会话列表），覆盖在内容之上，不挤压中栏；指针离开热区或窗口即收回。
数据与写操作走 DSH 官方公开的 root hooks 与服务（useSessions、useWorkspaces、ctx.uiWorkspace 等），不抓官方侧边栏 DOM，也不依赖官方哈希类名选择器。
架构上解决了什么¶
与 dsh-floating-sidebar 相比，本插件的差异可以概括为：
| 维度 | 旧方案（CSS 覆盖） | dsh-sidebar-overlay |
|---|---|---|
| 承载方式 | 改官方列 + 覆盖 grid | 注册 shell.overlay |
| 官方 grid | 开合时被覆盖 | 不触碰 |
| 中栏重排 | 有 | 无（README 称开合全程 grid 取值不变） |
| 动画 | 多为 left（layout） |
transform（合成） |
官方 sidebar / sidebar.workspaces 是 single 座位，第三方不能重复声明；因此浮层里的列表是自建 UI，而不是把官方侧边栏 DOM 搬过来。其他插件挂在官方侧边栏上的扩展位（例如 sidebar.workspaces.session.menu.item）不会出现在本浮层里——这是 slot「声明即认领」规则带来的已知限制。
核心功能¶
以下能力均来自插件 README 中的功能清单与说明。
浮层交互与热区¶
- 默认仅在侧边栏折叠时浮出（
onlyWhenCollapsed: true可改）。 - 热区上边界为对话内容容器顶边（对话区 header 下方）；标题栏、对话/轨迹 tab 等不在热区内。
- 热区右边界为「窗口左缘 → 对话内容列左缘」留白的 40%（
triggerRatio，可配置）；例如 1020px 宽窗口下内容列左边缘 170px 时，热区约为0..68，而不是贴边 24px 窄带。 - 几何在冷路径重测（初始、
resize、开合瞬间、指针在热区外时最多每 500ms），热路径读缓存，减轻pointermove上的布局压力。
顶栏¶
- 左侧个人信息（头像）：点击直接打开官方设置弹窗，不弹账户菜单，因此没有「联系我们 / 退出登录」。账户数据来自
settings.launcher的accountobservable；打开设置走sidebar.settings条目的store.create().actions.open()。README 明确警告：不要用ctx.shortcuts.invoke('settings.open')，会静默失败。 - 右侧「新会话」按钮，带快捷键提示；可用
showProfile/showNewSession单独关闭。
工作区与会话¶
- 工作区分组：按工作区 / 按工作区树 / 单列表，可切换并持久化到
localStorage（键dsh.floatingSidebarOverlay.view.v1）。 - 新建、重命名、删除工作区，拖拽排序，添加目录；「未分组」桶行为与官方一致（无「…」菜单与新建会话按钮，且仅在可见成员非空时显示）。
- 会话行：状态点、标题、相对时间、置顶、hover 操作（菜单 → 归档 → 置顶）；打开、重命名、分叉、置顶/归档及「停止并归档」确认等，语义对齐官方。
- 搜索：本地标题与工作区名匹配，远端内容搜索 250ms 防抖；视图选项菜单支持排序、筛选已归档等。
视觉¶
- 优先
require官方@deepseek-ai/dsh-client-ui-primitives的Menu、Modal、Tooltip等；缺失时逐项降级为内置最简实现。
安装与启用¶
插件已发布到 npm。在 DSH「插件」页点「添加插件」，输入包名 dsh-sidebar-overlay；或使用 CLI（Web profile）：
# Web profile
dsh plugin --profile web add dsh-sidebar-overlay
# 其他 profile 把 web 换成对应名字；Desktop 内置 profile 请走图形界面，
# CLI 不允许管理 desktop profile。
装完后重启 DSH（启用 HMR 的 profile 会自动重组，不必重启）。package.json 声明引擎为 dsh ^0.2.0-rc.2，客户端为 web 平台且 immediately: true。
卸载可在插件页操作，或：
dsh plugin --profile web remove dsh-sidebar-overlay
然后重启 DSH；README 称会移除注入样式与相关 DOM 标记。
互斥：不要与 dsh-floating-sidebar 同时启用，否则会出现两个浮动侧边栏。
典型用法¶
- 用
Ctrl+B或标题栏按钮折叠官方侧边栏。 - 将鼠标移到窗口左侧、对话区 header 下方的留白区域（热区左 40% 留白，见上表）。
- 浮层卡片出现后，照常浏览工作区、打开或管理会话；移出热区或窗口后卡片收回。
总开关默认快捷键为 Ctrl+Alt+L（可在配置里改 hotkeyBinding）。也可在浏览器控制台调用：
window.__dshFloatingSidebarOverlay.toggle() // 切换
window.__dshFloatingSidebarOverlay.disable() // 停用（回到官方行为）
window.__dshFloatingSidebarOverlay.enable()
window.__dshFloatingSidebarOverlay.isEnabled()
window.__dshFloatingSidebarOverlay.isOpen()
在 profile 的 cordis.patch.yml 中可覆盖插件条目 sidebar-overlay 的 config，例如热区比例、卡片宽度、是否仅在折叠时显示等：
- id: sidebar-overlay
name: 'dsh-sidebar-overlay'
config:
enabled: true
width: 280
gap: 8
radius: 16
trigger: 'content'
triggerRatio: 0.4
closeSlack: 8
animationMs: 180
onlyWhenCollapsed: true
groupBy: 'workspace'
orderBy: 'updated'
showNewSession: true
showProfile: true
hotkey: true
hotkeyBinding: { code: 'KeyL', modifiers: ['primary', 'alt'] }
Desktop 的 patch 路径示例为 ~/.dsh/profiles/desktop/cordis.patch.yml；Web profile 将 desktop 换成 web。完整字段见 GitHub README。
适用场景与注意¶
适合谁：习惯折叠官方侧边栏、又需要频繁切换工作区与会话的 DSH Web 用户；希望浮层开合时不牵动中栏布局、并愿意使用一套与官方侧边栏并行、而非扩展官方 DOM 的列表 UI。
使用前请知悉：
- DSH 插件在当前 DSH 进程权限下运行，安装前建议阅读 源码 与 MIT 许可证，自行判断是否信任维护者与依赖链。
- 社区目录 SkillHub 插件页 是独立站点，与 DeepSeek / 幻方无官方从属关系，并非官方应用商店。
- 不含官方
sidebar.panellist的全局面板图标；依赖官方 hook 名与 primitives 模块，变更时可能降级为空列表并打控制台告警。 - README 注明未在带 launch token 的真机 DSH Web 上完整端到端验证；真机可用
document.querySelector('[data-dsh-fso-card]')自检浮层是否挂载。
结尾¶
dsh-sidebar-overlay 把「折叠后仍能快速浏览工作区与会话」做成独立浮层：注册官方 shell.overlay，自建 UI，读写官方公开数据契约，从设计上避开对官方 grid 与侧边栏 DOM 的改造。若你在用旧的 CSS 浮动侧边栏且介意中栏重排，可以评估迁移；安装时注意与 dsh-floating-sidebar 互斥，并按 profile 正确添加 npm 包。
