[Bug] Plugin/profile composition drift only surfaces as a fatal crash on the next boot — needs preflight validation and a dsh profile doctor

[nanami-0713]

Summary

A dsh web profile only boots if several mutable files stay in sync: the profile package.json (dependencies plus the dsh.profile.bundles list), the composition layers (cordis.yml, user cordis.patch.yml), and — for host-side injector setups — separate plugin registries. Renames, source-directory moves, partial installs, home-directory migrations, and deleted-but-still-declared bundles desync these silently. Nothing checks that state until the next boot, where it becomes a fatal crash:

Error: dsh: cannot resolve profile bundle "…" from the dsh installation or <profileDir>;
run 'dsh plugin --profile <name> install' if its dependency is not installed

That message is actionable (genuinely good!), but it arrives as a full startup failure — under a service manager this is a crash loop, discovered while unattended.

Incident forms we hit in ~3 weeks of heavy plugin development

1. Declared but unresolvable bundle — an entry in dsh.profile.bundles whose dependency was never installed, or whose link: source directory was moved/deleted. The crash happens on a later restart, long after the edit that caused it.
2. Malformed patch wiring — a bundle package.json whose dsh.bundle.patch declaration was missing, pointed at a missing file, or was not a top-level array. Same deferred-crash shape.
3. Rename without re-registration — a plugin's package.json name changed (scope rename), but the bundles list still referenced the old name; the plugin then loads without registering, and injector registries keep stale entries pointing at directories that no longer exist.
4. During one home-directory reorganization, our static checker counted 16 declared bundles unresolvable at once — any boot in that window would have crashed, and nothing in dsh itself would have told us before booting.

We now run a custom static "doctor" script (~300 lines) that replicates resolveBundleDir()'s resolution chain and reports dangling links, name mismatches, and stale registry entries on a schedule. It works — which is the point: the checks are mechanical and belong upstream.

Asks

1. dsh profile doctor [--profile <name>] — validate without booting: every bundles entry resolvable from the install anchor or profile dir; link: targets exist; dsh.bundle.patch declarations well-formed; dangling symlinks in the profile tree; stale third-party registry entries. Report-only by default.
2. Boot preflight / dry-run (e.g. dsh web --dry-run): run composition + resolution and exit 0/1, so service managers and CI can smoke-test a profile right after any change.
3. Opt-in degraded boot: start without a broken non-core bundle, with a loud warning in UI and logs, instead of refusing to start. The web UI — including its plugin marketplace — is where many users manage plugins, so a hard boot failure also removes the tool they would use to fix the problem.

Related: #6459 covers a different layer of the same theme (multiple installations flipping the shared profiles/node_modules fallback tree); this post is about single-install composition integrity.

Environment

macOS 15.5 arm64; dsh 0.1.x across 0.1.1-rc.1 → 0.1.5-rc.1; a web profile with ~18 bundles, mostly local link: plugins under active development.

[myongyi825-beep]

补充一种与本文三种形态都不同的 drift：不崩溃、静默丢弃（no crash, silent drop）。

环境

@deepseek-ai/dsh 0.1.5-rc.1（CLI）· profile web · pnpm 11.8.0 · Node v22.20.0 · Windows 10 · 插件以本地目录依赖安装（file: 协议）

现象

对同一个插件跑 dsh plugin --profile web remove <pkg> 之后再 add（本地目录依赖必须 remove→add 才会重新快照，因为 pnpm 会缓存旧目录内容）：

• dependencies 正确写回：

"dependencies": { "@toustifer/dsh-agentflow": "file:C:/Users/***/.dsh/plugins/agentflow/dsh-agentflow" }

• 但 dsh.profile.bundles 少了一项（该包 package.json 里明确声明了 dsh.bundle.patch，本应被自动追加）：

"bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-harvest"]

• dsh --profile web --dump-config 只给一行 warning，没有 error、退出码 0：

dsh: [C:\Users\***\.dsh\profiles\web\cordis.patch.yml] patch: entry "dsh-agentflow" not found

