DeepSeek Harness (DSH) 的插件系统在遇到故障时倾向于静默失败：条目崩坏后默默退位，面板留空，错误仅停留在控制台，难以排查。dsh-ballute 是一款崩坏防护插件，旨在将这种不可见的故障转化为可见、可归因、可恢复的状态。
安装与启用¶
通过官方 CLI 安装插件：
dsh plugin add github:Zlyraz/dsh-ballute
安装完成后，Ballute 会自动注入 L1-L4 防护能力，并在运行时提供崩溃观测与恢复接口。
核心能力¶
插件通过五个层级（L1-L5）构建防护网，覆盖从装载前检查到运行时恢复的全流程。
L1 预检：静态契约体检¶
在插件装载前，通过 GET /api/ballute/v1/inspect 接口进行静态检查。它能发现结构层面的故障，例如 bundle 注册 ID 与包名不匹配、缺少必要导出或 name 字段缺失等。
L2 隔离：运行时崩卡展示¶
订阅官方 ctx.slots.onEntryError 钩子，在右下角展示崩卡。崩卡包含插件名、槽位 key、错误信息，将原本在控制台静默发生的崩溃暴露在 UI 层面。
L3 观测：黑匣子与历史¶
记录崩溃遥测日志为 JSONL 格式，存储在 $DSH_HOME/ballute/crash-log.jsonl。日志包含时间戳、堆栈、启动版本哈希（rev）等信息，支持重启后回溯。同时提供历史列表接口供查询。
L4 恢复：一键禁用¶
在崩卡 UI 中提供“关闭插件”操作，通过写入补丁层（disabled: true）实现 HMR 卸载，无需重启 DSH 实例即可让坏插件失效。
L5 兜底：安全模式¶
当主 profile 坏死时，启动一个包含最小 bundle 和 Ballute 自身的 safe profile，通过跨 profile API 体检并禁用坏插件，实现外部救场。
安全模式搭建¶
官方 CLI 尚未提供 --safe-boot 旗标，需手动构建最小 profile。
在 $DSH_HOME/profiles/safe/ 目录下放置以下文件：
package.json
{
"name": "dsh-profile-safe",
"private": true,
"dependencies": {
"dsh-ballute": "github:Zlyraz/dsh-ballute"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"dsh-ballute"
]
}
}
}
cordis.yml（空树即可）
[]
cordis.patch.yml（保持空数组）
[]
pnpm-workspace.yaml
packages:
- .
nodeLinker: hoisted
autoInstallPeers: false
执行 pnpm install 后，使用以下命令启动安全模式：
dsh --profile safe
启动后，Ballute 会检测到 safe profile，并在 UI 顶部显示恢复区，允许对目标 profile 进行体检或禁用操作。
自测与使用¶
夹具测试¶
使用插件自带的夹具验证体检功能：
curl 'http://127.0.0.1:3080/api/ballute/v1/inspect?fixture=fault-mismatch'
curl 'http://127.0.0.1:3080/api/ballute/v1/inspect?fixture=fault-load'
常见夹具包括 fault-load（缺失文件）、fault-apply（apply 抛错）、fault-mismatch（ID 不匹配）等。
开发模式安装¶
建议先在隔离的 dev profile 中验证，再安装到日常 profile。
dsh plugin --profile dev add /path/to/dsh-ballute
dsh web --profile dev --port 3081
开发期推荐使用 link 方式修改代码即生效。
注意事项¶
诚实边界¶
插件主要覆盖 L2 域（运行时条目崩溃）。
* Loader 级故障：如 client apply 抛错导致启动失败、bundle 文件缺失导致 host 进程崩溃，此时 UI 尚未渲染，Ballute 无法捕获，需依赖安全模式从外部恢复。
* SlotAssemblyError：该错误会穿透错误边界导致整页空白。此时 Ballute UI 不可见，无法捕获，只能查看控制台日志，刷新可恢复。
维护状态¶
该插件为业余维护，响应可能较慢。欢迎提交 Issue 或 PR。
许可证¶
MIT。
