@tokensapi/dsh-plugin-check 0.3.4 → 0.4.0

package/README.md

@@ -28,7 +28,7 @@ npx @tokensapi/dsh-plugin-check --package @scope/name@1.2.3 --runtime 0.1.3-alph
 **阶段① 清单体检**(纯静态、离线、秒级):检查 package.json 与 cordis 补丁的声明是否合规。
 **阶段② 隔离启动冒烟**(联网、约 1–3 分钟):在临时工作区按你声明的 peer 范围装出真实运行时,然后逐补丁行做真实网关启动时做的事——解析入口 → `import` → `new Context()` + `ctx.plugin()` 应用。三段都过,你的插件就不会以"装上即崩"的方式杀死用户的 Cowork。全程 `--ignore-scripts`,你的代码只在一次性子进程里运行,超时即杀。
 
-清单存在 error 时冒烟不执行——先修再跑。
+清单存在 error 时冒烟不执行——先修再跑。跳过冒烟时输出会说明**真实原因**(清单有 error / 补丁没有可用行 / 读不到 package.json / `--skip-smoke`),不会拿一个笼统的理由搪塞。
 
 ## 规则清单
 
@@ -37,16 +37,18 @@ npx @tokensapi/dsh-plugin-check --package @scope/name@1.2.3 --runtime 0.1.3-alph
 | 规则 | 级别 | 内容 | 拦的是什么事故 |
 |---|---|---|---|
 | C0-contract | warning | `--runtime` 不在本工具核对过的版本里时提示 | 拿过时的上游口径当结论 |
-| M1-manifest | error/warning | package.json 合法,name/version 齐全;预发布版本给出上架提示 | 无法入库 |
+| M1-manifest | error/warning | package.json 合法,name/version 齐全且包名满足市场约束(不在上游黑名单里);预发布版本给出上架提示 | 无法入库 |
 | M2-lifecycle | warning | 不要声明 `preinstall/install/postinstall/prepare`(构建用 `prepack`) | 受控安装未加 `--ignore-scripts`:脚本要么在用户机器上执行任意代码,要么被包管理器默认策略拦下、脚本产物缺失导致装完即坏 |
 | M3-core-peer | error | `@deepseek-ai/cordis*`、`@deepseek-ai/dsh*` 只能是 peerDependencies | 双内核实例 → Symbol 不等 → 服务注册对不上 → **Cowork 启动失败** |
-| M4-bundle | error | `dsh.bundle.patch` 必填、文件存在、能解析出插件行 | 宿主无法把插件挂进加载树 |
+| M4-bundle | error | `dsh.bundle.patch` 必填、文件存在、能解析出插件行,且路径形状满足上游 `safeBundlePatch`(相对路径、无反斜杠、无 `..`、段内无冒号、≤512 字节) | 宿主无法把插件挂进加载树;形状不合规则受控安装验证器直接拒绝,用户端只剩手动命令 |
 | M5-row-scope | error | 补丁行只能指向本包(或其子路径) | 插件行劫持挂载其他包 |
 | M6-engine | error/warning | `dsh.engine` 声明目标运行时 SemVer 范围;与 `--runtime` 不相交为 error(未声明为 warning——上游目前不强制读取此字段) | 装进不适配的宿主版本 |
-| M7-peer-range | warning | 各 `dsh-*` peer 范围应包含目标运行时 | 宿主升级后接口错配,运行时断裂 |
-| M8-node-engines | warning | 建议声明 `engines.node`(宿主为 Node 22+) | 语法/API 不可用 |
+| M7-peer-range | error/warning | 核心 peer(`@deepseek-ai/cordis*`、`@deepseek-ai/dsh*`)的范围必须合法;`dsh-*` 的范围应包含目标运行时 | 范围写坏则受控安装装不出来;不含目标运行时则宿主升级后接口错配 |
+| M8-node-engines | warning | 建议声明 `engines.node`,且要与宿主的 `^22.19.0 \|\| >=24.0.0` 有交集 | 语法/API 不可用;无交集则安装阶段报 unsupported engine |
 | M9-license | warning | 建议声明 license | 分发合规 |
 | M10-secrets | error/warning | 发布内容不得包含 `.env`、私钥等凭据样式文件 | 凭据泄露 |
+| M11-row-identity | error | 补丁行 `id` 同层不得重复、不得含 `:`、不得占用宿主保留 id(`settings`、`web-runtime` 等) | **重复 id 会让用户整个 Desktop 起不来**;而市场安装装完从不重新解析补丁、也没有回滚,一路绿灯装上、下次开机才炸 |
+| M12-client | error/warning | 声明 `dsh.client` 时,字段形状与 `exports["./client"]` 必须成立 | 宿主构造期同步解析,一份写坏会让整个 client-modules 失败——**同宿主其他插件的前端模块一起挂** |
 | S1-pack | error | `npm pack --ignore-scripts` 必须成功 | 包本身发布不出来 |
 | S2-install | error/warning | 按你声明的依赖必须装得出来;宿主内核包(`@deepseek-ai/*`)的内部版本在公开源取不到时降级为 warning 并跳过冒烟 | 用户受控安装会同样失败 |
 | S3/S4-apply | error | 每个补丁行:入口可解析、`import` 不抛、`ctx.plugin()` 应用不抛(声明 `inject` 等待服务注入属正常,不算失败) | **启动链击穿**——一行 import 失败会拖死整棵插件树 |

