dsh-compat-vet

DSH 插件兼容性体检 + 页面上的一键修复 —— 检查已安装插件与当前 dsh 运行时是否冲突， 中文预警并给出可直接执行的命令；装了本插件之后，dsh web 的页面顶部会直接弹出横幅， 照着按键就能当场修掉（不提供「版本豁免」这个选项，理由见 §4④）。

它跟着 dsh 版本自己变，不需要你为任何 dsh 版本改一行代码。（见 §2）

---

1. 它解决什么问题

dsh 升级后，老插件常常因为 peer 依赖范围不匹配而被启动预检拒绝加载。此时的表现很有迷惑性：

• 插件还在 dsh plugin list 里、文件也还在 node_modules 里，看起来没坏；
• 但功能整块消失，或者 dsh 直接起不来；
• dsh 只会往 stderr 打一行英文告警，而且只在恰好安装那一个插件时才出现 —— 等到某天重启 dsh 才发现问题，已经很难回溯。

本插件把这件事变成主动、集中、中文、可操作的体检 —— 而且在 dsh web 上 直接变成页面顶部的一条横幅，按键就能当场修掉（§4④）。

本机实测（这就是它的目标场景）

当前环境 dsh 0.2.0-rc.2，profile web。dsh 自己的启动日志：

dsh: skipping profile bundle "dsh-cost-meter": Error: Plugin dsh-cost-meter@1.7.35 is
incompatible with dsh 0.2.0-rc.2: peerDependencies {"@deepseek-ai/dsh-credentials":
"^0.1.0-rc.6 || ^0.1.1-0 || ^0.1.2-0 || ^0.1.3-0 || ^0.1.5-0", ...}

本插件对同一环境的结论（dsh-compat-vet / plugin_compat_check 工具）：

[阻断] dsh-cost-meter @ 1.7.35
  [阻断] 与 dsh 0.2.0-rc.2 不兼容，启动时会被拒绝加载
         处理办法：
           dsh plugin --profile web add dsh-cost-meter@latest
           dsh plugin --profile web remove dsh-cost-meter
           dsh plugin --profile web allow-version dsh-cost-meter@1.7.35 \
             --dsh-version 0.2.0-rc.2 --accept-risk

两者结论一致；差别在于本插件是集中报告 + 中文 + 带修复命令。

---

2. 怎么做到「适配任意 dsh 版本」——实测，不是猜

2.1 先说不做什么：不写版本号 if

最省事、也最不靠谱的做法是维护一张表：

// ❌ 本插件刻意不这么写
if (semver.gte(version, '0.1.7-rc.1') && semver.lt(version, '0.3.0')) { … }

这种代码每个 dsh 新版本都要人来改一次 —— 正是要避免的事。而且它基于一个错误假设： 「dsh 版本号 → 能力」这个映射是稳定的、可以事先写死的。实际上不是。

2.2 实际做法：把 dsh 自己的判定函数拿过来跑一遍

dsh 的兼容性预检在 @deepseek-ai/dsh-app-boot 里。插件在启动时：

1. 动态 import() 本机 dsh 安装目录下的 dsh-app-boot；
2. 看它有没有导出 evaluatePluginCompatibility —— 有没有这件事不靠版本号假设；
3. 有的话，用几个合成的假插件清单真调它一次，看它到底会不会报、报什么：
   • 造一个 peer 范围是 >=999.0.0 的清单（任何真实 dsh 都不可能满足）→ 看它拦不拦；
   • 造一个完全没有 peerDependencies 的清单 → 看它管不管（这是它的盲区）；
   • 造一个只有 dsh.engines.dsh 的清单 → 看它看不看字段（也是盲区）；
   • 找找有没有 compatibility 文件常量 / 读写函数 → 判断有没有版本豁免机制。

于是「本机这个 dsh 有没有预检、会不会拦、有没有豁免」全是实测结论，不是版本推断。 报告里会明确标出结论依据：

适配信息（结论依据，不是假设）
  dsh 版本      : 0.2.0-rc.2｜来源：anchor-manifest
  能力探测      : 成功 —— 已就本机这个 dsh 实测校准
  兼容性预检    : 存在且实测有效
    · 会因 peer 不匹配拦下插件 : 会
    · 会检查没有 peer 的插件   : 不会（盲区）
    · 会看非标准版本声明       : 不会（盲区）
    · 版本豁免机制             : 有（compatibility.json）

探测不成功时不下结论：报告改说「本次未能实测」，措辞退到最保守的说法 （会不会拦下它：未能实测），并提示用 --anchor <dsh 的 package.json> 重跑一次。 三种状态是明确的 covered / not-covered / unknown，不存在「猜一个」。

2.3 顺带解决了一个更隐蔽的问题：措辞不能错

老版本 dsh 根本没有兼容性预检。那里插件会照常加载，兼容性风险直接暴露在运行时。 如果在那种版本上还打「启动时会被拒绝加载」，就是说反了 —— 用户会以为自己安全了。

所以告警措辞跟着实测走：

