dsh-auto-reconnect：DSH Web 客戶端斷線與殭屍連接修復插件

前言¶

DeepSeek Harness (DSH) 的 Web 客戶端官方連接控制器內置了退避重連機制，但在實際使用中存在兩個盲點：一是終端斷開狀態進入死循環後無法自動恢復，二是網絡波動導致 WebSocket 保持 OPEN 但實際已斷開的“殭屍連接”。dsh-auto-reconnect 插件通過監聽瀏覽器可見性、焦點等事件，喚醒並修復這兩個場景。

插件介紹¶

這是一個僅運行在客戶端的自動重連插件，零構建，不觸碰官方包。由維護者 tqcq 提供，採用 MIT 許可證。

核心功能¶

插件通過訂閱連接狀態存儲，僅在狀態不等於 connected 時調用 connection.reconnect()，避免中斷健康連接。具體能力如下：

事件喚醒：監聽 visibilitychange、focus、pointerdown、keydown、pageshow(persisted) 等事件。當瀏覽器可見性變化或頁面恢復時，若連接狀態異常則立即重連。
修復終端斷開：針對官方控制器在終端 disconnected 狀態下睡眠的問題，增加自動重試邏輯。默認間隔 3 秒，最多重試 20 次，直到連接成功。
修復殭屍連接：針對 TCP 靜默掉線導致的 connected 狀態假象，增加可見性和焦點監聽器，確保連接狀態與實際網絡一致。
日誌記錄：所有觸發操作均帶有 [dsh-auto-reconnect] 前綴，方便在 DevTools 控制台排查問題。

安裝與啓用¶

安裝插件需要重啓 dsh-web 進程，瀏覽器刷新無效。

安裝：
執行以下命令安裝插件：

    dsh plugin --profile web add github:tqcq/dsh-auto-reconnect

更新：
若需升級插件：

    dsh plugin --profile web update dsh-auto-reconnect

移除：
若需卸載插件：

    dsh plugin --profile web remove dsh-auto-reconnect

典型用法¶

安裝完成後，無需重啓 dsh-web 進程即可在瀏覽器中通過 localStorage 調整重連策略。修改後刷新頁面生效：

localStorage["dsh-auto-reconnect"] = JSON.stringify({
    minIntervalMs: 3000,     // 最小重連間隔
    retryDelayMs: 3000,      // 重連延遲
    maxAutoRetries: 20,      // 最大自動重試次數
    log: true                // 啓用日誌
});

適用場景與注意¶

兼容版本：已驗證兼容 @deepseek-ai/dsh 0.1.5-rc.2 和 @deepseek-ai/dsh-client-connection 0.1.2-rc.1。若接口結構發生漂移，插件會保持靜默而非導致頁面崩潰。
侷限性：無法檢測客戶端背景標籤頁 NAT 掉線（需要心跳機制）。此類問題需由主機端提供心跳或死連接掃描。
權限說明：插件以當前 dsh 進程的權限運行，安裝前建議檢查源碼與許可證。

結語¶

dsh-auto-reconnect 旨在解決 DSH Web 客戶端在複雜網絡環境下的連接穩定性問題。更多細節與源碼可參考：GitHub 倉庫。