悬停侧边栏 ingeb0rga/dsh-sidebar-hover

dsh-sidebar-hover

DeepSeek Harness 的悬停展开侧边栏——运行时客户端插件（客户端 UI 扩展），参照 Claude Code 的侧边栏设计。鼠标悬停在折叠的侧边栏导轨上（或 macOS 标题栏的重新展开区域），经过短暂的意图延迟后，侧边栏会浮在内容之上展开；移开后经过宽限期自动收起；激活会话、工作区、New Session 或 Settings 会立即收起。悬停展开期间点击侧边栏开关会将其固定展开；通过点击打开或固定的侧边栏会忽略悬停，直到再次点击关闭。悬停展开期间按 Mod+B 可关闭。

同时在 macOS 上，于侧边栏开关旁添加 Claude Code 的会话历史箭头（← →），快捷键为 ⌘[ / ⌘]。

设置位于独立页面：Settings → Sidebar hover。

- "Hover to reveal sidebar"——默认开启；悬停延迟 50–1000 ms。
- "Session history arrows"——默认开启。

已在 DeepSeek Harness macOS 桌面应用 0.2.0-rc.2 上测试。

| | 桌面端（macOS） | Web（dsh web，浏览器） |
| 悬停展开 | 悬停在红绿灯按钮旁的侧边栏开关上 | 悬停在折叠的 56 px 导轨上——未做实测 |
| 历史箭头 ← → | 支持 | 不支持（仅 macOS 桌面端） |
| ⌘[ / ⌘] | 支持 | 不支持（浏览器占用） |
| Settings → Sidebar hover | 支持 | 同一份客户端代码——未做实测 |

Windows / Linux 桌面版未测试。
当前版本 0.1.22。

文档：

- DEVELOPMENT.md——版本历史、当前状态、待办事项；
- FINDINGS.md——集成分析，以及插件所依托的宿主接缝；
- QA-CHECKLIST.md——手动测试矩阵；
- dsh-sidebar-hover-plugin-task.md——原始任务规格。

行为（规则 → 实现）

| 规则 | 实现 |
| 悬停导轨 / darwin 侧边栏开关图标 → 180 ms 意图 → 展开（New Session 及其旁边的箭头不触发展开） | 窗口级 pointermove + 区域矩形计算；意图延迟可配置（50–1000 ms）。 |
| 展开时浮在内容之上（不重排） | src/client/overlay.ts：布局确实会扩展（这样侧边栏才能渲染出完整宽度），但框架网格通过 CSS 变量上的 !important 规则固定为折叠轨道；宽侧边栏根节点用不透明填充 + 阴影溢出其折叠列。基于 [data-sidebar-collapsed] 的布局 CSS（darwin 前导留白、居中边框）做了镜像处理。 |
| 开关图标保持在红绿灯按钮旁（darwin） | 功能开启时，侧边栏顶部条将开关左对齐到前导座位的偏移量（88 px；全屏时已是 12 px），因此折叠、展开和固定三种状态下都显示在同一位置。 |
| 展开期间点击开关 → 固定 | 文档捕获阶段的 click 在 React 之前吞掉开关点击；状态机将扩展权交给用户（惰性），网格从浮层动画过渡到推挤布局。点击关闭（或 Mod+B）后重新启用悬停。 |
| 离开 peek → 250 ms 宽限 → 折叠；重新进入则取消 | 纯状态机（src/client/state-machine.ts），只有在没有 hold 生效时才启用宽限。 |
| 选择折叠（会话/工作区行、New Session、Settings 点击）、peek 中按 Esc | document 上的冒泡阶段 click（在 React 之后，因此会 stopPropagation 的行内控件——会话 ... 菜单、行操作——永不折叠）+ 捕获阶段 keydown Esc；绝不触碰用户自己的展开状态。 |
| Mod+B / 切换按钮优先 | 不是由我们发起的 frame data-sidebar-collapsed 翻转，会作为外部事件上报给状态机。没有定时锁定：peek 是边沿触发的，所以指针仍停在切换按钮上时不会再次 peek，直到它离开再回来。 |
| 启动 | DSH 启动时侧边栏始终展开；如果首次加载偏好设置时该功能已开启，插件会折叠一次，让悬停立即生效。会话中途启用该功能则永不折叠。 |
| Holds：指针在内、键盘焦点、拖拽/滚动、右侧面板刚打开、打开的菜单/对话框（[role=menu\|dialog\|alertdialog]，portal 到侧边栏之外） | 全部编码为状态机 hold 规则；focus-visible 立即显示，没有意图延迟。 |
| prefers-reduced-motion | 上游 CSS 已禁用 frame/sidebar 过渡——插件无需处理。 |
| a11y | Rail tooltip/aria 保持原样；侧边栏容器上没有 aria-expanded（它不是 disclosure 控件）；Esc 折叠 peek。 |
| 会话历史箭头 ← →（darwin）+ ⌘[ / ⌘] | navigator.ts：DSH 不保留导航历史，所以插件把每次主视图选择（uiWorkspace.selection）记录进浏览器风格的后退/前进栈（history.ts，最多 100 条，会话作用域），并用 uiWorkspace.openSession() 步进。箭头是 shell.overlay 条目，放在切换按钮右侧（left 124 px / fullscreen 48 px）；折叠时，座位的 New Session 和内容的前导留白右移 68 px。无法打开（已删除）的条目会被丢弃。快捷键通过 ctx.shortcuts（仅桌面端），无处可去时直接透传。 |
| 自己的设置页 "Sidebar hover"（切换 + 延迟、箭头切换） | 宿主设置命名空间 dsh-sidebar-hover，带 volatile 字段；通过插件自己的 /sidebar-hover/api 路由访问（见下文「持久化」），不新增 store，不用 localStorage。 |