实测结论	告警措辞
该版本会拦	— 与 dsh X 不兼容，启动时会被拒绝加载
该版本不拦	— 与 dsh X 不兼容（本机 dsh 不会拦下它，会照常加载）
没测出来	— 与 dsh X 不兼容（本次未能实测本机 dsh 会不会拦下它）

同理，allow-version 这条修复建议只在真的有豁免机制时才给 —— 在没有豁免机制的老版本上给这条命令，等于给一条根本跑不通的命令。

2.4 实测矩阵（本机真的装了 4 个 dsh 版本，逐个跑出来的）

dsh 版本	兼容性预检函数	会因 peer 不匹配拦下	版本豁免机制	会看 dsh.engines.dsh 等野生声明	会看没有 peerDependencies 的插件
0.1.1-rc.2	没有	不会	没有	不会	不会
0.1.5-rc.3	没有	不会	没有	不会	不会
0.1.7-rc.1	有且实测有效	会	有（compatibility.json）	不会	不会
0.2.0-rc.2	有且实测有效	会	有	不会	不会

这张表由 npm test 每次自动重测（test/versions.test.mjs），不是文档里抄下来的死数据： 将来你机器上多一个新版本 dsh，测试会自己把它加进来跑。遇到完全不认识的未来版本时， 测试只做自洽性检查并打一个 ⚠️ 提示，不会因此失败、也不需要谁来更新代码。

2.5 真机启动验证：光有结论不够，要真启动一次

单元测试里的 cordis 上下文是捏出来的假货。「插件在真 dsh 启动流程里到底会不会被调用、 输出长什么样」只能真启动一次才算数。所以还有一个真机验证脚本：

npm run verify:boot        # 把本机所有 dsh 版本各真启动一次

它在一个临时的 DSH_HOME 里、用 dsh 自带的 headless 模板起一个最小 profile， 塞进本插件 + 一个「对任何版本都不兼容」的金丝雀插件，然后真的把这个 dsh 跑起来， 核对四件事：

dsh 版本	插件真被调用	告警措辞	dsh 实际是否拦下金丝雀	探测结论	一致
0.1.1-rc.2	✅	会照常加载	否	不会拦	✅
0.1.5-rc.3	✅	会照常加载	否	不会拦	✅
0.1.7-rc.1	✅	会被拒绝加载	是	会拦	✅
0.2.0-rc.2	✅	会被拒绝加载	是	会拦	✅

最后两列是重点：「探测说会拦」必须和「dsh 真的把金丝雀跳过了」对得上。 这是「实测校准」这四个字唯一的硬证据 —— 校准自己错了，上面所有结论都是假的。

这个脚本不碰你的真实环境：全程在临时 DSH_HOME 里跑、不监听端口、 不动 ~/.dsh、不影响正在运行的 Web GUI。

2.6 真机验证抓出来的 6 个 bug（这就是它存在的理由）

这几个都是单元测试全绿也照样漏掉的，只有真启动才暴露：

#	问题	后果	修法
1	ctx.profileContext 这种服务属性读取会抛异常（cordis 在插件没 inject 该服务时抛 cannot get property "profileContext" without inject；0.1.5-rc.3 实测如此）	整个启动自检炸掉，又被 apply() 的兜底吞掉 —— 插件在那个版本上什么都不做，且一声不吭	改走 serviceOf()，逐个来源 try/catch，读不到就换下一个来源
2	0.1.1-rc.2 上根本没有 profileContext 服务，插件退回继承来的 DSH_PROFILE_DIR	张冠李戴：在一个 web 会话里 dsh --profile tui，子进程继承的环境变量仍指向 web，插件就去体检 web 了，还理直气壮地报警	从进程自己的命令行反推 --profile，并让「显式指定 / 运行时事实」压过 DSH_PROFILE_DIR
3	定位 dsh 安装目录只扫 PATH	本机 npx 缓存里躺着 4 个 dsh，可能定位到不是正在运行的那个 —— 「实测校准」测错了对象，结论看着像实测，其实测的是别人	新增 anchorFromProcessEntry()：从当前进程入口脚本反推，权威性最高
4	CLI 的 --home / --profile 被环境里的 DSH_PROFILE_DIR 悄悄盖掉	命令行参数看着生效了、其实没生效，检查的是另一个 profile	「显式指定」的优先级提到环境变量之前
5	「复检不过就回滚」把一次正确的修复判成了失败：setBundleEnabled() 返回 restart-required，紧接着问 listBundles()，拿到的还是本进程的旧结论	于是一次已经正确落盘的隔离被自动回滚 —— 表面上"很安全"，实际上这个功能在真机上永远修不成功。单测全绿也发现不了（假 service 不会"慢半拍"）	判定依据改成「改动真的落盘 + 本插件复检干净」，dsh 本进程的即时结论只作为信息如实上报；并且 listBundles() 改为轮询若干秒，不采样一次就下结论
6	有阻断问题时，「快要不适配」的预警整块看不见 —— 横幅只渲染 problems[0]，"其余问题"也只列 problems，从不带 upcoming	用户最想提前知道的那条消息（"dsh 升到 0.3.0 时 dshmarket 会被拦下"）被当前那条更紧急的盖住 —— 真机上两者是同时存在的	阻断视图底部加一行预警摘要 + 「查看 / 预防性处理」切换视图，两者同屏可达

