【Bug】[Windows] 设置改动被静默回退 —— 启动路径的盘符大小写把 dsh-app-boot 加载成了两个模块实例

[KnifeOfLife]

[Windows] 设置改动被静默回退 —— 启动路径的盘符大小写把 dsh-app-boot 加载成了两个模块实例

概要

在 Windows 上，如果打包 CLI 的启动路径盘符为小写（例如 PATH 项 d:\Users\<user>\Application Data\npm，由 npm 生成的 dsh.ps1 启动 dsh web），设置面板里的任何改动都会被 Host 拒绝并静默回退：选项立刻弹回原值，~/.dsh/profiles/<profile>/cordis.patch.yml 永远不会被改写。

原因是 @deepseek-ai/dsh-app-boot 这个包在同一个进程里被加载成了两个模块实例：启动器自身的模块图沿用启动时的拼写（小写盘符），而运行时解析拦截（installRuntimeInterception）交给每个插件的路径都经过 realpath 规范化（Windows 上返回大写盘符）。ESM 按解析后的 URL 字符串缓存模块，因此同一个文件的两个拼写互不相等。根 Include 条目记录在模块级 WeakMap bootstrapIncludes 里，插件侧那个实例查不到，于是 reconcileProfilePatches() 抛出 dsh: profile reload requires the root Include entry；Host 拒绝写入，浏览器把这次拒绝当成可恢复的「重读一次」，于是回退到已存的值。

同一份 profile 用源码方式启动（node --import tsx/esm apps/cli/src/bin.ts web）完全正常，因为那时所有模块 URL 拼写一致 —— 这正是它只在打包安装形态出现的原因。

环境

dsh	0.1.7-rc.1，npm 全局安装（npm i -g @deepseek-ai/dsh）
启动方式	dsh web（经由 npm 生成的 dsh.ps1 / dsh.cmd shim）
系统	Windows 11
Node	v24.19.0（D:\nodejs\node.exe；shim 旁边没有 node.exe，因此回落到 PATH 里的 node）
全局 bin 的 PATH 项	d:\Users\<user>\Application Data\npm —— 注意盘符是小写 d:
Profile	默认 web；$DSH_HOME 未改动
正常的情况	同一份 profile 从源码启动：node --import tsx/esm apps/cli/src/bin.ts web

当前源码树里就是同一段实现，所以这不是旧构建产物，相关位置为：packages/boot/app-boot/src/index.ts 的 :255（bootstrapIncludes 声明）、:274（读取）、:275（抛错）、:581（写入）、:929（audit 使用），以及 packages/boot/app-boot/src/profile.ts:406（createRuntimeResolution）、packages/boot/app-boot/src/profile-resolution/legacy-links.ts:18（realModuleDirectory，即那次 realpath）、packages/boot/app-boot/src/profile-resolution/resolver.ts:698（installRuntimeInterception）。

复现步骤

1. 让打包 CLI 自身从小写盘符的路径启动（PATH 项写成 d:\...\npm，再执行 dsh web）。
2. 打开 设置 → 通用 → 工作步骤展示，选择另一个模式。
3. 选择器立刻弹回此前已存的模式；cordis.patch.yml 的修改时间不变。

证据

• 界面表现：不做任何提示，选项自己弹回；工作步骤展示、主题、语言、模型页、插件启用/禁用都一样，说明不是某个设置项的问题。
• 与浏览器无关的复现：直接调用 Host 自己的 settings RPC（与浏览器同一信封）时，describe 返回的存储层 user 已是新值（说明补丁文件被读到了），而运行时 value 仍是旧值；mutate 返回 settings/rejected，message 正是 dsh: profile reload requires the root Include entry。二者长期不一致，说明失败发生在「把补丁应用进 Loader」这一步，而不是读取或校验。
• 文件层与运行时层的分离：手工把补丁文件改成目标值后，describe 的 user 立刻反映新值，但运行时 value 不变，直到重启进程才生效 —— 印证了重载链路正是坏掉的那一环。
• 判定为模块实例分裂的方法（无需起服务、无需 profile）：把同一个 dsh-app-boot/lib/index.js 分别以大写盘符与小写盘符两种 URL 导入，得到两个互不相等的模块实例，导出的 reconcileProfilePatches 也不是同一个函数；用一个实例 boot 出最小 include 树、再用另一个实例对该 ctx 调用 reconcileProfilePatches，即可复现同一句报错，而用 boot 的那一侧调用同一函数则成功返回。这与运行中的 Host 报出的错误完全一致。

预期

选择被持久化：补丁文件被改写，运行时条目同步更新，界面保持所选模式。

实际