package/bin/dsh-plugin-check.mjs

@@ -61,19 +61,30 @@ const manifestResult = checkManifest(options.dir, { runtime: options.runtime })
 findings.push(...manifestResult.findings)
 phases.push({ phase: 'manifest', findings: manifestResult.findings })
 
-let smokeSkipped = true
-if (!options.skipSmoke
-  && manifestResult.manifest !== undefined
-  && manifestResult.rows !== undefined
-  && !manifestResult.findings.some(finding => finding.level === 'error')) {
-  smokeSkipped = false
+/**
+ * 冒烟跳过的**真实**原因。以前无论因为什么跳过都打印"清单体检存在
+ * error",作者拿着一份 0 error 的报告被告知有 error,只能干瞪眼。
+ * @returns {string | undefined} 不跳过时返回 undefined。
+ */
+function smokeSkipReason() {
+  if (options.skipSmoke) return '按 --skip-smoke 跳过'
+  if (manifestResult.manifest === undefined) return '读不到 package.json,清单体检未完成'
+  if (manifestResult.findings.some(finding => finding.level === 'error')) return '清单体检存在 error,冒烟不再执行'
+  if (manifestResult.rows === undefined) return 'dsh.bundle.patch 缺失或补丁文件读不到,没有可冒烟的插件行'
+  if (manifestResult.rows.length === 0) return '补丁未声明任何插件行,没有可冒烟的对象'
+  return undefined
+}
+
+const skipReason = smokeSkipReason()
+const smokeSkipped = skipReason !== undefined
+if (!smokeSkipped) {
   const smokeResult = checkSmoke(options.dir, manifestResult.manifest, manifestResult.rows, {
     keepWorkspace: options.keepWorkspace,
   })
   findings.push(...smokeResult.findings)
   phases.push({ phase: 'smoke', findings: smokeResult.findings, workspace: smokeResult.workspace })
 } else if (!options.skipSmoke) {
-  phases.push({ phase: 'smoke', skipped: '清单体检存在 error,冒烟不再执行' })
+  phases.push({ phase: 'smoke', skipped: skipReason })
 }
 
 const errors = findings.filter(finding => finding.level === 'error')
@@ -90,6 +101,7 @@ if (options.json) {
     contract: CONTRACT,
     errors,
     warnings,
+    infos,
     phases,
   }, undefined, 2)}\n`)
   process.exit(failed ? 1 : 0)
@@ -108,11 +120,7 @@ for (const finding of infos) process.stdout.write(`  ✅ ${finding.message}
 `)
 if (findings.length === 0) process.stdout.write('  全部规则通过\n')
 process.stdout.write('\n')
-if (smokeSkipped && !options.skipSmoke && errors.length > 0) {
-  process.stdout.write('清单存在 error,隔离冒烟未执行;修复后重跑。\n')
-} else if (options.skipSmoke) {
-  process.stdout.write('已按 --skip-smoke 跳过隔离冒烟。\n')
-}
+if (smokeSkipped) process.stdout.write(`隔离冒烟未执行:${skipReason}。\n`)
 process.stdout.write(failed
   ? `结论: 不合格(${errors.length} error / ${warnings.length} warning)\n`
   : `结论: 合格(0 error / ${warnings.length} warning)\n`)

package/docs/CHECKS.md

@@ -38,31 +38,55 @@
 
 | 入口 | 拿到的是什么 | 跑哪些规则 |
 | --- | --- | --- |
-| CLI `dsh-plugin-check [目录]` | 本地工作区文件 | M1–M10 + S1–S4(完整) |
-| CLI `--package <name@ver>` | `npm pack` 下载并解包的目录 | M1–M10 + S1–S4(完整) |
-| 会话内 `plugin_check(path=…)` | 本地工作区文件 | M1–M10 |
-| 会话内 `plugin_check(package=…)` | registry 版本清单 + tarball 里抽出的 `cordis.patch.yml` | M1–M10(除 M10 的目录扫描) |
+| CLI `dsh-plugin-check [目录]` | 本地工作区文件 | M1–M12 + S1–S4(完整) |
+| CLI `--package <name@ver>` | `npm pack` 下载并解包的目录 | M1–M12 + S1–S4(完整) |
+| 会话内 `plugin_check(path=…)` | 本地工作区文件 | M1–M12 |
+| 会话内 `plugin_check(package=…)` | registry 版本清单 + tarball 里抽出的 `cordis.patch.yml` | M1–M12(除 M10) |
 
 会话内不跑冒烟:冒烟要装依赖、起子进程、执行被测插件代码,这些不能发生在用户的
 Cowork 宿主进程里。所以会话内的结论只覆盖清单侧,输出里的 `note` 会如实说明这
 一点,不冒充完整体检。
 
-**M4/M5 只有一份实现**(`lib/patch-rows.mjs` 的 `checkPatchContent`),目录体检和
-会话内体检共用。这一点是踩过坑之后加的:两边曾经各写各的,会话内看不到 M5,把
-「装上即崩」的插件判成了合格。
+### 同源:两条路径不允许对同一个包给出不同结论
+
+- **只看清单就能判的规则只有一份实现** —— `lib/manifest-check.mjs` 的
+  `checkManifestFields`,注册表路径的 `checkPublishedManifest` 就是它的直接调用。
+  版本类判定进一步收在 `lib/semver-rules.mjs`,`dsh.client` 收在
+  `lib/client-check.mjs`,路径/包名/保留 id 这些谓词收在 `lib/contract.mjs`。
+- **M4/M5/M11 的补丁内容部分也只有一份** —— `lib/patch-rows.mjs` 的
+  `checkPatchContent`,两边只是取文件的方式不同(读盘 vs 解 tarball)。
+- `tests/cross-path.test.mjs` 是这条约束的闸门:同一份清单喂给两条路径,
+  逐条比对 `level:rule`,不一致直接红。
+
+这些都是踩过坑之后收的。0.3.x 时两边各写各的:会话内看不到 M5,把「装上即崩」的
+插件判成合格;注册表侧还自带一套手写迷你 SemVer,把 `>=1.2`、`1.x`、`1.2.0 - 2.0.0`
+这些完全合法的 npm 范围判成「不可识别」→ error,合格插件被判不合格。
+
+**唯一允许的差异是 M10-secrets**:它要扫工作区文件,registry 路径根本没有工作区。
+这是有意的取舍,不是漏。
 
 ---
 
 ## 2. 清单规则(M 系列)
 
-判定实现:`lib/manifest-check.mjs`(读磁盘)与 `lib/registry-check.mjs`(读 registry
-清单)。两份的语义相同,后者不依赖文件系统,因此内置了一个够用的迷你 SemVer。
+判定实现:`lib/manifest-check.mjs` 的 `checkManifestFields` —— **两条路径共用这一份**
+(见 §1)。版本范围一律用真 `semver`,并且一律带 `includePrerelease`:目标运行时本身
+长期是 `0.1.3-alpha.1` 这种预发布版,不带这个选项 semver 会把它排除在任何范围之外,
+得出「谁都不兼容」的荒谬结论。
 
 ### M1-manifest — 清单本身可用
 
 - **error**:`package.json` 不存在 / 不是合法 JSON / `name` 缺失 / `version` 不是
   合法 SemVer。
+- **error**:`name` 不满足市场的包名约束(小写字母或数字开头,只含 `a-z 0-9 . _ -`,
+  可带一层 `@scope`,总长 ≤214),或落在上游黑名单(`dsh-plugin-desktop`、
+  `dsh-plugin-desktop-beta`、`dsh-community-market`、`@deepseek-ai/dsh-desktop-app`)。
+  这两类包无论内容多干净都装不进市场 —— 验证器在看清单内容之前就拒了。
+  **上游锚点**:`install/service.ts:26` 的 `PACKAGE_NAME_PATTERN`、
+  `desktop-plugins.ts:193` 的 `safePackageName`、`BLOCKED_PRODUCT_PACKAGES`。
 - **warning**:`version` 是预发布版(如 `0.2.0-beta.1`)。
+- **warning**:声明了 `dsh.profile` 或 `dsh.moduleFallback` —— 这两个是宿主/Profile
+  侧字段,插件包声明它没有作用,多半是从 Profile 的 `package.json` 误抄过来的。
 - **为什么只是 warning**:上游市场的 npm 验证器要求 `latest` 是**稳定的精确版**,
   预发布版拿不到一键安装按钮,只会退回手动命令 —— 但插件完全可以把预发布发在
   `next` 之类的 dist-tag 上,让 `latest` 保持稳定。工具看到的是清单里的版本号,
@@ -105,14 +129,19 @@ Cowork 宿主进程里。所以会话内的结论只覆盖清单侧,输出里的
 - **error**:`dsh.bundle.patch` 缺失;指向的文件不存在(目录体检)或不在发布内容里
   (会话内体检,常见原因是 `files` 白名单漏了它);补丁不是合法 YAML;补丁没声明
   任何插件行。
+- **error**:`dsh.bundle.patch` 的**路径形状**不满足上游 `safeBundlePatch` —— 绝对路径
+  (`/abs/patch.yml`)、越出包根(`../outside/patch.yml`)、含反斜杠(`dist\patch.yml`)、
+  空路径段(`./a//b.yml`)、段内含冒号(`./c:/patch.yml`)、含 NUL、超过 512 字节。
+  这一条 0.3.x 时是**放行**的:这类包能装、能跑、体检全绿,但市场受控安装的验证器
+  一律拒绝 —— 用户端永远看不到一键安装按钮,只会看到手动安装命令。
 - **warning**:会话内体检取不到 tarball(离线/超时/过大)—— 如实标注「补丁行本次
   未检查」,绝不因网络问题把插件判成不合格。
 - **判什么**:宿主靠 `dsh.bundle.patch` 把插件挂进 cordis 加载树。取不到补丁,插件
   根本挂不上。