第 5 个是修复功能的真机验证抓出来的（npm run verify:repair）； 第 6 个是用真实数据预览横幅抓出来的（npm run preview）—— 单测用的假报文里 upcoming 一直是空的，所以"两种情况同屏"这件事从来没被测到过。 这两个例子说明为什么这个项目的验证要分四层：单元测试 → 真机启动 → 真机改造 + 再启动一次 → 用真实数据渲染一遍界面。

顺带把「一个坏来源拖垮整条链路」这件事也堵了：所有可选来源都各自 try/catch 降级 （safe()），任何一处出错只会退到下一个来源，不会让自检整体失能。

---

3. 相对 dsh 内置检查，多查了什么

dsh 的兼容性预检只检查 peerDependencies 中以 @deepseek-ai/dsh / @deepseek-ai/dsh- 开头的键，而且插件只要没有 peerDependencies 字段，就直接判定为兼容 （源码里那句 if (!Object.hasOwn(fields, "peerDependencies")) return void 0）。

所以下面这些情况 dsh 全程不看（「会不会发现」一列是逐版本实测的，见 §2.4）：

检查项	说明	dsh 是否会发现
peerDependencies 不满足	peer 范围与运行时不符	✅ 会发现（仅 0.1.7-rc.1 及以后；老版本连这个都不看）
非标准位置的 dsh 版本声明	dsh.engines.dsh / dsh.compatibility.dsh / dshhub.compatibility.dsh —— 三种野生写法实测都存在	❌ 4 个版本实测全部不会
完全没有 peerDependencies 的插件	无法从元数据判断兼容性，升 dsh 时最需要人工回归	❌ 4 个版本实测全部不会
engines.node 不匹配	Node 版本不符可能导致语法/API 不可用	❌ 不会
bundles 里引用了但没装的包	dsh 加载器会打印 skipping profile bundle 并跳过	⚠️ 加载器会打日志，但那不是兼容性预检，本插件只标「未能实测」不敢替 dsh 下断言
「快要不适配」（可预测的版本失配）	声明范围现在能满足，但 dsh 的下一个小版本 / 大版本就会掉出去 —— 也就是「下一个 dsh-cost-meter」	❌ 不会（dsh 只判当前版本）。本插件按声明范围推算，并告诉你坏在哪个版本（例：dshmarket@1.66.6 会在 dsh 0.3.0 失配）
装了但不在 bundles 里	装了却不激活，白占依赖	❌ 不会
profile 声明范围 vs 实际安装版本不一致	lock 与 manifest 漂移	❌ 不会
读不到插件清单	包损坏 / 安装不完整	❌ 不会
版本豁免状态	区分「已知不兼容但接受风险」与「真的没问题」	⚠️ 部分（且老版本没有豁免机制）

报告里每条发现都会标出「dsh 自己会不会发现」，三态且带依据：

[dsh 内置检查：同样会发现｜依据：dsh 兼容性预检（实测校准）]
[dsh 内置检查：不会发现｜依据：dsh 兼容性预检（实测：该版本没有这个检查）]
[dsh 内置检查：会不会发现未实测，不下断言｜依据：…]

实测例子：@linxin666/dsh-perf@0.3.14 声明了 dsh.engines.dsh = ">=0.1.2-rc.1"， 但没有任何 dsh peer 依赖 —— 所以 dsh 侧从未校验过它。本插件会读这个字段。

---

4. 四种用法

① 装成插件：启动自动预警 + 会话内工具（推荐）

装进 profile 后，每次 dsh 启动会自动体检，有问题就往 stderr 打一段中文告警：

dsh-compat-vet: 检测到 1 个插件与 dsh 0.2.0-rc.2 存在兼容性问题：
  [阻断] dsh-cost-meter@1.7.35 — 与 dsh 0.2.0-rc.2 不兼容，启动时会被拒绝加载
      建议：dsh plugin --profile web add dsh-cost-meter@latest
  完整报告：运行 `dsh-compat-vet`，或在会话里用 plugin_compat_check 工具。

同时注册一个 plugin_compat_check 工具，会话里随时可以复查：

「帮我看看插件兼容性」→ agent 调用 plugin_compat_check → 返回完整中文报告与修复命令。

还有一个系统提示词段落：只要存在未解决的兼容性问题，它就会被注入到模型的上下文里， 模型会在你提到插件/报错/功能异常时主动提醒，不需要你想到去问。

② 独立 CLI：dsh 起不来时唯一能用的入口

插件只在 dsh 成功启动之后才跑得起来；而版本冲突最坏的后果恰恰是 dsh 起不来。 所以同一个引擎同时提供独立 CLI —— 它不依赖 dsh 的任何模块：

