前言¶
DSH 会话一旦拉长，找一个历史消息就要反复滚动。常见的导航做法是点开后弹出一个面板，或者靠浏览器原生 title 显示预览，前者容易与侧边栏、底栏错位遮挡，后者信息量有限。@max-null/dsh-chat-rail 走的是另一条路：在会话面板右侧放一条竖排导航，每条用户消息一个指示点，hover 时像打开画卷一样展开完整列表，点击即可跳转。下面介绍这个插件的功能、安装方式和使用方法。
这是什么¶
@max-null/dsh-chat-rail 是 Max-Null 维护的 DSH 插件，定位是「画卷式消息导航栏」：右侧竖条 hover 展开画卷，scroll-spy 高亮跟随阅读位置，消息项带编号、相对时间和完整预览。当前 package.json 版本号为 0.6.1，许可证 MIT。
它属于 @max-null/* 插件系列，这一系列共同构成 SSID（思灵 · Seek Soul in Darkness）桌面体验。兼容性方面，要求 DSH ≥ 0.1.0-rc.6，完整适配 DSH 0.1.2-alpha.4。
核心功能¶
画卷式展开与 scroll-spy¶
- 收起时是一条干净的竖条，hover 时从右往左平滑展开。展开走单容器，各消息项高度天然一致。
- scroll-spy 跟随阅读位置：无论会话滚到哪里，当前消息的指示点始终保持在导航条可视区中央，导航条会自动滚动补偿。
- 切换会话时，自动定位到新会话当前阅读位置，而不是回到顶部。
与 better-sidebar 的同步避让¶
- 安装了 dsh-better-sidebar 时，导航栏的右缘和垂直位置跟随
--dsh-sidebar-width/--dsh-sidebar-heightCSS 变量，与面板共享同一段 transition 动画，右栏、底栏展开收起时同步移动，互不遮挡。 - 没有 better-sidebar 时走 CSS fallback（右缘 12px + 垂直居中），纯 DSH 环境开箱即用。
- DSH
0.1.2-alpha.1+自带 TurnNavigator 轮次导航竖轨。安装本插件后会自动隐藏官方竖轨（通过 aria-label 双文案锚点定位，不依赖构建 hash），由本插件统一承担会话导航；卸载本插件后官方导航照常显示。
深历史跳转¶
长会话的历史是分页加载的，跳到未加载的消息需要先补载。本插件的处理：
- DSH
0.1.2-alpha.3+内核：走官方loadThrough(seq)精确跳转装载器，200 条/页一次到位。 - 旧内核：自动回退为逐页
loadOlder循环，50 条/页。
跳转远距离消息时显示 spinner 和「加载中」反馈，导航条收起态只留图标。
tip 预览面板¶
hover 消息项时左侧弹出 tip 面板：显示完整内容，在展开动画结束后精准定位，避免面板位置跳动。面板内是编号 + 相对时间 + 文本三列对齐，编号固定宽、时间靠右，文本区域最大化。
含图消息在展开态显示柔和图片角标（收起态不显示，保持竖条干净），tip 面板则在文本上方显示图片缩略图。
收藏与快速填充¶
- 每条用户消息的复制按钮左侧有两个操作按钮：星 ★ 收藏/取消收藏（收藏后变黄色实心星）；加号 ＋ 一键把该消息全文和附件回填输入框，历史图片经官方附件通道回填。
- 收藏状态按会话持久化在 localStorage，刷新与重启后保留。
- 导航条联动：收藏消息的指示条显示为黄色，展开态在标题前显示小星标。
- 导航条顶部有星形过滤开关，点亮后只显示已收藏的消息，再点恢复全部。
主题适配¶
全部使用 DSH 主题变量（--dsw-alias-*），浅深色自动适配。
架构简述¶
插件分为两半：
- host 半端（
lib/index.mjs）：注册chatRail会话投影，从 session log 折叠用户消息锚点{ seq, time, text, id }，排除插件和工具注入的上下文行。 - client 半端（
lib/client.js）：向conversation.input.dock槽注入，通过 portal 渲染到 body。
数据源优先序为：chatRail 投影 → 已加载聊天节点 → 后台 loadOlder 循环。
安装与启用¶
使用官方安装命令：
dsh plugin --profile <name> add @max-null/dsh-chat-rail
或手动编辑 profile 的 package.json，在 dependencies 中加入包名，并在 dsh.profile.bundles 中登记：
- id: chat-rail
name: '@max-null/dsh-chat-rail'
安装重启后无需配置，导航竖条会出现在会话面板右侧，同时 DSH 自带的 TurnNavigator 竖轨自动隐藏。
想参与开发的话，仓库提供以下脚本：
pnpm install
pnpm typecheck # tsc 严格类型检查
pnpm build # 产出 lib/
典型用法¶
日常使用围绕几个动作：
- hover 导航条：画卷展开，浏览消息的编号、相对时间和预览。
- hover 消息项：左侧弹出 tip 面板查看完整内容，含图消息会先看到缩略图。
- 点击消息项：跳转到对应消息，未加载的历史自动补载。
- 滚动会话：高亮点跟随阅读位置并保持居中。
- 星标重要消息：之后用顶部星形开关只看收藏，用加号把某条消息全文和附件回填输入框继续追问。
适用场景与注意¶
适合的人群：经常在 DSH 里跑长会话、需要回看和整理历史消息的人；使用 better-sidebar 双面板布局、希望导航不与侧边栏底栏错位的人；想用收藏功能沉淀重要消息的人。
使用前注意几点：
- 插件以当前 dsh 进程的权限运行，收藏状态会写入 localStorage。安装前建议检查源码与许可证，本插件为 MIT。
- 需要 DSH ≥
0.1.0-rc.6；深历史精确跳转依赖0.1.2-alpha.3+内核，旧内核会自动回退逐页加载。 - 安装后官方 TurnNavigator 会隐藏，导航职责由本插件接管；不想要这个行为就卸载本插件，官方导航恢复显示。
结尾¶
@max-null/dsh-chat-rail 把「在长会话里找消息」变成一条竖条上的定位操作：收起不占空间，hover 展开全貌，滚动时高亮跟随，跳转远距离历史也有加载反馈。配合收藏和快速填充，它同时承担了回看和整理两类需求。
- 社区插件目录页：https://www.skillhub.cn/plugins/Max-Null/dsh-chat-rail（独立站点，与 DeepSeek、幻方无官方从属关系）
- GitHub 仓库：https://github.com/Max-Null/dsh-chat-rail
