前言¶

在使用 DeepSeek Harness (DSH) 处理长对话流时，在长列表中定位特定问题较为困难。dsh-qnav 插件通过在右侧边缘添加导航栏，实现了对每个真实用户问题的快速定位与跳转。该插件适配 DSH Web 客户端，支持多平台，由 lin-nanxing 维护。

核心功能¶

1. 精确提取
   使用 data-chat-flow-kind="user" 读取真实用户问题，过滤引导/待定/上下文行；若不存在，则回退至 [class*="userRow"]。
2. 元素引用跳转
   保存 flowItem DOM 元素引用而非文本前缀匹配；点击时直接调用 scrollIntoView()，避免了去重错误、前缀冲突和 @ 引用文本节点分割问题。
3. 自动过滤非用户行
   通过 data-pending-steering 和 data-chat-flow-kind 排除未提交输入和系统注入的上下文，确保没有误导性的空勾选标记。
4. 比例布局
   勾选标记均匀分布在右边缘，随问题数量增加自动调整密度。
5. 暗黑模式支持
   利用 CSS color-scheme: light dark 和 @media (prefers-color-scheme: dark)，高亮颜色随页面主题自动切换。
6. 悬停提示气泡
   悬停时在左侧显示 “N. <完整问题>”；气泡锚定左侧以避免视口溢出，并在定位前测量尺寸以防止闪烁。
7. 当前位置高亮
   通过 getBoundingClientRect().top <= 120px 更新高亮状态，而非脆弱的文本树遍历，不受答案正文引用干扰。
8. MutationObserver 同步
   内容变化时重新扫描并渲染勾选标记（500ms 防抖），高亮轮询间隔为 600ms。
9. HMR 安全
   apply(ctx) 返回清理程序，负责销毁观察者、定时器和注入的 DOM/样式表，防止热重载或禁用时泄漏。

安装与启用¶

1. 克隆仓库：

   git clone https://github.com/lin-nanxing/dsh-qnav.git
   cd dsh-qnav

2. 构建源码（仅修改源代码时需要）：

   npm run build

3. 通过 DSH 安装：

   dsh plugin --profile web add link:.

适用场景与限制¶

• 可见范围限制：仅支持滚动到已渲染的项目；超过分页边界（”加载更早” 截止点）的问题尚无法跳转。
• 超长会话：问题数超过 500 个时，勾选标记密度会增大，未来将通过搜索面板优化。
• 仅限用户问题：当前仅将用户 flowItem 作为跳转目标，助手回答不可点击。

结语¶

dsh-qnav 适配 DSH Web 客户端，无需修改 Electron 原生代码即可在多平台使用。通过直接操作 DOM 引用和 MutationObserver，实现了对长对话流的稳定导航。