dsh-compat-vet                  # 检查默认 profile（$DSH_PROFILE 或 web）
dsh-compat-vet --profile web    # 指定 profile（会压过环境里的 DSH_PROFILE_DIR）
dsh-compat-vet --home <目录>     # 指定 ~/.dsh 所在目录
dsh-compat-vet --anchor <路径>   # 指定 dsh 的 package.json（校准要用的那个）
dsh-compat-vet --json           # 输出结构化 JSON
dsh-compat-vet --all            # 连没有问题的插件也列出来
dsh-compat-vet --quiet          # 只输出一行结论（给脚本用）

退出码：0 没问题 / 1 发现问题 / 2 体检未完成。可以拿来做启动前的守门脚本。 探测失败时会把「每个字段是从哪个来源推出来的」一并打印，方便定位。

③ 直接引用引擎

import { auditProfile } from 'dsh-compat-vet/audit'
import { auditProfileProbed } from 'dsh-compat-vet/audit'   // 会先做实测校准
const report = auditProfile({ profileDir, profileName: 'web', installAnchor })

④ 页面上的一键修复（web profile 专属）

装了插件、用 dsh web 打开界面就会看到顶部横幅 —— 不用敲命令，直接按键修：

┌────────────────────────────────────────────────────────────────────────────┐
│ [插件冲突] dsh 0.2.0-rc.2 与 dsh-cost-meter@1.7.35 冲突，它下次启动会被 dsh   │
│            拒绝加载。                                                  [×] │
│ 与运行时不兼容 —— 要求 ^0.1.0-rc.6 || ^0.1.1-0 || … ，当前 0.2.0-rc.2       │
│ [1] 隔离   [2] 卸载   [3] 升级   [R] 重新体检                              │
│ 不在输入框时可直接按数字键；正在输入时按 Alt+数字                          │
└────────────────────────────────────────────────────────────────────────────┘

按键	动作	可逆性	能保证消除冲突吗
1 隔离（默认）	用 dsh 自己的服务把它从 dsh.profile.bundles 摘掉，包和依赖都留着	随时加回去	✅ 能
2 卸载| 走dsh plugin remove`，彻底删掉	要重装	✅ 能
3 升级| 装latest`（需要联网）	——	❌ 不能保证
R	立刻重新体检	——	——
Esc	收起（同一批问题不再重复弹；问题集合变了会重新弹）	——	——

补充几点：

• 按键不会抢你的输入：正在输入框里打字时裸数字键原样放过，只有 Alt+数字 才触发。
• 「快要不适配」不会被「已经冲突」盖住：真机上两者会同时存在 （dsh-cost-meter@1.7.35 已阻断 + dshmarket@1.66.6 将在 dsh 0.3.0 失配）， 所以阻断视图底部会多一行预警摘要 + 一个「查看 / 预防性处理」入口，点进去是预警视图， 可以「预防性处理」（把它提升成可操作的问题行，数字键继续有效）。 想先看会显示成什么样：npm run preview（只读，用你真实 profile 的数据渲染一遍横幅，不发修复请求）。
• 结果直接显示在横幅上（含每一步做了什么、是否已落盘、要不要重启、以及失败时的「已自动回滚」）； 修完之后横幅不会立刻消失，免得你以为"什么都没发生"。
• 改动前自动备份 profile 的 package.json / cordis.patch.yml / compatibility.json 到 <profile>/.compat-vet-backup/<时间戳>/；改完自动复检，保证类动作复检不过就自动回滚。
• 刻意不提供「豁免（allow-version）」这个选项：豁免只是"接受风险继续加载"， 它不会让 dsh 下次启动不被拦下 —— 与本插件的目标正好相反。

⚠️ 接口只认本机回环（127.0.0.1/::1 + 同源校验）。所以从局域网地址打开的 GUI 会被拒绝（403），修复功能不可用但页面其余部分照常。这是刻意取舍：这条接口会改 profile 配置， 宁可不可用也不能给跨站请求留门。

---

5. 安装 / 卸载

从 npm 安装（给使用者的那条路）

已发布到 npm：dsh-compat-vet（latest = 0.3.1）

dsh plugin --profile web add dsh-compat-vet

源码仓库：liujianqiao701/dsh-compat-vet

「陌生人装上能不能用」是实测过的，不是推断：node scripts/verify-tarball-install.mjs --from-npm dsh-compat-vet 会在空白 profile 里用 dsh 自己的安装命令装registry 上那个包、真启动、取回页面横幅代码、再卸载干净（16 项）。 单测跑的是源码目录，而别人装到的是 npm 包 —— 两者不是一回事（files 少一项就够让单测全绿而别人装完是坏的）。

关于名字（改过两次）： 最初叫 dsh-plugin-doctor —— 但这个名字在 npm 上已经被别人占用（作者 Xrainsmile，0.1.1）， 生态里另有两个同名插件，所以第一次改成了 dsh-compat-doctor（并以此名发布过一次）。 随后发现 doctor / guard / health / sentinel 这一族名字在插件目录里已经用滥 （dsh-doctor 3 条、dsh-plugin-doctor 3 条、dsh-plugin-guard 2 条，dsh-plugin-sentinel、 dsh-boot-guard、dsh-startup-guard、dsh-conflict-guardian 等均已占用）， 而 compat 在 4392 条目录里只被用过 2 次且都不是这个用途 —— 因此最终定名 dsh-compat-vet。

