启动故障保护 fengs2021/dsh-boot-failsafe

dsh-boot-failsafe v2

适用于 DeepSeek Harness Web GUI 的启动故障保护 —— 纯客户端、零磁盘写入、零宿主逻辑、被动响应。如果某个客户端插件在加载时崩溃（模板缺陷，如 exports is not defined / received object，或任何工厂函数抛出异常），它会被跳过并显示可见横幅，而不是破坏 UI；缺失 bundle 的 404 会被报告，而不会自动“修复”。即使某个插件损坏，你也始终能进入界面。

WebUI 加载容错（对抗审查修订版）。纯 client、零磁盘写入、零 host 逻辑、被动响应——坏插件加载失败时自动跳过 + 横幅提示，绝不破坏页面与服务端。

安全契约（v2 硬性规则）

- ❌ 任何形式的磁盘写入（node_modules / patch / 任何东西）
- ❌ 无服务端路由、无 loader 服务访问、无 manifest 修改
- ❌ 无探测、无“它是否已卸载”的猜测
- ✅ 唯一的持久化是浏览器 localStorage
- 最坏的可能结果：某个插件被跳过（可恢复）。服务端绝不会被触碰。

历史（v0.1）：一个宿主侧自动补丁曾将 no-op 包写入 profile node_modules，它曾把 128 个官方包误分类 → 崩溃循环（NRestarts=65）→ 502。v2 的宿主部分明确为 no-op。

能力

1. 工厂故障保护：包装 window.__ModuleLoader__.load —— 在模块顶层安装（在 arrive 阶段，远早于宿主 EntryTree 导入插件；如果 __ModuleLoader__ 未就绪，则轮询 ≤30 秒）。抛出异常或未返回 apply 的工厂函数会被替换为 no-op 占位符，并列在横幅中（插件名 + 原因 + 禁用按钮）。包装器本身完全由 try/catch 保护 —— 它绝不会破坏注册链。
- 诚实说明：顺序是尽力而为（script 阶段 ≪ import 阶段），并非硬性保证。
2. 缺失 bundle 报告：严格 404 检测 —— error 事件（捕获）+ SCRIPT 目标 + /plugins/ src + 从启动 manifest 解析出的 id（只读）。仅报告，绝不自动修复。
3. 黑名单（localStorage dsh.bootFailsafe.blocked.v2）：
- 条目为 {id, rev}；当 manifest 的 rev 变化时，条目自动清除（该插件可能已被修复）
- 自我保护：拒绝禁用 dsh-boot-failsafe 自身或 @deepseek-ai/dsh-client-modules
- “全部解除”逃生按钮会清除整个黑名单
- 修复插件后：刷新页面即可恢复（全新的 loadCache，无陈旧 no-op）

覆盖边界（诚实说明）

| 场景 | 行为 |
| 工厂模板缺陷（无 apply / 工厂抛出异常） | ✅ 跳过 + 横幅 + 禁用 |
| 顶层转译错误（模块顶层的 exports is not defined） | ⚠️ script-error 路径：横幅 + manifest id 查找，不跳过 |
| Bundle 404（已卸载、未重启） | ⚠️ 仅报告（“刷新 / 重启服务”） |
| 运行时 apply 半崩溃 | ❌ 不覆盖（运行时错误） |

安装

dsh plugin --profile web add github:fengs2021/dsh-boot-failsafe
systemctl restart dsh-web # or hot-mount via dev tools (no restart)
之后请硬刷新页面（浏览器必须加载新的客户端 bundle）。

安全契约（v2 铁律）

- ❌ 不写任何磁盘文件（node_modules / patch / 任何路径）
- ❌ 不注册服务端路由、不访问 loader 服务、不修改 __DSH_BOOT__
- ❌ 不探测、不判定「已卸载」
- ✅ 唯一持久状态 = 浏览器 localStorage
- 最坏结果 = 某个插件被跳过（可恢复）；服务端零影响

历史教训（v0.1）：host 半自动补写 no-op 包曾把 128 个官方包误判替换成占位 → crash loop（NRestarts=65）→ 502。v2 host 半显式为 no-op。

能力

1. factory 容错：包装 window.__ModuleLoader__.load（模块顶层安装，早于 EntryTree import 阶段；__ModuleLoader__ 未就绪则 ≤30s 轮询等待）。factory 抛错 / 未返回 apply → no-op 占位 + 横幅（插件名+原因+禁用按钮）。包装自身异常全兜底回退原始 load，绝不破坏注册链。
- 诚实声明：时序为尽力而为（script 阶段远早于 import 阶段），非硬保证。
2. 资源缺失提示：严格 404 检测——error 事件（capture）+ SCRIPT target + /plugins/ 前缀 + manifest（只读）id 反查。只提示不自动修。
3. 黑名单（localStorage dsh.bootFailsafe.blocked.v2）：
- 条目 {id, rev}；manifest rev 变化 → 自动解除（可能已修复）
- 自我保护：禁止禁用 dsh-boot-failsafe 自身与 @deepseek-ai/dsh-client-modules
- 横幅「全部解除」逃生按钮
- 修复插件后：刷新页面即可恢复（loadCache 全新，无残留 no-op）

覆盖边界（诚实）

| 场景 | 行为 |
| factory 模板缺陷（未返回 apply / factory throw） | ✅ 跳过 + 横幅 + 禁用 |
| 顶层转译错误（exports is not defined 在模块顶层） | ⚠️ script-error 路径：横幅提示 + manifest 反查 id，不跳过 |
| bundle 404（已卸载未重启） | ⚠️ 只提示「刷新/重启」，不自动修 |
| apply 运行期半崩 | ❌ 不覆盖（运行时错误） |

安装

dsh plugin --profile web add github:fengs2021/dsh-boot-failsafe
systemctl restart dsh-web # 或 dev 工具热装配（免重启）

安装后硬刷新页面（浏览器需加载新版 client bundle）。

License

MIT