@tokensapi/dsh-plugin-check 0.3.3 → 0.4.0

package/lib/manifest-check.mjs

@@ -4,26 +4,112 @@
  * 每一条规则都对应一种已经真实发生过的"把宿主搞崩/搞坏"路径,
  * 规则说明写在 README;error 挡上架,warning 提示即将收紧或
  * 潜在错配。判定为纯函数,便于单测与市场门禁复用。
+ *
+ * 与会话内体检(registry-check.mjs)的关系:凡是只看清单就能判的
+ * 规则,两边**必须**调同一份实现(semver-rules / client-check /
+ * contract 里的谓词),否则同一个包在两条路径上会得出不同结论。
+ * tests/cross-path.test.mjs 是这条约束的闸门。
  * ============================================================ */
 import { existsSync, readFileSync, statSync } from 'node:fs'
 import { join, resolve } from 'node:path'
 import semver from 'semver'
 import { checkPatchContent } from './patch-rows.mjs'
+import { checkVersionRules } from './semver-rules.mjs'
+import { checkClientDeclaration } from './client-check.mjs'
+import {
+  BLOCKED_PACKAGE_NAMES,
+  HOST_NODE_ENGINES,
+  LIFECYCLE_SCRIPTS,
+  bundlePatchProblem,
+  isIdentityCore,
+  lifecycleMessage,
+  safePackageName,
+} from './contract.mjs'
 
-/** 安装即执行任意代码的脚本;市场受控安装的既有红线。 */
-const FORBIDDEN_LIFECYCLE = ['preinstall', 'install', 'postinstall', 'prepare']
+const SUSPICIOUS_FILE = /(\.env(\.|$)|id_rsa|\.pem$|\.p12$|\.key$)/u
 
 /**
- * 携带身份语义的核心包:cordis 上下文与 dsh 服务在宿主/插件各持一份时
- * Symbol 不等,注册对不上。schemastery、cosmokit 等纯工具库不在此列,
- * 插件可以正常依赖。
+ * 只看清单就能判的规则,两条执行路径共用这一份。
+ * @param {object} manifest - package.json / registry 版本文档。
+ * @param {string | undefined} runtime - 目标 DSH 运行时版本。
+ * @returns {Array<{level: string, rule: string, message: string}>}
  */
