@tokensapi/dsh-plugin-check 0.1.0 → 0.3.0

package/README.md

@@ -16,6 +16,9 @@ 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` 保留临时工作区排查。
@@ -71,4 +74,6 @@ npx @tokensapi/dsh-plugin-check --json
 
 ## 上架流程中的位置
 
-市场上架要求本工具体检通过:提交插件版本后,门禁会以相同规则复检并记录"验证于运行时 x.y.z"。本地先跑一遍,提交即通过。
+1. 开发者:发布 npm 版本前本地跑体检,全绿再发。
+2. 管理员:在仓库 Actions 的 **Plugin Check** workflow 填「包名@版本」手动触发,体检报告生成在该次运行的 Summary。
+3. 上架:后台 publish 对话框把这次运行的链接填入「检查记录链接」——链接的红/绿即审核证据,`reviewed_version` 随上架落库。存在 error 的版本不满足上架条件。

package/bin/dsh-plugin-check.mjs

@@ -17,18 +17,20 @@
 import { resolve } from 'node:path'
 import { checkManifest } from '../lib/manifest-check.mjs'
 import { checkSmoke } from '../lib/smoke-check.mjs'
+import { fetchPackage } from '../lib/fetch-package.mjs'
 
 const args = process.argv.slice(2)
-const options = { dir: process.cwd(), runtime: undefined, skipSmoke: false, keepWorkspace: false, strict: false, json: false }
+const options = { dir: process.cwd(), package: undefined, 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 === '--package') { options.package = 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.stdout.write('用法: dsh-plugin-check [插件目录] [--package <name@version>] [--runtime <version>] [--skip-smoke] [--keep-workspace] [--strict] [--json]\n')
     process.exit(0)
   }
   if (arg.startsWith('--')) {
@@ -41,6 +43,16 @@ for (let index = 0; index < args.length; index += 1) {
 const findings = []
 const phases = []
 
+if (options.package !== undefined) {
+  const fetched = fetchPackage(options.package)
+  if ('error' in fetched) {
+    process.stderr.write(`无法获取 ${options.package}: ${fetched.error}
+`)
+    process.exit(1)
+  }
+  options.dir = fetched.dir
+}
+
 const manifestResult = checkManifest(options.dir, { runtime: options.runtime })
 findings.push(...manifestResult.findings)
 phases.push({ phase: 'manifest', findings: manifestResult.findings })

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: tokens-plugin-check
+      name: '@tokensapi/dsh-plugin-check'

package/lib/cowork-plugin.mjs

@@ -0,0 +1,78 @@
+/* ============================================================
+ * 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>',
+      }
+    },
+  }))
+}

package/lib/fetch-package.mjs

@@ -0,0 +1,44 @@
+/* ============================================================
+ * 已发布包获取:npm pack 指定 spec 并解包,供市场门禁按
+ * "包名@版本"体检(而不是本地目录)。
+ * ============================================================ */
+import { mkdtempSync, mkdirSync, readdirSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { runNpm } from './npm.mjs'
+
+const FETCH_TIMEOUT_MS = 180_000
+
+/**
+ * 拉取并解包一个已发布的 npm 包。
+ * @param {string} spec - 如 "@scope/name@1.2.3"(建议锁定精确版本)。
+ * @returns {{ dir: string } | { error: string }} dir 为解出的包根目录
+ *   (临时位置,由调用方决定何时清理)。
+ */
+export function fetchPackage(spec) {
+  const workspace = mkdtempSync(join(tmpdir(), 'dsh-plugin-fetch-'))
+  const pack = runNpm(['pack', spec, '--pack-destination', workspace], workspace, FETCH_TIMEOUT_MS)
+  if (pack.status !== 0) {
+    return { error: `npm pack ${spec} 失败: ${(pack.stderr || pack.stdout || '').trim().split('\n').slice(-3).join(' ')}` }
+  }
+  const tarball = readdirSync(workspace).find(name => name.endsWith('.tgz'))
+  if (tarball === undefined) return { error: 'npm pack 未产出 tgz' }
+  const extractDir = join(workspace, 'extracted')
+  mkdirSync(extractDir)
+  // Windows 自带 bsdtar,macOS/Linux 自带 tar;相对路径调用避开
+  // MSYS tar 对盘符路径的误判。
+  const extract = spawnSync('tar', ['-xzf', tarball, '-C', 'extracted'], {
+    cwd: workspace,
+    encoding: 'utf8',
+    timeout: FETCH_TIMEOUT_MS,
+    shell: process.platform === 'win32',
+  })
+  if (extract.status !== 0) {
+    return { error: `解包失败: ${(extract.stderr || '').trim().split('\n').slice(-2).join(' ')}` }
+  }
+  // npm 打包约定顶层目录名为 package/。
+  const [root] = readdirSync(extractDir)
+  if (root === undefined) return { error: '解包结果为空' }
+  return { dir: join(extractDir, root) }
+}

package/lib/npm.mjs

@@ -0,0 +1,13 @@
+/* npm 子进程调用:统一 --ignore-scripts,被检代码没有机会在检查器
+ * 进程里执行安装钩子。 */
+import { spawnSync } from 'node:child_process'
+
+export 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' },
+  })
+}

package/lib/registry-check.mjs

@@ -0,0 +1,158 @@
+/* ============================================================
+ * 已发布包体检(注册表版,零依赖纯函数)
+ * ============================================================
+ * 对 npm registry 的版本文档跑清单规则,与目录体检(manifest-check)
+ * 同一套语义,但不需要文件系统 —— 供 Cowork 插件进程内使用。
+ * 冒烟阶段无法在宿主进程执行,完整体检走 CLI 或 Plugin Check
+ * workflow。
+ * ============================================================ */
+
+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
+}
+
+/* --------------------------- 规则 --------------------------- */
+
+/**
+ * 对一份 npm 版本清单跑体检规则。
+ * @param {object} manifest - registry 版本文档(scripts/dependencies/
+ *   peerDependencies/dsh/engines/license/version)。
+ * @param {string} runtime - 目标 DSH 运行时版本。
+ * @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
+}

package/lib/smoke-check.mjs

@@ -16,6 +16,7 @@ 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'
+import { runNpm } from './npm.mjs'
 
 const RUNNER_TIMEOUT_MS = 90_000
 const INSTALL_TIMEOUT_MS = 300_000
@@ -76,15 +77,6 @@ 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' },
-  })
-}
 
 /**
  * 对插件目录执行隔离冒烟。

package/package.json

@@ -1,7 +1,7 @@
 {
   "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",
+  "version": "0.3.0",
+  "description": "TokensCowork/DSH \u63d2\u4ef6\u5408\u683c\u6027\u4f53\u68c0:CLI \u4e00\u6761\u547d\u4ee4\u5224\u5b9a\u63d2\u4ef6\u80fd\u5426\u5b89\u5168\u88c5\u5165\u5bbf\u4e3b;\u88c5\u5165 Cowork \u540e\u63d0\u4f9b\u4f1a\u8bdd\u5185 plugin_check \u5de5\u5177\u3002",
   "type": "module",
   "bin": {
     "dsh-plugin-check": "bin/dsh-plugin-check.mjs"
@@ -9,6 +9,7 @@
   "files": [
     "bin",
     "lib",
+    "cordis.patch.yml",
     "README.md"
   ],
   "scripts": {
@@ -26,5 +27,19 @@
     "type": "git",
     "url": "https://github.com/TokensAPI/TokensCowork.git",
     "directory": "plugin-check"
+  },
+  "main": "lib/cowork-plugin.mjs",
+  "exports": {
+    ".": "./lib/cowork-plugin.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.1 || 4.0.2",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.8 || 0.1.3-alpha.1"
+  },
+  "dsh": {
+    "engine": ">=0.1.0-rc.8 <0.2.0",
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
   }
 }