settings.yaml 一次性迁移在启动竞态下全数失败且永不重试：4 个配置段静默丢失（0.1.7-rc.1，rc.2 仍在，附根因与修复建议）

[sheldonslin]

settings.yaml 一次性迁移在启动竞态下全数失败且永不重试：4 个配置段静默丢失（0.1.7-rc.1 实测，rc.2 仍在；附根因与修复建议）

English TL;DR: SettingsForms.importLegacyDocument() renames settings.yaml to .imported before the first write. When the loader context is still inactive at that moment (startup race: port conflict + HMR reload), write() throws cannot get required service "configEditor" in inactive context, all sections fail, and because the file is already renamed the import never retries — the user's entire legacy settings (providers/models/theme) vanish from the UI with only a logger.warn as evidence. Reproduced on 0.1.7-rc.1; verified the same code path remains in 0.1.7-rc.2. Suggested fix: rename only after successful import (or retry on next boot) + surface a UI error.

1. 基本信息

项目	内容
问题名称	settings.yaml 一次性迁移失败后永不重试，配置全量静默丢失
发生版本	0.1.7-rc.1（2026-09-24）
复核版本	0.1.7-rc.2（@deepseek-ai/dsh-settings/lib/index.js 的 importLegacyDocument 与 rc.1 逐字相同）
影响范围	所有从旧版 settings.yaml 升级到 profile 配置体系的用户
环境	macOS 15，Node 25.9.0，npm 全局安装
分析材料	启动日志（含完整错误栈）、被改名的 settings.yaml.imported 原件、两版源码对比

2. 结论摘要

importLegacyDocument() 把 settings.yaml 改名为 .imported 之后才开始逐段写入 profile；而写入依赖的 configEditor 服务在「端口占用 + HMR reload」的启动竞态下处于 inactive 状态，于是每一个配置段都抛 cannot get required service "configEditor" in inactive context。由于文件已被改名，导入逻辑永远不会重试——实测 4 个配置段（含全部 LLM provider 与模型选择）全部丢失，设置界面一片空白，用户唯一的线索是日志里 4 条 warn。这不是「部分失败」而是原子性倒置：迁移的提交点（改名）发生在所有写入之前。

3. 关键时间线

时间（UTC）	事件	证据
02:44:10.011	宿主启动（该次启动撞上端口占用 + HMR reload 竞态）	启动日志文件名 startup-2026-09-24T02-44-10.011Z-….log
02:44:09.991	importLegacyDocument 将 settings.yaml 改名为 settings.yaml.imported	失败日志中所有 warn 均指向 ~/.dsh/settings.yaml.imported
同一毫秒 ×4	4 个配置段逐一写入失败，全部报同一错误（见 §10）	4 条 settings: section %s … was not imported + 4 条错误栈
之后任意时刻	用户打开设置：模型/provider 全部消失；重启不重试（文件已是 .imported）	改名先于写入，见 §6 根因

4. 问题清单

级别	问题	定性
P0	迁移提交点（rename）先于任何写入 → 失败即永久放弃，无重试	主因
P0	失败仅 logger.warn，设置界面无任何提示 → 用户只看到"配置没了"	放大因素
P1	configEditor 服务在 loader 尚未 active 时被调用，竞态窗口内必然抛错	触发条件
P1	settings.yaml.imported 残留但无任何机制消费它（既不重试也不提示可恢复）	体验问题
P2	单段失败（catch 后继续）与全段失败（同一批 warn）在日志里长得一样，难以区分严重程度	可观测性

5. 预期与实际

项目	预期	实际	判断
迁移原子性	全部段写入成功才改名（或失败可重试）	改名在首次写入前	错误
失败恢复	重启后自动重试，或提示用户	永不重试，.imported 无人消费	缺失
用户感知	迁移失败应有显式报错	仅日志 warn，UI 无感知	缺失
部分失败处置	段级失败应保留原文并可续传	原文保留在 .imported（✅ 这点是对的）但无法续传	半成品
错误信息	应指明"迁移未完成、如何恢复"	cannot get required service "configEditor" in inactive context（对用户无指导性）	不合格

6. 根因分析

已确认事实（源码 + 日志双向验证）：

