@tokensapi/dsh-plugin-check 0.3.1 → 0.3.2

package/README.md

@@ -1,79 +1,91 @@
-# dsh-plugin-check
-
-TokensCowork / DSH 插件合格性体检。给所有插件开发者的统一标准:一条命令,当场知道你的插件**能否安全装入宿主、会不会把用户的 Cowork 搞崩**。同一套规则同时用于:开发者本地自查、插件仓库 CI、插件市场上架门禁。
-
-## 用法
-
-```bash
-# 在插件目录里
-npx @tokensapi/dsh-plugin-check
-
-# 指定目标运行时(启用兼容范围判定;当前产品运行时版本见市场公告)
-npx @tokensapi/dsh-plugin-check --runtime 0.1.3-alpha.1
-
-# 只跑离线清单体检(秒级,无网络)
-npx @tokensapi/dsh-plugin-check --skip-smoke
-
-# 机器可读输出(CI / 市场门禁)
-npx @tokensapi/dsh-plugin-check --json
-
-# 体检一个已发布的 npm 包(市场上架审核用)
-npx @tokensapi/dsh-plugin-check --package @scope/name@1.2.3 --runtime 0.1.3-alpha.1
-```
-
-退出码:`0` 合格,`1` 存在 error(`--strict` 时 warning 也计入)。冒烟失败时加 `--keep-workspace` 保留临时工作区排查。
-
-## 体检分两个阶段
-
-**阶段① 清单体检**(纯静态、离线、秒级):检查 package.json 与 cordis 补丁的声明是否合规。
-**阶段② 隔离启动冒烟**(联网、约 1–3 分钟):在临时工作区按你声明的 peer 范围装出真实运行时,然后逐补丁行做真实网关启动时做的事——解析入口 → `import` → `new Context()` + `ctx.plugin()` 应用。三段都过,你的插件就不会以"装上即崩"的方式杀死用户的 Cowork。全程 `--ignore-scripts`,你的代码只在一次性子进程里运行,超时即杀。
-
-清单存在 error 时冒烟不执行——先修再跑。
-
-## 规则清单
-
-每条规则都对应一种真实发生过的宿主故障。
-
-| 规则 | 级别 | 内容 | 拦的是什么事故 |
-|---|---|---|---|
-| M1-manifest | error/warning | package.json 合法,name/version 齐全;预发布版本给出上架提示 | 无法入库 |
-| M2-lifecycle | error | 禁止 `preinstall/install/postinstall/prepare` 脚本(构建用 `prepack`) | 安装即执行任意代码;市场受控安装的既有红线 |
-| M3-core-peer | error | `@deepseek-ai/cordis*`、`@deepseek-ai/dsh*` 只能是 peerDependencies | 双内核实例 → Symbol 不等 → 服务注册对不上 → **Cowork 启动失败** |
-| M4-bundle | error | `dsh.bundle.patch` 必填、文件存在、能解析出插件行 | 宿主无法把插件挂进加载树 |
-| 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 不可用 |
-| M9-license | warning | 建议声明 license | 分发合规 |
-| M10-secrets | error/warning | 发布内容不得包含 `.env`、私钥等凭据样式文件 | 凭据泄露 |
-| S1-pack | error | `npm pack --ignore-scripts` 必须成功 | 包本身发布不出来 |
-| S2-install | error | 按你声明的依赖必须装得出来 | 用户受控安装会同样失败 |
-| S3/S4-apply | error | 每个补丁行:入口可解析、`import` 不抛、`ctx.plugin()` 应用不抛(声明 `inject` 等待服务注入属正常,不算失败) | **启动链击穿**——一行 import 失败会拖死整棵插件树 |
-
-## `dsh.engine` 字段
-
-在 package.json 声明你适配的 DSH 运行时范围:
-
-```json
-{
-  "dsh": {
-    "engine": ">=0.1.3-alpha.1 <0.2.0",
-    "bundle": { "patch": "./cordis.patch.yml" }
-  }
-}
-```
-
-宿主升级越过你的范围时,市场会把你的插件标记为"待适配"而不是硬载崩溃。
-
-## CI 集成示例
-
-```yaml
-# .github/workflows/check.yml
-- run: npx @tokensapi/dsh-plugin-check --runtime 0.1.3-alpha.1 --strict
-```
-
-## 上架流程中的位置
-
-1. 开发者:发布 npm 版本前本地跑体检,全绿再发。
-2. 管理员:在仓库 Actions 的 **Plugin Check** workflow 填「包名@版本」手动触发,体检报告生成在该次运行的 Summary。
-3. 上架:后台 publish 对话框把这次运行的链接填入「检查记录链接」——链接的红/绿即审核证据,`reviewed_version` 随上架落库。存在 error 的版本不满足上架条件。
+# dsh-plugin-check
+
+TokensCowork / DSH 插件合格性体检。给所有插件开发者的统一标准:一条命令,当场知道你的插件**能否安全装入宿主、会不会把用户的 Cowork 搞崩**。同一套规则同时用于:开发者本地自查、插件仓库 CI、插件市场上架门禁。
+
+## 用法
+
+```bash
+# 在插件目录里
+npx @tokensapi/dsh-plugin-check
+
+# 指定目标运行时(启用兼容范围判定;当前产品运行时版本见市场公告)
+npx @tokensapi/dsh-plugin-check --runtime 0.1.3-alpha.1
+
+# 只跑离线清单体检(秒级,无网络)
+npx @tokensapi/dsh-plugin-check --skip-smoke
+
+# 机器可读输出(CI / 市场门禁)
+npx @tokensapi/dsh-plugin-check --json
+
+# 体检一个已发布的 npm 包(市场上架审核用)
+npx @tokensapi/dsh-plugin-check --package @scope/name@1.2.3 --runtime 0.1.3-alpha.1
+```
+
+退出码:`0` 合格,`1` 存在 error(`--strict` 时 warning 也计入)。冒烟失败时加 `--keep-workspace` 保留临时工作区排查。
+
+## 体检分两个阶段
+
+**阶段① 清单体检**(纯静态、离线、秒级):检查 package.json 与 cordis 补丁的声明是否合规。
+**阶段② 隔离启动冒烟**(联网、约 1–3 分钟):在临时工作区按你声明的 peer 范围装出真实运行时,然后逐补丁行做真实网关启动时做的事——解析入口 → `import` → `new Context()` + `ctx.plugin()` 应用。三段都过,你的插件就不会以"装上即崩"的方式杀死用户的 Cowork。全程 `--ignore-scripts`,你的代码只在一次性子进程里运行,超时即杀。
+
+清单存在 error 时冒烟不执行——先修再跑。
+
+## 规则清单
+
+每条规则都对应一种真实发生过的宿主故障。
+
+| 规则 | 级别 | 内容 | 拦的是什么事故 |
+|---|---|---|---|
+| M1-manifest | error/warning | package.json 合法,name/version 齐全;预发布版本给出上架提示 | 无法入库 |
+| M2-lifecycle | error | 禁止 `preinstall/install/postinstall/prepare` 脚本(构建用 `prepack`) | 安装即执行任意代码;市场受控安装的既有红线 |
+| M3-core-peer | error | `@deepseek-ai/cordis*`、`@deepseek-ai/dsh*` 只能是 peerDependencies | 双内核实例 → Symbol 不等 → 服务注册对不上 → **Cowork 启动失败** |
+| M4-bundle | error | `dsh.bundle.patch` 必填、文件存在、能解析出插件行 | 宿主无法把插件挂进加载树 |
+| 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 不可用 |
+| M9-license | warning | 建议声明 license | 分发合规 |
+| M10-secrets | error/warning | 发布内容不得包含 `.env`、私钥等凭据样式文件 | 凭据泄露 |
+| S1-pack | error | `npm pack --ignore-scripts` 必须成功 | 包本身发布不出来 |
+| S2-install | error/warning | 按你声明的依赖必须装得出来;宿主内核包(`@deepseek-ai/*`)的内部版本在公开源取不到时降级为 warning 并跳过冒烟 | 用户受控安装会同样失败 |
+| S3/S4-apply | error | 每个补丁行:入口可解析、`import` 不抛、`ctx.plugin()` 应用不抛(声明 `inject` 等待服务注入属正常,不算失败) | **启动链击穿**——一行 import 失败会拖死整棵插件树 |
+
+## 会话内体检(装进 Cowork)
+
+本包同时是一个 Cowork 插件。装进宿主后会注册 `plugin_check` 工具,在会话里直接问"这个插件能装吗":
+
+```
+plugin_check(package="@scope/name", version="1.2.3")
+```
+
+会话内跑的是**清单规则 + 包内补丁行检查**:工具会把已发布的 tarball 取下来,解出 `cordis.patch.yml` 真读补丁行——只看 registry 清单会漏掉"补丁行 `name` 写成 cordis 插件名而不是 npm 包名"这类装上即让整棵插件树崩溃的缺陷。取不到包时如实标注补丁未检查(warning),不会因网络问题把插件判成不合格。
+
+隔离启动冒烟无法在宿主进程里执行,完整体检仍走 CLI 或 Plugin Check workflow。
+
+## `dsh.engine` 字段
+
+在 package.json 声明你适配的 DSH 运行时范围:
+
+```json
+{
+  "dsh": {
+    "engine": ">=0.1.3-alpha.1 <0.2.0",
+    "bundle": { "patch": "./cordis.patch.yml" }
+  }
+}
+```
+
+宿主升级越过你的范围时,市场会把你的插件标记为"待适配"而不是硬载崩溃。
+
+## CI 集成示例
+
+```yaml
+# .github/workflows/check.yml
+- run: npx @tokensapi/dsh-plugin-check --runtime 0.1.3-alpha.1 --strict
+```
+
+## 上架流程中的位置
+
+1. 开发者:发布 npm 版本前本地跑体检,全绿再发。
+2. 管理员:在仓库 Actions 的 **Plugin Check** workflow 填「包名@版本」手动触发,体检报告生成在该次运行的 Summary。
+3. 上架:后台 publish 对话框把这次运行的链接填入「检查记录链接」——链接的红/绿即审核证据,`reviewed_version` 随上架落库。存在 error 的版本不满足上架条件。