按设计不在范围内：折叠几何、rail 宽度、darwin 标题栏契约（data-window-drag、--dsh-frame-leading-clearance）、Mod+B 绑定，以及客户端 UI 之外的任何内容。

包结构

src/
shared/prefs.ts namespaced constants + defaults + coercion
node/index.ts node half: schemastery Config (volatile) + settings-page suppression + /sidebar-hover/api route
client/
state-machine.ts pure hover state machine (no DOM, injected clock)
state-machine.test.ts 36 vitest cases: intent, grace, select-collapse, Mod+B, keyboard, holds, init, overlay, pin
controller.ts 把机器绑定到实时侧边栏（DOM 锚点、监听器） overlay.ts 浮层预览：冻结的网格轨道 + 注入样式表，pin 交接 dom.ts 与 hash 无关的 DOM 锚点 + 悬停区几何 prefs-store.ts 偏好镜像，走插件 HTTP 路由（+ 退避重试、失效通知） settings-row.tsx 「Sidebar hover」设置区（悬停开关 + 延迟、箭头开关） history.ts 纯前进/后退会话历史 history.test.ts 11 个 vitest 用例 navigator.ts 从 uiWorkspace.selection 喂入历史，⌘[ / ⌘] 快捷键，箭头 CSS arrows.tsx 标题栏 ← → 按钮（shell.overlay 入口） locale.ts 带类型的 en/zh 词典 index.ts 客户端胶水（只放 slots + effects） types/dsh.d.ts 环境服务接口（独立编译）

持久化

开关和延迟是插件条目自身 Config 的易失字段（enabled、hoverDelayMs），位于设置命名空间 dsh-sidebar-hover 下（即 loader 行 id）。写入走宿主设置服务，由 loader 提交到配置档补丁层（~/.dsh/profiles/<name>/cordis.patch.yml，插件行的 config: 块），因此重启应用后依然保留。渲染进程在这里没法直接调用 settings remote （在桌面部署上 ctx.remote.settings.describe() 返回空命名空间列表），所以 node 那一半——跑在宿主进程里——通过插件自有的 HTTP 前缀路由暴露两个方法：

- POST /sidebar-hover/api/prefs.get → {ok, value: {value, revision}}；
- POST /sidebar-hover/api/prefs.update，带 {payload: {patch, expectedRevision}} → 回显视图。

这条路由的防护方式和 dsh-better-sidebar 给 /sidebar 路由做的一样： Host 必须是回环地址或部署的可信 authority， sec-fetch-site: cross-site 会被拒绝，若带 Origin 则必须与 Host 主机名匹配。
版本不匹配会以 settings/conflict 报出，客户端重新读取一次。

构建

要求：Node 20+（开发环境是 26）、npm。不需要 pnpm。
bash
cd ~/git/dsh-sidebar-hover
npm install # esbuild install-script may need: npm install-scripts approve esbuild
npm run typecheck # tsc --noEmit
npm test # vitest run — state machine suite
npm run build # lib/index.js (node half, ESM) + lib/client.js (client bundle)
npm pack # dsh-sidebar-hover-<version>.tgz (git-ignored)

