前言¶

在使用 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，實現了對長對話流的穩定導航。