@kkabuka/dsh-session-nav

Fork 说明：本包是 @kiligzzz/dsh-session-nav（MIT，Copyright © 2026 kiligzzz）的再发布 fork，仅把包名/插件注册名改为 @kkabuka/dsh-session-nav 以便 npm registry 直装，代码逻辑与上游 0.1.4 一致，原作者注释与 LICENSE 文件原样保留。行为问题请先到上游仓库核对。

钢琴键风格的会话内导航条 —— 为 DeepSeek Harness Web GUI 的单个会话提供多轮对话导航： 每根键锚定一条用户消息，悬停显示该轮「用户消息 + 模型回复」预览，点击平滑跳转到对应消息。 基于 DSH 官方双面插件机制（host + browser half），不侵入 DSH 源码。

| 整体效果 | 悬停预览 | 点击跳转 | | --- | --- | --- | | | | | | 一个 43 轮的会话 —— 每根键对应一个用户问题，紧凑簇在消息区垂直居中。 | 悬停某键显示用户消息（单行）+ 该轮模型回复（最多 3 行）。 | 点击任意键自动翻页历史（与官方「加载更早」同一通道）并精确定位到视口顶部。 |

截图取自一个真实的 43 轮会话（浅色主题）。参考实现：KeLearns/dsh-navigation-bar（视觉规格与交互对齐，代码独立重写）。

适配与依赖

| 项 | 要求 | | :--- | :--- | | DeepSeek Harness（dsh） | 0.1.1-rc.2（实测通过的全链路版本）；依赖 @deepseek-ai/dsh-client-runtime / dsh-client-ui-slots 兼容版本（见 package.json peerDependencies） | | Node.js | ≥ 18 | | 安装通道 | 本 fork：npm registry 直装（推荐）；上游原版不在 registry，仅 github: / link: |

快速开始（怎么装）

前置：已安装 dsh 并初始化过 web profile（~/.dsh/profiles/web）。

# 推荐：registry 直装（不依赖 github 可达性）
dsh plugin --profile web add -w @kkabuka/[email protected]

# 备选：从上游 GitHub 安装（公司网等 github 不可达环境不适用）
dsh plugin --profile web add github:kiligzzz/dsh-session-nav

插件名单在实例启动时加载 —— 装完重启 dsh web 再刷新浏览器页面（§3）。

使用（怎么用）

打开任意会话，消息区右侧/中部出现钢琴键导航条（group "会话消息导航"）：

• 悬停键：变长变色 + 阶梯展开（上下 3 级阶梯，首/尾自然单侧裁剪）+ 该轮预览气泡
• 点击键：目标在已加载窗口内 → 平滑滚动直达；在窗口外 → 按官方分页通道按需翻页后精确到位
• 当前位：非悬停时当前查看内容的键仅变色（长度不变），随滚动实时联动
• 深浅色主题自适应（data-ds-dark-theme + prefers-color-scheme 兜底）

提示：会话内真实用户提问不足 2 条时不显示导航（无导航意义，属设计非故障）。

功能细节（完整保留上游说明）

客户端消息键与快照去重 / 视觉规格（10px 键距、2px 键高、6px 最短、26px 悬停 ≈4.3×）/ 当前位高亮 / 分页跳转 / 性能模型等完整说明见上游仓库 README；本 fork 与上游 0.1.4 行为一致。

如何更新

dsh plugin --profile web add -w @kkabuka/dsh-session-nav@latest   # 拉最新 fork 版本

本 fork 与上游 0.1.4 对齐。上游出新版本后，重做一次 fork + 改名（四处必须一致：package.json name、cordis.patch.yml 的 bundle 行 name、index.js 的 export const name、lib/client.js 的 id 与 PLUGIN_ID），保留注释与 LICENSE，再发新版。

卸载

dsh plugin --profile web remove -w @kkabuka/dsh-session-nav

重启 dsh web 后导航条消失；无残留文件/配置/数据目录。

故障排查

| 现象 | 处理 | | :--- | :--- | | 安装后无导航条 | 确认已重启 dsh web；确认会话内确实有 ≥2 条真实用户提问（agent 注入/工具消息不计键） | | 怀疑 host 未挂载 | curl http://127.0.0.1:3080/_dsh/session-nav/questions 无参应返回 400 missing-session-id | | 点击窗口外的键跳不过去 | 与控制台行为同源（session.loadOlder 与「加载更早」同一通道）；仍失败看浏览器 console，host 端问题先到上游仓库核对 | | 长会话体感卡顿 | 本 fork 与上游同逻辑（虚拟化键节点 + rAF 合并）；若确认问题，反馈上游或按「切换会话必须秒切」底线先卸载 |

结构

| 文件 | 说明 | | :--- | :--- | | index.js | host 半端：读取会话全量日志并暴露同源路由 /_dsh/session-nav/questions | | lib/client.js | browser 半端（手写 bundle，无构建步骤；window.__ModuleLoader__.load） | | cordis.patch.yml | bundle patch：把插件行插入 web profile 名单 | | package.json | dsh.bundle.patch + dsh.client（platform web）声明 |

数据来源（全部官方 API）：ctx.sessions.binding(...) 会话快照（实时订阅）· sessionPersistence.readFrom 全量日志 · DOM 锚点 [data-conversation-scroll] / [data-chat-anchor-key] · 分页 session.loadOlder()。

性能

事件驱动几何跟踪：scroll capture / resize / 惰性附加的 scrollport ResizeObserver → rAF 合并重算；无常驻 MutationObserver、无定时器。锚点行走 isConnected 校验的缓存，虚拟滚动回收重建不影响正确性。

开发

环境要求：Node.js ≥ 18。

pnpm install        # 开发依赖（vitest / eslint / prettier）
pnpm test           # 运行单元测试（31 个用例）
pnpm lint / format  # 静态检查 / 格式化

browser 半端手写 bundle 无构建步骤（改 lib/client.js 刷新生效；host 端改动需重载插件）；window.__dssnNavDebug__ 暴露诊断信息（entryCount / fullCount / stats）。

许可与归属

• 代码：MIT（LICENSE 文件原样保留，Copyright © 2026 kiligzzz）
• 上游：github.com/kiligzzz/dsh-session-nav · 本 fork 维护者：jankin_lv（@kkabuka scope）