前言¶
在 DSH（DeepSeek Harness）里跑 QQ 机器人时，常见做法是挂 NapCat、LLOneBot 等 OneBot v11 实现，再用脚本或外部监控看端口是否在听。端口正常并不代表机器人在回消息：进程还在、WebUI 也能打开，网关连接却可能已经断掉，这就是常说的「假死」。只能人工重启 QQ，既打断开发调试，也不适合长期 unattended 运行。
下面介绍社区插件 dsh-qqbot-guard（维护者 13377184330）：在 DSH 进程内定期请求网关状态 JSON，按 connected 等字段判断连接是否健康，连续失败则执行配置好的重启流程，并带防抖与冷却，减少误杀和扫码窗口被反复关掉的情况。
这是什么¶
dsh-qqbot-guard 是 DeepSeek Harness 插件，定位是 OneBot v11 系（NapCat / LLOneBot / Go-cqhttp 等）假死自愈守卫。它不替代 OneBot 本身，而是在 DSH 组合包里做「深度健康检查 → 自动重启 → 防抖 + 冷却」。
README 中归纳的典型根因（2026-10 实测复现）包括：承载机器人的 utility 子进程会被 QQ 不定期重开且无崩溃日志；重开后反向 WebSocket 往往不会自行重连（配置里的 reconnectInterval 在此场景下形同虚设），从而出现「端口活、连接死」。常规 netstat 或端口探测发现不了这类状态。
插件版本在 package.json 中为 0.1.0，运行时要求 Node 20+，仅使用内置 fetch 与 child_process，无第三方运行时依赖。许可证为 MIT。社区目录页：skillhub.cn/plugins/13377184330/dsh-qqbot-guard；源码：github.com/13377184330/dsh-qqbot-guard。SkillHub 为社区插件目录，与 DeepSeek / 幻方无官方从属关系。
核心功能¶
深度健康检查¶
默认每 2 分钟请求一次 health.endpoint（示例为 http://127.0.0.1:3001/api/state），在 timeoutMs 内完成 fetch。超时或非 2xx 记一次失败；对 JSON 按顺序尝试 gateway.connected、connected、data.status、status、ok、online 等字段，也可通过 health.healthyField 自定义点分路径。布尔 true 或字符串 ok|online|listening 视为健康；false|failed|offline|error 视为假死。若 HTTP 200 但找不到任何健康字段，保守判为健康，避免误杀。
防抖与救援¶
连续失败达到 health.maxFailures（默认 2）才触发救援：按 rescue.processName 清理残留进程，再执行 rescue.command（argv 数组，必填）。救援后进入 cooldownMs（默认 15 分钟）冷却，期间只记录不再次动手——README 说明这是为避免连接反复断开时，用户来不及完成扫码登录就被再次重启。
状态持久化¶
失败计数与上次救援时间写入 rescue.stateDir（默认 ~/.dsh/dsh-qqbot-guard），DSH 重启后仍保留。调试时可看 DSH 日志里 [guard] 关键词，以及状态文件中的 failures、lastRescueAt。
安装与启用¶
安装前请自行阅读仓库源码与 MIT 许可证；插件以当前 DSH 进程权限执行健康检查与重启命令，重启脚本涉及杀进程与启动 QQ，权限与路径需与运行环境一致。
从 Git 安装（发布后）¶
资料原文示例（需替换占位符并固定 commit）：
dsh plugin --profile demo add github:<you>/dsh-qqbot-guard#<commit-sha>
git 安装会走源码构建（prepare 脚本）。若使用 pnpm ≥10，首次安装可能要求显式授权构建脚本：将 pnpm 提示的包键写入 profile 的 pnpm-workspace.yaml 的 allowBuilds 后重试；只对可信源码授权并固定 commit。
从 npm 安装（发布后）¶
dsh plugin --profile demo add dsh-qqbot-guard
将 demo 换成你的 profile 名。启用方式与 DSH 其它插件相同：在对应 profile 下启动 DSH，并在 cordis.patch.yml 中覆盖配置。
典型配置¶
默认片段在插件包内 cordis.patch.yml；在你 profile 的 cordis.patch.yml 中后写覆盖项即可：
- id: qqbot-guard
name: dsh-qqbot-guard
config:
health:
endpoint: http://127.0.0.1:3001/api/state
intervalMs: 120000
timeoutMs: 8000
maxFailures: 2
# healthyField: gateway.connected
rescue:
processName: QQ
command:
- powershell.exe
- -NoProfile
- -ExecutionPolicy
- Bypass
- -File
- D:\scripts\restart-qq-gateway.ps1
retWaitMs: 3000
restartWaitMs: 25000
cooldownMs: 900000
stateDir: ~/.dsh/dsh-qqbot-guard
rescue.command 必须填成你环境中真实的重启方式（上例为 Windows PowerShell 脚本）。endpoint 需与 NapCat / LLOneBot 等实际暴露的状态接口一致。若机器人采用快速登录、启动很快，README 建议可将 cooldownMs 调小；需要人工扫码时，应保留足够冷却时间。
适用场景与注意¶
适合：长期用 DSH 托管 OneBot v11 网关、已遇到过「进程在、消息不回」、且愿意用 HTTP 状态接口 + 自动化重启替代纯端口监控的场景。
注意：
- 救援逻辑依赖你配置的
command与processName，错误配置可能导致误杀或重启失败。 - 插件无法代替 OneBot 侧修复 WebSocket 重连；它是在连接已断时从外部拉一把。
- 安装与授权构建脚本前，应检查 GitHub 仓库内容与 commit，勿对不可信源码开放
allowBuilds。
结尾¶
dsh-qqbot-guard 把「查网关连接而不仅是查端口」做成 DSH 插件：防抖减少刚重启时的误判，冷却给扫码登录留窗口，状态落盘避免 DSH 重启丢计数。若你的栈是 NapCat / LLOneBot 等 OneBot v11 系，且假死问题已复现，可在目录页查看条目说明，并在 GitHub README 核对最新配置字段与安装方式。
- 目录页：https://www.skillhub.cn/plugins/13377184330/dsh-qqbot-guard
- GitHub：https://github.com/13377184330/dsh-qqbot-guard