-- **上游锚点**:`dsh-community-market/src/install/service.ts` → `safeBundlePatch()`
-  (非空、≤512 字节、无 NUL、相对路径、不含反斜杠、路径段不为 `.` / `..` / 不含冒号),
-  在 `createNpmRegistryVerifier` 里强制;宿主侧 `dsh-plugin-desktop/src/profile.ts` 的
-  `DESKTOP_PATCH_PATH` 与 `profile-checkpoint.ts` 里的 `cordis.patch.yml` 条目。
+- **上游锚点**:`dsh-community-market/src/install/service.ts:268` → `safeBundlePatch()`
+  (`lib/contract.mjs` 里逐字照抄),在 `createNpmRegistryVerifier` 里强制;宿主侧
+  `dsh-plugin-desktop/src/profile.ts` 的 `DESKTOP_PATCH_PATH` 与 `profile-checkpoint.ts`
+  里的 `cordis.patch.yml` 条目。
 
 ### M5-row-scope — 补丁行只能挂自己
 
@@ -138,14 +167,24 @@ Cowork 宿主进程里。所以会话内的结论只覆盖清单侧,输出里的
 
 ### M7-peer-range — peer 范围与运行时的交集
 
-- **error**:`@deepseek-ai/dsh*` 的 peer 范围不合法/不可识别。
+- **error**:核心 peer 的范围不是合法 SemVer 范围。范围口径是全部
+  `isIdentityCore` 的包 —— `@deepseek-ai/cordis`、`@deepseek-ai/cordis-*`、
+  `@deepseek-ai/dsh*`。0.3.x 时过滤写的是 `startsWith('@deepseek-ai/dsh')`,
+  于是把 `@deepseek-ai/cordis` 的范围写成 `not-a-range` **完全不报** —— 偏偏
+  cordis 正是 S2 冒烟真正要装的那个包,范围写坏下一步必然装不出来。
 - **warning**:给了 `--runtime` 而 peer 范围不含它。
