dsh-crash-guard

DSH Crash Guard (防崩卫士)

English | 中文

面向 DeepSeek Harness (DSH) 打造的启动防白屏与崩溃隔离守护插件。效仿 Minecraft 社区 Not Enough Crashes 的容错设计，在第三方插件产物存在语法损坏或未激活时，自动热摘除故障插件并放行正常界面加载，避免触发整窗崩溃白屏。

---

核心功能

• 双层崩溃防护
  • Node 宿主预检：在服务端启动时对前端插件 bundle 执行基于文件指纹 (rev) 的 V8 经典脚本语法与 Lazy-CJS 契约预检，提前从 ClientModuleRegistry 剥离损坏产物并自动重建干净的启动图谱。
  • Web 引导拦截：在浏览器端官方 IZ() 严格审计前动态介入，通过 loader.remove() 无损摘除未成功激活的前端条目并清理残留样式，杜绝 N entries did not activate 导致的 Electron 白屏崩溃弹窗。
• 指纹绑定静默隔离 (Revision-bound Quarantine)
  • 启动阶段发现故障时自动启用静默隔离，将隔离记录保存在独立的 .dsh-market/crash-guard-quarantine.json 中，完全不改动用户的正式配置文件 (package.json、state.json 与 cordis.patch.yml)。
  • 插件代码未变时，下次启动自动静默跳过并不再弹窗打扰；一旦在本地修改了插件代码或在插件市场更新了插件（文件指纹改变），自动解除隔离并恢复尝试加载。
• 手动持久化禁用入口
  • 当确认需要彻底停用某个插件时，可在顶栏救援面板中点击永久禁用。此时插件会执行三层正式配置写入：同步写入 .dsh-market/state.json、从 package.json 的 dsh.profile.bundles 中移除该项、并在 cordis.patch.yml 中将对应条目标记为 disabled: true。
• 轻量级顶栏可视化救援面板
  • 深度跟随 DSH 系统语义色彩变量 (--dsw-alias-*)，明暗主题无缝自适应。
  • 最小化胶囊紧凑嵌在 Windows 40px 标题栏右侧最小化按钮左方空白拖拽带内 (right: 150px)，平时不遮挡工具栏、聊天区或右侧终端分栏；点击即可向下展开故障分类、上游阻断源 (blockedBy) 与详细报错堆栈。

---

技术方案对比

在 DSH 生态中，保障启动稳定性的常见方案有两类，两者在架构与介入时机上存在根本差异：

评估维度	外部守护进程方案（如 watchdog 启动器包装）	DSH Crash Guard 纯插件方案
运行形态	依赖外部独立监控进程，需重写 bin/dsh.cmd 启动链路	纯插件形态，零外部依赖，不侵入系统原生启动链路
故障拦截层	仅在 Node 进程挂起或异常崩溃后被动介入	Node 宿主预检 + 渲染层 __ModuleLoader__ 双层主动拦截
前端白屏防护	无法阻断前端 Web 启动审计抛错引发的白屏弹窗	介入 IZ() 审计前置剪枝，剔除未激活项并正常拉起 GUI
隔离与自愈	依赖改写配置文件或外部状态标记	基于文件指纹 (rev) 自动隔离与自愈，改动代码即刻重试
调试排查	查看本地文本日志或等待命令行输出	原生标题栏救援胶囊，直观展示报错堆栈与阻断因果链

---

安装方法

方式一：通过 DSH 命令行安装

若使用官方 npm 源：

dsh plugin add dsh-crash-guard

若直接从 GitHub 源码仓库安装：

dsh plugin add github:zxzc114514/dsh-crash-guard

方式二：在 Profile 中手动引入

在当前 Profile 的 package.json (通常位于 ~/.dsh/profiles/desktop/package.json) 中声明依赖并加入 bundle：

{
  "dependencies": {
    "dsh-crash-guard": "^1.0.0"
  },
  "dsh": {
    "profile": {
      "bundles": [
        "dsh-crash-guard"
      ]
    }
  }
}

若引用 GitHub 仓库版本：

{
  "dependencies": {
    "dsh-crash-guard": "github:zxzc114514/dsh-crash-guard#v1.0.0"
  }
}

---

运行环境与依赖说明

版本支持范围

• DSH 版本约束：>=0.2.0-rc.2 <0.3.0-0
• Node.js 环境：>=20
• 说明：DSH 从 0.2.0-rc.2 版本起引入客户端模块注册表 (ClientModuleRegistry) 与浏览器端 IZ() 严格审计流程，本插件依托该架构构建防御链路，因此不向下兼容 0.1.x 系列。

内部依赖与机制声明

• Node 宿主层：挂钩 ctx.clientModules.table 模块表，通过 vm.Script 执行经典语法预编译与 Lazy-CJS 结构核对，调用 compose() 动态重构干净的启动图谱。
• Web 渲染层：在 index.html 的 <head> 阶段注入引导拦截器包装 __ModuleLoader__.create，在 modules.entries.start 执行完毕且在官方 IZ() 审计触发前执行拓扑剪枝 (pruneInactiveEntries)，摘除状态异常条目。

---

实测验证记录

在 DSH 0.2.0-rc.2 与 0.2.0-rc.3 环境下，本插件针对典型崩溃场景完成以下测试：

1. 客户端脚本语法损坏：为测试插件注入非法顶层 return 语句。启动时 Node 端预检在 11ms 内成功捕获语法异常，自动将其移入隔离记录并重构启动图，避免后端向前端分发损坏的 bundle。
2. 缺失上游依赖导致未激活：为测试插件声明未安装的依赖项，触发状态停滞在初始化阶段。Web 端引导拦截器在官方严格审计前自动剪除未激活节点，Electron 窗口正常进入主界面，标题栏救援胶囊准确标注故障插件并高亮显示 blockedBy 依赖包名。

---

许可证

本项目基于 MIT 许可证 开源。