dsh-death-forensics：DSH 主機進程死亡黑盒

前言¶

DSH Web 進程可能因外部殺死、凍結的事件循環或崩潰而靜默死亡。外部啓動器可以記錄如何死亡（退出代碼、stderr、運行時間），但只有進程內部才能記錄死亡前發生了什麼：最後心跳時間、崩潰堆棧以及上一次啓動是否正常結束。本插件是進程內那一半。需要與外部啓動器（見 DESIGN.md）配合使用以獲得完整畫面。

插件簡介¶

dsh-death-forensics 是一個 Cordis 插件（Bundle 格式），用於在 DeepSeek Harness (dsh) 主機中充當進程內死亡黑盒。它記錄死亡前發生的事件（心跳窗口、崩潰堆棧、啓動時的自我檢查）。該插件由 shenhuanageshei 維護，類別爲 admin-security，許可證爲 MIT。

核心能力¶

心跳記錄¶

插件會向 <DSH_HOME>/death-forensics/heartbeat.log 追加 JSONL 格式的日誌。記錄間隔由 heartbeatIntervalMs 控制，默認爲 15 秒。日誌文件有行數上限（maxHeartbeatLines），達到上限後會截斷。

結束類型自我檢查¶

插件在進程退出時記錄結束類型：
* graceful：通過 SIGTERM 或 SIGINT 觸發。
* neutral：通過 exit 事件觸發。
* running：進程崩潰或被強制殺死。
下次啓動時，插件會檢測到上一次的非優雅結束，並將其記錄到 crash.log 中。

崩潰堆棧捕獲¶

插件捕獲 uncaughtException（包括通過 Node 默認拋出鏈處理的無處理拒絕），記錄完整的堆棧信息，重新打印堆棧並調用 exit(1)。在主機行爲上，這等同於未安裝插件的情況。

報告工具¶

使用 death_forensics_report 工具可以查看當前啓動、上一次的結束類型、死亡窗口（最後一次心跳到下次啓動）、crash 日誌尾部以及外部啓動器日誌尾部（如果存在）。

安裝與啓用¶

通過 CLI 安裝¶

將插件添加到指定的 dsh profile（例如 web）：

dsh plugin --profile web add /path/to/dsh-death-forensics

添加後重啓 dsh。

通過配置文件安裝¶

在 profile/profiles/web/package.json 中添加依賴和 bundle 配置：

{
  "dependencies": {
    "dsh-death-forensics": "link:/path/to/dsh-death-forensics"
  },
  "dsh": {
    "profile": {
      "bundles": [ ..., "dsh-death-forensics" ]
    }
  }
}

典型用法¶

添加插件到 profile 並重啓 dsh。
使用 death_forensics_report 工具查看死亡前後的日誌信息。

適用場景與注意事項¶

適用場景¶

適用於需要深入排查 DSH 主機靜默崩潰、分析死亡窗口以及驗證優雅退出的場景。

注意事項¶

依賴環境：安裝前需確保 dsh checkout 或 profile install 包含 @deepseek-ai/* 包。
安全機制：
- 零子進程：插件不啓動任何子進程，僅進行文件寫入。
- 降級策略：熱路徑採用同步寫入並使用 try/catch。寫入失敗時僅禁用黑盒，不會影響主機運行。
- 無 Monkey-patching：不修改主機服務的內部邏輯。
- 鉤子清理：僅添加監聽器，插件銷燬時會自動清理。
數據存儲：所有數據文件存儲在 <DSH_HOME>/death-forensics/ 目錄下。

配置說明¶

配置項	默認值	說明
`heartbeatIntervalMs`	15000	心跳間隔，最小值爲 5000ms
`maxHeartbeatLines`	20000	心跳日誌文件行數上限
`reportTailLines`	40	報告工具顯示的日誌尾部行數
`dataDir`	`<DSH_HOME>/death-forensics`	數據目錄覆蓋路徑

總結¶

dsh-death-forensics 提供了進程內視角的死亡診斷能力。它通過心跳記錄、崩潰堆棧捕獲和結束類型自檢，填補了外部啓動器無法獲取的進程內部信息。對於追求高可靠性的 DSH 管理員，這是一個必要的排查輔助工具。插件詳情可參考社區目錄或GitHub。