+- **「是否含目标运行时」只对 `@deepseek-ai/dsh*` 判**:核心包里只有它跟着 DSH 运行时
+  版本走,`@deepseek-ai/cordis` 自成一条 4.x 版本线。拿 `"4.0.1 || 4.0.2"` 去比对运行时
+  `0.1.3-alpha.1` 是范畴错误,不是插件的问题(本工具自己的清单就是这个形状)。
+  区分写在 `lib/contract.mjs` 的 `isRuntimeVersioned`。
 - **为什么只是 warning**:范围不含目标运行时,不代表当场就崩 —— 它预示的是宿主升级
   之后的接口错配。判死会挡住「暂时还能跑、只是没来得及放宽范围」的插件。
 
 ### M8-node-engines / M9-license
 
 - **warning**:`engines.node` 未声明(宿主跑在 Node 22+)、`license` 未声明。
+- **warning**:`engines.node` 声明了但不是合法范围,或与宿主的
+  `^22.19.0 || >=24.0.0` **无交集** —— 包管理器会在安装阶段报 unsupported engine。
 - 都是发布卫生问题,不影响能不能装,所以都不判死。
 
 ### M10-secrets — 别把凭据发上去
@@ -155,6 +194,49 @@ Cowork 宿主进程里。所以会话内的结论只覆盖清单侧,输出里的
   把它带上。
 - 只有目录体检能做后半条(要看文件系统);会话内 `package=` 模式看不到工作区。
 