-const CORE_SCOPE = '@deepseek-ai/'
-const isIdentityCore = (name) => name === '@deepseek-ai/cordis'
-  || name.startsWith('@deepseek-ai/cordis-')
-  || name.startsWith('@deepseek-ai/dsh')
+export function checkManifestFields(manifest, runtime) {
+  const findings = []
+  const error = (rule, message) => findings.push({ level: 'error', rule, message })
+  const warning = (rule, message) => findings.push({ level: 'warning', rule, message })
 
-const SUSPICIOUS_FILE = /(\.env(\.|$)|id_rsa|\.pem$|\.p12$|\.key$)/u
+  // M1 / M6 / M7
+  findings.push(...checkVersionRules(manifest, runtime))
+
+  // M1:包名形状。上游市场验证器在拿到清单之前就用这个谓词拒绝,
+  // 名字不合规的包无论内容多干净都装不进去。
+  if (typeof manifest.name === 'string' && manifest.name !== '') {
+    if (!safePackageName(manifest.name)) {
+      error('M1-manifest', `name "${manifest.name}" 不满足市场的包名约束`
+        + `(小写字母/数字开头,只含 a-z 0-9 . _ -,可带一层 @scope,总长 ≤214);`
+        + `不满足时受控安装会在验证阶段直接拒绝`)
+    }
+    if (BLOCKED_PACKAGE_NAMES.has(manifest.name)) {
+      error('M1-manifest', `name "${manifest.name}" 是宿主/市场自身的包名,被上游列入黑名单,永远装不进市场`)
+    }
+  }
+
+  // M2
+  const scripts = manifest.scripts ?? {}
+  for (const script of LIFECYCLE_SCRIPTS) {
+    if (typeof scripts[script] === 'string') warning('M2-lifecycle', lifecycleMessage(script))
+  }
+
+  // M3
+  for (const name of Object.keys(manifest.dependencies ?? {})) {
+    if (isIdentityCore(name)) {
+      error('M3-core-peer', `${name} 出现在 dependencies;核心运行时必须声明为 peerDependencies,`
+        + `否则宿主与插件各持一份实例,服务注册无法对上,典型症状是整个 Cowork 启动失败`)
+    }
+  }
+
+  // M4:声明本身(补丁文件内容由调用方按各自的取文件方式补上)
+  const patch = manifest.dsh?.bundle?.patch
+  if (typeof patch !== 'string' || patch === '') {
+    error('M4-bundle', 'dsh.bundle.patch 缺失;宿主靠它把插件挂进加载树')
+  } else {
+    const problem = bundlePatchProblem(patch)
+    if (problem !== undefined) {
+      error('M4-bundle', `dsh.bundle.patch "${patch}" ${problem};`
+        + `市场受控安装的验证器(上游 safeBundlePatch)会直接拒绝这个包,`
+        + `用户端永远看不到一键安装按钮,只会看到手动安装命令`)
+    }
+  }
+
+  // M8
+  const nodeEngine = manifest.engines?.node
+  if (nodeEngine === undefined) {
+    warning('M8-node-engines', 'engines.node 未声明;宿主运行在 Node 22+')
+  } else if (typeof nodeEngine !== 'string' || semver.validRange(nodeEngine) === null) {
+    warning('M8-node-engines', `engines.node "${nodeEngine}" 不是合法 SemVer 范围`)
+  } else if (semver.validRange(HOST_NODE_ENGINES) !== null
+    && !semver.intersects(nodeEngine, HOST_NODE_ENGINES, { includePrerelease: true })) {
+    warning('M8-node-engines', `engines.node "${nodeEngine}" 与宿主的 "${HOST_NODE_ENGINES}" 无交集;`
+      + `包管理器会在安装阶段报 unsupported engine`)
+  }
+
+  // M9
+  if (manifest.license === undefined) warning('M9-license', 'license 未声明')
+
+  // M12
+  findings.push(...checkClientDeclaration(manifest))
+
+  // 宿主/Profile 侧字段被插件误抄
+  for (const field of ['profile', 'moduleFallback']) {
+    if (manifest.dsh?.[field] !== undefined) {
+      warning('M1-manifest', `dsh.${field} 是宿主/Profile 侧字段,插件包声明它没有作用,`
+        + `多半是从 Profile 或宿主的 package.json 误抄过来的`)
+    }
+  }
+
+  return findings
+}
 
 /**
  * 对一个插件目录执行全部清单规则。
@@ -50,40 +136,17 @@ export function checkManifest(pluginDir, options = {}) {
     return { findings }
   }
 
-  if (typeof manifest.name !== 'string' || manifest.name === '') {
-    error('M1-manifest', 'name 缺失')
-  }
-  if (typeof manifest.version !== 'string' || semver.valid(manifest.version) === null) {
-    error('M1-manifest', 'version 不是合法 SemVer')
-  } else if (semver.prerelease(manifest.version) !== null) {
-    warning('M1-manifest', `version ${manifest.version} 是预发布版;市场上架要求精确稳定版`)
-  }
-
-  const scripts = manifest.scripts ?? {}
-  for (const script of FORBIDDEN_LIFECYCLE) {
-    if (typeof scripts[script] === 'string') {
-      error('M2-lifecycle', `禁止 ${script} 生命周期脚本(安装即执行任意代码,市场受控安装会拒绝);构建请改用 prepack`)
-    }
-  }
-
-  const dependencies = manifest.dependencies ?? {}
-  for (const name of Object.keys(dependencies)) {
-    if (isIdentityCore(name)) {
-      error('M3-core-peer', `${name} 出现在 dependencies;核心运行时必须声明为 peerDependencies,否则宿主与插件各持一份实例,服务注册无法对上,典型症状是整个 Cowork 启动失败`)
-    }
-  }
+  findings.push(...checkManifestFields(manifest, options.runtime))
 
-  const dsh = manifest.dsh ?? {}
-  const bundle = dsh.bundle ?? {}
+  // M4/M5/M11 的补丁内容部分:目录路径直接读盘。
+  const patch = manifest.dsh?.bundle?.patch
   let rows
-  if (typeof bundle.patch !== 'string' || bundle.patch === '') {
-    error('M4-bundle', 'dsh.bundle.patch 缺失;宿主靠它把插件挂进加载树')
-  } else {
-    const patchPath = resolve(pluginDir, bundle.patch)
+  if (typeof patch === 'string' && patch !== '') {
+    const patchPath = resolve(pluginDir, patch)
     if (!existsSync(patchPath)) {
-      error('M4-bundle', `dsh.bundle.patch 指向的文件不存在: ${bundle.patch}`)
+      error('M4-bundle', `dsh.bundle.patch 指向的文件不存在: ${patch}`)
     } else {
-      // M4/M5 与会话内体检共用同一份实现,避免两条路径判定漂移。
+      // 与会话内体检共用同一份实现,避免两条路径判定漂移。
       const checked = checkPatchContent(
         typeof manifest.name === 'string' ? manifest.name : '',
         readFileSync(patchPath, 'utf8'),
@@ -93,35 +156,8 @@ export function checkManifest(pluginDir, options = {}) {
     }
   }
 
-  const engine = typeof dsh.engine === 'string' ? dsh.engine : undefined
-  if (engine === undefined) {
-    warning('M6-engine', 'dsh.engine 未声明(目标 DSH 运行时 SemVer 范围,如 ">=0.1.3-alpha.1 <0.2");该字段将成为上架必填')
-  } else if (semver.validRange(engine, { includePrerelease: true }) === null) {
-    error('M6-engine', `dsh.engine 不是合法 SemVer 范围: ${engine}`)
-  } else if (options.runtime !== undefined
-    && !semver.satisfies(options.runtime, engine, { includePrerelease: true })) {
-    error('M6-engine', `dsh.engine "${engine}" 不覆盖目标运行时 ${options.runtime}`)
-  }
-
-  const peers = manifest.peerDependencies ?? {}
-  if (options.runtime !== undefined) {
-    for (const [name, range] of Object.entries(peers)) {
-      if (!name.startsWith(`${CORE_SCOPE}dsh`)) continue
-      if (semver.validRange(range, { includePrerelease: true }) === null) {
-        error('M7-peer-range', `peer ${name} 的范围不合法: ${range}`)
-      } else if (!semver.satisfies(options.runtime, range, { includePrerelease: true })) {
-        warning('M7-peer-range', `peer ${name}@"${range}" 不含目标运行时 ${options.runtime};宿主升级后此插件可能在运行时断裂(接口错配类故障)`)
-      }
-    }
-  }
-
-  if (manifest.engines?.node === undefined) {
-    warning('M8-node-engines', 'engines.node 未声明;宿主运行在 Node 22+')
-  }
-  if (manifest.license === undefined) {
-    warning('M9-license', 'license 未声明')
-  }
-
+  // M10:依赖文件系统,只在目录路径可判(registry 路径没有工作区,
+  // 这是有意的差异,不是漏 —— 见 docs/CHECKS.md §1)。
   const filesList = Array.isArray(manifest.files) ? manifest.files : []
   for (const entry of filesList) {
     if (typeof entry === 'string' && SUSPICIOUS_FILE.test(entry)) {

package/lib/patch-rows.mjs

@@ -7,23 +7,51 @@
  * 不可静态求值(冒烟时跳过该行的 config)。
  * ============================================================ */
 import yaml from 'js-yaml'