package/lib/cowork-plugin.mjs

@@ -1,78 +1,83 @@
-/* ============================================================
- * Cowork 插件入口:会话内插件体检工具
- * ============================================================
- * 装进 TokensCowork 后注册 plugin_check 工具:对任意 npm 插件包
- * 跑清单规则(与 CLI 的清单阶段同源),模型或用户在会话里即可
- * 判断"这个插件装进来会不会有问题"。含隔离启动冒烟的完整体检
- * 仍走 CLI:npx @tokensapi/dsh-plugin-check --package <name@ver>。
- * ============================================================ */
-import { defineTool } from '@deepseek-ai/dsh-tools'
-import { checkPublishedManifest } from './registry-check.mjs'
-
-/** 缺省比对的运行时版本;宿主升级后可通过插件配置覆盖。 */
-const DEFAULT_RUNTIME = '0.1.3-alpha.1'
-const REGISTRY = 'https://registry.npmjs.org'
-const FETCH_TIMEOUT_MS = 15_000
-
-export const name = 'tokens-plugin-check'
-export const inject = ['tools']
-
-async function fetchManifest(packageName, version) {
-  const controller = new AbortController()
-  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
-  try {
-    const response = await fetch(
-      `${REGISTRY}/${encodeURIComponent(packageName)}/${encodeURIComponent(version)}`,
-      { signal: controller.signal, headers: { accept: 'application/json' } },
-    )
-    if (!response.ok) {
-      throw new Error(response.status === 404 ? `npm 上未找到 ${packageName}@${version}` : `npm 查询失败(HTTP ${response.status})`)
-    }
-    return await response.json()
-  } finally {
-    clearTimeout(timer)
-  }
-}
-
-/**
- * @param {import('@deepseek-ai/cordis').Context} ctx
- * @param {{ runtime?: string }} [config]
- */
-export function apply(ctx, config = {}) {
-  const runtime = typeof config.runtime === 'string' && config.runtime !== '' ? config.runtime : DEFAULT_RUNTIME
-  ctx.tools.register(defineTool({
-    name: 'plugin_check',
-    description: 'Check whether a published DSH/TokensCowork plugin npm package is safe to install: '
-      + 'forbidden lifecycle scripts, dual-kernel core dependencies, missing dsh bundle patch, '
-      + 'and runtime/peer compatibility against the current DSH runtime. '
-      + 'Returns ok=false with per-rule findings when the plugin would break the host.',
-    parameters: {
-      package: {
-        type: 'string',
-        required: true,
-        description: 'npm package name, e.g. "@tokensapi/dsh-progressive-tools".',
-      },
-      version: {
-        type: 'string',
-        description: 'Exact version to check. Defaults to the latest dist-tag.',
-      },
-    },
-    output: {
-      schema: { type: 'json' },
-      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
-    },
-    isConcurrencySafe: () => true,
-    async execute(args) {
-      const manifest = await fetchManifest(args.package, args.version ?? 'latest')
-      const findings = checkPublishedManifest(manifest, runtime)
-      return {
-        package: manifest.name,
-        version: manifest.version,
-        runtime,
-        ok: !findings.some(finding => finding.level === 'error'),
-        findings,
-        note: '以上为清单规则;含隔离启动冒烟的完整体检请运行 npx @tokensapi/dsh-plugin-check --package <name@version>',
-      }
-    },
-  }))
-}
+/* ============================================================
+ * Cowork 插件入口:会话内插件体检工具
+ * ============================================================
+ * 装进 TokensCowork 后注册 plugin_check 工具:对任意 npm 插件包
+ * 跑清单规则 + 包内补丁行检查(与 CLI 的清单阶段同源),模型或
+ * 用户在会话里即可判断"这个插件装进来会不会有问题"。补丁行会
+ * 从 tarball 里真读出来 —— 只看 registry 清单会漏掉"补丁行 name
+ * 写成插件名"这类装上即崩的缺陷。含隔离启动冒烟的完整体检仍走
+ * CLI:npx @tokensapi/dsh-plugin-check --package <name@ver>。
+ * ============================================================ */
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { checkPublishedPackage } from './registry-check.mjs'
+
+/** 缺省比对的运行时版本;宿主升级后可通过插件配置覆盖。 */
+const DEFAULT_RUNTIME = '0.1.3-alpha.1'
+const REGISTRY = 'https://registry.npmjs.org'
+const FETCH_TIMEOUT_MS = 15_000
+
+export const name = 'tokens-plugin-check'
+export const inject = ['tools']
+
+async function fetchManifest(packageName, version) {
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS)
+  try {
+    const response = await fetch(
+      `${REGISTRY}/${encodeURIComponent(packageName)}/${encodeURIComponent(version)}`,
+      { signal: controller.signal, headers: { accept: 'application/json' } },
+    )
+    if (!response.ok) {
+      throw new Error(response.status === 404 ? `npm 上未找到 ${packageName}@${version}` : `npm 查询失败(HTTP ${response.status})`)
+    }
+    return await response.json()
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{ runtime?: string }} [config]
+ */
+export function apply(ctx, config = {}) {
+  const runtime = typeof config.runtime === 'string' && config.runtime !== '' ? config.runtime : DEFAULT_RUNTIME
+  ctx.tools.register(defineTool({
+    name: 'plugin_check',
+    description: 'Check whether a published DSH/TokensCowork plugin npm package is safe to install: '
+      + 'forbidden lifecycle scripts, dual-kernel core dependencies, missing dsh bundle patch, '
+      + 'and runtime/peer compatibility against the current DSH runtime. '
+      + 'Returns ok=false with per-rule findings when the plugin would break the host.',
+    parameters: {
+      package: {
+        type: 'string',
+        required: true,
+        description: 'npm package name, e.g. "@tokensapi/dsh-progressive-tools".',
+      },
+      version: {
+        type: 'string',
+        description: 'Exact version to check. Defaults to the latest dist-tag.',
+      },
+    },
+    output: {
+      schema: { type: 'json' },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
+    isConcurrencySafe: () => true,
+    async execute(args) {
+      const manifest = await fetchManifest(args.package, args.version ?? 'latest')
+      const { findings, inspectedPatch } = await checkPublishedPackage(manifest, runtime)
+      return {
+        package: manifest.name,
+        version: manifest.version,
+        runtime,
+        ok: !findings.some(finding => finding.level === 'error'),
+        inspectedPatch,
+        findings,
+        note: inspectedPatch
+          ? '以上为清单规则 + 包内补丁行检查;含隔离启动冒烟的完整体检请运行 npx @tokensapi/dsh-plugin-check --package <name@version>'
+          : '未读到包内补丁文件,补丁行未检查;请运行 npx @tokensapi/dsh-plugin-check --package <name@version> 做完整体检',
+      }
+    },
+  }))
+}

package/lib/manifest-check.mjs

@@ -1,144 +1,139 @@
-/* ============================================================
- * 阶段①:清单体检(纯静态,秒级,离线)
- * ============================================================
- * 每一条规则都对应一种已经真实发生过的"把宿主搞崩/搞坏"路径,
- * 规则说明写在 README;error 挡上架,warning 提示即将收紧或
- * 潜在错配。判定为纯函数,便于单测与市场门禁复用。
- * ============================================================ */
-import { existsSync, readFileSync, statSync } from 'node:fs'
-import { join, resolve } from 'node:path'
-import semver from 'semver'
-import { extractPatchRows } from './patch-rows.mjs'
-
-/** 安装即执行任意代码的脚本;市场受控安装的既有红线。 */
-const FORBIDDEN_LIFECYCLE = ['preinstall', 'install', 'postinstall', 'prepare']
-
-/**
- * 携带身份语义的核心包:cordis 上下文与 dsh 服务在宿主/插件各持一份时
- * Symbol 不等,注册对不上。schemastery、cosmokit 等纯工具库不在此列,
- * 插件可以正常依赖。
- */
-const CORE_SCOPE = '@deepseek-ai/'
-const isIdentityCore = (name) => name === '@deepseek-ai/cordis'
-  || name.startsWith('@deepseek-ai/cordis-')
-  || name.startsWith('@deepseek-ai/dsh')
-
-const SUSPICIOUS_FILE = /(\.env(\.|$)|id_rsa|\.pem$|\.p12$|\.key$)/u
-
-/**
- * 对一个插件目录执行全部清单规则。
- * @param {string} pluginDir - 插件根目录(含 package.json)。
- * @param {{ runtime?: string }} [options] - runtime 为目标 DSH 运行时
- *   版本(如 0.1.3-alpha.1);给出时才执行 engine/peer 与其的交集判定。
- * @returns {{ findings: Array<{level: 'error'|'warning', rule: string, message: string}>, manifest?: object, rows?: object[] }}
- */
-export function checkManifest(pluginDir, options = {}) {
-  const findings = []
-  const error = (rule, message) => findings.push({ level: 'error', rule, message })
-  const warning = (rule, message) => findings.push({ level: 'warning', rule, message })
-
-  const manifestPath = resolve(pluginDir, 'package.json')
-  if (!existsSync(manifestPath)) {
-    error('M1-manifest', 'package.json 不存在')
-    return { findings }
-  }
-  let manifest
-  try {
-    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
-  } catch (cause) {
-    error('M1-manifest', `package.json 不是合法 JSON: ${cause instanceof Error ? cause.message : String(cause)}`)
-    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 启动失败`)
-    }
-  }
-
-  const dsh = manifest.dsh ?? {}
-  const bundle = dsh.bundle ?? {}
-  let rows
-  if (typeof bundle.patch !== 'string' || bundle.patch === '') {
-    error('M4-bundle', 'dsh.bundle.patch 缺失;宿主靠它把插件挂进加载树')
-  } else {
-    const patchPath = resolve(pluginDir, bundle.patch)
-    if (!existsSync(patchPath)) {
-      error('M4-bundle', `dsh.bundle.patch 指向的文件不存在: ${bundle.patch}`)
-    } else {
-      const extracted = extractPatchRows(readFileSync(patchPath, 'utf8'))
-      for (const problem of extracted.problems) error('M4-bundle', `补丁行不合法: ${problem}`)
-      rows = extracted.rows
-      if (rows.length === 0 && extracted.problems.length === 0) {
-        error('M4-bundle', '补丁未声明任何插件行')
-      }
-      const packageName = typeof manifest.name === 'string' ? manifest.name : ''
-      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});插件只能挂载自己的入口`)
-        }
-      }
-    }
-  }
-
-  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 未声明')
-  }
-
-  const filesList = Array.isArray(manifest.files) ? manifest.files : []
-  for (const entry of filesList) {
-    if (typeof entry === 'string' && SUSPICIOUS_FILE.test(entry)) {
-      error('M10-secrets', `files 白名单包含疑似凭据文件: ${entry}`)
-    }
-  }
-  for (const candidate of ['.env', 'id_rsa']) {
-    const candidatePath = join(pluginDir, candidate)
-    if (existsSync(candidatePath) && statSync(candidatePath).isFile() && filesList.length === 0) {
-      warning('M10-secrets', `目录含 ${candidate} 且未用 files 白名单限定发布内容,npm pack 可能把它带上`)
-    }
-  }
-
-  return { findings, manifest, rows }
-}
+/* ============================================================
+ * 阶段①:清单体检(纯静态,秒级,离线)
+ * ============================================================
+ * 每一条规则都对应一种已经真实发生过的"把宿主搞崩/搞坏"路径,
+ * 规则说明写在 README;error 挡上架,warning 提示即将收紧或
+ * 潜在错配。判定为纯函数,便于单测与市场门禁复用。
+ * ============================================================ */
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import semver from 'semver'
+import { checkPatchContent } from './patch-rows.mjs'
+
+/** 安装即执行任意代码的脚本;市场受控安装的既有红线。 */
+const FORBIDDEN_LIFECYCLE = ['preinstall', 'install', 'postinstall', 'prepare']
+
+/**
+ * 携带身份语义的核心包:cordis 上下文与 dsh 服务在宿主/插件各持一份时
+ * Symbol 不等,注册对不上。schemastery、cosmokit 等纯工具库不在此列,
+ * 插件可以正常依赖。
+ */
+const CORE_SCOPE = '@deepseek-ai/'
+const isIdentityCore = (name) => name === '@deepseek-ai/cordis'
+  || name.startsWith('@deepseek-ai/cordis-')
+  || name.startsWith('@deepseek-ai/dsh')
+
+const SUSPICIOUS_FILE = /(\.env(\.|$)|id_rsa|\.pem$|\.p12$|\.key$)/u
+
+/**
+ * 对一个插件目录执行全部清单规则。
+ * @param {string} pluginDir - 插件根目录(含 package.json)。
+ * @param {{ runtime?: string }} [options] - runtime 为目标 DSH 运行时
+ *   版本(如 0.1.3-alpha.1);给出时才执行 engine/peer 与其的交集判定。
+ * @returns {{ findings: Array<{level: 'error'|'warning', rule: string, message: string}>, manifest?: object, rows?: object[] }}
+ */
+export function checkManifest(pluginDir, options = {}) {
+  const findings = []
+  const error = (rule, message) => findings.push({ level: 'error', rule, message })
+  const warning = (rule, message) => findings.push({ level: 'warning', rule, message })
+
+  const manifestPath = resolve(pluginDir, 'package.json')
+  if (!existsSync(manifestPath)) {
+    error('M1-manifest', 'package.json 不存在')
+    return { findings }
+  }
+  let manifest
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  } catch (cause) {
+    error('M1-manifest', `package.json 不是合法 JSON: ${cause instanceof Error ? cause.message : String(cause)}`)
+    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 启动失败`)
+    }
+  }
+
+  const dsh = manifest.dsh ?? {}
+  const bundle = dsh.bundle ?? {}
+  let rows
+  if (typeof bundle.patch !== 'string' || bundle.patch === '') {
+    error('M4-bundle', 'dsh.bundle.patch 缺失;宿主靠它把插件挂进加载树')
+  } else {
+    const patchPath = resolve(pluginDir, bundle.patch)
+    if (!existsSync(patchPath)) {
+      error('M4-bundle', `dsh.bundle.patch 指向的文件不存在: ${bundle.patch}`)
+    } else {
+      // M4/M5 与会话内体检共用同一份实现,避免两条路径判定漂移。
+      const checked = checkPatchContent(
+        typeof manifest.name === 'string' ? manifest.name : '',
+        readFileSync(patchPath, 'utf8'),
+      )
+      findings.push(...checked.findings)
+      rows = checked.rows
+    }
+  }
+
+  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 未声明')
+  }
+
+  const filesList = Array.isArray(manifest.files) ? manifest.files : []
+  for (const entry of filesList) {
+    if (typeof entry === 'string' && SUSPICIOUS_FILE.test(entry)) {
+      error('M10-secrets', `files 白名单包含疑似凭据文件: ${entry}`)
+    }
+  }
+  for (const candidate of ['.env', 'id_rsa']) {
+    const candidatePath = join(pluginDir, candidate)
+    if (existsSync(candidatePath) && statSync(candidatePath).isFile() && filesList.length === 0) {
+      warning('M10-secrets', `目录含 ${candidate} 且未用 files 白名单限定发布内容,npm pack 可能把它带上`)
+    }
+  }
+
+  return { findings, manifest, rows }
+}