前言¶
用 DSH Web 客户端跑长对话时，有一个常见的小麻烦：想回到前面发过的某条指令，只能靠滚轮一屏一屏往上翻，消息越多越难定位。
dsh-nav-pointer 解决的就是这个导航问题。它在聊天区域左侧加一条消息指针导轨，每条用户消息对应一个短横条标记，点击就平滑滚动到对应位置，悬停还能预览消息内容。下面介绍这个插件的定位、功能、安装和配置。
这是什么¶
dsh-nav-pointer 是一个 DSH（DeepSeek Harness）Web 客户端插件，由 kongdexu 维护，MIT 许可证，当前版本 0.4.0。
它通过 shell.overlay 槽位挂载一个 frame-wide 浮层（list 槽位），不替换任何内置 UI；滚动容器和用户消息行的定位基于 DSH 公开约定的稳定属性 [data-conversation-scroll] 和 [data-chat-flow-kind="user"]。导轨位置用 requestAnimationFrame 循环逐帧读取 getBoundingClientRect() 重算，消息列表变化由 MutationObserver 监听。
核心功能¶
- 消息指针导轨：聊天区域左侧垂直排列短横条，每个用户消息对应一个
- 点击跳转：点击横条平滑滚动到对应的用户消息
- 当前位置高亮：当前视口所在消息的横条自动高亮为蓝色
- 悬停预览气泡：鼠标悬停横条弹出消息预览，毛玻璃背景、箭头指向、圆角
- 拖拽快速滚动：按住横条上下拖动，像滚动条一样快速浏览对话；轻点（不拖动）仍精确跳转
- 键盘快捷键：
Alt+↑ / Alt+↓在用户消息间上下跳转，Alt+Shift+↑ / Alt+Shift+↓跳到第一条 / 最后一条消息 - 实时位置跟随：侧栏开合、窗口缩放、滚动时导轨位置逐帧跟随
- 深浅模式自适应：颜色使用 DSH 主题 token，自动适配深色 / 浅色主题
安装与启用¶
通过 dshmarket（推荐）¶
在 dshmarket 市场里搜索 dsh-nav-pointer 一键安装。与其他插件一致，多数情况刷新页面即生效。
需要说明的是，dshmarket 是独立的社区目录站点，与 DeepSeek / 幻方没有官方从属关系。
命令行安装¶
用 DSH 官方的插件管理命令安装：
dsh plugin --profile web add dsh-nav-pointer
该命令会安装到 ~/.dsh/profiles/web，并因为本包声明了 dsh.bundle.patch，自动把 dsh-nav-pointer 追加进 dsh.profile.bundles。之后重启 dsh web 生效。
如果 pnpm ≥ 11 报 ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION，这是新发布的包触发的 24 小时安全等待期策略，可以加参数一次性放行：
dsh plugin --profile web add dsh-nav-pointer --config.minimumReleaseAge=0
重启后看不到导轨¶
先确认两点：
dsh.profile.bundles里包含dsh-nav-pointer- 当前会话存在用户消息——没有用户消息时插件不渲染
清空聊天后重新发送一条再看。
配置项¶
所有偏好都在 设置 → 消息指针 页面调整，改动即时生效并持久化：
| 配置项 | 默认 | 说明 |
|---|---|---|
| 滚动时长 | 260ms | 点击 / 键盘跳转的动画时长（固定时长，范围 60–2000ms） |
| 显示指针导轨 | 开 | 关闭后不渲染导轨 |
| 悬停预览气泡 | 开 | 鼠标悬停标记时的消息预览 |
| 键盘跳转 | 开 | Alt+↑/↓ 在用户消息间跳转 |
另外两点行为需要知道：
- 标记压缩：用户消息很多、自然高度超出可用视口时，标记间距会自动压缩到刚好铺满视口。这是固定行为，不可关闭。
- 动画打断：滚轮滚动、手指触摸、拖拽导轨都会立即打断进行中的跳转动画。
插件还兼容旧用法 window.__DSH_NAV_POINTER_SCROLL_MS__，可覆盖滚动时长，优先级高于设置面板，但需要在插件加载前设置。推荐直接改用设置面板。
开发模式与验证¶
想在本地改代码或跟踪开发版，可以走本地 link：
git clone https://github.com/kongdexu/dsh-nav-pointer
cd ~/.dsh/profiles/web
dsh plugin --profile web add link:/path/to/dsh-nav-pointer
改完代码后，用一条命令跑完整校验（类型检查 → 构建 → 行为测试 → 加载契约）：
npm run check
它依次执行：
npm run typecheck：tsc --noEmit类型检查src/npm run build：esbuild 产出lib/npm test：vitest + jsdom，覆盖导轨压缩几何、高亮推导、预览裁剪、行收集与样式注入npm run test:smoke：无浏览器加载构建产物，断言插件导出和槽位注册符合契约
适用场景与注意¶
适合的用户：日常在 DSH Web 客户端里跑多轮长对话，需要反复回滚定位自己发过的指令的人。对话越长，这条导轨省下的翻找时间越多。
环境要求：engines 要求 Node >= 20；peerDependencies 为 @deepseek-ai/dsh-settings ^0.1.2-alpha.2 和 @deepseek-ai/schemastery ^3.18.2。
安全提醒：插件以当前 dsh 进程权限运行，安装前建议查看源码和许可证。本项目 MIT 许可，源码公开在 GitHub，安装命令也只从官方插件管理通道拉取。
小结¶
dsh-nav-pointer 做的事很聚焦：给 DSH Web 聊天界面加一条消息指针导轨，让回滚定位从「滚动翻找」变成「点击直达」。配合设置面板的滚动时长、开关和键盘快捷键，可以按自己的习惯调整。
- GitHub：https://github.com/kongdexu/dsh-nav-pointer
- 社区目录页：https://www.skillhub.cn/plugins/kongdexu/dsh-nav-pointer