+### M11-row-identity — 补丁行的 id 会崩掉整个 Desktop
+
+- **error**:同一层里 `id` 重复;`id` 含 `:`;`id` 撞宿主保留行 id
+  (`settings`、`web-runtime`、`desktop-webserver`、`community-market`、`dsh-market`);
+  行 `name` 撞宿主保留包名(`dsh-community-market`、`dshmarket`)。
+- **判什么**:这一条查的不是「插件自己能不能跑」,而是「装上之后用户的 Desktop
+  还起不起得来」。三种写法各自对应一个宿主硬失败:
+
+  | 写法 | 宿主真实行为 | 上游锚点 |
+  | --- | --- | --- |
+  | 同层 `id` 重复 | `TypeError: duplicate loader entry id: <id>`;Desktop 还有一道前置检查先抛 `duplicate loader entry id "<id>" in the composed profile` | `vendor/loader/src/config/group.ts:64`;`dsh-plugin-desktop/src/profile.ts:633-646`(在 `:949` 对**合成后**的整份行集调用) |
+  | `id` 含 `:` | `EntryTree.sep === ':'`,嵌套行的寻址被破坏 | `vendor/loader/src/config/tree.ts:8` |
+  | 撞保留身份 | 行被静默剥离,并让整个 Market provider 以 `conflicting Market provider Loader identity was removed` 失败;`settings` / `web-runtime` 则直接抛错 | `profile.ts:122-129, 704-750, 913, 955-958, 977-979`;`desktop-market.ts:28-39` |
+
+- **为什么必须是 error**:市场安装路径装完**从不重新解析** `cordis.patch.yml`
+  (`install/service.ts:626-665` 只比对版本号,而且**没有回滚**)。所以这类包一路绿灯
+  装上,下次开机才炸 —— 到那时用户面对的是一个打不开的 Cowork,而不是一个坏掉的插件。
+- **唯一性按「层」判**,与上游 `assertUniqueEntryIds` 同构:它每递归一层新建一个 Set,
+  所以父层与子层的同名 `id` 不算冲突。`group: true` 行的 `config` 数组会递归进去。
+- **查不到的部分(如实说明)**:跨插件的 id 冲突、以及与宿主自身行集的冲突,需要完整
+  的宿主行清单;那要求本工具跟宿主行集同步演进,成本与收益不匹配。这里只查已知保留 id。
+- **顶层的「修改」操作不参与判定**:形如 `- id: web-runtime` + `config:`(没有 `insert:`)
+  的顶层条目是**按 id 修改一条已存在的行**,不是新增。宿主自己的
+  `dsh-plugin-desktop/cordis.patch.yml` 就这么用,判它反而是误伤。
+
+### M12-client — `dsh.client` 声明错会拖垮别的插件
+
+- **error**:`dsh.client` 不是对象;`platform` 缺失或不是字符串;`inject` / `external`
+  不是字符串数组;`external` 条目不是精确的裸包根(scope 名恰好两段、非 scope 名不含
+  `/`)或含本包自身;`immediately` 不是布尔值;声明了 `dsh.client` 却没有
+  `exports["./client"]`,或它不是字符串 / 不是带字符串 `default` 的对象。
+- **warning**:`platform !== 'web'` —— 宿主只把 `platform === 'web'` 的行当作前端模块,
+  其他取值等于这段声明不会生效。
+- **为什么是 error 而不是「你自己的事」**:宿主的 client-modules 在**构造期同步**解析
+  所有已加载包的 `dsh.client`,一份声明写坏会抛出并让整个 client-modules fiber FAIL ——
+  受害的不止这个插件,而是同一宿主里所有需要前端模块的插件。
+- **字段全集**就是 `{ platform, inject?, external?, immediately? }`,未知键被忽略。
+- **上游锚点**:`packages/client/modules/src/index.ts` → `parseDshClient`(`:200-221`)、
+  `exactPackageSpecifier`(`:192-198`)、`clientExportOf`(`:224-234`)、
+  自引用检查(`:454-461`)、`platform === 'web'` 过滤(`:756`)、
+  缺 `./client` 的抛出(`:760-763`)。
+- 没有 `dsh.client` 的插件(绝大多数)完全不产生任何发现。
+
 ---
 
 ## 3. 隔离冒烟(S 系列,只在 CLI)
@@ -198,6 +280,16 @@ S4 之所以要在子进程里做,是因为它**真的执行插件代码**:顶
    用的是宽容 schema(未知标签收敛成占位对象),行照常提取,该行的 config 标记为
    不可静态求值,冒烟时**以空配置 apply**,并给一条 warning 说明。不因为看不懂配置
    就拒绝这个插件。
+
+   > 这条到 0.4.0 才真正做到。0.3.x 时宽容标签只注册了 `'!'` 前缀,而 js-yaml 的
+   > multi type 查找是**对解析后的完整标签串做前缀匹配**:`!env FOO` 解析成 `!env`
+   > (命中),`!!js foo` 解析成 `tag:yaml.org,2002:js`(**不命中**)。于是宿主**唯一**的
+   > 动态配置写法反而被判成「补丁不是合法 YAML」→ M4-bundle error —— 而宿主自带的
+   > 6 份 `cordis.patch.yml` 有 5 份在用它(如 dsh-base 的
+   > `root: !!js dshHomePath('sessions')`),照抄宿主惯用法的插件因此被判不合格。
+   > 现在两个前缀都注册(`'!'` 与 `'tag:yaml.org,2002:js'`,后者同时覆盖裸 `!!js`
+   > 与 `!!js/function`),并拿这 6 份真实补丁做过回归:全部 `problems === []`、行数 > 0。
+   > 标签定义见 `deepseek-harness/scripts/cordis-yaml.ts`。
 4. **`inject` 声明的服务没注入** —— 插件声明了依赖服务而冒烟环境里没有,cordis 会
    正常停车等待。这是预期行为,不算失败。
 
@@ -210,17 +302,24 @@ S4 之所以要在子进程里做,是因为它**真的执行插件代码**:顶
 
 | 规则 | 去看什么 | 什么情况下必须改 |
 | --- | --- | --- |
