@tokensapi/dsh-plugin-check 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# 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
+```
+
+退出码:`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
+```
+
+## 上架流程中的位置
+
+市场上架要求本工具体检通过:提交插件版本后,门禁会以相同规则复检并记录"验证于运行时 x.y.z"。本地先跑一遍,提交即通过。

package/bin/dsh-plugin-check.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/* ============================================================
+ * dsh-plugin-check:插件合格性体检 CLI
+ * ============================================================
+ * 用法:
+ *   npx @tokensapi/dsh-plugin-check [插件目录] [选项]
+ *
+ * 选项:
+ *   --runtime <version>  目标 DSH 运行时版本(启用 engine/peer 交集判定)
+ *   --skip-smoke         只跑清单体检(离线、秒级)
+ *   --keep-workspace     保留冒烟临时工作区供排查
+ *   --strict             warning 也计入失败
+ *   --json               机器可读输出(市场门禁用)
+ *
+ * 退出码:0 = 合格;1 = 存在 error(--strict 时含 warning)。
+ * ============================================================ */
+import { resolve } from 'node:path'
+import { checkManifest } from '../lib/manifest-check.mjs'
+import { checkSmoke } from '../lib/smoke-check.mjs'
+
+const args = process.argv.slice(2)
+const options = { dir: process.cwd(), runtime: undefined, skipSmoke: false, keepWorkspace: false, strict: false, json: false }
+for (let index = 0; index < args.length; index += 1) {
+  const arg = args[index]
+  if (arg === '--runtime') { options.runtime = args[++index]; continue }
+  if (arg === '--skip-smoke') { options.skipSmoke = true; continue }
+  if (arg === '--keep-workspace') { options.keepWorkspace = true; continue }
+  if (arg === '--strict') { options.strict = true; continue }
+  if (arg === '--json') { options.json = true; continue }
+  if (arg === '--help' || arg === '-h') {
+    process.stdout.write('用法: dsh-plugin-check [插件目录] [--runtime <version>] [--skip-smoke] [--keep-workspace] [--strict] [--json]\n')
+    process.exit(0)
+  }
+  if (arg.startsWith('--')) {
+    process.stderr.write(`未知选项: ${arg}\n`)
+    process.exit(2)
+  }
+  options.dir = resolve(arg)
+}
+
+const findings = []
+const phases = []
+
+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
+  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,冒烟不再执行' })
+}
+
+const errors = findings.filter(finding => finding.level === 'error')
+const warnings = findings.filter(finding => finding.level === 'warning')
+const infos = findings.filter(finding => finding.level === 'info')
+const failed = errors.length > 0 || (options.strict && warnings.length > 0)
+
+if (options.json) {
+  process.stdout.write(`${JSON.stringify({
+    ok: !failed,
+    plugin: manifestResult.manifest?.name,
+    version: manifestResult.manifest?.version,
+    runtime: options.runtime ?? null,
+    errors,
+    warnings,
+    phases,
+  }, undefined, 2)}\n`)
+  process.exit(failed ? 1 : 0)
+}
+
+const title = manifestResult.manifest?.name !== undefined
+  ? `${manifestResult.manifest.name}@${manifestResult.manifest.version ?? '?'}`
+  : options.dir
+process.stdout.write(`\ndsh-plugin-check · ${title}\n`)
+if (options.runtime !== undefined) process.stdout.write(`目标运行时: ${options.runtime}\n`)
+process.stdout.write('\n')
+for (const finding of errors) process.stdout.write(`  ❌ [${finding.rule}] ${finding.message}\n`)
+for (const finding of warnings) process.stdout.write(`  ⚠️  [${finding.rule}] ${finding.message}\n`)
+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')
+}
+process.stdout.write(failed
+  ? `结论: 不合格(${errors.length} error / ${warnings.length} warning)\n`
+  : `结论: 合格(0 error / ${warnings.length} warning)\n`)
+process.exit(failed ? 1 : 0)

package/lib/manifest-check.mjs

@@ -0,0 +1,144 @@
+/* ============================================================
+ * 阶段①:清单体检(纯静态,秒级,离线)
+ * ============================================================
+ * 每一条规则都对应一种已经真实发生过的"把宿主搞崩/搞坏"路径,
+ * 规则说明写在 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 }
+}

package/lib/patch-rows.mjs

@@ -0,0 +1,86 @@
+/* ============================================================
+ * cordis.patch.yml 行提取
+ * ============================================================
+ * 补丁文件由 cordis-plugin-loader 的方言消费,可能携带 !!js 等
+ * 自定义标签。体检工具只做只读判定,解析必须永不因未知标签而死:
+ * 未知标签统一收敛为占位对象,携带它的行照常提取,配置标记为
+ * 不可静态求值(冒烟时跳过该行的 config)。
+ * ============================================================ */
+import yaml from 'js-yaml'
+
+const JS_EXPR_PLACEHOLDER = Symbol('dsh-plugin-check:js-expr')
+
+const tolerantSchema = yaml.DEFAULT_SCHEMA.extend(
+  ['scalar', 'sequence', 'mapping'].map(kind => new yaml.Type('!', {
+    kind,
+    multi: true,
+    construct: () => ({ [JS_EXPR_PLACEHOLDER]: true }),
+  })),
+)
+
+/** 配置里是否携带无法静态求值的表达式(!!js 等自定义标签)。 */
+export function hasDynamicConfig(value) {
+  if (value === null || typeof value !== 'object') return false
+  if (value[JS_EXPR_PLACEHOLDER] === true) return true
+  const children = Array.isArray(value) ? value : Object.values(value)
+  return children.some(child => hasDynamicConfig(child))
+}
+
+/**
+ * 从补丁内容提取全部插件行。
+ * 支持顶层两种形状:直接的行数组,或 { insert: [...] } 之类的
+ * 操作映射(取所有数组值展平)。行内的 group 嵌套按 config 递归。
+ * @param {string} content - cordis.patch.yml 的完整文本。
+ * @returns {{ rows: Array<{id?: string, name: string, config?: unknown, disabled?: boolean, dynamicConfig: boolean}>, problems: string[] }}
+ */
+export function extractPatchRows(content) {
+  const problems = []
+  let document
+  try {
+    document = yaml.load(content, { schema: tolerantSchema })
+  } catch (cause) {
+    return { rows: [], problems: [`补丁不是合法 YAML: ${cause instanceof Error ? cause.message.split('\n')[0] : String(cause)}`] }
+  }
+  const topLevel = []
+  if (Array.isArray(document)) {
+    topLevel.push(...document)
+  } else if (document !== null && typeof document === 'object') {
+    for (const value of Object.values(document)) {
+      if (Array.isArray(value)) topLevel.push(...value)
+    }
+  }
+  const candidates = []
+  for (const operation of topLevel) {
+    if (Array.isArray(operation)) candidates.push(...operation)
+    else if (operation !== null && typeof operation === 'object' && !('name' in operation)) {
+      for (const value of Object.values(operation)) {
+        if (Array.isArray(value)) candidates.push(...value)
+      }
+    } else candidates.push(operation)
+  }
+  const rows = []
+  const visit = (entry, at) => {
+    if (entry === null || typeof entry !== 'object') {
+      problems.push(`${at} 不是行对象`)
+      return
+    }
+    if (entry.group === true) {
+      const children = Array.isArray(entry.config) ? entry.config : []
+      children.forEach((child, index) => visit(child, `${at} group 第 ${index + 1} 行`))
+      return
+    }
+    if (typeof entry.name !== 'string' || entry.name === '') {
+      problems.push(`${at} 缺少 name`)
+      return
+    }
+    rows.push({
+      id: typeof entry.id === 'string' ? entry.id : undefined,
+      name: entry.name,
+      config: entry.config,
+      disabled: entry.disabled === true,
+      dynamicConfig: hasDynamicConfig(entry.config),
+    })
+  }
+  candidates.forEach((entry, index) => visit(entry, `第 ${index + 1} 行`))
+  return { rows, problems }
+}

package/lib/smoke-check.mjs

@@ -0,0 +1,182 @@
+/* ============================================================
+ * 阶段②:隔离启动冒烟(联网,分钟级)
+ * ============================================================
+ * 在临时工作区里按插件自己声明的 peer 范围装出一套真实运行时,
+ * 然后在子进程里逐行做真实网关会做的事:import 补丁行入口、
+ * new Context()、ctx.plugin() 应用。这里能过,插件就不会以
+ * "装上即崩"的方式杀死用户的 Cowork:
+ *  - 装不上(依赖解析失败)在 install 步暴露;
+ *  - import 期崩溃(顶层异常/缺模块/ESM 形状)在 import 步暴露;
+ *  - 应用期崩溃(apply 抛出/插件形状不合法)在 plugin 步暴露;
+ *  - 声明了 inject 而服务未注入属正常停车,不算失败。
+ * 全程 --ignore-scripts,被测代码没有机会在检查器进程里执行
+ * 安装钩子;插件代码只在一次性子进程里运行,超时即杀。
+ * ============================================================ */
+import { spawnSync } from 'node:child_process'
+import { mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync, readdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+const RUNNER_TIMEOUT_MS = 90_000
+const INSTALL_TIMEOUT_MS = 300_000
+
+/** 子进程执行的行级冒烟脚本;结果写文件,避开插件对 stdout 的污染。 */
+const RUNNER_SOURCE = `
+import { pathToFileURL } from 'node:url'
+import { writeFileSync } from 'node:fs'
+const [workspace, resultPath, rowsJson] = process.argv.slice(2)
+const rows = JSON.parse(rowsJson)
+const results = []
+let current = null
+process.on('uncaughtException', (cause) => finish(cause))
+process.on('unhandledRejection', (cause) => finish(cause))
+function finish(cause) {
+  if (current !== null) {
+    results.push({ ...current, status: 'failed', stage: current.stage,
+      error: cause instanceof Error ? cause.message : String(cause) })
+    current = null
+  }
+  writeFileSync(resultPath, JSON.stringify(results))
+  process.exit(0)
+}
+const { createRequire } = await import('node:module')
+const workspaceRequire = createRequire(pathToFileURL(workspace + '/x.js'))
+let Context
+try {
+  const cordis = await import(pathToFileURL(workspaceRequire.resolve('@deepseek-ai/cordis')))
+  Context = cordis.Context
+} catch (cause) {
+  writeFileSync(resultPath, JSON.stringify([{ name: '@deepseek-ai/cordis', stage: 'import',
+    status: 'failed', error: '无法载入 cordis 运行时: ' + (cause instanceof Error ? cause.message : String(cause)) }]))
+  process.exit(0)
+}
+for (const row of rows) {
+  current = { name: row.name, stage: 'resolve' }
+  try {
+    const entryPath = workspaceRequire.resolve(row.name)
+    current.stage = 'import'
+    const mod = await import(pathToFileURL(entryPath))
+    const plugin = mod.default ?? mod
+    current.stage = 'apply'
+    const ctx = new Context()
+    if (row.dynamicConfig) ctx.plugin(plugin)
+    else if (row.config === undefined) ctx.plugin(plugin)
+    else ctx.plugin(plugin, row.config)
+    await new Promise((r) => setTimeout(r, 750))
+    results.push({ name: row.name, status: 'ok',
+      note: row.dynamicConfig ? '配置含动态表达式,以空配置应用' : undefined })
+    current = null
+  } catch (cause) {
+    results.push({ name: row.name, status: 'failed', stage: current.stage,
+      error: cause instanceof Error ? cause.message : String(cause) })
+    current = null
+  }
+}
+writeFileSync(resultPath, JSON.stringify(results))
+process.exit(0)
+`
+
+function runNpm(args, cwd, timeout) {
+  return spawnSync(process.platform === 'win32' ? 'npm.cmd' : 'npm', args, {
+    cwd,
+    encoding: 'utf8',
+    timeout,
+    shell: process.platform === 'win32',
+    env: { ...process.env, npm_config_ignore_scripts: 'true' },
+  })
+}
+
+/**
+ * 对插件目录执行隔离冒烟。
+ * @param {string} pluginDir - 插件根目录。
+ * @param {object} manifest - 已解析的 package.json。
+ * @param {Array<{name: string, config?: unknown, disabled?: boolean, dynamicConfig: boolean}>} rows - 补丁行。
+ * @param {{ keepWorkspace?: boolean }} [options]
+ * @returns {{ findings: Array<{level: 'error'|'warning', rule: string, message: string}>, workspace?: string }}
+ */
+export function checkSmoke(pluginDir, manifest, rows, options = {}) {
+  const findings = []
+  const error = (rule, message) => findings.push({ level: 'error', rule, message })
+  const warning = (rule, message) => findings.push({ level: 'warning', rule, message })
+
+  const workspace = mkdtempSync(join(tmpdir(), 'dsh-plugin-check-'))
+  const cleanup = () => {
+    if (options.keepWorkspace) return
+    try { rmSync(workspace, { recursive: true, force: true }) } catch { /* 临时目录残留不影响判定 */ }
+  }
+
+  try {
+    // S1 打包:--ignore-scripts 跳过 prepack 等脚本,只验证发布内容本身。
+    const pack = runNpm(['pack', resolve(pluginDir), '--ignore-scripts', '--pack-destination', workspace], workspace, INSTALL_TIMEOUT_MS)
+    if (pack.status !== 0) {
+      error('S1-pack', `npm pack 失败: ${(pack.stderr || pack.stdout || '').trim().split('\n').slice(-3).join(' ')}`)
+      return { findings, workspace: options.keepWorkspace ? workspace : undefined }
+    }
+    const tarball = readdirSync(workspace).find(name => name.endsWith('.tgz'))
+    if (tarball === undefined) {
+      error('S1-pack', 'npm pack 未产出 tgz')
+      return { findings, workspace: options.keepWorkspace ? workspace : undefined }
+    }
+
+    // S2 安装:插件走 tgz(等价用户侧的受控安装),运行时按插件自己
+    // 声明的 peer 范围解析;cordis 是冒烟宿主的最低要求,未声明则补上。
+    const dependencies = { [manifest.name]: `file:./${tarball}` }
+    const peers = manifest.peerDependencies ?? {}
+    for (const [name, range] of Object.entries(peers)) dependencies[name] = range
+    if (dependencies['@deepseek-ai/cordis'] === undefined) {
+      dependencies['@deepseek-ai/cordis'] = '*'
+      warning('S2-install', 'peerDependencies 未声明 @deepseek-ai/cordis,冒烟以最新版补齐;建议显式声明')
+    }
+    writeFileSync(join(workspace, 'package.json'), JSON.stringify({
+      name: 'dsh-plugin-check-workspace',
+      private: true,
+      dependencies,
+    }, undefined, 2))
+    const install = runNpm(
+      ['install', '--ignore-scripts', '--no-audit', '--no-fund', '--loglevel=error'],
+      workspace,
+      INSTALL_TIMEOUT_MS,
+    )
+    if (install.status !== 0) {
+      error('S2-install', `依赖装不出来(用户侧受控安装会同样失败): ${(install.stderr || '').trim().split('\n').slice(-4).join(' ')}`)
+      return { findings, workspace: options.keepWorkspace ? workspace : undefined }
+    }
+
+    // S3+S4 行级冒烟:解析/import/apply 三段判定在子进程完成。
+    const activeRows = rows.filter(row => !row.disabled)
+    if (activeRows.length === 0) {
+      warning('S3-rows', '补丁没有启用状态的行,冒烟无事可做')
+      return { findings, workspace: options.keepWorkspace ? workspace : undefined }
+    }
+    const runnerPath = join(workspace, '__runner.mjs')
+    const resultPath = join(workspace, '__result.json')
+    writeFileSync(runnerPath, RUNNER_SOURCE)
+    const run = spawnSync(process.execPath, [
+      runnerPath,
+      workspace,
+      resultPath,
+      JSON.stringify(activeRows.map(row => ({ name: row.name, config: row.config, dynamicConfig: row.dynamicConfig }))),
+    ], { cwd: workspace, encoding: 'utf8', timeout: RUNNER_TIMEOUT_MS })
+    if (!existsSync(resultPath)) {
+      const reason = run.signal === 'SIGTERM'
+        ? `超时(${RUNNER_TIMEOUT_MS / 1000}s):入口疑似在顶层做阻塞等待`
+        : (run.stderr || '子进程未产出结果').trim().split('\n').slice(-3).join(' ')
+      error('S4-apply', `冒烟子进程异常: ${reason}`)
+      return { findings, workspace: options.keepWorkspace ? workspace : undefined }
+    }
+    const results = JSON.parse(readFileSync(resultPath, 'utf8'))
+    const passed = results.filter(result => result.status === 'ok').length
+    findings.push({ level: 'info', rule: 'S4-apply', message: `隔离冒烟: ${passed}/${results.length} 行通过(解析→import→应用)` })
+    for (const result of results) {
+      if (result.status === 'ok') {
+        if (result.note !== undefined) warning('S4-apply', `${result.name}: ${result.note}`)
+        continue
+      }
+      const stageLabel = { resolve: '入口解析', import: 'import 载入', apply: '插件应用' }[result.stage] ?? result.stage
+      error('S4-apply', `${result.name} 在 ${stageLabel} 阶段失败: ${result.error}(装入用户 Cowork 会在启动链同点崩溃)`)
+    }
+    return { findings, workspace: options.keepWorkspace ? workspace : undefined }
+  } finally {
+    cleanup()
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@tokensapi/dsh-plugin-check",
+  "version": "0.1.0",
+  "description": "TokensCowork/DSH \u63d2\u4ef6\u5408\u683c\u6027\u4f53\u68c0:\u4e00\u6761\u547d\u4ee4\u5224\u65ad\u63d2\u4ef6\u80fd\u5426\u5b89\u5168\u88c5\u5165\u5bbf\u4e3b,\u4e0d\u628a Cowork \u641e\u5d29\u3002",
+  "type": "module",
+  "bin": {
+    "dsh-plugin-check": "bin/dsh-plugin-check.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test \"tests/*.test.mjs\""
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0",
+    "semver": "^7.6.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TokensAPI/TokensCowork.git",
+    "directory": "plugin-check"
+  }
+}