baosfeng/my-dsh-plugins#dsh-my-guardian

dsh-my-guardian：DSH 插件隔离与失败兜底——新装/刚更新的插件先进候选区，启动完成后由守护插件逐个热挂载，成功自动转正、失败自动隔离、连续失败冻结，附一键安全模式与侧边栏诊断面板。

功能

• 两段式加载：新插件先进候选区，坏插件不再拖垮 dsh web 启动（DSH 启动名册是 all-or-nothing，任一插件失败即整个进程起不来）。
• 失败自动隔离：挂载失败记录尝试次数 + 失败类型 + 错误摘要，连续失败 3 次冻结，需手动重试。
• 挂载前依赖预检：检查候选插件 peerDependencies 是否安装、版本是否满足；硬缺失与版本不满足分开成句、分开字段、分开徽标，不进入挂载。宿主提供的包（@deepseek-ai/*、react/react-dom）不给 dsh plugin add 建议（按提示执行会把宿主自有包装进 profile）。桌面版宿主的 287 个 @deepseek-ai/* 包归档在 app.asar 内，预检会先读 desktop-runtime.json 建宿主清单再判定，不再把它们误报为缺失；客户端插件（有 dsh.client）的 9 个前端种子模块（react / react-dom 等）视为已满足（#481）。
• 成功自动转正：挂载成功的插件进入持久化清单，后续启动自动恢复。
• 运行中热挂载：运行期间往候选区加条目即自动挂载，无需重启。
• 安全模式：一键跳过全部候选/已转正插件，快速救回被插件搞坏的环境。
• 诊断面板：侧边栏「插件守护」页签（宿主原生扩展点）——状态列表 / 重试 / 移除 / 错误详情 / 失败分类徽标 / 安全模式开关 / 最近事件。

安装

💡 npm 安装（普通用户推荐）：dsh plugin --profile web add dsh-my-guardian --trust-lockfile——无需克隆本仓库；依赖 dsh-shared 随 npm 自动安装。link 方式供本仓库开发者使用。

git clone https://github.com/baosfeng/my-dsh-plugins.git
dsh plugin --profile web add link:<仓库路径>/plugins/dsh-my-guardian

装完硬刷新浏览器（Cmd/Ctrl+Shift+R）。手动安装：在 profile 的 cordis.patch.yml insert 列表第一行加 id: guardian / name: 'dsh-my-guardian'——守护插件自己是看门狗，必须最先加载。

使用

候选区文件 ~/.dsh/profiles/web/cordis.staged.json（与 cordis.patch.yml 同目录），每项为 { id, name, config? }：id 唯一标识、name 插件包名（profile 内可解析）、config 可选配置。

[{ "id": "my-plugin", "name": "dsh-my-plugin", "config": { "option": 1 } }]

写入后自动挂载：成功则该条从候选文件移除（转正），失败则保留。面板状态：运行中（可移除）/ 待加载（安全模式等）/ 失败 ×N（重试或移除）/ 冻结（连续失败 3 次，重试解除冻结）。失败条目带失败类型徽标（依赖缺失 / 版本不满足 / 代码错误 / 其他），并在存在可执行的修复命令时附安装建议（宿主提供的包、含空格/管道的版本范围不给命令）。

启动名册静态预检：直接写进 cordis.patch.yml / profile / bundles 的插件仍由 DSH 启动时 all-or-nothing 加载，守护每次启动对名册做静态预检，问题写入 $DSH_HOME/guardian/startup-issues.json（type 区分 unresolvable / dependency-missing / dependency-mismatch / duplicate-id，依赖字段分 missingDeps / mismatchedDeps）并在面板「最近事件」置顶展示；预检只记录告警，不阻断启动。

检查范围与解析顺序（逐行显式，不留静默免检）：

检查	覆盖范围	解析顺序
包可解析（unresolvable）	所有行（含 scoped @scope/pkg 与子路径 pkg/sub，按 basePackage() 归一）	<profileDir>/node_modules → <profileDir>/../node_modules（$DSH_HOME/profiles/node_modules），两处都无才报
peerDependencies	仅非 scoped 行（保持既有范围，不因 scoped 行放开而扩大）	插件自身 nested → profile → profiles 根
重复 entry id	全名册	—

宿主供给行（@deepseek-ai/*、react / react-dom）跳过可解析性检查：它们由宿主安装目录供给，不在上述两段根内，硬查只会误报。跳过不是静默的——报告里有 skippedHostRows 计数与 notes 说明（例如「已跳过 8 个宿主供给行…」），快照同步携带，用来区分「都查过且没问题」与「有 N 行没查」。

配置

无应用层配置项（插件激活即生效）。运行时状态：$DSH_HOME/guardian/state.json 持久化候选/转正清单、失败次数、安全模式与事件日志（损坏自动降级为空状态）；安全模式为面板开关，也可直接编辑 state.json 的 safeMode: true，开启后候选/已转正插件都不加载。

诚实的边界

• 提供的是加载时序与失败处置的兜底隔离，不是进程级资源隔离（server 端插件仍在同一 Node 进程，client 端仍在同一浏览器页面）。
• 启动阶段的正式核心区（cordis.patch.yml）仍遵循 all-or-nothing：新插件请先进候选区验证，稳定后再考虑放核心区。

相关文档

→ 插件治理概述