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 環境的開發者而言，這是一個減少手動排查成本的實用工具。