[bug] DSH 0.2.1-rc.5：Web GUI 改模型配置必报 profile reload requires the root Include entry

[HermanChen]

1. 一句话结论

dsh web 下，在 Settings → Models 页面修改任一模型配置，请求都会被 dsh-config-editor 的持久化回调拒绝：

代码块

dsh: profile reload requires the root Include entry

重启进程后 100% 复现，与浏览器访问地址、运行时长、网络路径完全无关。根因是 ConfigEditor.edit() 内部把被编辑条目自己的 entry context（this.ownerContext.root）当作"根上下文"传给 reconcileProfilePatches()，而 bootstrapIncludes 这个 WeakMap 的 key 是应用根 Context（boot() 里 new Context() 那个），两者永远不相等。

---

2. 环境

项 | 值 -- | -- DSH 版本 | 0.2.1-rc.5（npm dist-tags: latest = next = 0.2.1-rc.5；另有 alpha = 0.2.2-alpha.2） 启动方式 | dsh web --no-open --host 127.0.0.1 --port 19387 --trusted-host 10.10.10.105:19388（systemd user service） 系统 / Node | Linux 5.4.0，Node v22.23.2 Profile | ~/.dsh/profiles/web（hoisted），bundles：dsh-base、dsh-web-app 及其余第三方 bundle 配置文件 | ~/.dsh/profiles/web/cordis.yml（空根）+ cordis.patch.yml（用户 patch 层）；无 home 级 patch，无 --patch overlay 复现相关插件 | @deepseek-ai/dsh-config-editor@0.2.1-rc.5、@deepseek-ai/dsh-settings@0.2.1-rc.5、@deepseek-ai/dsh-app-boot@0.2.1-rc.5

---

3. 复现步骤

1. systemctl --user restart dsh-web，从日志取新 URL（dsh web: http://127.0.0.1:19387/?token=...），浏览器打开。
2. 进入 Settings → Models，任意修改一个字段后保存（哪怕只是点开再保存）。
3. 立即报错：

代码块

dsh: profile reload requires the root Include entry

已验证排除的因素：

• 不是访问地址问题：loopback（127.0.0.1:19387）与经 socat 转发的 10.10.10.105:19388 → 127.0.0.1:19387 表现一致。
• 不是进程陈旧：systemctl --user status 显示启动时间为刚刚，PID 为新值（如 1764215，since Mon 2026-11-02 15:50:23 CST），ss -ltnp 确认 19387 只有这一个 node 进程，19388 只是 socat。
• 不是单次偶发：重启后每次修改都失败；此前同一部署运行约 9 天期间也是每次失败。也就是说，这条路径从未成功过，与"运行久了状态丢失"无关。

---

4. 根因分析（已逐行核对 rc.5 发布产物）

4.1 报错点

@deepseek-ai/dsh-app-boot/lib/index.js：

js

const bootstrapIncludes = /* @__PURE__ */ new WeakMap();          // L3762

