dsh-ui-state

August 27, 2026 · View on GitHub

界面状态持久化插件（DSH Web GUI）——官方侧边栏与详情面板跨重启恢复。

功能

  • 侧边栏开合：展开/收起状态自动持久化，重启 DSH 后自动恢复。
  • 侧边栏宽度：拖拽后的宽度自动持久化，重启后模拟拖拽恢复到上次宽度（264–420px 官方契约范围）。
  • 详情面板（details 列）开合：右侧详情面板的打开/关闭自动持久化并恢复（仅在会话打开时记录，避免把"无会话"误判为用户关闭）。
  • 对话滚动位置：切走/隐藏页面时保存当前对话的非底部阅读位置；视图因重连/重建回到顶部后自动恢复到切走前的位置（按消息 anchor 对齐，新消息追加也不会偏）。
  • 无需配置：全自动，无设置界面。

原理

官方 layout store 是瞬态设计（宽度/开合不持久化）。插件：

  1. 检测（事件驱动）：MutationObserver 监听 AppFrame 的 data-sidebar-collapsed / data-details-collapsed 属性与 grid-template-columns（style），ResizeObserver 监听视口（窄屏判定）；变化防抖 600ms，聚合为单次批量 mutate 写入 settings.yaml。 另保留 60s 安全兜底轮询，兜住观察者漏网的 DOM 替换 / portal 重渲染。
  2. 恢复：settings 就绪 / 框架挂载 / 会话流挂载等事件触发（600ms 重试链，最多 6 次， 事件可重新武装）：
    • 侧边栏开合：调用官方 ctx.layout.toggleSidebar()（等 layout 服务挂载后自动重试）
    • 侧边栏宽度：找到 [data-side="sidebar"] 拖拽手柄，派发合成 pointer 序列（pointerdown/move/up， 与官方 DragHandle 的监听协议一致；同步窗口内 stub pointer capture）
    • 详情面板：ctx.layout.openDetails() / closeDetails()（仅在会话打开时恢复）
  3. 窄屏保护：视口 < 1024px 时官方自动折叠侧边栏，此时不持久化、不恢复，避免与自动行为打架。
  4. 卸载保护：pagehide / freeze / 页面隐藏时同步落盘（fetch 带 keepalive）， 600ms 防抖窗口内关闭页面也不会丢最后一次操作。

性能

  • 零空闲轮询：状态读取由事件驱动，空闲时无周期任务；60s 安全兜底仅兜异常路径。 相对旧版 400ms 轮询，空闲开销从 2.5 次 DOM 扫描/秒降为 0。
  • 批量写入：一次折叠/宽度/详情变更合并为 1 次 mutate POST（旧版最多 3 次）， revision 乐观锁只校验一次。
  • 观察者收窄：会话区变更只检查新增节点；滚动恢复按 （scrollport, session） 实例 只执行一次，聊天流渲染期间不重复扫描。

配置存储

ui-state:
  sidebarCollapsed: false   # 用户显式折叠后为 true
  sidebarWidth: 360         # 最近一次展开宽度
  chatScroll:               # 按会话保存的非底部阅读位置（自动维护，可手删）
    "<sessionId>":
      anchorKey: "..."
      anchorTop: 120
      scrollTop: 480
      updatedAt: 1750000000000

兼容性

已验证目标为 DSH 0.1.1-rc.2（npm 最新已装版本，本仓库按该版本构建逐 seam 核对： @deepseek-ai/dsh@0.1.1-rc.2 + @deepseek-ai/cordis@4.0.1 + React 18.3 运行时）， 同一 0.1.x 版本线的最低 0.1.0-rc.8 同样覆盖。依赖范围故意写成双线 >=0.1.0-rc.8 <0.2.0 || >=0.1.1-rc.0：npm 的 prerelease「同元组」规则使 ^0.1.0-rc.8 并不包含 0.1.1-rc.2，双线范围可让宿主升级后 npm 去重为同一份 dsh-settings 实例（避免双实例导致的 SettingsConflictError instanceof 失效）。 实现基于能力探测与事件驱动，不绑定具体 rc 细节，跨版本漂移时以兜底分支降级。