• 写入被拒绝：settings/rejected: dsh: profile reload requires the root Include entry。
• 浏览器重新读取已存的值并回退，改动静默复原，界面不报错。
• 补丁文件不被改写（mtime 不变）。
• 使用同一批调用点的另外两条链路同样失效：profile 补丁热重载与插件启用/禁用，见 packages/boot/config-editor/src/index.ts:84,132,135、packages/boot/hmr/src/index.ts:230、packages/boot/plugin-manager/src/index.ts:764。

根因

1. mountRootInclude() 把「根 Include 条目」通过模块级状态（bootstrapIncludes，一个模块级 WeakMap）交给进程内其它消费者，因此这次交接只在运行它的那个模块实例内可见。
2. 运行时解析表用 realpath 规范化了每个包目录（realModuleDirectory()），并且 installRuntimeInterception() 让每一次插件导入都从这些规范化路径解析。
3. Windows 上 realpath 返回的盘符是大写；而启动器自身的模块 URL 保留进程启动时的拼写 —— npm 生成的 shim 执行 node "$basedir/node_modules/@deepseek-ai/dsh/lib/bin.js"，其中 $basedir 直接来自 PATH 项。
4. ESM 按解析后的 URL 字符串做模块缓存，于是 file:///d:/…/dsh-app-boot/lib/index.js 与 file:///D:/…/dsh-app-boot/lib/index.js 是同一个文件的两个模块实例。启动器把 Include 记在小写实例的 bootstrapIncludes 里；而 dsh-config-editor、dsh-hmr、dsh-plugin-manager 经拦截（大写）导入，从大写实例调用 reconcileProfilePatches(ctx.root, …)，那张表是空的，于是命中 packages/boot/app-boot/src/index.ts:274-275 的抛错。
5. 任何拼写差异都会造成同类分裂，尤其是 junction/软链路径与其真实路径 —— 本仓库自己就会为 profile link farm 建立这类链接，同样的方式也已实测到实例不等；盘符大小写只是普通 Windows 安装最容易撞上的那一种。
6. 影响只限于「跨实例的模块级状态」，所以其它功能看起来完全正常：两套实例加载的是同样的文件、并通过 Cordis context 交互，被劈开的只有模块级注册表。

影响

• 所有设置写入被拒绝并静默回退，且不给用户任何错误提示，因此极难自诊断。
• profile 补丁热重载与插件启用/禁用以同样方式失败。
• 触发条件很常见（Windows + npm 全局安装 + PATH 项盘符小写），而源码/开发运行拼写一致、永远复现不了，所以日常开发和 CI 都抓不到，只在打包安装形态暴露。

建议修法

把这次交接移出模块作用域，使其不再依赖模块身份：在 boot 时把根 Include 条目挂到 boot context 上（或挂到已经共享的 profileContext 服务上）携带，reconcileProfilePatches() 与 auditStartupEntries() 先读它、再回落到现有 WeakMap。这样无论进程里存在几个 dsh-app-boot 实例，交接都可见。同一文件 :607 的 assembledActivationRejections 是同类跨实例模块状态（fail-loud 审计使用），建议在同一轮一并迁移。

可选加固（二者择一即可）：构建解析表时沿用安装 anchor 的盘符拼写，而不是 realpath 的结果，使整个进程只保留一种拼写；或在拦截层 / Loader.import 导入前统一拼写规范化。

用户侧绕过

• 用大写盘符的完整路径直接启动 lib/bin.js（绕开 shim 的拼写），例如 node "D:\Users\<user>\AppData\Roaming\npm\node_modules\@deepseek-ai\dsh\lib\bin.js" web。
• 或把 PATH 项的大小写改对：d:\...\npm → D:\...\npm，让 shim 传出大写路径。
• 也可以直接编辑 ~/.dsh/profiles/<profile>/cordis.patch.yml 并重启，让某个偏好生效。

补充背景

这台机器上症状曾分成两段：写入先是卡在约 2 秒的锁超时（一次被中断的插件操作留下的孤儿 package.json.lock，与本问题无关）；清掉锁之后，失败立即变成上面描述的即时 settings/rejected。也就是说模块分裂从头到尾都在，只是先前被那把锁挡在前面。

[PerryLink]

你的机制分析我逐条核过了，成立——而且"只有打包形态出现"这一点正是它的指纹

1. bootstrapIncludes 确实是模块级的 WeakMap

packages/boot/app-boot/src/index.ts：

const bootstrapIncludes = new WeakMap<Context, Entry>()                       // :255
...
const entry = bootstrapIncludes.get(ctx)                                      // :274
if (entry === undefined) throw new Error(`${binName}: profile reload requires the root Include entry`)   // :275
...
bootstrapIncludes.set(ctx, entry)                                             // :581

