插件装载去重守卫Lstalu/dsh-bundle-dedup-guard

dsh-bundle-dedup-guard

CI
npm version
[node]()
License

DeepSeek Harness 插件守卫：每次装载插件时检查 profile 的 bundles 列表是否存在重复 loader 条目，并对整机插件环境做站点级体检（vendor 依赖树、插件 @deepseek-ai junction、已知冲突对）。

当 profile 的 dsh.profile.bundles 同时列出聚合包（其 patch 一次性插入全部子插件条目，
如 @linxin666/dsh-web-ui-all）和它的子插件时，loader 会对同一 loader 条目 id
收到两次 insert。EntryGroup.update 在任何插件条目创建之前就抛
duplicate loader entry id: ，整个 profile 启动失败。本插件让这类问题不再无声发生。

为什么存在

2026-08-18 事故：web profile 同时列出了 @linxin666/dsh-web-ui-all（聚合 13 个子插件
为一个 patch）和全部 13 个子插件。每个子插件 id 被 insert 两次，第一个被撞上的是
duplicate loader entry id: ui-dsh-aionui-panel。只修 bundles 列表还不够——
dsh plugin 的 reconcilePlugins 会在每次 pnpm 操作后把 *dependencies 里所有声明了
dsh.bundle 的包按依赖顺序追加回 bundles，一小时后子插件被重新写回，下次启动又崩。

2026-08-21 事故：插件批量更新清空了各插件的 node_modules（8 个插件以
Cannot find package 崩溃）；修复时 npm install 顺着 @deepseek-ai junction 跑进
vendor 树把它搅坏；依赖修好后 dsh-better-sidebar 又被双入口挂载（/sidebar/api
重复路由崩溃）。v0.2.0 把这些红线变成自动的站点级体检，见下文
站点级体检。

完整事故记录：docs/KNOWN-ISSUE-bundle-duplicate.md
（2026-08-18），以及 2026-08-21 的自修复手册（由站点体检自动提示位置）。

工作原理

loader 的故障链路是：cordis-plugin-include 的 applyEntryPatches 平铺累加各 bundle
的 insert 条目不去重，随后 cordis-plugin-loader 的 EntryGroup.update 按 id 去重、
碰到第一个重复就抛错——此时任何插件条目都还没创建。本插件用纯 Node 复刻这套
「平铺累加 + 按 id 去重」语义，报告违规 id、来源（哪个 bundle/patch 插入的）与修复指引。

每次装载插件都检查

| 时机 | 触发 | 说明 |
| --- | --- | --- |
| 启动装载 | 插件 apply | 每次启动体检一次 |
| loader 事件 | loader/entry-init / loader/partial-dispose | 运行时热装载/新增插件，800ms 防抖复查 |
| 清单文件变化 | fs.watch 监听 profile 目录 | dsh plugin add、插件市场安装、手改 package.json / cordis.patch.yml 的瞬间立刻警告，无需等重启 |

报告内容

- 重复 loader 条目 id——每个被多个来源插入的 id 及完整来源链（如
ui-dsh-aionui-panel: @linxin666/dsh-web-ui-all ← @linxin666/dsh-client-ui-aionui-panel）。
- 未解析 bundle——列在 bundles 里但解析不到（loader 同样会 loud fail）。
- 无 patch 的包——列了但没有 dsh.bundle.patch 段（按 loader 契约属配置错误）。
- reconcile 预测警告——dependencies 里声明了 dsh.bundle 但不在 bundles 列表的包。
dsh plugin 的 reconcile 会在下次装/更新插件时把它追加进 bundles；若它是聚合包已覆盖的
子插件，将重新造成崩溃。警告会点名已被覆盖的 id。处理：把这些包移入 devDependencies
（reconcile 只读 dependencies）。

报告落盘 $DSH_HOME/dsh-bundle-dedup-guard/reports/-.json 与
.latest.json。

站点级体检（v0.2.0 新增）

除上述 profile 清单检查外，每次检查还做一次整机站点体检（lib/site-health.mjs，
零依赖纯只读），把 2026-08-21 事故的红线变成自动检查：

