dsh-bundle-dedup-guard

English | 简体中文

  ![node]() 

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: <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 把这些红线变成自动的站点级体检，见下文 [站点级体检](#站点级体检v020-新增)。

完整事故记录：[docs/KNOWN-ISSUE-bundle-duplicate.md](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 插入的）与修复指引。

每次装载插件都检查

报告内容

• 重复 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/<profile>-<时间戳>.json 与 <profile>.latest.json。

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

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

每个问题都附可直接复制的修复命令（重建 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 加： ``json "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 <path-to-package.json>

# 机器可读 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 <name> 直到绿灯，再重启。

开发

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