-| M1 | market `src/install/service.ts` → `stableExactVersion` | 稳定版要求放宽/收紧 → 调级别与措辞 |
+| M1 | market `src/install/service.ts` → `stableExactVersion`、`PACKAGE_NAME_PATTERN`(`:26`);`desktop-plugins.ts:193` → `safePackageName`、`BLOCKED_PRODUCT_PACKAGES` | 稳定版要求放宽/收紧 → 调级别与措辞;包名约束或黑名单变化 → 同步 `lib/contract.mjs` |
 | M2 | 同上 → `createNpmRegistryVerifier` 是否重新检查 `scripts`;`installOptions()` 是否加了 `--ignore-scripts`;Profile 的 `pnpm-workspace.yaml` 是否配了 `onlyBuiltDependencies` | 验证器重新拒绝脚本 → 升回 error;安装加了 `--ignore-scripts` → 改措辞 |
 | M3 | `@deepseek-ai/cordis` 主版本、dsh 服务注册方式 | 身份对齐机制改变 → 重新划 `isIdentityCore` 的范围 |
-| M4 | 同上 → `safeBundlePatch`;`dsh-plugin-desktop/src/profile.ts` 的补丁路径 | 补丁路径形状约束变化 → 同步 |
+| M4 | market `src/install/service.ts:268` → `safeBundlePatch`(本仓逐字照抄在 `lib/contract.mjs`);`dsh-plugin-desktop/src/profile.ts` 的补丁路径 | 谓词改一个字 → 同步照抄,否则我们放行的包上游照拒 |
 | M5 | `dsh-plugin-desktop/src/module-resolution.ts` → `selectedOverlayCandidate` / `PackageOverlayNotFoundError` | 行 `name` 的解析语义变化 → 这条必须跟着改 |
 | M6 | 全仓搜 `dsh.engine` 有没有被真正读取 | 一旦上游开始强制 → 「未声明」从 warning 升 error |
-| M7 | 宿主提供的 `@deepseek-ai/dsh*` 版本 | 无需改代码,更新 `CONTRACT.runtimes` 即可 |
-| M8/M9 | 宿主 Node 版本、上架元数据要求 | 要求变化 → 同步措辞 |
+| M7 | 宿主提供的 `@deepseek-ai/dsh*` 版本;`@deepseek-ai/cordis` 是否并入同一条版本线 | 版本变了只需更新 `CONTRACT.runtimes`;版本线合并 → 改 `isRuntimeVersioned` |
+| M8/M9 | 宿主 `engines.node`(现为 `^22.19.0 \|\| >=24.0.0`,记在 `HOST_NODE_ENGINES`)、上架元数据要求 | 宿主 Node 区间变化 → 同步常量 |
 | M10 | 无上游依赖(发布卫生) | 基本不用改 |
+| M11 | `vendor/loader/src/config/group.ts:64`(duplicate id 抛出)、`tree.ts:8`(`EntryTree.sep`)、`dsh-plugin-desktop/src/profile.ts:633-646` → `assertUniqueEntryIds`、`desktop-market.ts:28-39` → `DESKTOP_MARKET_IDENTITIES` | 分隔符或保留 id 集合变化 → 同步 `RESERVED_ROW_IDS` / `RESERVED_ROW_NAMES`;唯一性作用域改成全局 → 改 `checkRowIdentity` 的按层逻辑 |
+| M12 | `packages/client/modules/src/index.ts:200-221` → `parseDshClient`;`:192-198` → `exactPackageSpecifier`;`:224-234` → `clientExportOf` | 字段全集或接受形状变化 → 同步 `lib/client-check.mjs` |
 | S1–S4 | cordis 的 `new Context()` / `ctx.plugin()` API | cordis 主版本升级 → 复核 `RUNNER_SOURCE` |
 
+另外一条**没有对应规则、但复核时值得看一眼**的:`scripts/verify-cordis-config.ts` 要求
+「补丁引用的包名必须在自己的 `dependencies` 里」。这条**故意不照搬** —— 它是 monorepo
+内部约束,而第三方插件的核心包必须走 `peerDependencies`(M3),照搬会与 M3 直接打架、
+制造假报。
+
 复核完成后,请一并更新 `lib/contract.mjs` 里的 `verifiedAt`、`upstream`、`runtimes`
 和 `runtimeRange`,再 bump 版本发布 —— 这样用户从输出的基线一行就能看出「这套结论
 是照着哪个上游核对的」。

package/lib/client-check.mjs