+import { RESERVED_ROW_IDS, RESERVED_ROW_NAMES } from './contract.mjs'
 
 const JS_EXPR_PLACEHOLDER = Symbol('dsh-plugin-check:js-expr')
 
+/**
+ * 宽容标签前缀。
+ * js-yaml 的 multi type 查找是**对解析后的完整标签串做前缀匹配**,
+ * 所以这里必须写解析后的形式,而不是源码里的写法:
+ *  - `!foo`      → `!foo`                      (前缀 '!')
+ *  - `!!js`      → `tag:yaml.org,2002:js`      (前缀 'tag:yaml.org,2002:js')
+ *  - `!!js/function` → `tag:yaml.org,2002:js/function`(同一前缀覆盖)
+ *
+ * 只注册 '!' 曾经漏掉整个 `!!js` 家族 —— 而 `!!js` 恰恰是宿主唯一的
+ * 动态配置写法(标签定义见 deepseek-harness/scripts/cordis-yaml.ts:
+ * `new yaml.Type('tag:yaml.org,2002:js', { kind: 'scalar' })`),宿主
+ * 自带的 6 份 cordis.patch.yml 全部在用。于是"照抄宿主惯用法的插件"
+ * 被判成补丁不是合法 YAML → M4-bundle error。
+ */
+const TOLERANT_TAG_PREFIXES = ['!', 'tag:yaml.org,2002:js']
+
 const tolerantSchema = yaml.DEFAULT_SCHEMA.extend(
-  ['scalar', 'sequence', 'mapping'].map(kind => new yaml.Type('!', {
-    kind,
-    multi: true,
-    construct: () => ({ [JS_EXPR_PLACEHOLDER]: true }),
-  })),
+  TOLERANT_TAG_PREFIXES.flatMap(prefix =>
+    ['scalar', 'sequence', 'mapping'].map(kind => new yaml.Type(prefix, {
+      kind,
+      multi: true,
+      construct: () => ({ [JS_EXPR_PLACEHOLDER]: true }),
+    })),
+  ),
 )
 