已逐项核对的官方契约（0.1.1-rc.2 构建实测一致）：

  • settings 接缝：@deepseek-ai/dsh-settings（双线范围，见上），register / describe / mutate（含 SettingsConflictError 冲突拒绝与 revision 乐观锁）不变。
  • webServer 路由：register({ kind: "exact", path, handler }) 签名不变，返回 disposer。
  • layout 服务：ctx.layout.toggleSidebar() / openDetails() / closeDetails() 与 AppFrame 的 data-sidebar-collapsed / data-details-collapsed / grid-template-columns 契约不变；拖拽手柄 [data-side="sidebar"]（展开时才渲染， pointer capture + rAF 节流，pointerup 同步落宽）、窄屏 1024px 自动折叠同样保留。
  • DOM 锚点：[data-shell-overlay]（AppFrame 直接子节点）、[data-chat-flow]、 [data-chat-anchor-key]、[data-conversation-scroll]、[data-composer-seat] 在官方会话视图原样保留（官方自身滚动恢复同用这套锚点）。
  • client 通道：window.__ModuleLoader__.load 包格式、插件清单 dsh.client.inject/platform、sessions.list.getSnapshot().current、 connection.isLoopback 探针、ctx.layout 面板动作均不变。

跨插件兼容与加固（0.3.1）

  • settings 写冲突自动重试：另一插件抢先写同一 namespace 导致 settings-conflict 时，客户端刷新 revision 后重试一次，不再静默丢最后一次操作。
  • 存储容错：schema 全字段 .loose()——settings.yaml 被手改/旧版本/其他插件写入 越界或类型错误的值时，只把该字段降级为「未记录」，不会让整个 namespace 注册失败、 桥接不可用；下一次正常写入会覆盖。
  • chatScroll 有界：按 updatedAt 保留最近 200 条会话记录，长期使用 settings.yaml 不会无限增长。
  • 探测降级（官方 UI 升级耐性）：frameOf 在 overlay 层级漂移时回退到按 data-sidebar-collapsed / data-details-collapsed 直接找框架；会话判定用 [data-chat-flow] 存在性探测。官方 DOM 小幅变更时限入降级，而不是报错。
  • 宽度钳制：恢复侧边栏宽度前先钳到官方契约 264–420px，历史/外来越界值不会把 面板拖出可渲染范围。
  • 热装/重载幂等：settings 注册与其桥接路由挂在长期存活的 provider/webServer fiber 上，二次加载（loader.create 热装、HMR 重建）遇到上一实例残留的同名 namespace / 同 path 路由时复用而非抛错，不会因 "already registered" 挂掉挂载。
  • 共存原则：命名空间 ui-state 与桥接路由 /api/dsh-ui-state/* 均为本插件独占 （已核对官方与已知插件零冲突）；不补丁原生原型、不注入全局样式、不劫持事件， 合成拖拽仅同步窗口内 stub pointer capture，与 better-sidebar 等 localStorage 方案 以及 dsh-chat-width / dsh-client-ui-custom 等设置/样式/快捷键插件无交互冲突。

安装 / 下载

从 npm 安装（推荐）

dsh plugin --profile web add @zink-ning-lkr/dsh-ui-state

也可以手动安装依赖并装配：

npm install @zink-ning-lkr/dsh-ui-state

然后在 profile 的 package.json 中把 @zink-ning-lkr/dsh-ui-state 加入 dsh.profile.bundles。

从 GitHub Release 下载

到 Releases 下载 dsh-ui-state-0.3.0.tgz，然后安装：

dsh plugin --profile web add ./dsh-ui-state-0.3.0.tgz

本地开发 / 热装

profile package.json 的 dsh.profile.bundles 加入 @zink-ning-lkr/dsh-ui-state，依赖用 link: 指向本目录； 或使用 dev_install_package 热装（junction + loader.create，免重启）。

License

MIT © zink-ning (zink_ning)

关联

better-sidebar 等插件把状态存浏览器 localStorage——localStorage 按「域名+端口」隔离， DSH 启动端口随机（--port 0）时每次重启都会丢失。配套修复：DSH Desktop 源码 （D:\Code\dsh-desktop\main.js）已支持从 config.json 读 port 字段，把 %APPDATA%\DSH Desktop\config.json 的 "port" 固定为 13372 后，localStorage 状态 （含 better-sidebar 的面板布局）跨重启稳定。

结构

  • lib/index.js — Node half：注册 ui-state settings namespace + loopback 桥接路由 （makeBridgeHandlers / makeBridgeRoutes / namespaceSchema 导出供测试）。
  • lib/client.js — 浏览器 half：事件驱动的状态持久化 + 开合/宽度/滚动恢复。
  • tests/bridge.test.mjs — 桥接单测 + cordis 挂载幂等测试（node --test tests/bridge.test.mjs）。