async function recompose(ctx, patches, binName, options, withResolution) {
  const entry = bootstrapIncludes.get(ctx);                       // L3802
  if (entry === void 0) throw new Error(`${binName}: profile reload requires the root Include entry`);  // L3803

async function mountRootInclude(ctx, absoluteConfigPath, ...) {   // L4125
  ...
  bootstrapIncludes.set(ctx, entry);                              // L4151  ← key 是 boot() 的根 ctx
  return entry;
}

boot() 中：

js

const ctx = new Context();                 // 根
await ctx.plugin(Loader);
await prepare?.(ctx);                      // 这里 provide('profileContext') / PluginPackages
await mountRootInclude(ctx, ...);          // 只有这个 ctx 被登记进 WeakMap

所以 只有 boot 时那个应用根 Context 才能取到 entry。

4.2 触发路径

@deepseek-ai/dsh-config-editor/lib/index.js：

js

async edit(entry, change) {                                // L66
  const run = async () => {
    ...
    await reconcileProfilePatches(this.ownerContext.root, beforePatches, "dsh");   // L75  ← 嫌疑点
    ...
    await reconcileProfilePatches(this.ownerContext.root, patches, "dsh", [entry.options.id]);  // L125
    ...
  }
  const hmr = this.ownerContext.get("hmr");
  await (hmr === void 0 ? run() : hmr.runExclusive(run));
}

其中 this.ownerContext 是 ConfigEditor 构造时注入的插件条目作用域 ctx：

js

var ConfigEditor = class extends Service {
  static inject = ["loader", "profileContext"];
  constructor(ownerContext) { super(ownerContext, "configEditor"); this.ownerContext = ownerContext; }

Cordis 语义：ctx.root 是"应用根上下文（every child context shares it）"，不论调用方处于哪个插件条目作用域，ctx.root 都应解析到 boot 的根 Context。而 DSH 的 WeakMap 却以"传入的那个 Context 对象"为 key。这两者在 ConfigEditor 里对不上。

4.3 为什么 dsh-hmr 没报同样的错

@deepseek-ai/dsh-hmr/lib/index.js L1359 调用 recomposeProfile(this.ownerContext.root, ...) 却能工作——这与上面"应该恒等"的预期相矛盾，说明问题出在 ownerContext 的来源或某个 scoped context 上，而不是 ctx.root 本身：

• 若 ConfigEditor 实例是在某个 Loader 条目（internal/loader/entry）或 group 的 scoped ctx 上实例化的，ownerContext.root 会指向该 scoped context 的真实根（例如 ctx.createPlugin(...) 时传入的 this.ctx），而不是 boot 的实例根；
• 而 mountRootInclude 登记的是 boot 的实例根。

因此建议修正方向（二选一，任一即可修复）：

1. 登记所有兼容的根：mountRootInclude 除了 bootstrapIncludes.set(ctx, entry)，还应对 ctx.root、ctx[Context.isolate] 的根标签等所有等价根建立别名映射；
2. 或在 recompose()/reconcileProfilePatches() 里回退查找：当 bootstrapIncludes.get(ctx) 为空时，沿 ctx.root / ctx.root.root 链、以及 loader.entries() 中 parent.tree.ctx.fiber.entry?.id === "include" 的条目反查根 Include entry，找不到才抛错；
3. 或让 ConfigEditor 显式持有 boot 根：ConfigEditor 构造时用 ctx.root 之外的可靠来源（例如通过 profileContext 一并带过来，或新增一个 bootstrapContext 服务）保存真正的应用根。

上游 master 分支的 packages/boot/config-editor/src/index.ts L96/L143 仍是 this.ownerContext.root，packages/boot/app-boot/src/index.ts L334 仍是 bootstrapIncludes.get(ctx)，L335 仍是同一句报错 —— 该问题在 master 上尚未修复。

---

5. 影响

• Web GUI 的任何"活配置"编辑都不可用：Models 页、Settings 里所有走 configEditor.edit() / settings.write() 的字段全部失败（settings.write() → configEditor.edit()）。
• 用户被迫放弃 GUI，改为手改 cordis.patch.yml + systemctl --user restart dsh-web（本文档的环境即如此绕过）。
• 由于错误抛出发生在写入 YAML 成功之后的回滚分支里（L125 写文件 → L128 回滚），频繁触发还会反复重写 patch 文件，存在把用户手写注释/!!js 表达式写坏的风险（这点需要单独验证）。

---

6. 期望行为

点击保存后配置应原子落盘并热重载，不应抛出"requires the root Include entry"；若确实无法找到根 Include，应给出一句可操作的诊断（例如"配置编辑器所处的 context 不是应用根，请报告该条目的 ownerContext 链"），而不是让用户以为配置文件写坏了。

---

7. 临时绕过（供其他用户参考）

1. 直接编辑 ~/.dsh/profiles/web/cordis.patch.yml（注意：id 定向覆盖会替换整个 config，必须重述原字段；!!js 表达式原样保留）。
2. systemctl --user restart dsh-web，从 journalctl --user -u dsh-web 取新 token URL 打开。
3. 升级到 0.2.2-alpha.2 属于未验证路径（本次未测试）。

[ltxhhz]

运行 where.exe dsh 看看盘符是不是小写，如果是的话在环境变量里改成大写，我是这么解决的
Run where.exe dsh and check if the drive letter is lowercase. If it is, update it to uppercase in the PATH environment variable.
This is how I resolved it.

[HermanChen]

哦，我 dsh-web 运行环境是在 ubuntu 上

[ArvinDevel]

Follow-up: I've opened a dedicated proposal with concrete patch sketches for this failure class — #12076.

TL;DR of the proposal:

• Root cause fix: share bootstrapIncludes across module instances via a Symbol.for-keyed globalThis registry (~20 lines, user-patches.spec.ts:351-358 stays green)
• Error message fix: the current profile reload requires the root Include entry message misstates the fault (the root Include is registered — in another copy's registry). Proposed replacement distinguishes "registry split" (with duplicate-package self-diagnosis) from "genuinely not mounted", and prints import.meta.url of the throwing copy
• Prevention: plugin add should reject installation-shipped bundles in profile dependencies (with --force escape hatch), since that's a confirmed non-Windows trigger of the same dual-instance failure

@tianyicui @LegGasai @imccyu — the proposal is ready to be picked up directly if the team agrees with the direction.

[ArvinDevel]

补充两个从 0.2.1-rc.5（macOS Intel / dsh web）实测得到的关键信息，与楼上的分析互为印证。

一个 30 秒判别步骤：先区分「双模块实例」与「ctx 归属」

dsh: profile reload requires the root Include entry 这个文案有歧义——它可能对应两种不同的故障。判别方法：

# 临时把 profile 的 node_modules 挪走，重启 dsh web
mv ~/.dsh/profiles/web/node_modules /tmp/nm-backup
# 如果设置写入立刻恢复正常 → 是「profile 里装了重复的 @deepseek-ai 包」导致的双模块实例
# 如果仍然报同样的错 → 才是 ctx 归属 / 配置损坏方向的问题

我用运行时插桩（在 mountRootInclude 和 recompose 各加一行日志）拿到了直接证据：

[installation 那份 app-boot] mountRootInclude: ctxId=ctx#1   ← 注册进副本 A 的 WeakMap
[profile 那份 app-boot]      recompose MISS                  ← 去副本 B 的 WeakMap 里找 → 落空

bootstrapIncludes 是模块级 WeakMap，两份 dsh-app-boot 实体各持一张表——root Include 其实注册得好好的，只是在另一张表里。移走重复包后 settings/mutate 立即恢复，revision 0→1 正常递增、过期 revision 被 settings/conflict 正确拒绝，说明 read-back 校验和乐观锁都不是本案成因。

错误文案本身在误导排查方向

profile reload requires the root Include entry 把「模块实例不一致」说成了「缺少 root Include」。我最初（以及可能包括本帖的初步分析）都被它带向"配置损坏/Include 缺失"方向排查了很久。建议上游至少：

1. 在报错里带上抛错模块的 import.meta.url；
2. 失败时顺带探测 profile node_modules/@deepseek-ai 是否存在重复实体并写入错误信息。

完整修复提案

我把根因分析、插桩证据和三组可直接采纳的代码方案整理成了独立提案：#12076（Symbol.for 全局注册表根治 / 文案修正+自诊断 / plugin add 拦截 installation 自带 bundle）。@tianyicui @LegGasai @imccyu

（环境：@deepseek-ai/dsh 0.2.1-rc.5 npm 安装，macOS 14 Intel，Node v25.3.0，dsh web，profile ~/.dsh/profiles/web。触发原因是我手动把 installation 自带的 dsh-base/dsh-web-app 用 pnpm add 装进了 profile 的 dependencies——属用户误用，但工具链既不拦截也不警告，详见 #12076 的 Fix 3。）

[HermanChen]

确认 #12076 的诊断，已在我们环境完整复现并修复成功（Linux, systemd user service, dsh web 0.2.1-rc.5, Node 22, pnpm 12）。

环境特征：profile（~/.dsh/profiles/web，hoisted layout）的 dependencies 里手工 pin 了 @deepseek-ai/dsh-base、dsh-web-app、dsh-http-proxy —— 源自"升级全局包后同步 profile pins + pnpm install"的维护习惯，即你列的触发条件 2（但不是 Windows，路径大小写无关）。进程内同时存在两份 dsh-app-boot 真实目录：

安装副本：~/.npm-global/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-app-boot（mountRootInclude 注册）
profile 副本：~/.dsh/profiles/web/node_modules/@deepseek-ai/dsh-app-boot（recompose 查找 → miss → settings/rejected）

复现 100%：重启后 1 分钟内、改任何配置都报 dsh: profile reload requires the root Include entry。已排除访问地址（loopback 与经 socat 转发一致）、进程时长、配置内容、第二实例进程（ss 确认无）。

修复步骤（成功）：

从 profile dependencies 删除上述三个 @deepseek-ai 包（保留 cordis、dsh-mnemon 等真第三方包），pnpm install（+3 −486）；
关键补充步：pnpm 并未清掉 hoisted 遗留 —— node_modules/@deepseek-ai/ 下仍残留 dsh-app-boot、dsh-config-editor 两个真实目录（非 symlink，时间戳还是安装日），把它们 mv 走后才根除；
restart 后 GUI 保存即恢复正常，已连续验证多次。

两点补充供参考：

Fix 2 的自诊断探测建议把"hoisted 残留真实目录（非 symlink）"也纳入重复副本检测特征：仅删 dependencies + pnpm install 不一定清干净残留目录，我们就因此在第一轮清理后仍复现，直到检查 node_modules 才发现。
排查时撞到一个无关但容易混淆的拦截：whale 生态插件按浏览器 Host 头拒绝非回环写请求（经 socat/反代转发时即使来源 IP 是 loopback 也会被拒），症状容易被误认为同一个 bug；远程管理需 ssh -L 使地址栏为 127.0.0.1:19387，或声明 DSHW_ADMIN_HOSTS。

@ArvinDevel 确认问题解决，非常感谢！