建议：在 profile 激活前增加第三方插件兼容性预检

[Mo-xi-ao]

建议：在 profile 激活前增加第三方插件兼容性预检

目前 dsh plugin 的安装路径对第三方 bundle 很简洁，但也因此把许多问题推迟到了下一次 profile boot。

当前行为

apps/cli/src/plugin.ts 将 dsh plugin --profile <name> <args...> 作为 pnpm forwarder。pnpm 成功后，reconcilePlugins() 主要检查依赖解析出的 package manifest 是否声明了 dsh.bundle；如果声明存在，就把包名追加到 dsh.profile.bundles。

docs/user/develop/basic/publish.md 也把 bundle manifest 的核心字段描述为：

dsh: { bundle: { patch: ./cordis.patch.yml } }

当前没有一个面向 out-of-tree bundle 的 Harness compatibility declaration，也没有在加入 profile layer 之前执行的 activation preflight。于是以下问题可能都要到下一次启动才出现：

• 插件要求的 Harness 版本或 peer capability 不满足；
• dsh.bundle.patch 指向缺失或不可解析的文件；
• bundle 引用的 Host/Client artifact 没有随包发布；
• 依赖拓扑导致错误的 Cordis 解析或重复运行时；
• patch 可以被读取，但组合后的 Loader entry 无法激活。

这与一方包已有的 workspace、artifact 和 publication gates 形成了明显不对称：外部插件只要安装成功且声明了 dsh.bundle，就可能立即进入 profile 的 layer list。

建议方向

是否可以增加一个可选的 packaged-plugin compatibility declaration，并在 pnpm 完成物化后、写入 dsh.profile.bundles 之前进行有限预检？可考虑放在 dsh.bundle 下，或放在同级的 dsh.plugin 中，内容例如：

• 支持的 Harness version range；
• 需要的 runtime face 或明确 artifact；
• 可由 manifest、已解析文件和 composed configuration 确定的 required capability。

预检应只验证可以确定性判断的事实，不应通过执行第三方插件代码来“证明安全”，也不应把 version-range match 宣称为语义兼容。

当预检失败时，我倾向于：

• 保留 pnpm 已安装的依赖，方便用户检查和修复；
• 不把 bundle 加入 dsh.profile.bundles，因此不改变当前可启动 profile；
• 报告实际解析到的 package name、失败条件、受影响的 profile 和修复建议。

在 developer preview 阶段，没有兼容性 metadata 的旧 bundle 可以继续使用，但应明确给出 compatibility-unknown warning。

不建议扩大到的范围

• 不替换 pnpm，也不实现第二套 dependency solver。
• 不在安装阶段执行未经信任的插件代码。
• 不自动修改用户的 cordis.patch.yml 或迁移插件配置。
• 不因为预检失败删除 pnpm 已成功安装的依赖。
• 不把兼容性预检当成 sandbox 或供应链安全机制。

相关源码

• apps/cli/src/plugin.ts
• packages/boot/app-boot/src/profile.ts
• apps/cli/reference/README.md
• docs/user/develop/basic/publish.md
• docs/cookbook/adding-a-package.md

想请教维护者的问题

1. 兼容性 metadata 更适合放在 dsh.bundle、同级 dsh.plugin，还是使用 npm peer dependency 加 Harness 专用 artifact declaration？
2. 哪些检查应该在 install-time 完成，哪些仍应留给 boot-time Loader diagnostics？
3. 预检失败时，是否应保持“依赖已安装但 bundle 未激活”，还是让 dsh plugin 使整个 pnpm 操作失败？

[zoahdev]

这个提案和社区已有的实现完全对口——dsh-plugin-doctor 就是"装进 profile 之前的预检"，只是目前以社区工具形式存在。你的每一项失败模式都能对应到具体检查：

提案里的失败模式	对应检查	证据
插件要求的 Harness 版本/peer 不满足	manifest + 模板的运行时守卫（dsh-tools 版本不匹配直接抛带指引错误）	dsh-plugin-template
dsh.bundle.patch 缺失/不可解析	manifest + patch（YAML 合法性 + 至少一条带 id 的 insert）	doctor --full
Host/Client artifact 没随包发布	files（白名单是否含构建产物）+ pack（tarball 内容清单）	doctor --full
依赖拓扑导致重复运行时	profile-shadow（profile 顶层真实目录 @deepseek-ai/* 副本检测，#1697 前置条件）	doctor --profile，已被 moonquake2004 独立验证
patch 可读但组合后 Loader entry 无法激活	install（全新 DSH_HOME profile 里真实 dsh plugin add + --dump-config 断言插件 id 出现）	doctor --full
兼容性未知的旧 bundle	我们的检查对"无兼容性声明"的 bundle 给 WARN 而不是 FAIL，和你的 compatibility-unknown warning 一致	doctor 输出语义

为了和提案术语对齐，v1.5.0 刚加了 preflight 模式：

dsh-plugin-doctor preflight ./my-plugin   # = build + pack + 全新 profile 安装 + 合成配置验证

输出 {ok, checks:[{name,status,detail}]} + 退出码，CI/脚本可直接消费；失败时保留已安装依赖、不写 profile、报告包名/失败条件/修复建议——和你列的非目标完全一致（不执行用户代码的是结构检查；--build/--full 是在全新隔离 profile 里按需跑的验证，不会碰用户配置）。

如果官方想把这个 preflight 收编进 dsh plugin，这个实现可以作为起点：checks 是纯函数、JSON 输出稳定、已经过 12 个单测 + 打包冒烟 + 自检。

Release：https://github.com/zoahdev/dsh-plugin-doctor/releases/tag/v1.5.0