名字牵连的地方（客户端的模块 id 必须等于包名，否则 dsh 路由不到横幅）都已对齐： package.json 的 name/bin、lib/client.js 的模块 id、cordis.patch.yml 的 name、 lib/index.js 的 name 导出、页面接口前缀、横幅 DOM id、存储键、备份目录名、全部测试与文档。

上架进度与投稿文件见 publish/：收录到插件市场（dshmarket 的清单来自 awesome-dsh-plugin） 需要往那边提一个 PR，加一个 YAML 条目；npm 发布与收录是独立的， 发不发 npm 都不影响收录，收录也不依赖 npm。

从源码安装（本机开发就是这样装的）

# link: 指向源码目录，改完代码重启 dsh 即生效
dsh plugin --profile web add link:D:/playwright-AI/playwright/dsh-compat-vet

# 卸载（两种安装方式都用同一条命令）
dsh plugin --profile web remove dsh-compat-vet

dsh plugin add 会自动把包名同时写进 package.json 的 dependencies 与 dsh.profile.bundles 两处（本机实测：两处都已按预期更新，且原有 8 个插件未受影响）； remove 由同一套命令包装负责，会同步清理 bundles 条目。

本插件自己的 dsh.engines.dsh 写的是 "*" —— 一个声称「适配任意 dsh 版本」的插件 不该反过来给自己设版本门槛。

⚠️ Windows 上有个 pnpm 自己的坑（与插件无关，但会撞到）： 同一个目录如果被长短两种路径写法混用（...\liujianqiao\... 与 ...\LIUJIA~1\...）， pnpm 会报 ERR_PNPM_UNEXPECTED_VIRTUAL_STORE 并拒绝 add/remove。 照它提示先在 profile 目录里跑一次 pnpm install 即可恢复。 （本插件的验证脚本因此先把临时目录解析成长路径再用——见 scripts/verify-tarball-install.mjs。）

---

6. 设计取舍（为什么代码长这样）