-/** 配置里是否携带无法静态求值的表达式(!!js 等自定义标签)。 */
-export function hasDynamicConfig(value) {
+/**
+ * 配置里是否携带无法静态求值的表达式(!!js 等自定义标签)。
+ * YAML 锚点可以自引用,递归必须带环保护,否则一份合法补丁能把体检
+ * 工具自己搞成栈溢出。
+ * @param {unknown} value
+ * @param {WeakSet<object>} [seen]
+ * @returns {boolean}
+ */
+export function hasDynamicConfig(value, seen = new WeakSet()) {
   if (value === null || typeof value !== 'object') return false
   if (value[JS_EXPR_PLACEHOLDER] === true) return true
+  if (seen.has(value)) return false
+  seen.add(value)
   const children = Array.isArray(value) ? value : Object.values(value)
-  return children.some(child => hasDynamicConfig(child))
+  return children.some(child => hasDynamicConfig(child, seen))
 }
 
 /**
@@ -82,27 +110,94 @@ export function extractPatchRows(content) {
     })
   }
   candidates.forEach((entry, index) => visit(entry, `第 ${index + 1} 行`))
-  return { rows, problems }
+  return { rows, problems, entries: candidates }
+}
+
+/**
+ * M11:补丁行的身份约束。
+ *
+ * 这一条查的不是"插件自己能不能跑",而是"装上之后用户的 Desktop
+ * 还起不起得来"——三种写法各自对应一个宿主硬失败:
+ *
+ *  - 同层 id 重复:vendor/loader/src/config/group.ts:64 抛
+ *    `TypeError: duplicate loader entry id: <id>`;dsh-plugin-desktop
+ *    还有一道前置检查 assertUniqueEntryIds(profile.ts:633-646,在
+ *    :949 对合成后的整份行集调用)先抛 `duplicate loader entry id
+ *    "<id>" in the composed profile`。
+ *  - id 含 ':':EntryTree.sep === ':'(vendor/loader/src/config/tree.ts:8),
+ *    嵌套路径解析被破坏。
+ *  - id/name 撞宿主保留身份:见 contract.mjs 的 RESERVED_ROW_IDS。
+ *
+ * 而市场安装路径装完**从不重新解析** cordis.patch.yml(service.ts:626-665
+ * 只比对版本号,且没有回滚),所以这类包一路绿灯装上、下次开机才炸。
+ *
+ * 唯一性按"层"判,与 assertUniqueEntryIds 同构:它每递归一层新建一个
+ * Set,所以父层与子层的同名 id 不算冲突。
+ *
+ * 查不到的部分(如实说明):跨插件、以及与宿主自身行集的 id 冲突需要
+ * 完整的宿主行清单,那要求本工具跟宿主同步演进,这里只查已知保留 id。
+ *
+ * @param {unknown[]} entries - extractPatchRows 返回的原始行(含 group 行)。
+ * @returns {Array<{level: 'error', rule: string, message: string}>}
+ */
+export function checkRowIdentity(entries) {
+  const findings = []
+  const error = (message) => findings.push({ level: 'error', rule: 'M11-row-identity', message })
+
+  const visitLevel = (level, at) => {
+    const seen = new Set()
+    for (const [index, entry] of level.entries()) {
+      if (entry === null || typeof entry !== 'object') continue
+      const where = `${at}第 ${index + 1} 行`
+      const id = entry.id
+      if (typeof id === 'string') {
+        if (seen.has(id)) {
+          error(`${where} 的 id "${id}" 与同层前面的行重复;`
+            + `宿主合成加载树时会直接抛 duplicate loader entry id,`
+            + `装上这个插件的用户下次启动整个 Desktop 都起不来(不只是本插件失效)`)
+        }
+        seen.add(id)
+        if (id.includes(':')) {
+          error(`${where} 的 id "${id}" 含 ":";`
+            + `":" 是加载树的层级分隔符(EntryTree.sep),用在 id 里会破坏嵌套行的寻址`)
+        }
+        if (RESERVED_ROW_IDS.has(id)) {
+          error(`${where} 的 id "${id}" 是宿主保留行 id;`
+            + `占用它会让宿主启动时抛错或让市场 provider 整体失效,请改用带包名前缀的 id`)
+        }
+      }
+      if (typeof entry.name === 'string' && RESERVED_ROW_NAMES.has(entry.name)) {
+        error(`${where} 的 name "${entry.name}" 是宿主保留包名;该行会被静默剥离并让市场 provider 失效`)
+      }
+      if (entry.group === true && Array.isArray(entry.config)) {
+        visitLevel(entry.config, `${where} group 内 `)
+      }
+    }
+  }
+
+  visitLevel(Array.isArray(entries) ? entries : [], '')
+  return findings
+}
+
+/**
+ * 对补丁内容执行 M4/M5 判定。
+ * 目录体检与会话内体检共用这一份实现:两边曾经各写各的,结果
+ * 会话内看不到 M5,把装上即崩的插件判成合格。
+ * @param {string} packageName - 本包 npm 包名。
+ * @param {string} content - cordis.patch.yml 全文。
+ * @returns {{ findings: Array<{level: 'error', rule: string, message: string}>, rows: object[] }}
+ */
+export function checkPatchContent(packageName, content) {
+  const findings = []
+  const error = (rule, message) => findings.push({ level: 'error', rule, message })
+  const { rows, problems, entries } = extractPatchRows(content)
+  for (const problem of problems) error('M4-bundle', `补丁行不合法: ${problem}`)
+  if (rows.length === 0 && problems.length === 0) error('M4-bundle', '补丁未声明任何插件行')
+  findings.push(...checkRowIdentity(entries))
+  for (const row of rows) {
+    if (packageName !== '' && row.name !== packageName && !row.name.startsWith(`${packageName}/`)) {
+      error('M5-row-scope', `补丁行 "${row.id ?? row.name}" 指向 ${row.name},超出本包命名空间(${packageName});插件只能挂载自己的入口`)
+    }
+  }
+  return { findings, rows }
 }
-
-/**
- * 对补丁内容执行 M4/M5 判定。
- * 目录体检与会话内体检共用这一份实现:两边曾经各写各的,结果
- * 会话内看不到 M5,把装上即崩的插件判成合格。
- * @param {string} packageName - 本包 npm 包名。
- * @param {string} content - cordis.patch.yml 全文。
- * @returns {{ findings: Array<{level: 'error', rule: string, message: string}>, rows: object[] }}
- */
-export function checkPatchContent(packageName, content) {
-  const findings = []
-  const error = (rule, message) => findings.push({ level: 'error', rule, message })
-  const { rows, problems } = extractPatchRows(content)
-  for (const problem of problems) error('M4-bundle', `补丁行不合法: ${problem}`)
-  if (rows.length === 0 && problems.length === 0) error('M4-bundle', '补丁未声明任何插件行')
-  for (const row of rows) {
-    if (packageName !== '' && row.name !== packageName && !row.name.startsWith(`${packageName}/`)) {
-      error('M5-row-scope', `补丁行 "${row.id ?? row.name}" 指向 ${row.name},超出本包命名空间(${packageName});插件只能挂载自己的入口`)
-    }
-  }
-  return { findings, rows }
-}

package/lib/registry-check.mjs

@@ -1,168 +1,41 @@
 /* ============================================================
- * 已发布包体检(注册表版,零依赖纯函数)
+ * 已发布包体检(注册表版)
  * ============================================================
  * 对 npm registry 的版本文档跑清单规则,与目录体检(manifest-check)
- * 同一套语义,但不需要文件系统 —— 供 Cowork 插件进程内使用。
+ * **同一份实现** —— 不是"同一套语义"而已:清单侧规则全部来自
+ * checkManifestFields,两条路径不可能再对同一个包给出不同结论。
+ *
+ * 这里曾经自带一套手写的迷你 SemVer,理由是"会话内要零依赖";
+ * 那个前提本来就不成立(semver 是本包的 dependencies,宿主进程里
+ * 早就通过 cowork-plugin → manifest-check 加载了),代价却是把
+ * ">=0.1 <0.2"、"1.x"、"1.2.0 - 2.0.0" 这些完全合法的 npm 范围判成
+ * "不可识别" → error,合格插件被判不合格。已删除。
  *
  * 两个入口:
- *  - checkPublishedManifest 纯同步零依赖,只看清单字段;
+ *  - checkPublishedManifest 只看清单字段;
  *  - checkPublishedPackage 额外取 tarball 读出 cordis.patch.yml,
- *    补上 M4/M5 —— 只看清单会漏掉"补丁行 name 写成插件名"这类
- *    装上即让整棵插件树崩溃的缺陷。
+ *    补上 M4/M5/M11 —— 只看清单会漏掉"补丁行 name 写成插件名"
+ *    这类装上即让整棵插件树崩溃的缺陷。
  * 冒烟阶段无法在宿主进程执行,完整体检走 CLI 或 Plugin Check
  * workflow。
  * ============================================================ */
 import { checkPatchContent } from './patch-rows.mjs'
 import { fetchTarEntry } from './tarball.mjs'
+import { checkManifestFields } from './manifest-check.mjs'
 
-const FORBIDDEN_LIFECYCLE = ['preinstall', 'install', 'postinstall', 'prepare']
-const isIdentityCore = (name) =>
-  name === '@deepseek-ai/cordis' || name.startsWith('@deepseek-ai/cordis-') || name.startsWith('@deepseek-ai/dsh')
-
-/* ------------------------- 迷你 SemVer ------------------------- */
-// 只实现体检需要的子集:比较 + 范围判定(空格=且、||=或、^、~、
-// >=、>、<=、<、=、裸版本),预发布参与比较;识别不了的范围返回
-// null 由调用方按"范围不合法"处理。
-
-function parseVersion(input) {
-  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(String(input).trim())
-  if (!match) return null
-  return {
-    parts: [Number(match[1]), Number(match[2]), Number(match[3])],
-    prerelease: match[4] === undefined ? [] : match[4].split('.'),
-  }
-}
-
-function compareVersions(a, b) {
-  for (let index = 0; index < 3; index += 1) {
-    if (a.parts[index] !== b.parts[index]) return a.parts[index] < b.parts[index] ? -1 : 1
-  }
-  if (a.prerelease.length === 0 && b.prerelease.length === 0) return 0
-  if (a.prerelease.length === 0) return 1
-  if (b.prerelease.length === 0) return -1
-  const length = Math.max(a.prerelease.length, b.prerelease.length)
-  for (let index = 0; index < length; index += 1) {
-    const left = a.prerelease[index]
-    const right = b.prerelease[index]
-    if (left === undefined) return -1
-    if (right === undefined) return 1
-    const leftNumeric = /^\d+$/u.test(left)
-    const rightNumeric = /^\d+$/u.test(right)
-    if (leftNumeric && rightNumeric) {
-      if (Number(left) !== Number(right)) return Number(left) < Number(right) ? -1 : 1
-    } else if (leftNumeric !== rightNumeric) {
-      return leftNumeric ? -1 : 1
-    } else if (left !== right) {
-      return left < right ? -1 : 1
-    }
-  }
-  return 0
-}
-
-function comparatorHolds(version, operator, boundary) {
-  const cmp = compareVersions(version, boundary)
-  if (operator === '>') return cmp > 0
-  if (operator === '>=') return cmp >= 0
-  if (operator === '<') return cmp < 0
-  if (operator === '<=') return cmp <= 0
-  return cmp === 0
-}
-
-export function versionSatisfies(versionInput, rangeInput) {
-  const version = parseVersion(versionInput)
-  if (version === null) return null
-  const alternatives = String(rangeInput).split('||')
-  let recognized = false
-  for (const alternative of alternatives) {
-    const comparators = alternative.trim().split(/\s+/u).filter(Boolean)
-    if (comparators.length === 0) continue
-    let holds = true
-    let valid = true
-    for (const comparator of comparators) {
-      if (comparator === '*' || comparator === 'x') continue
-      const match = /^(>=|<=|>|<|=|\^|~)?(.+)$/u.exec(comparator)
-      const boundary = parseVersion(match[2])
-      if (boundary === null) { valid = false; break }
-      const operator = match[1] ?? '='
-      if (operator === '^') {
-        const upper = boundary.parts[0] > 0
-          ? { parts: [boundary.parts[0] + 1, 0, 0], prerelease: ['0'] }
-          : boundary.parts[1] > 0
-            ? { parts: [0, boundary.parts[1] + 1, 0], prerelease: ['0'] }
-            : { parts: [0, 0, boundary.parts[2] + 1], prerelease: ['0'] }
-        holds = holds && comparatorHolds(version, '>=', boundary) && comparatorHolds(version, '<', upper)
-      } else if (operator === '~') {
-        const upper = { parts: [boundary.parts[0], boundary.parts[1] + 1, 0], prerelease: ['0'] }
-        holds = holds && comparatorHolds(version, '>=', boundary) && comparatorHolds(version, '<', upper)
-      } else {
-        holds = holds && comparatorHolds(version, operator, boundary)
-      }
-      if (!holds) break
-    }
-    if (!valid) continue
-    recognized = true
-    if (holds) return true
-  }
-  return recognized ? false : null
-}
-
-/* --------------------------- 规则 --------------------------- */
+export { versionSatisfies } from './semver-rules.mjs'
 
 /**
  * 对一份 npm 版本清单跑体检规则。
  * @param {object} manifest - registry 版本文档(scripts/dependencies/
  *   peerDependencies/dsh/engines/license/version)。
- * @param {string} runtime - 目标 DSH 运行时版本。
+ * @param {string} [runtime] - 目标 DSH 运行时版本;省略时只判范围合法性,
+ *   不判是否覆盖(以前这是必填位置参数且无 guard,传 undefined 会产生
+ *   一批凭空的 M6/M7 error)。
  * @returns {Array<{level: 'error'|'warning', rule: string, message: string}>}
  */
 export function checkPublishedManifest(manifest, runtime) {
-  const findings = []
-  const error = (rule, message) => findings.push({ level: 'error', rule, message })
-  const warning = (rule, message) => findings.push({ level: 'warning', rule, message })
-
-  const scripts = manifest.scripts ?? {}
-  for (const script of FORBIDDEN_LIFECYCLE) {
-    if (typeof scripts[script] === 'string') {
-      error('M2-lifecycle', `禁止 ${script} 生命周期脚本(安装即执行任意代码);构建请改用 prepack`)
-    }
-  }
-
-  for (const name of Object.keys(manifest.dependencies ?? {})) {
-    if (isIdentityCore(name)) {
-      error('M3-core-peer', `${name} 出现在 dependencies;核心运行时必须是 peerDependencies,否则双内核实例会让 Cowork 启动失败`)
-    }
-  }
-
-  const bundle = manifest.dsh?.bundle ?? {}
-  if (typeof bundle.patch !== 'string' || bundle.patch === '') {
-    error('M4-bundle', 'dsh.bundle.patch 缺失;宿主靠它把插件挂进加载树')
-  }
-
-  const engine = typeof manifest.dsh?.engine === 'string' ? manifest.dsh.engine : undefined
-  if (engine === undefined) {
-    warning('M6-engine', 'dsh.engine 未声明(目标运行时 SemVer 范围);该字段将成为上架必填')
-  } else {
-    const satisfied = versionSatisfies(runtime, engine)
-    if (satisfied === null) error('M6-engine', `dsh.engine 不是可识别的 SemVer 范围: ${engine}`)
-    else if (!satisfied) error('M6-engine', `dsh.engine "${engine}" 不覆盖当前运行时 ${runtime}`)
-  }
-
-  for (const [name, range] of Object.entries(manifest.peerDependencies ?? {})) {
-    if (!name.startsWith('@deepseek-ai/dsh')) continue
-    const satisfied = versionSatisfies(runtime, String(range))
-    if (satisfied === null) error('M7-peer-range', `peer ${name} 的范围不可识别: ${range}`)
-    else if (!satisfied) warning('M7-peer-range', `peer ${name}@"${range}" 不含当前运行时 ${runtime};宿主升级后可能运行时断裂`)
-  }
-
-  if (manifest.engines?.node === undefined) warning('M8-node-engines', 'engines.node 未声明;宿主运行在 Node 22+')
-  if (manifest.license === undefined) warning('M9-license', 'license 未声明')
-
-  const parsed = parseVersion(typeof manifest.version === 'string' ? manifest.version : '')
-  if (parsed !== null && parsed.prerelease.length > 0) {
-    warning('M1-manifest', `version ${manifest.version} 是预发布版;市场上架要求精确稳定版`)
-  }
-
-  return findings
+  return checkManifestFields(manifest, runtime)
 }
 
 /**
@@ -170,7 +43,7 @@ export function checkPublishedManifest(manifest, runtime) {
  * 取不到 tarball(离线、超时、体积过大)时降级为 warning 并如实
  * 标注未检查,绝不因网络问题把插件判成不合格。
  * @param {object} manifest - registry 版本文档(需含 dist.tarball)。
- * @param {string} runtime - 目标 DSH 运行时版本。
+ * @param {string} [runtime] - 目标 DSH 运行时版本。
  * @param {{ maxBytes?: number, timeoutMs?: number }} [options]
  * @returns {Promise<{ findings: object[], inspectedPatch: boolean }>}
  */