侧栏固定会话 AndreyTepaykin/dsh-sidebar-pins

dsh-sidebar-pins

为 DeepSeek Harness 左侧边栏提供自包含的固定会话：它有自己的固定集合、自己的固定按钮，以及侧边栏顶部的 「📌 PINNED」 区块——而不是一个会飘到右上角、点击外部就关闭的弹窗。

插件面向 DSH 0.1.5-rc.1 编写，完全取代 dsh-session-pin：安装之后，旧插件就可以移除了（见「移除旧插件」）。

为什么

dsh-session-pin 0.7.11 在这个核心版本上无法兑现它的承诺：

* 它会重排 host 列表（workspaces.insertSessionBefore）——这个列表确实被重排了，在 ~/.dsh/storages/workspace.json 里能看到；
* 但侧边栏渲染的是 browser 顺序（dsh.workspace.view.v5），host 列表对它不再有任何影响——而插件没有访问该 store 的公开 API；
* 核心把 sidebar.workspaces 槽位声明为 kind: "single"，所以无法在其中嵌入第二个区块；
* sessions.row.action 槽位在 0.1.5-rc.1 上不存在，所以行内按钮是 DOM 覆盖层。

它做什么

| 界面 | 行为 |
| 「Pinned」区块 | 位于侧边栏页脚内，在「Settings」行上方。位置只由它自己的锚点标记推导：从锚点向上收集整条容器链，面板把自己放在通向锚点的那条分支之前。按行排列子元素的容器（自带的 footerActions 正是如此）会通过测量被跳过，所以面板不会跑到「Settings」旁边；侧边栏根节点以上的层级完全不考虑——否则面板会跑到整个侧边栏上方。高度最多 30vh，固定列表在内部滚动。手动折叠按浏览器记忆；在 rail 模式下，面板只显示图标和数量 |
| 固定行 | 点击——打开会话；右侧的 ×——取消固定（悬停时出现） |
| 会话行内的按钮 | 悬停在行上时显示 📌——固定/取消固定。会话通过 React fiber 确定，回退方案是带唯一 title 的嵌套 span |
| 会话头部内的按钮 | 固定当前打开会话的开关（conversation.session.header.actions 槽位） |
| 缺失的会话 | 以变暗的形式留在列表中（显示原始 id），以便取消固定 |
| 旧面板 | 浮动面板、「Pinned sessions」页脚、栗色条、头部的旧按钮和行内的旧按钮都被隐藏——所有固定 UI 现在都在这里 |

插件不向会话日志写入任何内容，不访问网络，也不影响对模型的请求。

存储

* 主要位置是它自己的设置命名空间 sidebar-pins（由 host 半边注册），也就是说固定是持久的，并且能在 ~/.dsh/settings.yaml 中看到。
* 如果客户端看不到该命名空间（host 半边没有挂载、远程浏览器）——回退到 localStorage["dsh.sidebar-pins.pinned"]。
* 首次启动时，集合会从 session-pin 迁移一次（由宿主侧完成，在页面打开之前），所以即使卸载旧插件，固定项也会保留。只有当用户层中尚未出现 pinned 字段时，迁移才会继续：故意清空的集合永远不会被重新填充。

安装

从 GitHub 安装：

dsh plugin --profile web add github:AndreyTepaykin/dsh-sidebar-pins

从 npm 安装（包发布之后）：

dsh plugin --profile web add dsh-sidebar-pins

本地开发 —— 在存放插件工作副本的目录中执行：

dsh plugin --profile web add .

然后重启 DSH（重建启动图时，客户端 bundle 才会到达页面），并刷新 GUI 页面。

验证

node --test "test/.test.mjs" # 43 tests
dsh --profile web --dump-config | Select-String "sidebar-pins" # loader row

「Settings」按钮正上方会出现「📌 PINNED (3)」—— 一个高 30vh 的面板，可滚动；会话列表仍在其上方。

如果面板没有出现，插件会自己说明原因 —— 在浏览器控制台中：

__dshSidebarPins

诊断对象（window.__dshSidebarPins）始终有值：paneConnected、paneParent、anchors（锚点以及到锚点为止的容器链）、seat/seatLabel（选中的位置）、skipped（被丢弃的行容器位置）、rail、rows 和 rowButtons（侧边栏有多少行可见、按钮出现在多少行上）、styleNode、pinned、ignoredPosition，以及包含所有警告的 notes。详细日志需单独开启：

localStorage.setItem("dsh.sidebar-pins.debug", "1");
location.reload();