键是 Context、值是根 Include 的 Entry，而它是模块作用域的——不挂在 ctx 上，也不在全局注册表里。所以你说的那句话在代码层面完全成立：同一个文件被解析成两个模块实例时，插件侧那个实例拿到的是它自己那份空的 WeakMap，get(ctx) 必然是 undefined，于是抛出你看到的那句。

（顺带一条旁证：这条错误在测试里被钉着——tests/user-patches.spec.ts 断言 reconcileProfilePatches(ctx, [], NAME) 会抛 profile reload requires the root Include entry。也就是说"没有根 Include 就抛"是被预期的行为，只不过他们预期的是"真的没有"，而你遇到的是"确实有、但在另一个实例里"。）

2. 拦截层确实做 realpath 规范化

packages/boot/app-boot/src/profile-resolution/resolver.ts（这个文件在你本地是 dirty 的，我是用 git show HEAD: 读的提交内容）：

import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs'   // :3
...
return realpathSync(path)                                                    // :155

installRuntimeInterception 就在同一个文件（:698），由 config-schema/collect.ts:88 和 profile-resolution/service.ts:68 安装。所以"交给插件的路径经过 realpath、而启动器自己的模块图沿用启动时的拼写"这半边也和你说的一致。

Windows 上 realpath 会把盘符规范成大写——这正是两个拼写不相等的来源，而 ESM 按解析后的 URL 字符串缓存模块。

证据边界我要说清楚：我这边无法在 Windows 上实测"两个实例"，所以这一条是代码层面的确证 + 你的推理结论。但每一环都对得上，而且**"只有打包安装出现、源码启动正常"这个现象本身就是两个模块实例的指纹**——单实例不可能有这种差异。

3. 一个相邻的差异，可能是同类问题的另一处

profile-resolution/legacy-links.ts:19：

return isPackagedExecutable() ? realpathSync(path) : realpathSync.native(path)

打包形态用 realpathSync，非打包形态用 realpathSync.native——这两者在 Windows 上对大小写/短名的处理并不相同。我不确定它是否参与你这个 bug，但它说明"打包 vs 源码"在这条路径上确实有分叉，值得你顺带看一眼。

4. 我最想请你补的两条

1. 一次实测确认拼写假说：把 PATH 里那一项从 d:\... 改成 D:\...（或用绝对路径 node <...>\dsh ... 启动），如果设置改动立刻不再回退，那就等于实测确认了"拼写不同 ⇒ 两个实例"。这比任何推理都有力。
2. 两种启动方式（打包 vs node --import tsx/esm apps/cli/bin ...）各自的 stderr，一个抛一个不抛的对照。

5. 该修在哪（我认为你指的方向是对的）

最小修法是在边界处只规范化一次：启动器进入 app-boot 时就把自己那条路径规范化；或者让 bootstrapIncludes 不依赖模块实例身份——比如挂到 ctx 上，或用 Symbol.for(...) 之类进程级注册。把状态放在模块作用域上，本来就会在"同一模块被解析成两个 URL"时失效，而 Windows 的盘符大小写恰好能造出两个 URL。这条我认为可以直接作为修复建议写进报告。

[SAXEM1997]

同一根因的另一个触发路径 —— 这次在 Linux 上，与盘符大小写无关。

环境：Docker 里跑 dsh。CLI 树在 /npm-global/...（全局 npm 包），profile 树在 /dsh-home/profiles/web/node_modules（pnpm，nodeLinker: hoisted）。两边各有一份 @deepseek-ai/dsh-app-boot 的实体目录 —— 不是软链，inode 不同，但内容字节完全相同，所以按 md5 或版本比对会误判成「同一份」，这点挺坑的。

症状与楼主一致：设置改动不落盘，而线索只有一条启动告警：

dsh-mnemon: could not recover retained legacy settings
  Error: dsh: profile reload requires the root Include entry
    at reconcileProfilePatches (.../dsh-app-boot/lib/index.js:3469:30)

根因链（dsh-app-boot/lib/index.js）：3458 建了一个模块私有 WeakMap（bootstrapIncludes），写入方只有 mountRootInclude()（3716: bootstrapIncludes.set(ctx, entry)），读取方是 reconcileProfilePatches()（3468: const entry = bootstrapIncludes.get(ctx); → 3469: if (entry === void 0) throw ...）。两份副本各持一个 WeakMap：写入落在 A，读取发生在 B，读到的永远是 undefined。

影响面比「设置不落盘」大得多 —— reconcileProfilePatches 有 4 个调用方，全都会中招：

调用方	场景
dsh-config-editor/lib/index.js:69	每一次设置写入
dsh-plugin-manager/lib/index.js:2033	插件安装 / 卸载后的 reconcile
dsh-plugin-manager/lib/types/index.js:812	同上
dsh-hmr/lib/index.js:370	热重载