零 @deepseek-ai/* 依赖

这不是洁癖，是被逼的。link: 安装的插件，其真实路径在 profile 之外， Node 的 ESM 解析从真实路径向上找 node_modules —— 找不到 dsh 自带的包。 实测 profile 的 node_modules/@deepseek-ai/ 下只有 cosmokit 和 schemastery， dsh-tools / dsh-app-boot / dsh-system-prompt / semver 全都不在。

所以：

• 工具定义手写 JSON Schema，不走 defineTool（它只是把 spec 转成 JSON Schema）；
• SemVer 范围求值是自己实现的（lib/semver.js），不用 semver 包；
• 服务用 ctx.get() 机会性获取并降级，inject 留空 —— 保证在任何残缺环境下插件都能加载起来，而不是「因为缺个服务就连带不加载」。
• 探测 dsh-app-boot 用的是动态 import() + 绝对路径，不是静态 import： 静态 import 在本机根本解析不了。

体检工具不能自己成为故障源

apply() 全程 try/catch，启动自检、提示词段落、工具注册各自独立兜底， 任何一步失败只写一行 stderr 日志，绝不向上抛。系统提示词段落的 text() 失败时返回空串（空段落会被 dsh 丢弃，不占上下文）。

启动自检是同步做的：模块加载时（ESM 顶层 await）就把校准做完， apply() 里不再等待任何异步 —— 否则像 dsh web --help 这种「挂载完就退」的路径 可能在告警写出来之前就退出了。

运行时版本未知时不下结论

拿不到 dsh 版本就不做版本比对 —— 拿空串去比会把每个插件都误报成不兼容。 这种情况如实报「本次未判定版本兼容性」，并提示用 --anchor 恢复完整检查。 同理，定位不到 dsh 安装目录时，@deepseek-ai/* 的 bundle 只报「无法验证」， 不误报成「缺包」。

只读（默认）／要写就必须是你点的

体检、命令行、会话内工具全都是只读的：不改 profile 配置、不装不卸、不写 compatibility.json、 不联网；修复命令只打印，由你决定执不执行。

唯一的写路径是你在页面横幅上明确按键选择之后的那一次修复，而且：

1. 走 dsh 自己的 pluginManager 服务，不自己写文件（它加 profile 文件锁、原子写、还会协调 HMR； 而 dsh 内部那个 writeProfileManifest 是无锁非原子的 writeFileSync—— 自己写就是绕过锁，万一插件页同时在写就会互相覆盖）；
2. 改前自动备份，改后自动复检，保证类动作复检不过自动回滚；
3. 接口只认本机回环 + 同源，请求体上限 4 KiB；
4. 只有完全没有 pluginManager 的老宿主才退回自己原子写，并在结果里明确说明这一点。

---

7. 验证情况

npm test               # 134 个用例（含 4 个真实 dsh 版本的实测对拍）
npm run test:fast      # 跳过版本对拍，只跑纯逻辑
npm run verify:boot    # 真机启动验证（把本机每个 dsh 版本各真启动一次）
npm run verify:repair  # 真机「一键修复」验证（隔离环境里真修一次 + 再启动一次）
npm run verify:tarball # 打包安装验证：npm pack 出来 → dsh 自己装 → 真启动（21 项）
npm run preview        # 只读：用真实 profile 的数据把页面横幅渲染出来给你看

只想验线上那个包能不能被陌生人装上（不走本地源码）：

node scripts/verify-tarball-install.mjs --from-npm dsh-compat-vet@beta
# 用 dsh 自己的 `dsh plugin add` 装 npm 上已发布的版本 → 空白 profile → 真启动 → 取横幅代码 → 卸载

测试文件	覆盖
test/semver.test.mjs	与本机 dsh 自带的真 semver 穷举对拍 1312 组 satisfies + 41 组 validRange，零差异（两种 includePrerelease 模式都测）；SemVer §11 优先级；反直觉语义的回归断言
test/adapt.test.mjs	定位与上下文推导的全部来源与优先级；服务属性读取抛异常时不能失能（§2.6 的 bug 1）；命令行压过环境变量（bug 4）；从进程入口反推 dsh（bug 3）；从命令行反推 profile（bug 2）
test/audit.test.mjs	每种发现各一个用例；豁免文件的真实格式（裸 map，不是 {exemptions:…} 包装）；同一份插件代码在不同能力下给出相反结论（自适应核心）；未实测就不下断言；损坏输入不抛
test/plugin.test.mjs	工具定义形状、execute/render、提示词段落内容；残缺上下文下 apply() 不抛异常；启动告警是同步的；配置开关；拿不到 profile 时报可读错误；页面路由挂载 / 释放 / 关掉 / 老 cordis 安静降级 / pluginManager 延迟可取
test/upgrade.test.mjs	「快要不适配」的预测：用两个真实插件声明的范围（dsh-cost-meter 的长 || 串、@linxin666/dsh-perf 的 >=）断言分级；固定版本 / 只允许补丁 / 通配 / 垃圾输入各自的分级
test/repair.test.mjs	三个动作打到 dsh 的对的方法上；备份/还原往返；兜底直写是 2 空格 + 结尾换行；拒绝码与人话翻译；「已落盘但 dsh 还没重估」必须判成功（§2.6 的 bug 5）；复检不干净 / 没落盘 / 服务拒绝 → 回滚
test/routes.test.mjs	回环与同源围栏（跨站、伪造 Origin、非法 Host 全拒）；请求体超限；状态报文里插件版本号与 dsh 版本号都在；修复请求的参数校验与作业生命周期
test/client.test.mjs	用最小假 DOM 跑真的 client.js：横幅同时写明插件版本号与 dsh 版本号；1 映射到隔离；在输入框里裸数字键不被抢走、Alt+数字 有效；Esc 记住指纹不重复打扰；接口挂了安静退场；客户端产物没有 import
test/versions.test.mjs	对上表 4 个真实 dsh 版本逐个实测：预检有无、会不会拦、豁免机制、三个盲区；与 dsh 自己的豁免文件读取器对比 18 组样本，结论全部一致；未来新版本只做自洽检查、自动纳入

真实环境端到端已确认：

• dsh --profile web --dump-config → 组合树里出现 - id: compat-vet / name: dsh-compat-vet；
• 真机启动（npm run verify:boot）→ 4 个 dsh 版本上插件都被真正调用、措辞全部正确、 且「探测结论」与「dsh 真实是否拦下金丝雀」逐版本一致（见 §2.5）；
• 真机「一键修复」（npm run verify:repair）→ 在一个临时 DSH_HOME 里造一个必然不兼容的插件、 真启动 dsh web、走 HTTP 接口修一次、再真启动一次，全部通过： 状态报文里带着插件版本号与 dsh 版本号 → 修复走的是 dsh 自己的 pluginManager → 改动真的落盘 → 第二次启动不再跳过它、启动告警消失、体检 0 冲突；
• 客户端横幅真的会被浏览器加载：dsh 的启动注入里带着 dsh-compat-vet/client.js（真实 rev 从页面里取），按该 URL 取回 HTTP 200、 41 万字节，内容就是本插件的横幅代码；
• 打包产物装得上、装完能用（npm run verify:tarball，21 项）→ npm pack 出真 tarball、 用 dsh 自己的安装命令装进空白 profile、真启动、取到横幅代码、再卸载干净；
• npm 上已发布的那一个包也一样能用（--from-npm dsh-compat-vet@beta，16 项）→ 这条路就是陌生人点「一键安装」走的路：装出来的是 registry 上的真拷贝 （node_modules/.pnpm/dsh-compat-vet@0.3.1/…，不是指回本机源码目录）， 启动后体检 0 冲突、横幅代码 HTTP 200、卸载干净；
• 用真实数据把界面渲染了一遍（npm run preview）→ 你的 profile 上横幅会同时报出 dsh-cost-meter@1.7.35（已阻断）与 dshmarket@1.66.6（将在 dsh 0.3.0 失配）， 并给出了 [1] 隔离 [2] 卸载 [3] 升级；30 个依赖里只有 dshmarket 一个触发预警，不是噪音；
• CLI 在真实 profile 上 → 9 条、阻断 1（dsh-cost-meter@1.7.35）、退出码 1；
• 会话内 plugin_compat_check 工具实际调用成功，与「DSH 插件兼容性问题」提示词段落 均已在该会话生效；
• 结论与 dsh 自身的 skipping profile bundle "dsh-cost-meter" 日志逐条一致。

阶段性验证报告：report/页面预警与一键修复-验证报告-20260930.md（含逐条要求对照、真机输出、诚实边界）。

---

8. 本次改过什么 / 如何回滚

本插件在开发过程中被装进了用户的在用 profile ~/.dsh/profiles/web。改动与回滚：

改了什么（2026-09-30）：

文件	改动
~/.dsh/profiles/web/package.json	dependencies 增加 dsh-compat-vet: link:D:/playwright-AI/playwright/dsh-compat-vet；dsh.profile.bundles 末尾增加 dsh-compat-vet
~/.dsh/profiles/web/pnpm-lock.yaml	增加该 link 依赖的 lock 条目
~/.dsh/profiles/web/node_modules/dsh-compat-vet	新建 Junction，指向源码目录

同日两次改名同步（dsh-plugin-doctor → dsh-compat-doctor → 最终 dsh-compat-vet，原因见 §5）：

文件	改动
~/.dsh/profiles/web/package.json	依赖键与 bundles 条目同步改名；最后一次同时把 link: 目标路径改成改名后的源码目录
~/.dsh/profiles/web/pnpm-lock.yaml	同一条 lock 条目的键名与 link 路径同步
~/.dsh/profiles/web/node_modules/	旧 Junction 删除，新建 dsh-compat-vet Junction
源码目录	D:\playwright-AI\playwright\dsh-plugin-doctor → …\dsh-compat-vet（目录名与包名、仓库名彻底一致）

每次同步后都用只读方式复核：dsh --profile web --dump-config 里出现 - id: compat-vet / name: dsh-compat-vet，唯一的启动告警仍是本来就存在的 dsh-cost-meter，没有新增问题。

没有改：原有 8 个插件一个没动（版本、解析路径全部不变）、cordis.yml、 cordis.patch.yml、pnpm-workspace.yaml 均未改动；compatibility.json 未创建。

⚠️ 这一轮新增的「一键修复」会在你按键之后改 profile 配置（这正是它的用途）： 按 1 隔离会动 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles， 按 2 卸载会走 dsh 的 remove。每次改动前都会自动把 package.json / cordis.patch.yml / compatibility.json 备份到 ~/.dsh/profiles/web/.compat-vet-backup/<时间戳>/；复检不过会自动回滚。 本轮开发过程中没有对用户的真实 profile 执行过任何修复动作 —— 真机修复验证全程跑在临时 DSH_HOME 里（npm run verify:repair）。

改前快照：_profile-backup/20260930-152606/（安装前，含 package.json / pnpm-lock.yaml / pnpm-workspace.yaml / cordis.yml / cordis.patch.yml）与 _profile-backup/20260930-rename/（改名同步前）。

回滚（二选一）：

# 方式一：正规卸载（推荐）
dsh plugin --profile web remove dsh-compat-vet

# 方式二：直接用快照还原（连 lock 一起回到改前状态）
copy /Y _profile-backup\20260930-152606\package.json       %USERPROFILE%\.dsh\profiles\web\package.json
copy /Y _profile-backup\20260930-152606\pnpm-lock.yaml     %USERPROFILE%\.dsh\profiles\web\pnpm-lock.yaml
cd %USERPROFILE%\.dsh\profiles\web && pnpm install

_profile-backup/ 已被 .gitignore 排除：它里面是本机真实 profile 的配置快照， 不进公开仓库（report/ 同理，含本机路径与已装插件清单）。

dsh-cost-meter@1.7.35 的不兼容不是本次改动造成的 —— 它在安装本插件之前 就已经被 dsh 启动预检拒绝加载了（见 §1 的 dsh 原始日志）。本插件只是把它报了出来， 没有修改、也没有尝试修复它。

---

9. 已知限制

• 0.1.7-rc.1 之前没有兼容性预检，也没有版本豁免机制。 那些版本上不兼容的插件 会照常加载，风险直接暴露在运行时；allow-version 这条路也不适用。 本插件会如实这么说，但它无法替你拦下任何东西 —— 它只负责告诉你。
• SemVer 求值器覆盖常见语法（^ ~ >= > <= < =、||、空格分隔、 x/X/* 通配、- 连字符区间、预发布优先级），且已与真 semver 对拍 1300+ 组 零差异；但 npm 还有一些极冷门写法（如复杂嵌套、npm: 别名里的范围）未逐一对拍。
• 不联网（只有你按键选「升级」那一次会联网，因为那要装包）。因此常规体检只能告诉你 「去升级」，不会自动算出哪个版本才是兼容的 —— 那需要查 registry 的版本元数据。
• 「100%」的准确边界（§4④，这里必须说实话）：
  • 能保证的是：隔离 / 卸载之后，dsh 启动时的兼容性预检一定不会再因为这个插件拦下它 —— 依据是 profile 清单真的改了（下次启动读的就是它），并且再启动一次已经实测验证过；
  • 不能保证的是：插件升级到新版后就一定兼容（要装完才能验）， 也不能保证某个插件的运行时问题不会把 dsh 弄崩 —— 本插件管的是版本冲突导致启动失败这一件事；
  • 因此不提供「豁免（allow-version）」这个选项：豁免是"接受风险继续加载"， 它不会让启动不被拦下，与目标相反。
• 修复接口只认本机回环：从局域网地址打开的 GUI 拿不到修复功能（返回 403）， 页面其余部分照常。这是刻意取舍（该接口会改 profile 配置）。
• 修改能力依赖 dsh 自己的 pluginManager：完全没有这个服务的老宿主上， 隔离退化为自己原子写 profile 清单（结果里会明确标注「未走 dsh 服务」）， 而卸载/升级会直接报错让你改用命令行 —— 不会假装成功。
• 升级不受「保证」保护：它需要 pnpm 与网络，且装完之前无法预知新版兼不兼容； 它会如实报告结果，必要时你可以接着按「1」隔离。
• *`@deepseek-ai/的 bundle 被当作 dsh 安装自带**（依据实测的DEFAULT_PROFILE_BUNDLES` 与安装目录里是否真的存在该包，不是写死的名单）。若第三方占用了该 scope，会漏报。
• 校准是「本机这个 dsh」的实测结论。 换一台机器、换一个 dsh 版本，结论会重测； 但同一台机器上如果 dsh-app-boot 被改动过（少见），结论就以那次实测为准。
• 定位 dsh 安装目录的顺序：当前进程入口 → DSH_INSTALL_ANCHOR / DSH_ANCHOR → PATH 上的 dsh → npx 缓存 → 常见 npm 全局目录；都不中时用 --anchor 显式指定。

---

10. 目录结构

dsh-compat-vet/                # 目录名 = 包名 = GitHub 仓库名（三者彻底一致）
├── package.json                  # dsh.bundle.patch + dsh.client 声明 + bin 入口 + npm 元数据
├── cordis.patch.yml              # 把插件插进 profile 的 bundle 层
├── LICENSE                       # MIT
├── .gitignore                    # 排除私有快照与报告（见下）
├── .gitattributes                # 一律 LF 入库
├── lib/
│   ├── index.js                  # cordis 宿主插件：启动自检 + 工具 + 提示词段落 + 页面接口挂载
│   ├── adapt.js                  # 适配层：定位 + 上下文来源推导 + 运行时能力实测校准
│   ├── audit.js                  # 审计引擎（纯函数 + 文件读取，永不抛）
│   ├── upgrade.js                # 「快要不适配」预测：按声明范围推算何时会坏
│   ├── repair.js                 # 修复层：备份 → 走 dsh 服务改 → 落盘校验 + 复检 → 不过就回滚
│   ├── routes.js                 # 宿主 HTTP 接口：状态 / 发起修复 / 查询作业（回环 + 同源围栏）
│   ├── client.js                 # 页面横幅（手写 lazy-CJS，零依赖、无构建步骤）
│   ├── semver.js                 # 自包含 SemVer 范围求值器（与真 semver 对拍过）
│   ├── report.js                 # 中文报告渲染 + 修复命令生成（措辞随实测能力变）
│   ├── locate.js                 # 定位 dsh 安装目录（含从进程入口反推）
│   └── cli.js                    # 独立 CLI（dsh 起不来时用）
├── scripts/
│   ├── verify-real-boot.mjs      # 真机启动验证：每个 dsh 版本各真启动一次
│   ├── verify-real-repair.mjs    # 真机修复验证：真改一次 + 再启动一次（见 §2.6 bug 5）
│   ├── verify-tarball-install.mjs# 打包安装验证；--from-npm 可直接验线上那个包
│   ├── preview-banner.mjs        # 只读：用真实 profile 的数据把横幅渲染出来看
│   └── helpers/
│       ├── dsh-harness.mjs       # 真机验证公共件（临时 home / 启停 dsh / 建 profile）
│       └── fake-dom.mjs          # 最小假 DOM（测试与 preview 工具共用一份）
├── test/                         # 134 个用例（含 4 个真实 dsh 版本的实测对拍）
├── publish/                      # 投稿插件市场的文件与步骤（含那条 YAML 条目）
├── report/                       # 阶段性验证报告（含本机路径，故 gitignore）
└── _profile-backup/              # 本机 profile 配置快照（含插件清单，故 gitignore）