lib/client.js 是一个 window.__ModuleLoader__.load({ id, factory }) 闭包工厂 bundle，所有 @deepseek-ai/* + React 外部依赖都留给宿主模块表——和官方 tsdown.client.ts 产出的形态一致。

安装（桌面应用，macOS）

从 npm 安装，走配置档的插件管理器（它会在 ~/.dsh/profiles/desktop 里跑 pnpm）： bash
dsh plugin --profile desktop add dsh-sidebar-hover
或从插件市场安装。本地构建的安装方式相同，用打包好的 tarball： bash
npm run build && npm pack
dsh plugin --profile desktop add file:$PWD/dsh-sidebar-hover-<version>.tgz

这会把 file: spec 记录到配置档的 package.json + pnpm-lock.yaml，并把包加进 dsh.profile.bundles。cordis.patch.yml 里的 bundle 补丁层会挂载插件行（id: dsh-sidebar-hover，hover 默认 enabled: true）。

- 保留 tarball，放在记录下来的路径：每次配置档重新同步都会重新解析它，tarball 缺失会中断同步。
- 不要手动把文件拷进 node_modules：下一次重新同步会清掉配置档 package.json 里没列出的东西（2026-10-06 就因此删掉了一个手动打补丁的 0.1.9）。
- 版本升级 = npm pack + 用新 tarball 路径执行同样的 add。

重启应用（插件代码按进程缓存），然后检查 Settings → Plugins（dsh-sidebar-hover 已启用）和 Settings → Sidebar hover（插件自己的页面）。

安装（web / dsh web）

未做实测——见开头的支持表。对 web 配置档执行同样的命令： bash
dsh plugin --profile web add dsh-sidebar-hover

web 模板还额外带 dev:web watcher（dsh-client-hmr）；它跑起来后，改动 lib/client.js 会在重新加载时热替换，靠的是 /plugins 的 revision 路由（rev = mtime/ctime/size 哈希）。

卸载 / 禁用

- 运行时：Settings → Plugins → 把插件关掉（往配置档补丁层写入 disabled）——或者干脆让「Hover to reveal sidebar」开关保持 OFF，这样插件仍然挂载但完全休眠（没有监听器，没有 DOM 写入）。
- 彻底移除：dsh plugin --profile desktop remove dsh-sidebar-hover，或者手动删掉 - insert: 行 + bundle 条目。

已知限制

- DOM 锚点按哈希无关的方式解析（_[hash]_frame、_[hash]_sidebarCol、data-sidebar-collapsed、[data-shell-leading]）。如果未来的 DSH 构建改了这些名字，插件会休眠失败，只打一条控制台警告——它不会反复猜测，也不会跟 UI 对着干。
- 浮层依赖 DSH rc.2 的内部实现：frame 的内联 grid-template-columns（第一条轨道 = 侧边栏）、侧边栏开关的 _toggle class token，以及拖拽手柄的 data-side="sidebar"。这些一旦变化，peek 可能又把布局顶开，或者 pin 点击可能穿透到原生开关（折叠）——不会硬失败。
- peek 打开期间，中间/右列的标题栏条带不是窗口拖拽区域（Electron 按 DOM 顺序而非堆叠顺序决定拖拽区域，所以它们会吞掉浮层侧边栏上的点击）。要拖窗口，请用没被覆盖的条带，或等 peek 关闭后。
- 会话历史存在内存里：每次启动应用都从空开始（用恢复的会话做种子），窗口之间不共享。
- 箭头只在 macOS 上渲染（它们对齐 macOS 的 leading 座位）。
⌘[ / ⌘]（Ctrl+[ / Ctrl+]）快捷键只在桌面版注册，Web 模板不注册——在浏览器里这两个键归浏览器管。

- 浮层几何在 peek 开始时冻结，只有右侧面板打开、关闭或进入全屏时才重新读取。
- 窗口宽度小于屏幕可用宽度的 1/3（screen.availWidth）时，悬停展开关闭。这是相对值，所以任何分辨率、缩放或显示器都适用。窗口 resize 和指针移动（移到另一台显示器）时会重新检查。低于 1024 px 时，DSH 自己的侧边栏仍是一个网格列（narrowExpanded 开关）——插件在这时照常工作；右侧面板打开或窗口跨过 1024 px 时，DSH 会自己关掉它，插件把这种情况当作你手动收起。
- 选择收起覆盖那些能到达 document 的点击激活（会话行、New Session、Settings 触发按钮）。以下是有意排除的：
- 展开 / 弹窗控件（aria-expanded、aria-haspopup）——工作区行展开会话列表时，peek 保持存活；
- React 处理函数里调用了 stopPropagation 的控件——会话 / 工作区的 ... 菜单、取消归档、搜索清除，以及每个工作区的「+」（新建会话）：这一个不再收起 peek（已知取舍）。
- peek 还开着时，用键盘快捷键打开 Settings 或新建会话不会被拦截——peek 之后和其他离开一样，走 grace 消失。
- 选择收起只作用于插件自己打开的 peek。你手动展开的侧边栏（开关、Mod+B）永远不会被点击收起——这是有意设计。
- 浮层保持匹配文档里任何可见的 [role=menu|dialog|alertdialog]，不限于从侧边栏打开的那些。