@@ -0,0 +1,98 @@
+/* ============================================================
+ * M12-client:dsh.client 声明
+ * ============================================================
+ * 为什么这条是 error 而不是"你自己的事":宿主的 client-modules 在
+ * **构造期同步**解析所有已加载包的 dsh.client(parseDshClient,
+ * packages/client/modules/src/index.ts:200-221),一份声明写坏会抛出
+ * 并让整个 client-modules fiber FAIL —— 受害的不止这个插件,而是同
+ * 一宿主里所有需要前端模块的插件。
+ *
+ * 字段全集就是 { platform, inject?, external?, immediately? }
+ * (同文件 :51-64),未知键被忽略。
+ * ============================================================ */
+
+/**
+ * 上游 exactPackageSpecifier(index.ts:192-198):只接受精确的裸包根,
+ * scope 包恰好两段、非 scope 包不含 "/"。
+ * @param {string} specifier
+ * @returns {boolean}
+ */
+function isExactPackageSpecifier(specifier) {
+  if (specifier.startsWith('@')) {
+    const parts = specifier.split('/')
+    return parts.length === 2 && parts.every(Boolean)
+  }
+  return specifier.length > 0 && !specifier.includes('/')
+}
+
+/** 上游 clientExportOf(index.ts:224-234)接受的两种形状。 */
+function clientExportProblem(exportsField) {
+  if (typeof exportsField !== 'object' || exportsField === null) return 'missing'
+  const client = exportsField['./client']
+  if (client === undefined) return 'missing'
+  if (typeof client === 'string') return undefined
+  if (typeof client === 'object' && client !== null && typeof client.default === 'string') return undefined
+  return 'malformed'
+}
+
+/**
+ * 对一份清单执行 M12 判定。
+ * 没有 dsh.client 的插件(绝大多数)直接返回空,不产生任何噪音。
+ * @param {object} manifest - package.json / registry 版本文档。
+ * @returns {Array<{level: 'error'|'warning', rule: string, message: string}>}
+ */
+export function checkClientDeclaration(manifest) {
+  const findings = []
+  const error = (message) => findings.push({ level: 'error', rule: 'M12-client', message })
+  const warning = (message) => findings.push({ level: 'warning', rule: 'M12-client', message })
+
+  const declaration = manifest.dsh?.client
+  if (declaration === undefined) return findings
+
+  if (typeof declaration !== 'object' || declaration === null || Array.isArray(declaration)) {
+    error('dsh.client 不是对象;宿主解析到非对象声明会同步抛错,'
+      + '连带让整个 client-modules 失败(同宿主其他插件的前端模块一起挂)')
+    return findings
+  }
+
+  if (typeof declaration.platform !== 'string') {
+    error('dsh.client.platform 缺失或不是字符串;宿主 parseDshClient 会同步抛错')
+  } else if (declaration.platform !== 'web') {
+    warning(`dsh.client.platform 是 "${declaration.platform}";`
+      + '宿主只把 platform === "web" 的行当作前端模块,其他取值等于这段声明不会生效')
+  }
+
+  for (const field of ['inject', 'external']) {
+    const value = declaration[field]
+    if (value === undefined) continue
+    if (!Array.isArray(value) || value.some(item => typeof item !== 'string')) {
+      error(`dsh.client.${field} 必须是字符串数组`)
+      continue
+    }
+    if (field !== 'external') continue
+    const packageName = typeof manifest.name === 'string' ? manifest.name : ''
+    for (const item of value) {
+      if (!isExactPackageSpecifier(item)) {
+        error(`dsh.client.external 的 "${item}" 不是精确的裸包名;`
+          + 'scope 包必须恰好两段(@scope/name),非 scope 包不能含 "/"')
+      } else if (packageName !== '' && item === packageName) {
+        error(`dsh.client.external 不能包含本包自身 "${item}";`
+          + '宿主会判定这一行"请求了自己提供的模块"并抛错')
+      }
+    }
+  }
+
+  if (declaration.immediately !== undefined && typeof declaration.immediately !== 'boolean') {
+    error('dsh.client.immediately 必须是布尔值')
+  }
+
+  const exportProblem = clientExportProblem(manifest.exports)
+  if (exportProblem === 'missing') {
+    error('声明了 dsh.client 却没有 exports["./client"];'
+      + '宿主会以 "declares dsh.client but exports no ./client bundle" 抛错')
+  } else if (exportProblem === 'malformed') {
+    error('exports["./client"] 必须是字符串,或带字符串 default 的对象')
+  }
+
+  return findings
+}

package/lib/contract.mjs

@@ -78,3 +78,133 @@ export function lifecycleMessage(script) {
     + `要么在用户机器上执行任意代码,要么被包管理器默认策略拦下、脚本产物缺失导致插件装完即坏;`
     + `构建请改用 prepack`
 }