1. importLegacyDocument() 的顺序是 rename(settings.yaml → settings.yaml.imported) → for 每段 update()。JSDoc 自述："The document is renamed before the first write, so a partial import never repeats"——防重复的代价是失败后永不重试。
2. update() → write() 需要 configEditor 服务；该服务在 loader context 未 active 时抛 cannot get required service "configEditor" in inactive context（栈：write:502 ← update:472 ← importLegacyDocument:356）。
3. 实测该次启动 4 段全败（ui-onboarding、ui-theme、llm-pi-ai、agent-default-model），错误完全相同 → 不是某段数据问题，是写入通道整体不可用。
4. for 循环把每段错误 catch 后仅 logger.warn，函数正常返回，imported 文件保留——但没有任何代码路径会再次读取它。

高概率根因：importLegacyDocument 挂在 ctx.root.loader.await().then(…) 上，但本次启动叠加了端口占用 + HMR reload，loader 的 settle 信号到来时 configEditor 所在 context 已进入/仍处于 inactive（详见 dsh-settings/lib/index.js:339 的调用点）。「await settle」不等于「服务可用」。

待研发确认：

• configEditor 的 active 判据是什么？HMR reload 后是「短暂 inactive」还是「直到下次事件循环」？（决定修复用重试还是用等待）
• 此竞态是否只在端口冲突场景出现？（我这次的触发链是「端口被占用 → 重启 → HMR reload 叠加」；纯冷启动是否也存在窗口）

7. 研发排查建议

1. 在 importLegacyDocument 入口与 write() 处各加一行状态日志（ctx.fiber.state、configEditor 可用性），用端口占用复现一次即可确认竞态窗口宽度；
2. 确认 loader.await() resolve 时各服务的 active 时序（是否有 ctx.lifecycle/activated 钩子可用）；
3. 全库搜 .imported 的消费方——预期是 0 处（我这边已确认 rc.1/rc.2 均无）；
4. 检查是否有其他用户报过"升级后设置里的模型消失"（症状高度特异，应易检索）。

8. 修复建议（按优先级）

1. 调换提交点：所有段写入成功后才 rename；或改为「成功一段、从 .imported 删一段」的进度式迁移（部分失败可续传，天然幂等）。
2. 失败可恢复：写入通道不可用（inactive context）时不改名、直接 return，下轮启动自然重试；若必须先改名防重复，则失败时改回原名。
3. 显式报错：迁移失败时在设置页顶部出横幅「settings 迁移失败（4/4 段），已保留 settings.yaml.imported，重启将自动重试」——比 4 条 warn 有用得多。
4. 错误信息分层：段级失败（数据问题）与通道级失败（环境问题）应打不同日志级别/文案，后者应升级为 error。

9. 验收标准

• 可复现：在 importLegacyDocument 执行前人为置 configEditor 不可用（或按 §6 竞态复现），断言：settings.yaml 仍在原处（或 .imported 被还原），且下一轮启动导入成功；
• 可观察：失败时设置页有可见横幅，日志含「未完成、保留位置、重试方式」三要素；
• 可判定：4 段全部成功导入后 settings.yaml/settings.yaml.imported 均不存在；中途任意失败后二者至少存在一个且内容不丢。

10. 原始证据附录

A. 事发日志（~/.dsh/logs/startup-2026-09-24T02-44-10.011Z-….log，4 段同构，节选 2 段；路径已脱敏）：

{ ts: 1790217849991, name: 'settings-forms', type: 'warn',
  args: [ 'settings: section %s of %s was not imported into entry %s',
          'ui-onboarding', '~/.dsh/settings.yaml.imported', 'ui-settings-general' ] }
{ ts: 1790217849991, name: 'settings-forms', type: 'warn',
  args: [ Error: cannot get required service "configEditor" in inactive context
            at SettingsForms.write (…/dsh-settings/lib/index.js:502:35)
            at SettingsForms.update (…/dsh-settings/lib/index.js:472:14)
            at SettingsForms.importLegacyDocument (…/dsh-settings/lib/index.js:356:16) ] }
{ ts: 1790217849991, name: 'settings-forms', type: 'warn',
  args: [ 'settings: section %s of %s was not imported into entry %s',
          'ui-theme', '~/.dsh/settings.yaml.imported', 'ui-theme' ] }
… llm-pi-ai → llm-pi-ai、agent-default-model → agent-default-model 两条同构 …

