已安装 bundle 的「原地换代」缺少官方入口：连卸载后再挂载都拿不到新模块（附实测）

[HorusJiang]

[Feature] 已安装 bundle 的"原地换代"缺少官方入口：连"卸载后再挂载"都拿不到新模块

复测环境：DSH 0.1.6-alpha.2 / Windows 11 / Node v24
类型：feature request（两处判定都是刻意的）+ 一份实测证据
同源症状的第三方管理面报障见 dsh-market/dsh-market#685

TL;DR (English)

Nothing in a running host can make a replaced node_modules package take effect.
Install is live (the entry URL was never imported before); updates are not, and
neither is any workaround: I measured that a full unmount → remount of the row
goes through DSH's own reconcileProfilePatches, really disposes the old fiber and
really creates a new one — and the new fiber still evaluates the cached module
generation, because Node's ESM registry is keyed by URL and only
boot/hmr.partialReload() purges it (via --expose-internals) — and that path is
blocked for every npm-installed package by two url.includes('/node_modules/')
exclusions. Please expose that capability (or state the boundary as a documented
product rule).

现状

动作	当前行为	依据
全新安装一个 bundle	✅ 运行中生效	packages/boot/plugin-manager/src/index.ts:566（hmr 存在 → applied）
更新已安装的 bundle	❌ restart-required	同文件 :391：if (Object.hasOwn(before, name)) return 'restart-required'

两处都很保守，而且没有给插件作者留任何字段：plugin_manager 只读
dsh.bundle.patch；dsh.compatibility.dshReleases 在整个 DSH 源码里没有任何消费者
（按 compatibility?: / dshReleases 全仓 grep 零命中）。

同一个边界被第三方管理面独立复现了一遍：社区市场 dshmarket 自带
install.ts / hot.ts / verify.ts 管线，并用自己的
src/verify.ts:316 activationAfterReplace() 得出同样的"更新要重启"。
（它甚至因此报出错误的 verdict，见 docs/issue-hot-update-market.md：
restart:false / hot:true 而进程跑的是旧模块。）

实测：卸载-重挂载也拿不到新代际

方法（探针，事后已逐字节还原）：

1. 在 profile 副本的入口模块 node_modules/dsh-map-tools/lib/index.js 顶部插入一段
   模块作用域的副作用：向临时日志追加一行（不依赖任何 HTTP 路由注册）。
2. 阳性对照：新进程 await import('file:///.../lib/index.js') → 日志出现 1 行。
   仪器有效：真 import 了就一定会写。
3. 触发一次真正的卸载 → 重挂载：走 DSH 自己的配置层（profile 的
   cordis.patch.yml 给该行写 disabled: true 再移除），即
   reconcileProfilePatches() 那条路。

#	观测点	结果	含义
1	探针写入后、任何操作前	日志不存在	原地替换文件不会重新 import
2	off 期间 GET /dsh-map-tools/config	HTTP 404	旧 fiber 真被销毁（路由 disposer 跑了）
3	on 之后同一路由	HTTP 200	新 fiber 真被创建并重新注册了路由
4	处理组探针日志	仍不存在	新 fiber 求值的是缓存里的旧模块

#2 排除了"其实没卸载"，#3 排除了"旧处理器残留"（若旧 fiber 还在，
重复注册同一路径会抛错并被 ctx.inject 子作用域吞掉，路由会停在上个版本），
#4 说明换出来的是同一个模块命名空间。

根因：URL 级缓存，只有一处能清

Node 的 ESM registry 按 URL 缓存模块命名空间：同一 URL 一旦被求值过，
后续任何 import() 都拿回旧的那一份——DSH Loader 重新挂载、市场的
Include 热挂载、关掉再打开，全都一样。而 boot/hmr 明确处理了这一点：

// packages/boot/hmr/src/index.ts:474-513（partialReload）
for (const filename of this.accepted) {
  const job = Map.prototype.get.call(this.internal.loadCache, filename)
  esmBackup.set(filename, job)
  Map.prototype.delete.call(this.internal.loadCache, filename)   // ← 清 Node 内部 loadCache
}
const replacement = this.ctx.loader.unwrapExports(
  await this.ctx.loader.import(generation.filename, this.getOuterStack))  // ← 原地重导同一 URL

拦住它的只有两处硬编码排除（各一处）：

// packages/boot/hmr/src/index.ts:70
if (job.url.startsWith('node:') || job.url.includes('/node_modules/')) return

// packages/boot/hmr/src/index.ts:357
const isExcluded = (url: string) => url.startsWith('node:') || url.includes('/node_modules/')

于是 partialReload() 的 if (!dependencies.some(dep => this.accepted.has(dep))) continue
对 node_modules 下的包恒成立 → 静默跳过（不报错、不告警）。
而 npm 装出来的包必然在 node_modules 下：root 怎么配都绕不过去。

这一条同时解释了四件事，也说明这不是"保守"而是能力缺口：

场景	结果	原因
全新安装	✅ 免重启	该 URL 本进程从未 import 过
更新已安装的包	❌ 必须重启	URL 已在 registry 里
关掉再打开	❌ 无效（本次实测）	URL 仍在 registry 里
开发期 junction + hmr.root	✅ 有效	realpath 不含 node_modules，且 hmr 会清 loadCache

建议（任选，按上游成本排序）

1. 给一个官方入口：把 Hmr 已有的"清 loadCache + 原地重导入"能力暴露成公开 API
   （例如 hmr.replaceModule(url)），让 plugin_manager、dshmarket 这类热挂载消费者
   在更新后调用它，配合各自 fiber 的卸载/重挂载完成代际替换。
2. 放宽排除规则：对被 profile 显式声明 / 被显式挂载的包，允许其 realpath
   或"profile 声明的包名"参与重载判定，而不是按 URL 子串一刀切。
3. 让插件自己声明：在 package.json 的 dsh 段加可选字段
   （如 dsh.reload: 'module-generation'），声明该包支持原地换代；
   宿主与市场据此放行，未声明的包保持现状。
4. 最小改动：若短期不做能力，请把这条写成文档里的产品规则——
   "更新已安装的 bundle 需要重启 Host；浏览器半边除外"——
   好让插件作者能对用户如实说明，而不是各自去猜、各自去造（并各自造错）。

已排除的替代方案

• dsh.compatibility.dshReleases：无消费者，无法用来声明"本包可热替换"。
• "卸载 + 重新挂载"：本次已实测无效（上表 #4）。
• 市场侧自己做：dshmarket 试过了，结果是 restart:false 的假 verdict。
• 插件侧"薄壳 + cache-busted 动态 import"：技术上可行
  （import('./impl/x.js?rev=<mtime>') 是新的 ESM 代际，不碰内部 API），
  但它只能救作者自己的包，且宿主/市场仍会显示"需要重启"——提示与事实不符，
  反而更糟。这应当是上游能力，而不是每个作者的重复劳动。