crash-guard-dsh：DeepSeek Harness 插件崩溃自动隔离与恢复

前言¶

DeepSeek Harness (DSH) 采用插件化架构，允许开发者通过插件扩展功能。然而，当某个插件在加载阶段出现错误（如代码报错、依赖缺失）或导致进程完全阻塞（死循环、同步阻塞）时，整个 Harness 或 PawWork 进程会崩溃或卡死，导致应用无法启动。crash-guard-dsh 针对这一痛点，通过自动隔离故障插件来保证系统的连续性。

是什么¶

crash-guard-dsh 是一个 DeepSeek Harness 插件，由开发者 limochaishang 维护，采用 MIT 许可证。其核心功能是：当某个插件导致启动崩溃或卡死时，自动隔离该插件，避免反复崩溃。

核心能力¶

插件具备以下主要功能：

崩溃自动隔离：检测到加载期崩溃后，下次启动会自动禁用导致崩溃的插件。
卡死自动恢复：通过独立看门狗进程检测完全卡死（hang）状态，自动杀进程、禁用可疑插件并重启。
三层自愈架构：包含同进程监控、独立看门狗进程和手动恢复三个层级，层层兜底。
零配置：安装后无需额外配置，直接生效。
安全护栏：不误伤正常插件，不隔离自身（id: crash-guard）和核心包（@deepseek-ai/*），并防止重复禁用。
心跳监控：主进程每 2 秒写入心跳，看门狗每 5 秒检查，超过 30 秒无心跳判定为完全卡死。

工作原理¶

三层自愈架构¶

系统通过以下三层机制保障运行稳定性：

同进程监控：主进程每 50ms 跟踪正在加载的插件，记录状态。如果 15 秒内未完成加载或未进入 ready 状态，判定为崩溃。
独立看门狗：启动一个 detached（分离）的独立进程。它不加载任何插件，只监控心跳文件。如果 30 秒内未检测到心跳更新，判定主进程完全卡死，执行杀进程、禁用插件、重启操作。
手动恢复：当自动机制无法解决问题时，用户可手动编辑配置文件移除禁用条目。

崩溃检测流程¶

crash-guard 在每次启动时作为 profile bundles 的第一位加载。

启动：crash-guard 首先执行 apply，开始跟踪加载过程。
记录：每 50ms 记录当前正在加载的插件 ID 到状态文件。
判定：启动完成后状态标记为 ready，正常退出标记为 clean。
隔离：如果下次启动检测到状态文件停在 booting 且未走完流程，说明上次加载期崩溃。此时将崩溃前正在加载的插件写入 cordis.patch.yml 的 disabled: true，下次启动即跳过该插件。

独立看门狗机制¶

同进程监控的局限在于如果插件导致事件循环完全阻塞，监控线程也会被冻住。独立看门狗通过独立进程解决这个问题：
* 主进程每 2 秒写入 heartbeat.json。
* 看门狗每 5 秒检查文件修改时间。
* 超过 30 秒无更新，触发自动恢复流程。

安装与启用¶

前置要求：DeepSeek Harness / PawWork 已安装，Node.js 18+（DSH 自带运行时即可）。

在 Windows 系统下，执行以下命令：

# 克隆或下载本仓库
git clone https://github.com/limochaishang/crash-guard-dsh.git
cd crash-guard-dsh

# 运行安装脚本
.\install.ps1

安装脚本会自动将插件复制到目标 profile 的 node_modules/，并将其插入 package.json 的 dsh.profile.bundles 第一位，随后重启 DSH / PawWork 生效。

使用方法¶

安装后无需任何操作，crash-guard 即自动工作：

正常启动：crash-guard 跟踪加载过程，启动完成后进入 ready 状态。
插件崩溃：下次启动自动禁用导致崩溃的插件，保证 PawWork 正常启动。
插件卡死：看门狗检测到无心跳，自动杀进程、禁用插件、重启。
查看日志：检查 $DSH_HOME/crash-guard/quarantine.log 查看被禁用的插件记录。

手动恢复¶

如果需要重新启用被自动禁用的插件，需手动编辑用户层配置文件（如 profiles/web/cordis.patch.yml），删除类似如下内容：

# [crash-guard] 自动禁用：插件 "xxx" (yyy) 在最近一次启动时导致崩溃。
# 如需恢复，删除下面两行即可。
- id: yyy
  disabled: true

删除对应条目后重启即可。

局限性与注意¶

检测范围：只处理加载期崩溃或完全卡死；运行期崩溃或被系统强杀只记日志，不自动禁用（难以归因）。
归因限制：如果崩溃发生在 crash-guard 加载之前（如 base bundle 自身问题），无法归因。
启发式判定：归因是启发式的，极端情况下可能不准确（例如插件 A 阻塞导致 loader 误判插件 B 加载中）。
自身崩溃：crash-guard 自身崩溃不会写入状态，下次启动会重新尝试。
配置方式：插件不参与 UI，无配置项（虽然可通过 patch 修改参数，但默认零配置即用）。

结语¶

crash-guard-dsh 为 DSH 插件开发提供了一个安全护栏，通过三层自愈机制解决了插件崩溃导致的启动失败问题。对于维护复杂 DSH 环境的开发者而言，这是一个减少手动排查成本的实用工具。