shenhuanageshei/dsh-death-forensics

dsh-death-forensics

用于 DeepSeek Harness（dsh）宿主的进程内死亡黑匣子。一个 Cordis 插件
（bundle 格式），记录宿主死亡之前发生了什么——心跳
窗口、崩溃堆栈，以及下次启动时的结束类型自检。

为什么

dsh web 进程可能毫无痕迹地死亡（外部杀死、事件循环冻结、
崩溃）。外部启动器可以记录进程如何死亡（退出码 /
stderr / 运行时长），但只有进程内部的东西才能记录之前
发生了什么：最后一次心跳是什么时候、崩溃堆栈是什么，以及
上一次启动是否优雅结束。

本插件是进程内的那一半。将其与外部启动器配对（参见
DESIGN.md）以获得完整图景。

功能

| 功能 | 机制 |
|---|---|
| 心跳 | 每 heartbeatIntervalMs（默认 15 秒，文件有界）向 /death-forensics/heartbeat.log 追加 JSONL |
| 结束类型自检 | SIGTERM/SIGINT 记录 graceful；exit 事件记录中性的 exit；崩溃/被杀留下 running → 下次启动检测到非优雅结束并向 crash.log 追加一条记录 |
| 崩溃堆栈 | uncaughtException（包括通过 Node 默认抛出链产生的未处理 rejection）记录完整堆栈，然后重新打印并 exit(1) —— 宿主行为与无插件情况逐字节一致 |
| 报告工具 | death_forensics_report —— 当前启动、上一次结束类型、死亡窗口（最后一次心跳 → 下次启动）、崩溃日志尾部、外部启动器日志尾部（如果存在） |

数据文件（/death-forensics/）

- state.json —— 当前启动身份 + 上次结束类型（单一事实来源）
- heartbeat.log —— 仅追加的 JSONL，在 maxHeartbeatLines 处截断
- crash.log —— 仅追加的 JSONL 记录（崩溃 + 检测到的非优雅结束）

安全契约

- 零子进程 —— 从不生成任何东西；只进行文件写入。
- 热路径是带 try/catch 降级的同步写入 —— 失败会禁用
黑匣子，而绝不会禁用宿主。
- 钩子仅为附加监听器，在插件 dispose 时清理。
- 不对宿主服务进行 monkey-patching。

安装

添加到 dsh profile（例如 profile/profiles/web/package.json）：

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

然后重启 dsh。bundle 补丁会插入条目 id death-forensics。

或者，通过 CLI：dsh plugin --profile web add /path/to/dsh-death-forensics。

构建

需要一个携带 @deepseek-ai/* 包的 dsh checkout 或 profile 安装
（通过 $DSH_CHECKOUT，或 $HOME/dsh-harness、$HOME/dsh、
$HOME/.dsh/dsh-harness 解析），外加 typescript：

离线安装 devDependency（来自任意 pnpm store）
node  install --store-dir= --prefer-offline \
--config.node-linker=hoisted --config.auto-install-peers=false
编译 src/ → lib/
bash scripts/build.sh        # Windows 上的 Git Bash；node 必须在 PATH 中
node lib/selftest.js         # 17 个纯逻辑断言

已发布的 lib/ 已提交，因此该插件可直接从普通克隆中运行。

配置

| 键 | 默认值 | 描述 |
|---|---|---|
| heartbeatIntervalMs | 15000 | 心跳间隔（最小 5000） |
| maxHeartbeatLines | 20000 | 心跳文件行数上限 |
| reportTailLines | 40 | 报告工具显示的尾部行数 |
| dataDir | /death-forensics | 数据目录覆盖 |

文档

- DESIGN.md — 完整设计（中文）：状态机、钩子语义、验收标准。
- 死亡窗口解释：[上一次启动的最后一次心跳，本次启动的开始]。

许可证

MIT — 参见 LICENSE。