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 仓库。