B. 被改名的原件结构（settings.yaml.imported，字段值略去——含 provider 配置，仅供内部排查）：

ui-onboarding: …
ui-theme: …
llm-pi-ai: …        # 全部 LLM provider/模型定义在此
agent-default-model: …

C. 源码对照（0.1.7-rc.1 与 0.1.7-rc.2 的 dsh-settings/lib/index.js 该函数逐字相同）：

async importLegacyDocument() {
    const path = join(profile.home, "settings.yaml");
    if (!existsSync(path)) return;
    const imported = `${path}.imported`;
    await rename(path, imported);               // ← 提交点在所有写入之前
    const sections = parse(await readFile(imported, "utf8"));
    for (const [section, values] of Object.entries(sections ?? {})) {
        const ns = LEGACY_SECTION_ENTRIES[section] ?? section;
        try {
            await this.update(ns, values);      // ← configEditor 不可用时每段都抛
        } catch (error) {
            this.ownerContext.logger.warn("settings: section %s of %s was not imported into entry %s", section, imported, ns);
            this.ownerContext.logger.warn(error); // ← 失败只 warn，无重试、无 UI 提示
        }
    }
}

---

附：我们的临时恢复方案（供其他撞到的用户参考）

手工把 .imported 里的 4 段按当前 profile 的条目形态写回 cordis.patch.yml（即 importLegacyDocument 本应写入的目标），一次恢复成功。建议官方在修复前于升级文档里注明：若升级后设置空白，检查 ~/.dsh/settings.yaml.imported 并手工恢复——数据都在，只是没人消费它。

[Ragnoryok1]

Independent confirmation from a different environment: Windows 11, Node 24.17.0, source launch (not macOS, not a global npm install), on 0.1.7-alpha.2 — the same silent loss.

What I can add to your analysis:

• I verified the same ordering in rc.2: packages/settings/settings/src/index.ts — importLegacyDocument at :241, await rename(path, imported) at :246 before the loop, the swallowed failure at :253, and the fire-and-forget call at :235. Your configEditor-inactive-context race is one trigger; the ordering is what makes any write failure permanent, which is why both reports converge on the same fix.
• Worth checking in your logs which section vanished. Of the eight sections in my settings.yaml.imported, seven have a counterpart in the active profile and agent-presets has none — no entry of that name, and no mapping in LEGACY_SECTION_ENTRIES:201-206 (that table maps only ui-developer-tools → ui-settings, ui-onboarding → ui-settings-general, shell → pwsh-sandbox|bash-sandbox).
• Recovery that worked without the UI: the sections are intact in settings.yaml.imported, and the survivors are written into the profile's cordis.patch.yml, so a lost section can be re-added there by hand.

I filed the same defect separately as #7672 (Windows, before rc.1) — two independent reproductions on different platforms, so it is not environment-specific. One note for the fix: because the import runs from void ctx.root.loader.await().then(...) at :235, even a total failure only reaches the logger; a retry on the next boot, or a notice pointing at .imported, would cover your race without changing the ordering.

[SAXEM1997]

补充一个独立于启动竞态的成因 —— 迁移失败不止一种机制。

我在 0.1.7-rc.2 上逐节核对了 settings.yaml.imported 里的 10 个节，发现失败有三条互相独立的路径，任一条单独成立就足以让某一节静默丢失：

模式	抛错位置	触发条件
A	dsh-app-boot/lib/index.js:3469 — profile reload requires the root Include entry	同一个包存在两份物理副本（模块私有 WeakMap 读不到写入；Linux/pnpm 双树下同样会触发，见 #7675）
B	dsh-settings/lib/index.js:504 — No configurable plugin entry "<ns>"	旧节名 ≠ 真实 entry id
C	dsh-settings/lib/index.js:506 — has no volatile fields	该条目没有标任何 volatile() 字段

B 的实际映射：agent-presets → 真实 id 是 agent-preset-registry；subagent-model-selection → subagent-model-selection-settings；dsh-better-sidebar → better-sidebar。（agent-presets 的默认值后来改由 registry 的 config.default 承载，settings.yaml 里那条成了死配置。）

