插件体检医生 hollowfyh/dsh-plugin-doctor

dsh-plugin-doctor

插件体检与自动修复。某个插件行在加载时发生冲突（apply 抛错、服务重复注册、依赖缺失等），DSH 会把它标记为 failed 并让它停摆，但整个宿主继续运行。本插件周期扫描 Loader 树：

- 发现 failed 行时，调用官方 pluginManager.setPluginEnabled(id, false) 持久化禁用该行（写入 profile 的 cordis.patch.yml 并触发热重组），让其余插件照常工作；
- 每次修复写入 $DSH_HOME/plugin-doctor/incidents.jsonl，整份报告写入 report.json；
- 注册 /doctor 斜杠命令，随时手动体检。

配置（profile 的 cordis.patch.yml 里给本行加 config）

- id: plugin-doctor
name: 'dsh-plugin-doctor'
config:
autoFix: true # 默认 true：自动禁用加载失败的行 scanDelayMs: 3000 # 启动后延迟首次扫描的毫秒数 watchIntervalMs: 12000 # 运行期扫描间隔（0 = 只在启动时扫描一次） maxFixesPerBoot: 3 # 单次启动最多自动修复的行数

安全边界

- 只禁用，不卸载、不改 package.json 依赖；
- 不处理自身、dsh-plugin-manager 与插件清单模块，以及只读行（readOnlyReason）；
- 修复数量有上限；临时冲突（HMR transactions cannot be nested）自动重试，最多 6 次；
- 被修复的行在「插件」页仍可手动重新启用；修复记录完整可查。

报告格式

report.json 每次扫描重写：

{
"at": "…", "total": 199, "active": 174,
"failed": [{ "entryId": "…", "moduleName": "…", "readOnlyReason": null }],
"dormant": [],
"fixed": [{ "entryId": "…", "result": { "application": "applied", "changed": true } }],
"skipped": [{ "entryId": "…", "reason": "…" }],
"errors": []
}

dormant = 启用但没有任何存活 fiber 的行（常见于模块导入失败），仅报告、不自动处理。

测试

- node test/smoke.mjs：假上下文下的 4 个场景（正常禁用 / 临时冲突重试 / autoFix 关闭 / 修复上限）。
- test/broken-plugin.mjs：故意在 apply 抛错的测试插件，可通过 patch 的 insert 行临时装载，验证端到端自动修复（实测通过：失败行被禁用并写入 disabled: true）。

实现细节

- 失败检测：优先 pluginManager.listPlugins()（带 readOnlyReason 与 fiberPhase），拿不到时直读 ctx.loader.entries() 并按 fiber.state 映射阶段。
- 修复：pluginManager.setPluginEnabled(entryId, false) —— 官方开关 API，写入 profile 的 cordis.patch.yml 并触发 HMR 重组。
- HMR 上下文坑：本插件若在一次热重组中被挂载，apply 里创建的定时器会继承那次事务的 AsyncLocalStorage 上下文，runExclusive 会以 "HMR transactions cannot be nested" 拒绝修复。因此修复调用包在 hmr.executing.exit(callback) 里（临时清空事务上下文）；拿不到该字段时回退直接调用。此路径已在桌面实例实测通过。

局限

- 只看宿主侧 Loader 行；浏览器端模块加载失败、slot 层 UI 重叠不在本插件范围内。
- 若失败发生在宿主启动的极早期（Loader 树本身起不来），本插件同样无法启动——需要人工介入。
- 导入失败（模块不存在）通常不产生 failed fiber，只在 dormant 里出现；被 dormant 记录的模块需要人工检查模块名/依赖。

目录

lib/index.js 宿主侧插件实现 cordis.patch.yml 本 bundle 的插入行 test/smoke.mjs 假上下文冒烟测试 test/broken-plugin.mjs 端到端故障注入插件