+
+/* ============================================================
+ * 上游谓词的本地副本
+ * ============================================================
+ * 下面几个判定逐字照抄上游,注释里标出锚点。照抄而不是"按理解重写"
+ * 是有意的:上游改了这几行,diff 才看得出来我们跟着漂了没有。
+ * ============================================================ */
+
+/**
+ * 携带身份语义的核心包:cordis 上下文与 dsh 服务在宿主/插件各持一份时
+ * Symbol 不等,注册对不上。schemastery、cosmokit 等纯工具库不在此列,
+ * 插件可以正常依赖。
+ */
+export const CORE_SCOPE = '@deepseek-ai/'
+
+/**
+ * 是否为带身份语义的核心包(M3 / M7 共用)。
+ * 曾经 manifest-check 与 registry-check 各存一份,这里合并为一处。
+ * @param {string} name - npm 包名。
+ * @returns {boolean}
+ */
+export function isIdentityCore(name) {
+  return name === `${CORE_SCOPE}cordis`
+    || name.startsWith(`${CORE_SCOPE}cordis-`)
+    || name.startsWith(`${CORE_SCOPE}dsh`)
+}
+
+/**
+ * 是否与 DSH 运行时**同一条版本线**。
+ *
+ * 这条区分不能省:核心包里只有 @deepseek-ai/dsh* 跟着 DSH 运行时版本
+ * 走(0.1.3-alpha.1 这类),而 @deepseek-ai/cordis 自成一条 4.x 线 ——
+ * 拿 "4.0.1 || 4.0.2" 去比对运行时 0.1.3-alpha.1,得到的"不含目标运行时"
+ * 是范畴错误,而不是插件的问题(本包自己的清单就是这个形状)。
+ * 所以 M7 的**范围合法性**覆盖全部核心包,**是否含目标运行时**只对这条线判。
+ * @param {string} name - npm 包名。
+ * @returns {boolean}
+ */
+export function isRuntimeVersioned(name) {
+  return name.startsWith(`${CORE_SCOPE}dsh`)
+}
+
+/** 上游 dsh-community-market/src/install/service.ts:26 的 PACKAGE_NAME_PATTERN。 */
+export const PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/u
+
+/**
+ * 上游 desktop-plugins.ts:193 的 safePackageName(比市场侧多一条 214 长度限制)。
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function safePackageName(value) {
+  return typeof value === 'string' && value.length <= 214 && PACKAGE_NAME_PATTERN.test(value)
+}
+
+/**
+ * 永远装不进市场的产品包名。
+ * 上游 service.ts:35 BLOCKED_PRODUCT_PACKAGES + desktop-plugins.ts IMMUTABLE_BUNDLES
+ * 里对第三方有意义的那几个(宿主自身与市场自身)。
+ */
+export const BLOCKED_PACKAGE_NAMES = new Set([
+  'dsh-plugin-desktop',
+  'dsh-plugin-desktop-beta',
+  'dsh-community-market',
+  '@deepseek-ai/dsh-desktop-app',
+])
+
+/**
+ * 上游 dsh-community-market/src/install/service.ts:268 safeBundlePatch,逐字照抄。
+ * @param {unknown} value - dsh.bundle.patch 的值。
+ * @returns {boolean}
+ */
+export function safeBundlePatch(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.length > 512 || value.includes('\0')) return false
+  const path = value.startsWith('./') ? value.slice(2) : value
+  return path.length > 0
+    && !path.startsWith('/')
+    && !path.includes('\\')
+    && path.split('/').every(segment => segment.length > 0 && segment !== '.' && segment !== '..' && !segment.includes(':'))
+}
+
+/**
+ * safeBundlePatch 不通过时,说清楚具体违反了哪一条 —— 只说"不合法"
+ * 作者无从下手。
+ * @param {string} value - 已确认为非空字符串的 patch 路径。
+ * @returns {string | undefined} 违规原因,合法时返回 undefined。
+ */
+export function bundlePatchProblem(value) {
+  if (safeBundlePatch(value)) return undefined
+  if (value.length > 512) return '超过 512 字符'
+  if (value.includes('\0')) return '含 NUL 字节'
+  const path = value.startsWith('./') ? value.slice(2) : value
+  if (path.length === 0) return '去掉 "./" 之后为空'
+  if (path.startsWith('/')) return '是绝对路径(必须相对于包根)'
+  if (path.includes('\\')) return '含反斜杠(必须用 "/" 分隔,Windows 风格路径不接受)'
+  const segments = path.split('/')
+  if (segments.some(segment => segment.length === 0)) return '含空路径段(如重复的 "//")'
+  if (segments.some(segment => segment === '.' || segment === '..')) return '含 "." 或 ".." 路径段(不得越出包根)'
+  if (segments.some(segment => segment.includes(':'))) return '路径段含 ":"'
+  return '不满足上游 safeBundlePatch'
+}
+
+/**
+ * 宿主保留的 Loader 行 id。撞上的后果不是"这个插件不生效":
+ *  - settings / web-runtime:dsh-plugin-desktop 直接抛错,Desktop 起不来
+ *    (profile.ts:955-958、977-979);
+ *  - 市场行 id:该行被静默剥离,并让整个 Market provider 以
+ *    "conflicting Market provider Loader identity was removed" 失败
+ *    (profile.ts:704-750、913)。
+ */
+export const RESERVED_ROW_IDS = new Set([
+  'settings',
+  'web-runtime',
+  'desktop-webserver',
+  // DESKTOP_MARKET_IDENTITIES.{community,dshMarket}.rowId(desktop-market.ts:31,36)
+  'community-market',
+  'dsh-market',
+])
+
+/**
+ * 宿主保留的 Loader 行 name(MARKET_PACKAGE_NAMES,desktop-market.ts:32,37)。
+ * 补丁行的 name 撞上同样触发 Market provider 失败;不过这类 name 本来就
+ * 会先被 M5 拦在"超出本包命名空间"上,这里保留是为了措辞更准确。
+ */
+export const RESERVED_ROW_NAMES = new Set([
+  'dsh-community-market',
+  'dshmarket',
+])
+
+/** 宿主 dsh-plugin-desktop 2.0.5 的 engines.node。 */
+export const HOST_NODE_ENGINES = '^22.19.0 || >=24.0.0'