C 我觉得值得单独说一句：SettingsForms.write() 在调用 edit() 之前就要求「该条目至少声明一个 volatile() 字段」，而 volatile() 只有 @deepseek-ai/schemastery 才有 —— 原版 schemastery@3.18.x 里 volatile 这个词出现 0 次。于是任何使用原版 schemastery 的第三方插件，它的配置节永远无法被迁移：静默跳过、无任何提示、也没有替代入口。

我遇到的具体实例：@linxin666/dsh-remote-web-ui 的 requirePairingForLan: false 就是栽在 C 类被丢掉的，而它的后果是远端访问一直弹「此设备未配对」围栏 —— 排查了半天才发现根源在迁移，不在插件。

建议：

1. B/C 两类跳过时至少改成显式告警，并列出未能迁移的节名（现在是完全静默的）；
2. C 可能还需要一个兜底通道 —— 例如允许不经 volatile() 直接写入 profile 的 patch 文档，或提供一个「把 legacy 节转成 id 目标覆盖」的 CLI 子命令。否则第三方插件的设置永远卡在「看得见、迁不动」。

[SAXEM1997]

更正上面这条评论里的一处 —— 我把「旧节名与真实 entry id 的对应关系」写成了「代码里的映射」，这是错的。

dsh-settings 里唯一的 legacy 映射表只有三项（lib/index.js:303-308）：

const LEGACY_SECTION_ENTRIES = {
	"ui-developer-tools": "ui-settings",
	"ui-onboarding": "ui-settings-general",
	shell: process.platform === "win32" ? "pwsh-sandbox" : "bash-sandbox"
};

导入时查表是逐字兜底的（354: const ns = LEGACY_SECTION_ENTRIES[section] ?? section;），所以：

• agent-presets、subagent-model-selection、dsh-better-sidebar 不在表里 —— 它们以原样去查，各自在 504 抛 No configurable plugin entry "…"，然后被只记一条 warning 跳过。
• 我上一条写的 agent-presets → agent-preset-registry 等，是这些名字各自指向的真实 entry id，不是代码里的映射。代码并不做这个转换 —— 这恰恰是 B 类失败之所以成立的原因（如果代码真做了映射，它们就不会失败了）。

另一处要收紧的表述：volatile() 并非「只有 @deepseek-ai/schemastery 才有」，准确的说是该包的 3.18.4 及以后才有 —— 本机还装着一份 3.18.2 的嵌套副本，它和原版 schemastery@3.18.0 一样，volatile 出现 0 次。

其余（504/506 两个抛错点及其在 edit() 之前、原版 schemastery 零 volatile、remote-web-ui 用原版 schemastery 致其配置节无法写入、agent-presets.default 已成死配置）复核后无误。

[Ragnoryok1]

Your correction matches what I see from the other side: my loss was mode B, and I can name both ends of it.

• The section in my settings.yaml.imported is agent-presets. The entries the running build actually ships are agent-preset-registry, ui-agent-preset and preset-standard — no entry carries the id agent-presets, and the table in packages/settings/settings/src/index.ts:201-206 has no row for it, so the verbatim lookup cannot match and :504 throws exactly as you describe.
• That is consistent with your correction: the code performs no name-to-id translation, so any section whose name is not itself an entry id fails. In my profile the other seven sections all happen to be entry ids (ui-theme, agent-default-model, locale, llm-pi-ai, ui-chat, llm-deepseek, and ui-onboarding through its table row), which is why exactly one section disappeared.
• Recovery on my side: the section is intact in .imported, and I re-added it by hand into the profile's cordis.patch.yml, where the imported survivors live.
• Also confirming your volatile precision: the copy that dsh-settings resolves on my machine is 3.18.4 and contains 94 volatile occurrences, so mode C fires only for entries that genuinely declare none — not because the API is missing.

On mode A I cannot confirm it as my cause, but its precondition exists on Windows too: walking my source checkout hit ELOOP through a nested chain packages/acp/acp/node_modules/@deepseek-ai/cordis/node_modules/@deepseek-ai/cordis-plugin-include/…, so long nested duplicate chains are present in a checkout, not only under pnpm's Linux layout.

One addition to the three modes, if useful: mode B also covers a rename in the product itself — a section that imported cleanly on one release stops matching as soon as the entry id changes, which makes B self-inflicting on upgrades rather than only on hand-written config.

My separate report reaching the same conclusion is #7672; linking the two may help whoever picks this up.