前言¶
用 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