| 检查 | 命中形态 | 对应事故 |
| --- | --- | --- |
| 已知冲突对 | bundles 同时列出 @linxin666/dsh-web-ui-all 和 dsh-better-sidebar——两个入口执行同一份 lib/index.js，都注册 /sidebar/api 路由（apply 阶段 duplicate prefix route 崩溃） | 2026-08-21 |
| vendor 完整性 | vendor 的 @deepseek-ai/ 包 vs resources/vendor/dsh/node_modules/.package-lock.json：缺失 / 空目录 / package.json name 不符（内容装错）/ 版本不符；.名字- 临时目录残留（提示） | 2026-08-21 |
| 插件 junction 完整性 | 运行时代码 import 了 @deepseek-ai/ 的插件，其 package/node_modules/@deepseek-ai junction 缺失（08-21 崩溃同款 Cannot find package）/ 指向错误目标 / 悬空；真实目录替代（可用，提示）；.npmbak 残留（在含 junction 目录跑过 npm install 的痕迹） | 2026-08-21 |
| 自修复手册指针 | 提示最新的 $DSH_HOME/incidents//README.md 位置 | — |

每个问题都附可直接复制的修复命令（重建 junction / 跑 repair-vendor.ps1 / 删 bundles 条目），
守卫自身绝不修改任何文件。

junction 体检判定「插件是否需要 junction」的依据是源码扫描运行时的
import/require '@deepseek-ai/…'（不是 package.json 声明），且只审计当前在某个
profile 的 bundles 里激活的插件——休眠插件目录（如 dsh-workflow）不误报。

已知限制

loader 在创建任何插件条目之前就去重，所以「启动即崩溃」的场景下进程内检查无法运行
（插件树根本没装载）。此时请用下面的独立 CLI：纯读盘，崩溃状态下也能跑。

安装

作为 profile bundle（开发期推荐）：

1. 在 profile 的 package.json dependencies 加：
"dsh-bundle-dedup-guard": "link:F:/path/to/dsh-bundle-dedup-guard"

2. dsh.profile.bundles 加 "dsh-bundle-dedup-guard"（放最前面即可）。
3. 在 profile 的 node_modules 建立链接（dsh plugin add 会自动做）。

从 npm：

dsh plugin --profile web add dsh-bundle-dedup-guard

用法

插件自动检查，无需交互。手动诊断（含启动已崩溃时）：

检查全部 profile + 站点体检（DSH_HOME 缺省 ~/.dsh）
node bin/check.mjs

指定 profile
node bin/check.mjs --profile web

指定清单文件（如修复前的备份，测试用）
node bin/check.mjs --manifest

机器可读 JSON、不落盘报告
node bin/check.mjs --profile web --json --no-write

跳过站点级体检
node bin/check.mjs --no-site

退出码：0 = 健康；1 = 发现重复 / 未解析 bundle / 无 patch bundle / 站点体检问题
（可做 CI 门禁）。

修复重复

编辑 dsh.profile.bundles，每个 id 只保留一个来源。最常见的形态是「聚合包 + 子包」：

- 保留聚合包（如 @linxin666/dsh-web-ui-all）
- 删除单独列出的子包条目
- 同时把子插件从 dependencies 移入 devDependencies——否则 dsh plugin 的
reconcile 会在下次装/更新插件时把它们重新追加回 bundles（2026-08-18 复发的根因）

然后重跑 node bin/check.mjs --profile  直到绿灯，再重启。

开发

npm test          # node --test，零依赖
npm run check     # 对本机 profile 运行守卫

- lib/check.mjs — 检查核心（纯 Node，无第三方依赖）
- lib/site-health.mjs — 站点级体检（v0.2.0：冲突对 / vendor 完整性 / junction 完整性）
- index.mjs — Cordis 插件入口（apply + 监听器）
- bin/check.mjs — 独立 CLI（无需装载插件树）
- test/ — 带 fixture profile 的单元测试

License

MIT