双栏插件导航 A-Meng-E/dsh-two-pane-sidebar

dsh-two-pane-sidebar

给 DeepSeek Harness 用的常驻插件栏——它把插件导航从主侧边栏挪出来，单独放进一条窄栏，侧边栏只干一件事：新建会话、工作区、会话。

┌──────────────┬────────────────────┬─────────────────────┐
│ plugin rail │ sidebar │ conversation │
│ (52/208 px) │ new session │ │
│ ────────── │ workspaces │ │
│ ▣ plugins │ search │ │
│ ▣ market │ ▣ workspace A │ │
│ ▣ tasks │ ▣ workspace B │ │
│ ▣ skills │ sessions │ │
│ … │ │ │ └──────────────┴────────────────────┴─────────────────────┘ ↑ drawn by this plugin ↑ untouched, shipped SidebarRoot

插件栏是数据驱动的：宿主 sidebar.panellist 槽位里注册了什么，它就渲染什么（{ id, order, label, component }）。装一个注册了导航项的插件，它自动出现在这里——不用改代码，不用配置。取消注册，它就消失。

这个插件只跑在客户端。它不安装任何 Host 行为，不发网络请求，不上报遥测，也从不碰你的会话和工作区。它的全部状态就是一个 localStorage 键。

环境要求

| Harness | DSH Desktop / Web 0.2.1-rc.2（Windows、macOS、Linux） |
| 运行时 | 无——纯 ESM，不用构建，没有依赖 |
| 兼容性 | 声明 engines.dsh = ">=0.2.1-rc.2 <0.3.0"，见兼容性 |

安装

三选一。三种方式都走 Host 的插件管理器：它写配置档清单、跑 pnpm add、应用 bundle 补丁。

1. registry — not on npm yet, the name is reserved for a future release: plugin_manager install_bundle target=@a-meng-e/dsh-two-pane-sidebar@0.2.0

2. release tarball — no npm account, a fixed immutable artifact plugin_manager install_bundle target=https://github.com/A-Meng-E/dsh-two-pane-sidebar/releases/download/v0.2.0/dsh-two-pane-sidebar-0.2.0.tgz

3. straight from git
plugin_manager install_bundle target=git+https://github.com/A-Meng-E/dsh-two-pane-sidebar.git

然后重启应用（配置档改动不会热重载），再刷新页面。

安装源会原样转给 pnpm add，所以 file: / link: 本地路径也能用——开发时的安装就是这么做的。

使用

- 点一行，打开对应插件的面板；当前行左侧有高亮条。
- 在窄栏里悬停某一行，会弹出带主题样式的提示。
- 底部的箭头按钮在 52 px（仅图标） 和 208 px（图标 + 文字） 之间切换。两种宽度下按钮位置不变，所以不会跳。
- 选择存在 localStorage["dsh.two-pane-sidebar.v2"] 里，重启后仍然保留。
- prefers-reduced-motion 会禁用宽度过渡。

没有需要配置的模式：侧轨始终开启，侧边栏也始终保留自己的宽度（就是你上次拖到的宽度）。侧轨用框架上的左内边距占住自己的空间，所以对话列让出 52 px——侧边栏不会收缩。

卸载

plugin_manager remove_bundle target=dsh-two-pane-sidebar

或者先退出应用，再从 ~/.dsh/profiles/<profile>/package.json 里删掉 dsh-two-pane-sidebar 那一行，并从 dsh.profile.bundles 里删掉对应条目。改之前先确认：应用运行时编辑配置档文件，可能触发无关内置插件的热重载竞态。

除了 localStorage 里的一个键，什么都没留下，而它是惰性的。

工作原理

client.js 就是全部（约 670 行，无依赖）：

1. 往宿主框架级的 shell.overlay 插槽注册一个组件；
2. 找到布局框架（[data-shell-overlay].parentElement），在它上面设置 padding-left，为侧轨的列预留空间——这是唯一一处命令式 DOM 接触点，由 effect 清理函数还原；
3. 通过 slots.entriesOfSlot() 读取 sidebar.panellist，订阅插槽与语言环境变化，每个条目渲染一行；
4. 直接渲染每个条目自己的图标组件（宿主只给声明了子项的条目注入 renderSlot，这里没有声明），外面套一层错误边界，一个图标坏了不会拖垮整个侧轨；
5. 把原生侧边栏列计算出的背景、纹理、文字颜色复制到侧轨上，第三方皮肤无需任何按皮肤写的代码就能生效；
6. 用一条 CSS 规则隐藏原生侧边栏里现在重复的导航列表。

每处宿主交互都有防护：服务、插槽或 DOM 节点缺失时，侧轨降级，而不是让应用启动失败。

兼容性

本插件有意依赖宿主内部实现，这些在 Harness 各版本之间都可能变化：

| 依赖 | 用途 |
| shell.overlay 插槽 | 挂载侧轨 |
| sidebar.panellist 插槽 + 条目结构 {id, order, label, component} | 侧轨的内容 |
| [data-shell-overlay] 及其父框架 | 预留列空间 |
| nav[class="_panelList"]（哈希类名） | 隐藏重复的导航列表 |
| [class="sidebarCol"] / [class="_root"]（哈希类名） | 跟随当前皮肤 |
| @deepseek-ai/dsh-client-ui-primitives → Tooltip | 主题化提示框 |
| ctx.layout.selectPanel(id) | 点击时打开面板 |

如果某次更新破坏了其中一项，侧轨会降级或消失，不会损坏数据。Harness 升级后重新验证的清单在 docs/troubleshooting.md。

已知限制

- 不是原生的第二视图容器：侧轨位于覆盖层，用内边距预留空间。没有可拖拽的分隔条，侧轨只有两种宽度。
- 会话列少了 52 px；宿主的 viewport < 1024「窄窗口」阈值因此比之前提前 52 px 触发。
- 皮肤如果绘制在侧边栏列自身元素以外的地方，就不会被跟随——此时侧轨回退到该皮肤的主题 token。
- 图标组件直接渲染，只能依赖 { size, active }；依赖其他任何东西都会退化成中性占位方块。

开发

link the working copy into a profile, then restart the app
plugin_manager install_bundle target=link:/absolute/path/to/two-pane-sidebar

link: 安装的是符号链接，所以之后每次改动 client.js，刷新页面就能生效——不用构建，也不用拷贝。语言元数据（locale/.json 的 meta）在启动时读取，改动后需要重启。

在浏览器控制台按 [two-pane-sidebar] 过滤；每条降级路径都会在那里打一条警告。

许可证

MIT