AbelKeithsun/dsh-question-nav

DeepSeek Harness (DSH) Web GUI 的会话内提问导航插件：在对话栏左侧 内嵌一列竖排的圆点小按钮 —— 每个圆点对应一个用户提问。鼠标悬停圆点会把该圆点 连同其上下各两个圆点一起放大，并弹出竖排的清晰问题卡片显示对应提问的 全文与发出时间（点击任意卡片即可跳转）；点击圆点则把对话滚动跳到那一 提问的位置。

它是外部插件 bundle，零运行时依赖 —— 浏览器半区（lib/client.js）把一切 外部化给 DSH 外壳，加载时只往 GUI 里加一个很小的 bundle。

包名：@luziyang2026/dsh-question-nav（npm · GitHub）。

效果展示

插件设置页（导航条对齐 + 每次翻出数量）：

功能

• 左缘圆点迷你地图：内嵌，不占任何宽度。导航条锚定边可配置—— 设置 → 插件 → 提问导航 → 导航条对齐可在对话栏左/右缘之间切换。
• 限高 + 可滚动：圆点列垂直居中，最多占用对话栏高度的 60%；会话提问 更多时在带内上下滚动（滚轮在圆点上或圆点间隙上都能滚）。
• 一个圆点 = 一个含提问的 turn（与轨迹视图的 Turn 编号严格对齐）， 圆点列上方有圆点数量。
• 完整历史、持久化、不展开渲染窗口：插件的 host 半面注册 questionIndex 会话投影——投影注册表折叠完整事件日志（只读，对话的 分页窗口完全不被动），官方 projection-cache 跨重启持久化，新提问通过 推送帧实时到达。
• 悬停（聚焦）：圆点与其上下各两个圆点一起渐进放大（选中最大）， 选中点仅在被带边缘遮挡时才最小滚动到可视区（不强制居中，逐点浏览时 点列保持不动）；导航条旁出现一列竖排的 5 张清晰问题卡片 （portal 渲染，无原生 title 延迟）——窗口内每个圆点一张卡片，上下排布、 互不遮挡，以选中点为中心垂直居中。每张卡片显示该轮提问全文（一轮 多条提问时全部列出）与提问的发出时间（当天 HH:MM，跨天 MM-DD HH:MM，跨年 YYYY-MM-DD HH:MM）。层级采用两档聚焦： 中心卡片是焦点——全对比度文字、品牌色左 accent bar、浮起投影；上下 四张是干净的上下文卡（同背景、更窄、行数更少），hover 时会亮起、 明示它们同样可以点击。点击任意卡片即跳转到对应提问，与点击圆点 效果一致。
• 点击：跳转到该提问；只有这时跳转循环才 loadOlder() 扩窗，把那一页 带进视图——绝不会一次性展开整个历史。
• 分页式溢出：圆点太多超出 60% 限高时，原生滚动条被隐藏，点列上下会出现 两个与圆点同风格的三角按钮——队列上方 ▲、队列下方 ▼——每次点击翻出 下一页隐藏圆点，新翻出的圆点会带一个简短的逐个点弹入动画作为点击反馈。 每页数量可在 设置 → 插件 → 提问导航 → 每次翻出数量 中配置 （3 / 5 / 8 / 10，默认 5）。三角按钮本身就是溢出提示——只有对应方向还有 更多圆点时它才会出现（滚轮/触控板同样可滚）；悬停绝不滚动点列， 浏览时点列保持不动。
• 圆点列空白区域点穿到对话内容，不会挡住聊天。

环境要求

• DeepSeek Harness Web GUI（可运行的 DSH profile；需要 dsh CLI）。
• Node.js >= 20（与 DSH SDK peer 范围一致）。

选择哪个版本

同一个包名下发布两条版本线，请按你 GUI 所运行的 DSH 构建选择：

npm dist-tag	版本	适配的 DSH	状态
latest	0.7.x	0.1.1-rc.1 SDK 线	稳定版 —— 日常使用推荐
alpha	0.8.0-alpha.x	0.1.2-alpha.2 SDK 线	Alpha 版 —— 适配 Alpha GUI

• 绝大多数用户装 latest（稳定版）：跟随 DSH 稳定版发布线，日常使用安全。
• 你的 GUI 是 DSH Alpha 版（0.1.2-alpha.2）？ 请改用 alpha dist-tag。 稳定版读取的是 session.getSnapshot().chat 这个 chat 快照 API，它在 Alpha SDK 中已被移除；alpha 版改为通过新的 conversation 服务读取实时对话。若在 Alpha GUI 上装稳定版，导航条会降级（只剩投影圆点）。
• 不确定自己是什么 DSH 构建？ 在 GUI 里或 dsh --version 看版本号：0.1.1-rc.x 用 latest；0.1.2-alpha.x 用 alpha。

安装

从 npm 装预构建包并加进 profile。请使用与你的 DSH 构建匹配的 dist-tag（见上）：

稳定版（DSH 0.1.1-rc.1，大多数用户）：

dsh plugin --profile web add @luziyang2026/dsh-question-nav        # latest → 0.7.x

Alpha 版（DSH 0.1.2-alpha.2 GUI）：

dsh plugin --profile web add @luziyang2026/dsh-question-nav@alpha  # alpha → 0.8.0-alpha.x

如需锁定具体版本，可显式指定：

dsh plugin --profile web add @luziyang2026/dsh-question-nav@0.7.7        # 稳定版锁版
dsh plugin --profile web add @luziyang2026/dsh-question-nav@0.8.0-alpha.0 # Alpha 锁版

然后重启 DSH Web GUI 以加载新 bundle。

从源码构建 / 本地开发

本仓库是独立插件工程 —— 先构建，再作为可安装的 bundle 加进 profile：

pnpm install       # 安装 devDependencies（DSH SDK peers、tsdown、vitest）
pnpm build         # tsc 声明 + tsdown client bundle -> lib/

dsh plugin --profile web add ./dsh-question-nav

开发

pnpm typecheck     # tsc --noEmit
pnpm test          # vitest run
pnpm build         # 构建 host lib/index.js + client lib/client.js

构建方式

client 半区使用共享的 DSH client-bundle 预设（tsdown.client.ts， vendored 到本项目内），产出 window.__ModuleLoader__.load({ id, factory }) 闭包工厂产物，CSS Modules 内联， externals 经加载器模块表解析。

License

MIT。