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。