本地的绕法（仅供参考，不是建议上游这么做）：启动时若 profile 那份是实体目录、且与 CLI 副本版本相同，就把它挪走、换成指向 CLI 副本的符号链接。两处 realpath 收敛到同一个 URL，Node 按 URL 缓存模块，于是只剩一个实例。实测之后配置文件立刻恢复可写（能观察到 mtime 在写入时跳动），reconcileProfilePatches 不再抛。

建议的上游修法：bootstrapIncludes 不该用模块私有 WeakMap。挂到 ctx 上，或用 Symbol.for("@deepseek-ai/dsh-app-boot.bootstrapIncludes") 做进程级注册表 —— 这样多实例天然共享状态，跟路径怎么写、大小写如何、有没有软链都无关。

[SAXEM1997]

更正上面这条评论的两处 —— 我复核源码后发现自己写错了：

① 读取方不止 reconcileProfilePatches()。 还有一处：auditStartupEntries() 在 4010 行读同一个 WeakMap，那里一个未激活的 bootstrap Include 是致命的。准确说法：读取方是 reconcileProfilePatches()（3468 读 / 3469 抛）和 auditStartupEntries()（4010 读）。

② 调用方不是 4 个，是 6 处调用 / 4 个模块。 我漏了 dsh-config-editor 里的两处：

#	位置
1	dsh-config-editor/lib/index.js:69
2	dsh-config-editor/lib/index.js:119 ← 漏
3	dsh-config-editor/lib/index.js:122 ← 漏（写失败回滚时的那次 reconcile）
4	dsh-plugin-manager/lib/index.js:2033
5	dsh-plugin-manager/lib/types/index.js:812
6	dsh-hmr/lib/index.js:370

（dsh-plugin-manager/lib/types/index.js 被 exports 映射挡在外面、很可能不会被加载，但它是随包发布的真实文件。）

其余部分（3458 声明、3716 唯一写入、两份副本字节相同、错误串、符号链接使实例归一）复核无误。

[PerryLink]

你的自我更正是对的——读取方确实有两处，而且第二处是致命的

1. 按当前源码给你对齐（行号与你看到的构建产物不同）

packages/boot/app-boot/src/index.ts：

const bootstrapIncludes = new WeakMap<Context, Entry>()      // :255  模块级
const entry = bootstrapIncludes.get(ctx)                     // :274  ← 读取方 ①
if (entry === undefined) throw new Error(`${binName}: profile reload requires the root Include entry`)   // :275
...
bootstrapIncludes.set(ctx, entry)                            // :581  写入方
...
const required = new Set(failures.filter(({ entry }) => entry === bootstrapIncludes.get(ctx)   // :929  ← 读取方 ②
  || requiredStartupEntryIds.has(entry.options.id)).map(({ entry }) => entry))
if (required.size > 0) throw new StartupError(...)           // :932  致命

⇒ 你说的"不止 reconcileProfilePatches() 一处"成立。你引的 3468/3469 与 4010 应当是构建产物里的行号；对应到源码就是上面的 :274/:275（reconcile）与 :929（auditStartupEntries）。建议在报告里同时给出符号名（bootstrapIncludes、reconcileProfilePatches、auditStartupEntries），这样行号漂移也不会让结论失效。

2. 这个更正其实加强了你的报告（建议加一句）

两处读取方意味着同一根因可以呈现两种完全不同的症状：

• 读取方 ① 抛出的错误若被上层吞掉/降级 ⇒ 表现为设置静默回退（原帖的症状）；
• 读取方 ② 把"bootstrap Include 未激活"算进 required ⇒ 启动直接致命。

也就是说：同一份坏布局，有的人看到"改了没反应"，有的人看到"起不来"。这句话能解释为什么这个 bug 在不同人那里表现不一致——建议写进"影响面"。

3. 你的 Docker 触发路径很有价值，尤其"md5 相同"这一点

CLI 树在 /npm-global/...（全局 npm）、profile 树在 /dsh-home/profiles/web/node_modules（pnpm hoisted）⇒ 两份实体目录、inode 不同、内容字节相同。你指出"按 md5 或版本比对会误判成同一份"——这正是这个 bug 的险恶之处，也把修法指向了正确方向：

模块身份不能靠"路径拼写"或"内容相等"来判断，必须在边界处规范化一次（或用进程级注册表承载这类状态，而不是模块作用域的 WeakMap）。

你这条比原帖的"盘符大小写"更一般：盘符大小写只是产生"两个 URL"的一种方式，双份实体目录是另一种。两条并在一起，报告的分量完全不同。

4. 建议你补一句可判别的观测

请说明你在 Docker 那台上看到的是静默回退还是启动致命（上面两种症状之一）。这一条能把"两处读取方"的推论从代码层推进到现场证据，也方便维护者确认哪条路径先被触发。