此外，面板会自行恢复，不靠定时轮询：能移除它的都是 DOM 变化，所以只观察三个目标：document body（面板被移除/重绘）、head（样式节点）和侧边栏根类名（列表 ↔ 轨道切换）。其中任何一处变化，都会把面板和样式重新放回原位。

设置（浏览器，localStorage）

| 键 | 值 |
| dsh.sidebar-pins.collapsed | 1 —— 面板折叠为标题行 |
| dsh.sidebar-pins.show-legacy | 1 —— 不隐藏 dsh-session-pin 遗留界面 |
| dsh.sidebar-pins.debug | 1 —— 向控制台输出详细诊断信息 |

dsh.sidebar-pins.position 不再读取：面板位置已固定。旧版本遗留在 localStorage 中的值会在诊断信息里显示为 ignoredPosition，不影响任何行为。

卸载旧插件

dsh plugin --profile web remove dsh-session-pin

顺序很重要：先确认区块和按钮都能正常工作（固定项已迁移），再卸载。卸载后，~/.dsh/settings.yaml 中会留下一个未使用的 session-pin 段 —— 可以手动删除，插件不会读取它。

限制

主列表不会重新排序。 置顶会话放在底部面板里，同时仍留在常规列表中：浏览器的顺序存在核心的 props-store 里，插件访问不到。
* 面板高度最多 30vh（侧边栏占满窗口高度），不是固定的像素值；如果侧边栏很短，面板会让出空间，而不是把「Settings」挤出边缘。折叠的面板（以及 rail 模式下的任何面板）只占标题行。
* 会话行的识别依赖 React fiber（__reactFiber$…，React 18），并回退到任意嵌套的 span，要求标题唯一：标题重复时按钮不会出现（而不是去猜）。会话标题栏里的按钮不依赖这套启发式规则。
* rail 模式下 DOM 里根本没有会话行 —— 那里没有东西可以标记按钮，所以行内的 📌 只在侧边栏展开时出现（rail 模式下诊断信息里 rows: 0 是正常的，不是故障）。
* 面板位置只由它自己的锚点标记推导，既不依赖会话行，也不依赖外层容器。实时宿主会在侧边栏根节点外多加一个无名 div，并在 footer 槽的每个条目外各加一个 div，而 footerActions 本身把子元素排成一行。因此这里不采用固定链路，而是收集从锚点向上的整条路径，再通过测量选定位置：容器必须把子元素排成一列（否则面板会横在「Settings」旁边），并且面板最终要落在「Settings」行上方。侧边栏根节点以上的层级不考虑：从那里面板会落到整个侧边栏上方。选中的位置和被丢弃的位置都能在诊断信息里看到（seat、seatLabel、skipped），最后的兜底是最近的「列」容器末尾，也就是面板留在侧边栏内部。样式节点每一轮都会重新安装：没有样式的面板会撑大到适应内容，把「Settings」挤出边缘。
* 插件刻意不导入任何外部包。用 link: 方式安装到配置档时这也是被迫的：Node 从包的真实路径（工作副本）解析裸导入，那里没有 node_modules，入口会以 ERR_MODULE_NOT_FOUND 加载失败。所以设置 schema 是手写的（见下文）—— 用 npm/git 安装可以摆脱这个限制，但手写 schema 仍然保留，这样行为不依赖插件的安装方式。

序列化 schema

宿主那一半提供手写的 schema 信封 —— 它必须与 shell 内置的 schemastery 重新水合出的结果一致。验证：

node scripts/check-schema-envelope.mjs

脚本从 dsh-client-ui-settings/lib/client.js 加载同一份 vendored 代码，重新水合信封，并检查 {pinned:["a","b"]}、{}、{pinned:[1]}。
同一个测试也在测试套件里（test/host.test.mjs），如果机器上没有 shell 就跳过。更新 DSH 之后要跑一遍。

开发

node --test "test/*.test.mjs"

43 个测试：纯辅助函数（id 归一化、旧文档解析、行模型、字典、开关）、host 那一半（注册、schema、迁移、信封）、从自身锚点出发的位置链（包括实时 host 的额外包装层，以及没有会话行）、拒绝行容器、在「Settings」行上方就位、几何检查与切换到下一个位置、侧边栏内的最后兜底、rail 模式下的行为（只有图标和计数）、无变化时不重绘、观察到的目标、恢复被移除的面板和样式节点、行内按钮（fiber / 嵌套标题 / 歧义）、委托点击、头部按钮、回退到 localStorage 以及卸载。