前言¶
在 DSH（DeepSeek Harness）裏跑智能體，會話一長，DOM 節點和內存都會漲；流式輸出時還要自己盯滾動條，思考塊默認摺疊時容易錯過正在輸出的推理行。網關 502、靜默截斷、號池繁忙這類錯誤若只靠手動點重試，會打斷節奏。社區插件 dsh-perf-guard（顯示名「性能守衛」）面向這些痛點：只改交互與性能相關行爲，不改任何主題、配色或佈局。下面按定位、能力、安裝與設置說明用法與注意點。
這是什麼¶
dsh-perf-guard 由維護者 TaoLe-si 發佈，MIT 許可證，當前 package 版本爲 1.1.1。插件通過 Cordis patch 注入宿主與 Web 客戶端邏輯，基線要求 engines.dsh: ">=0.2.1-rc.4"；低於該版本的 DSH 內核會被直接禁用，無法掛載。DOM 行爲依賴 @deepseek-ai/dsh-client-ui-chat@0.2.1-rc.4 的選擇器契約，宿主 UI 大版本升級後需要複覈。
核心功能¶
自動跟隨（默認開啓）¶
長回覆流式到達時，若用戶處於貼底閱讀態，插件用 requestAnimationFrame 緩動追到最新一行（每幀逼近約 45%），而不是瞬移跳底。
- 向上滾動（滾輪、PageUp、拖動滾動條）會立即脫離跟隨。
- 內容重排、瀏覽器滾動錨定不會被誤判成用戶上滾。
- 視口回到底部 24px 內自動恢復跟隨。
- 跟隨過程中若宿主已渲染「回到底部」按鈕，點一次可讓宿主的
followingTail狀態機自愈（節流 900ms）。 - 閱讀態（非貼底）下不會寫
scrollTop，也不會自動點「回到底部」。
思考鏈自動展開（默認開啓）¶
只展開正在流式輸出的思考行，選擇器爲 [data-variant="think"][data-state="running"]。
過程組摺疊導致思考行不在 DOM 時，先用 [data-streaming] / [data-shimmer] 判斷是否在輸出，再展開最新的過程組。歷史回合保持摺疊；用戶手動收起過的行記入 WeakSet，之後不再自動打開。
截斷與傳輸失敗重試（默認開啓，可配置）¶
插件按 HTTP 狀態、LlmError、傳輸錯誤碼和消息模式分類處理：例如 429 / 502 / 503 默認重試，400–403 默認只記日誌；500 / 504 需在設置裏打開才重試。TRANSPORT、STREAM_*、TIMEOUT、ETIMEDOUT 以及「上游空轉」「賬號池繁忙」「上游輸出中斷」「靜默截斷」「長度截斷」等場景在 README 中有完整對照表。
重試次數上限爲 0–50，或設爲 不限（maxRetries = -1）。HTTP 狀態類錯誤默認只在本輪尚未輸出內容時重試；網關類 500/502/503/504 若在流到一半才返回，在「截斷 / 傳輸中斷重試」開關打開時也允許重試——已推給界面的增量無法收回，重試後可能出現半截再接完整內容，不需要該行爲時可關掉該開關。ABORTED / CANCELLED 永不重試；429 優先讀 Retry-After，其餘指數退避（0.8s 起，封頂 15s）。長度截斷（max_tokens 等）重試通常仍會截斷，根治方式是調大模型的 maxTokens。
長會話降載（默認開啓）¶
離屏過程塊使用 content-visibility: auto（整回合版本爲實驗項，默認關）。工具輸出限高並內部滾動；滾動期間暫停動畫與毛玻璃合成，停手 140ms 後恢復。DOM 節點超過 12000 或 JS 堆超過約 1.1GB 時自動切保守模式。
package 元數據中還概括了「待辦常駐」等能力；具體 UI 以當前版本客戶端爲準，安裝後可在設置頁查看開關說明。
安裝與啓用¶
先做 profile 爲 desktop 的安裝（命令來自倉庫 README）：
# 從 GitHub 安裝（無需發 npm）
dsh plugin --profile desktop add github:TaoLe-si/dsh-perf-guard
本地開發時可鏈接目錄：
dsh plugin --profile desktop add link:/absolute/path/to/dsh-perf-guard
也可在 <profile>/cordis.patch.yml 末尾手動插入 patch 條目（id: perf-guard，name: dsh-perf-guard）。宿主支持半熱重載；瀏覽器端通常需要刷新一次界面（Ctrl+R）。
設置與宿主接口¶
在 DSH 設置 → 性能守衛（settings.section，id perf-guard）中可調整：思考鏈與跟隨、錯誤與重試（含狀態碼開關與「不限」）、自檢（滾動容器、跟隨狀態、思考行計數、距底部）、會話日誌體積排行。
偏好寫入 localStorage['dsh-perf-guard:prefs']；重試策略寫入 ~/.dsh/perf-guard.retry.json。
除靜態資源外，下列 API 均要求請求頭 x-dsh-plugin: perf-guard：
| 路徑 | 說明 |
|---|---|
GET /api/perf-guard/health |
版本探活 |
GET /api/perf-guard/stats |
宿主內存、會話日誌排行、重試配置、最近錯誤 |
GET/POST /api/perf-guard/retry |
讀取或更新重試配置 |
典型用法與自檢¶
安裝並刷新 Web 界面後，默認即開啓跟隨、思考鏈展開、重試與降載。需要收緊重試時，在性能守衛設置裏關閉「截斷 / 傳輸中斷重試」或降低 maxRetries，避免與「不限」組合在上游持續空轉時長時間退避重試（退避封頂 15s）。
開發者在倉庫根目錄可跑自動化測試：
npm test
覆蓋項包括：test/host-smoke.mjs（狀態碼、退避、重試中間件）、test/follow-sim.mjs（跟隨控制器七場景）、test/client-smoke.mjs（客戶端裝配）、test/fixture/follow.html（Edge headless 瀏覽器斷言）。
適用場景與注意¶
適合經常在 DSH desktop profile 下進行長 transcript、多工具輸出的智能體開發或日常使用，希望少手動滾底、少手動展開思考塊，並在可恢復的網關/傳輸錯誤上自動退避重試的場景。
務必知曉：插件與 DSH 宿主同一進程權限運行，安裝前應閱讀 GitHub 源碼 與 MIT 許可證，自行判斷是否信任維護者。已知限制包括：長度截斷重試通常無效；優化側重渲染層，不降低宿主解壓會話日誌時的內存峯值。社區目錄 SkillHub 插件頁 與 GitHub 爲獨立信息源，與 DeepSeek / 幻方無官方從屬關係。
結尾¶
dsh-perf-guard 把長會話裏常見的滾動、思考鏈可見性與可恢復錯誤處理收成一組默認開啓、可在設置裏細調的行爲，且不碰主題與佈局。需要安裝命令、重試表與 API 細節時，以 GitHub README 爲準；瀏覽社區索引可打開 SkillHub 目錄頁。