结果：插件完全不进启动树（MCP 工具、技能、agent preset 全缺），但用户看到的是"安装成功"。再跑一次完全相同的 add，bundles 就被补回（实测），从而形成"重装一次就好了"的玄学。

复现性

不稳定：失败一次后，用完全相同的 remove→add 再跑一次未复现。怀疑是 pnpm 刚 materialize 包目录那一刻的时序/竞态。

代码路径

lib/plugin-*.js 的 reconcilePlugins() 依赖 exportsPatch() 判定"这个依赖是不是 bundle"，而后者吞异常：

function exportsPatch(packageName, profileDir) {
  let dir
  try { dir = resolveBundleDir(NAME, packageName, INSTALL_ANCHOR, profileDir) }
  catch { return false }                       // ← 解析失败被当成"没声明 dsh.bundle"
  return readProfileManifest(NAME, dir).dsh?.bundle?.patch !== void 0
}

若这一刻解析返回 false：① 不追加；② 第二个循环还会把同名项从 plugins 里 splice 掉（stillBundle=false）；③ 唯一的那行 warning 文案是 declares no dsh.bundle，与实际不符，反而把排查引向错误方向（包明明声明了）。

与本文三种形态的关系

• 形态 1/2（声明了但解析不到、补丁接线坏）→ 下次启动崩溃，报错文案清楚；
• 本形态 → 永不报错，只是少挂一个插件；bundles 与 dependencies 的不一致本身没有任何校验。

建议的不变量（供 preflight / dsh profile doctor 参考）

1. 强校验：凡 dependencies 中声明 dsh.bundle.patch 的包，若最终不在 dsh.profile.bundles → 视为错误（而非 warning）。缺 overlay 文件已经是硬错误，同类不一致不应静默。
2. exportsPatch() 不吞异常：区分"包不存在"与"解析过程异常"，后者上抛或至少打印 resolveBundleDir 已写好的原因与尝试过的锚点。
3. warning 文案修正：只有真的没声明时才说 declares no dsh.bundle。
4. --dump-config 诊断增强：patch: entry "X" not found 时，追加"X 属于哪个 bundle、该 bundle 是否在 dsh.profile.bundles 中"。
5. 在 dsh plugin add/remove 之后提示一句：建议跑 dsh --profile <p> --dump-config 校验（成本极低的用户侧护栏）。

顺带一个正面反馈：形态 1 的那条报错文案（cannot resolve profile bundle "X" …; run 'dsh plugin --profile <name> install'）确实清楚——问题只在于本形态根本不触发它。

[jeffliulab]

A concrete case of form 2 that reaches end users, not only plugin developers: the published npm plugin dsh-cad (0.9.1, and the current 0.11.0) declares dsh.bundle.patch: "./cordis.patch.yml" but leaves that file out of its tarball (LAU-MARS/dsh-cad#1). On @deepseek-ai/dsh@0.1.5-rc.3, anyone who installed it from npm gets:

Error: dsh: failed to read overlay <profile>/node_modules/dsh-cad/cordis.patch.yml: Error: ENOENT: no such file or directory
    at loadOverlayPatches (file:///.../@deepseek-ai/dsh-app-boot/lib/index.js:1165:9)
    at loadProfileDirectory (file:///.../@deepseek-ai/dsh-app-boot/lib/index.js:849:25)

and dsh web does not start at all. Even dsh web --help fails, since the profile is loaded first. Two points from this case in support of the asks above:

1. Unlike the unresolvable-bundle error quoted in the original post, this message gives no next step. Naming the bundle and suggesting dsh plugin --profile web remove dsh-cad would turn a long investigation into one command.
2. dsh-cad was one of four third-party bundles in the profile, and a missing patch file means the bundle contributes nothing. Skipping it with a loud warning (ask 3) would have kept the other plugins and the web UI working.

Environment: Linux x86_64, Node v24.21.0, @deepseek-ai/dsh@0.1.5-rc.3, pnpm 12.4.2.

[nanami-0713]

@/tmp/d6539-reply.md