@perrylink/dsh-plugin-doctor 0.1.0

package/lib/checks-collections.mjs

@@ -0,0 +1,129 @@
+// 生态·集合站清单校验（CC1–CC5）
+// 依据：工作区存量盘点（2026-09-07）——dsh-plugin-certification spec v1 注册表、
+// adp-list 收录条目 schema、dsh-catalog 市场目录、omdsh Workshop v2、dsh-plugin-kit 三门。
+import path from 'node:path'
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { runStep, pass, fail, warn, skip, tail, readJson, findFiles } from './util.mjs'
+
+export const GROUP = '生态·集合站清单'
+
+const CAT_IDS = ['agi', 'ui', 'usage', 'theme', 'model', 'identity', 'session', 'memory', 'tools', 'wsl', 'browser', 'vision', 'voice', 'docs', 'skill', 'workflow', 'git', 'notify', 'dev', 'security', 'remote', 'market', 'fun']
+const OMSDSH_ACTIVATION = ['immediate', 'hot-reload', 'restart-plugin', 'restart-profile', 'restart-host']
+
+function githubSlug(pkg) {
+  const repo = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url ?? ''
+  const m = String(repo).match(/github\.com[:/]([^/]+)\/([^/.]+?)(?:\.git)?$/)
+  return m ? { owner: m[1], repo: m[2], slug: `${m[1]}__${m[2]}` } : null
+}
+
+export function addChecks(doctor, ctx) {
+  const ws = ctx.workspaceRoot
+  const { pkg, pkgName, repoPath } = ctx
+  const g = githubSlug(pkg)
+
+  doctor.add(GROUP, 'CC1 认证注册表（dsh-plugin-certification spec v1）', () => {
+    const p = path.join(ws, 'dsh-plugin-certification', 'data', 'certified.json')
+    if (!existsSync(p)) return skip('认证仓本地不存在（--workspace 外运行无法核对）')
+    if (!g) return skip('无法从 repository 字段解析 GitHub owner/repo')
+    const data = readJson(p)
+    const hit = (data.entries ?? []).find((e) => String(e.repo).toLowerCase() === `${g.owner}/${g.repo}`.toLowerCase())
+    if (!hit) return skip('未收录于认证注册表（可选渠道）')
+    const problems = []
+    if (!hit.grade) problems.push('缺 grade')
+    if (!hit.snapshot) problems.push('缺 snapshot')
+    for (const d of ['manifest', 'buildHygiene', 'supplyChain', 'releaseIntegrity', 'installSmoke']) {
+      const dim = hit.dimensions?.[d]
+      if (!dim || !dim.evidence) problems.push(`维度 ${d} 缺 evidence`)
+      if (dim && d === 'installSmoke' && dim.result === 'install-fail') problems.push('installSmoke=install-fail（认证硬门失败级）')
+    }
+    if (hit.veto) problems.push(`存在 veto: ${JSON.stringify(hit.veto)}`)
+    if (problems.length) return warn(`已收录（grade ${hit.grade ?? '?'}）但有缺口:\n${problems.join('\n')}`)
+    const smoke = hit.dimensions.installSmoke.result
+    return pass(`grade ${hit.grade} · snapshot ${hit.snapshot} · installSmoke=${smoke} · 五维 evidence 齐全、无 veto`)
+  })
+
+  doctor.add(GROUP, 'CC2 收录条目（adp-list awesome-dsh-plugin）', () => {
+    if (!g) return skip('无法解析 GitHub slug')
+    const dir = path.join(ws, 'adp-list', 'data', 'plugins')
+    if (!existsSync(dir)) return skip('adp-list 本地不存在')
+    const hits = readdirSync(dir).filter((f) => f === `${g.slug}.yml` || f.startsWith(`${g.slug}--`))
+    if (!hits.length) return skip('未收录于 adp-list（可选渠道）')
+    const problems = []
+    for (const f of hits) {
+      const text = readFileSync(path.join(dir, f), 'utf8')
+      const kv = {}
+      // 注意：本环境 `$` 不匹配行尾孤立 \r 之前，行必须按 /\r?\n/ 切分并先剥 \r
+      for (const line0 of text.split(/\r?\n/)) {
+        const line = line0.replace(/\r$/, '')
+        const m = line.match(/^\s*([A-Za-z0-9_.-]+):\s*([\s\S]*)$/)
+        if (m) kv[m[1]] = m[2].trim()
+      }
+      for (const k of ['url', 'name', 'category']) if (!(k in kv)) problems.push(`${f}: 缺 ${k}`)
+      if (kv.category && !CAT_IDS.includes(kv.category)) problems.push(`${f}: category=${kv.category} 不在 23 值枚举`)
+      if (kv.url && !kv.url.includes(`${g.owner}/${g.repo}`)) problems.push(`${f}: url 与 repository 不符（${kv.url}）`)
+      if (!/description:/.test(text) || !/^\s*en:\s*\S+/m.test(text)) problems.push(`${f}: description.en 必填单行`)
+      if (kv.tarball) {
+        if (!/^https:\/\/(github\.com|objects\.githubusercontent\.com|release-assets\.githubusercontent\.com)\/.*\/releases\/.+\.tgz$/.test(kv.tarball)) problems.push(`${f}: tarball 必须 GitHub Release 托管 https .tgz`)
+      }
+    }
+    if (problems.length) return fail(problems.join('\n'))
+    return pass(`已收录 ${hits.length} 条（${hits.join(', ')}），字段/枚举/描述校验通过`)
+  })
+
+  doctor.add(GROUP, 'CC3 市场目录条目（dsh-catalog）', () => {
+    const p = path.join(ws, 'dsh-catalog', 'data', 'packages.json')
+    if (!existsSync(p)) return skip('dsh-catalog 本地不存在')
+    const list = readJson(p)
+    const hit = (Array.isArray(list) ? list : []).find((e) => e.npm === pkgName)
+    if (!hit) return skip('未收录于 DSH Desktop Market 目录（可选渠道）')
+    const problems = []
+    for (const k of ['npm', 'repo', 'displayName', 'categories', 'summary']) if (!(k in hit)) problems.push(`缺 ${k}`)
+    if (hit.repo && g && !String(hit.repo).includes(`${g.owner}/${g.repo}`)) problems.push('repo 字段与 repository 不符')
+    if (!Array.isArray(hit.categories) || !hit.categories.length) problems.push('categories 必须为非空数组')
+    if (typeof hit.summary === 'string' && hit.summary.length > 1000) problems.push('summary 超 v1 schema 1000 字符上限')
+    if (typeof hit.summary === 'string' && /dsh\s+plugin\s+--profile|pnpm\s+add|npm\s+i(nstall)?\s/.test(hit.summary)) problems.push('summary 含安装命令文本（v1 schema 禁止）')
+    if (typeof hit.summary === 'string' && !/[.!?)—–"」』]$/.test(hit.summary.trim())) problems.push('summary 疑被截断（未以句读符结尾）')
+    if (problems.length) return fail(problems.join('\n'))
+    return pass(`目录第 ${list.indexOf(hit) + 1} 条（displayName: ${hit.displayName}）`)
+  })
+
+  doctor.add(GROUP, 'CC4 omdsh Workshop 清单（dshWorkshop）', () => {
+    const w = pkg.dshWorkshop
+    if (!w) return skip('未声明 dshWorkshop（omdsh 可选渠道；harness 不读此字段，激活只看 dsh.bundle）')
+    const problems = []
+    const act = w.lifecycle?.activation
+    if (!act) problems.push('缺 lifecycle.activation')
+    else if (!OMSDSH_ACTIVATION.includes(act)) problems.push(`activation=${act} 不在 5 值枚举（build-omdsh-submission.mjs 会 throw）`)
+    if (problems.length) return fail(problems.join('\n'))
+    return pass(`activation=${act} · restartRequired=${/^restart-/.test(act)}（hub intake 推导规则一致）`)
+  })
+
+  doctor.add(GROUP, 'CC5 插件三门（license/五语 README/seam 三角色）', () => {
+    const kitCli = path.join(ws, 'dsh-plugin-kit', 'lib', 'verify', 'cli.js')
+    if (existsSync(kitCli)) {
+      const r = runStep('cc5-kit', process.execPath, [kitCli, 'all', repoPath], { cwd: ws, logDir: ctx.logDir, timeout: 120_000, shell: false })
+      if (r.ok) return pass('dsh-plugin-kit 三门 CLI 全过')
+      const out = `${r.out}\n${r.err}`
+      const note = /no source files found under src/.test(out)
+        ? '\n注：纯 JS 仓无 src/ 目录，kit verify-seam 结构不适用（建议 kit 扩展或人工豁免）' : ''
+      if (r.code === 1) return fail(`dsh-plugin-kit 三门失败:\n${tail(out, 12)}${note}`)
+      return fail(`dsh-plugin-kit 三门执行异常（exit ${r.code}）:\n${tail(r.err)}${note}`)
+    }
+    // 本地降级等价检查（kit lib 未构建时）
+    const problems = []
+    const hasLicenseFile = ['LICENSE', 'LICENSE.md', 'LICENSE.txt'].some((f) => existsSync(path.join(repoPath, f)))
+    if (!hasLicenseFile || !pkg.license) problems.push('缺 LICENSE 文件或 license 字段（kit 三门: error）')
+    else if (pkg.license !== 'Apache-2.0') problems.push(`license=${pkg.license}（kit 三门: warning，期望 Apache-2.0）`)
+    for (const lang of ['', '.zh', '.es', '.pt', '.hi']) {
+      const p = path.join(repoPath, `README${lang}.md`)
+      if (!existsSync(p)) problems.push(`缺 README${lang}.md`)
+    }
+    const srcFiles = findFiles(repoPath, 'src', /\.(ts|tsx|mjs|js)$/)
+    const all = srcFiles.map((f) => { try { return readFileSync(f, 'utf8') } catch { return '' } }).join('\n')
+    for (const marker of ['Service Definition', 'Service Provider', 'Consumer']) {
+      if (!all.includes(marker)) problems.push(`src 缺 seam 三角色 marker: ${marker}`)
+    }
+    if (problems.length) return fail(`三门（本地降级检查）未过:\n${problems.join('\n')}`)
+    return pass('三门本地降级检查通过（kit CLI 未构建，跳过官方实现）')
+  })
+}

package/lib/checks-cordis.mjs

@@ -0,0 +1,196 @@
+// 静态·cordis 契约扫描（K1–K9，启发式）
+// 依据：cordiverse/cordis v4 源码契约 + DSH 官方 cordis 文档（2026-09-07 调研）：
+//  - apply 可同步，亦可 async 返回 Promise<disposer>；返回非法形状抛 TypeError('Invalid effect')
+//  - inject 硬依赖 = (keyof M)[] | { name?: interceptConfig }；可选依赖走 ctx.get(name)
+//  - v4 删除 v3 的 fork/reusable/using/scope/runtime/lifecycle/config/collect/accept/decline/alias/off
+//  - ctx 活数据不可 JSON.stringify/structuredClone/展开
+import path from 'node:path'
+import { readFileSync, readdirSync } from 'node:fs'
+import { pass, fail, warn, skip, findFiles } from './util.mjs'
+
+export const GROUP = '静态·cordis 契约扫描'
+
+// v4 Context 固有成员（访问无需 inject）。v3 已删除成员（scope/config/fork/...）故意不列入，
+// 由 K7 精确追责。
+const CTX_INTRINSIC = new Set([
+  'get', 'on', 'once', 'effect', 'set', 'root', 'plugin', 'emit',
+  'parallel', 'waterfall', 'bail', 'serial', 'logger', 'name', 'deps',
+  'isolate', 'intercept', 'extend', 'accessor', 'mixin', 'provide',
+  'reflect', 'registry', 'inject', 'fiber', 'filter', 'select',
+])
+const KNOWN_SEAMS = new Set([
+  'tools', 'llm', 'shell', 'jobs', 'commands', 'web', 'logger', 'config', 'storage',
+  'session', 'sessions', 'slots', 'locale', 'connection', 'remote', 'settingsScope',
+  'approval', 'credentials', 'subagents', 'settings', 'systemPrompt',
+])
+
+// 剥注释后再扫描（JSDoc 里的 ctx.xxx 引用是假阳性大户）；(^|[^:]) 守卫避免伤及字符串内 ://
+function stripComments(text) {
+  return text
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/.*$/gm, '$1')
+}
+
+function readAll(files) {
+  return files.map((f) => { try { return { f, text: stripComments(readFileSync(f, 'utf8')) } } catch { return { f, text: '' } } })
+}
+
+const short = (f) => f.split(/[\\/]/).pop()
+
+// 源文件发现策略：src/** + 根目录一层 JS/TS；纯 JS 仓（无 build 脚本且 main 指向 lib/）的 lib 即源码
+function collectSourceFiles(ctx) {
+  const { repoPath, pkg } = ctx
+  const files = findFiles(repoPath, 'src', /\.(ts|mts|tsx|mjs|js)$/)
+  for (const entry of readdirSync(repoPath, { withFileTypes: true })) {
+    if (!entry.isFile()) continue
+    if (/\.(mjs|js|cjs|ts|mts|cts)$/.test(entry.name)) files.push(path.join(repoPath, entry.name))
+  }
+  if (!pkg.scripts?.build && String(pkg.main ?? '').startsWith('lib/')) {
+    files.push(...findFiles(repoPath, 'lib', /\.(mjs|js|cjs)$/))
+  }
+  return [...new Set(files)]
+}
+
+export function addChecks(doctor, ctx) {
+  const srcFiles = collectSourceFiles(ctx)
+
+  doctor.add(GROUP, 'K1 服务访问与 inject 声明一致', () => {
+    if (!srcFiles.length) return skip('无源文件可扫描')
+    const all = readAll(srcFiles)
+    // 全仓 inject 并集（多文件插件架构：inject 常集中声明在入口文件）
+    const injectList = new Set()
+    for (const { text } of all) {
+      const injectDecl = text.match(/(?:export\s+)?(?:const\s+)?inject\s*[:=]\s*\[([^\]]*)\]/)
+      for (const s of injectDecl?.[1]?.match(/['"][^'"]*['"]/g) ?? []) injectList.add(s.slice(1, -1))
+    }
+    const candidates = new Map()
+    for (const { f, text } of all) {
+      for (const m of text.matchAll(/ctx\.([A-Za-z_$][\w$]*)/g)) {
+        const name = m[1]
+        if (CTX_INTRINSIC.has(name) || injectList.has(name)) continue
+        if (!candidates.has(name)) candidates.set(name, [])
+        candidates.get(name).push(f)
+      }
+    }
+    if (!candidates.size) return pass('未发现未声明的 ctx.<服务> 访问')
+    const lines = [...candidates.entries()].slice(0, 10)
+      .map(([n, fs]) => `ctx.${n}（${fs.length} 处，如 ${short(fs[0])}）`)
+    return warn(
+      `以下服务被直接访问但未在 inject 声明（硬依赖必须 inject，否则运行时抛 "cannot get property ... without inject"；可选依赖应改用 ctx.get()）:\n${lines.join('\n')}`,
+    )
+  })
+
+  doctor.add(GROUP, 'K2 活数据序列化红线', () => {
+    if (!srcFiles.length) return skip('无源文件可扫描')
+    const hits = []
+    for (const { f, text } of readAll(srcFiles)) {
+      for (const m of text.matchAll(/JSON\.stringify\(\s*ctx\b|structuredClone\(\s*ctx\b|\{\s*\.\.\.ctx\b/g)) {
+        hits.push(`${short(f)}: ${m[0]}`)
+      }
+    }
+    if (hits.length) return fail(`检测到对 ctx 活数据的序列化/展开（Context 是 Proxy，序列化会丢 def/use-site 追踪或触发代理陷阱）:\n${hits.slice(0, 5).join('\n')}`)
+    return pass('未发现 ctx 序列化/展开')
+  })
+
+  doctor.add(GROUP, 'K3 定时器/全局监听生命周期', () => {
+    if (!srcFiles.length) return skip('无源文件可扫描')
+    const hits = []
+    for (const { f, text } of readAll(srcFiles)) {
+      const lines = text.split('\n')
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i]
+        if (!/(setInterval|setTimeout|setImmediate|process\.on|addEventListener\()/.test(line)) continue
+        const before = lines.slice(Math.max(0, i - 3), i).join('\n')
+        if (!/ctx\.effect|ctx\.scope|ctx\.on\b/.test(before) && !/return\s*\(\)\s*=>/.test(before + line)) {
+          hits.push(`${short(f)}:${i + 1} ${line.trim()}`)
+        }
+      }
+    }
+    if (hits.length) return warn(`定时器/全局监听疑似未包装进 ctx.effect（"Cordis API 之外的资源必须包在 ctx.effect 中"——教程 02；卸载后不回收，HMR 泄漏）:\n${hits.slice(0, 5).join('\n')}`)
+    return pass('未发现裸定时器/全局监听')
+  })
+
+  doctor.add(GROUP, 'K4 Schema 含函数', () => {
+    if (!srcFiles.length) return skip('无源文件可扫描')
+    const hits = []
+    for (const { f, text } of readAll(srcFiles)) {
+      if (/Schema\./.test(text) && /=>/.test(text)) hits.push(short(f))
+    }
+    if (hits.length) return warn(`以下文件同时出现 Schema 与箭头函数（函数值进不了 schema：不可校验、不可持久化）:\n${hits.slice(0, 5).join('\n')}`)
+    return pass('未发现 Schema 定义旁箭头函数')
+  })
+
+  doctor.add(GROUP, 'K5 apply 返回形状（v4 Effect 契约）', () => {
+    if (!srcFiles.length) return skip('无源文件可扫描')
+    const notes = []
+    for (const { f, text } of readAll(srcFiles)) {
+      if (/export\s+async\s+function\s+apply|apply\s*:\s*async\s*\(/.test(text)) {
+        notes.push(`${short(f)}: async apply（v4 允许，但必须返回 Promise<disposer>；settle 前 fiber 停留 LOADING、其服务对依赖方不可见）`)
+      }
+    }
+    if (notes.length) return warn(notes.join('\n') + '\nv4 合法返回值：函数 disposer / null / undefined / Promise<disposer> / (async) iterable；其余形状抛 TypeError("Invalid effect")')
+    return pass('apply 为同步声明')
+  })
+
+  doctor.add(GROUP, 'K6 inject 服务名属于已知 seam', () => {
+    if (!srcFiles.length) return skip('无源文件可扫描')
+    const unknown = new Set()
+    const provided = new Set()
+    for (const { text } of readAll(srcFiles)) {
+      const injectDecl = text.match(/(?:export\s+)?(?:const\s+)?inject\s*[:=]\s*\[([^\]]*)\]/)
+      for (const s of injectDecl?.[1]?.match(/['"][^'"]*['"]/g) ?? []) {
+        const name = s.slice(1, -1)
+        if (!KNOWN_SEAMS.has(name) && !name.includes('.')) unknown.add(name)
+      }
+      // 插件自 provide 的服务不算"未知"（自建 capability seam）
+      for (const m of text.matchAll(/(?:ctx\.)?provide\s*\(\s*['"]([^'"]+)['"]/g)) provided.add(m[1])
+    }
+    for (const p of provided) unknown.delete(p)
+    if (unknown.size) return warn(`inject 引用未知服务名（请确认由宿主/其它插件提供，否则 fiber 永久 PENDING、apply 永不执行）: ${[...unknown].join(', ')}`)
+    return pass('inject 服务名均在已知 seam 内或为自 provide 能力')
+  })
+
+  doctor.add(GROUP, 'K7 v3 遗留 API（3.x→4.x 已删除）', () => {
+    if (!srcFiles.length) return skip('无源文件可扫描')
+    const hard = []
+    const soft = []
+    for (const { f, text } of readAll(srcFiles)) {
+      for (const m of text.matchAll(/ctx\.(using|scope|runtime|lifecycle|collect|accept|decline|alias|off|fork)\b/g)) {
+        hard.push(`${short(f)}: ctx.${m[1]}（v3 API，v4 已删除）`)
+      }
+      if (/ctx\.config\b/.test(text)) hard.push(`${short(f)}: ctx.config（v4 改为 ctx.fiber.config）`)
+      if (/ctx\.(start|stop)\(/.test(text)) hard.push(`${short(f)}: ctx.start()/stop()（v4 改为 fiber.await()/dispose()/update()）`)
+      if (/inject\s*:\s*\{[^}]*\b(required|optional)\b|\binject\s*\.\s*(required|optional)/.test(text)) hard.push(`${short(f)}: inject {required,optional} 形状（v3；v4 为 string[] 或 {name: interceptConfig}，可选依赖用 ctx.get）`)
+      if (/\b(reusable|reactive)\s*:/.test(text)) soft.push(`${short(f)}: reusable/reactive 元数据（v4 已删除 fork 机制，该字段被忽略）`)
+      if (/\busing\s*:/.test(text)) soft.push(`${short(f)}: using 元数据（v3 的 inject 别名）`)
+      if (/static\s+immediate|protected\s+(start|stop|fork)\s*\(/.test(text)) soft.push(`${short(f)}: v3 Service 写法（static immediate/protected start/stop）`)
+      if (/return\s*\{\s*dispose\s*[:(]/.test(text)) soft.push(`${short(f)}: 返回 {dispose} 对象（v3 DisposableLike，v4 抛 Invalid effect，须返回函数 disposer）`)
+    }
+    if (hard.length) return fail([...new Set(hard)].slice(0, 8).join('\n'))
+    if (soft.length) return warn([...new Set(soft)].slice(0, 8).join('\n'))
+    return pass('未发现 v3 遗留 API')
+  })
+
+  doctor.add(GROUP, 'K8 Config 必须是 Standard Schema 校验器', () => {
+    if (!srcFiles.length) return skip('无源文件可扫描')
+    const hits = []
+    for (const { f, text } of readAll(srcFiles)) {
+      const m = text.match(/export\s+const\s+Config\s*=\s*([^\n]*)/)
+      if (m && !/Schema\./.test(m[1]) && !/interface|type\s/.test(text.match(/export\s+(?:interface|type)\s+Config/)?.[0] ?? '')) {
+        if (m[1].trim().startsWith('{')) hits.push(`${short(f)}: export const Config = {普通对象}（"将普通对象导出为 Config 无法工作"——教程 05；应导出 schemastery Schema）`)
+      }
+    }
+    if (hits.length) return fail(hits.join('\n'))
+    return pass('Config 声明为 Schema 校验器或纯类型')
+  })
+
+  doctor.add(GROUP, 'K9 插件 name 特例', () => {
+    if (!srcFiles.length) return skip('无源文件可扫描')
+    const hits = []
+    for (const { f, text } of readAll(srcFiles)) {
+      if (/name\s*:\s*['"]apply['"]/.test(text)) hits.push(short(f))
+    }
+    if (hits.length) return warn(`对象插件 name === 'apply' 会被框架重置为 undefined（registry.ts 特例），诊断名丢失:\n${hits.join('\n')}`)
+    return pass('无 name="apply" 特例')
+  })
+}

package/lib/checks-package.mjs

@@ -0,0 +1,175 @@
+// 静态·包结构检查（R0–R8）
+// 依据：deepseek-harness publish.md / apps/cli/src/plugin.ts（2026-09-07 调研）+
+// PerryLink 工作区双基线约定（AGENTS.md）
+import path from 'node:path'
+import { readFileSync, existsSync } from 'node:fs'
+import { runStep, pass, fail, warn, skip, tail, findFiles } from './util.mjs'
+
+export const GROUP = '静态·包结构'
+
+const stripDot = (p) => String(p ?? '').replace(/^\.\//, '')
+const normalizeEntry = (pkg) => stripDot(pkg.main ?? (typeof pkg.exports === 'string' ? pkg.exports : pkg.exports?.default?.default ?? pkg.exports?.['.']?.default) ?? 'index.js')
+
+export function addChecks(doctor, ctx) {
+  const { repoPath, pkg, pkgName } = ctx
+
+  doctor.add(GROUP, 'R0 基础字段（name/version/license/README/type）', () => {
+    const problems = []
+    if (!pkg.name) problems.push('缺 name')
+    if (!pkg.version) problems.push('缺 version')
+    if (!pkg.license) problems.push('缺 license（SPDX）')
+    if (!existsSync(path.join(repoPath, 'README.md'))) problems.push('缺 README.md')
+    const hasLicenseFile = ['LICENSE', 'LICENSE.md', 'LICENSE.txt'].some((f) => existsSync(path.join(repoPath, f)))
+    if (!hasLicenseFile) problems.push('缺 LICENSE 文件')
+    if (!pkg.type) problems.push('未声明 type（官方范式 "module"）')
+    if (problems.length) return warn(problems.join('；'))
+    return pass('基础字段齐全')
+  })
+
+  doctor.add(GROUP, 'R1 激活门 dsh.bundle.patch', () => {
+    const patch = pkg.dsh?.bundle?.patch
+    if (typeof patch === 'string' && patch.length > 0) return pass(`dsh.bundle.patch = ${patch}`)
+    return fail(
+      'package.json 缺少 dsh.bundle.patch —— 该包安装后只会作为普通依赖，宿主永远不会把它加入 dsh.profile.bundles（最静默的失败模式）',
+    )
+  }, { critical: true })
+
+  doctor.add(GROUP, 'R2 tarball 完整性（npm pack --dry-run）', () => {
+    const r = runStep('r2-pack', 'npm', ['pack', '--dry-run', '--json', '--ignore-scripts'], { cwd: repoPath, logDir: ctx.logDir, timeout: 300_000 })
+    if (!r.ok) return fail(`npm pack 失败（exit ${r.code}）:\n${tail(r.err)}`)
+    let pack
+    try {
+      const json = r.out.replace(/^\uFEFF/, '').trim()
+      pack = JSON.parse(json.slice(json.indexOf('['), json.lastIndexOf(']') + 1))[0]
+    } catch {
+      return fail('npm pack --json 输出解析失败')
+    }
+    const files = pack.files ?? []
+    const paths = files.map((f) => f.path)
+    const problems = []
+    const patch = stripDot(pkg.dsh?.bundle?.patch ?? '')
+    const entry = normalizeEntry(pkg)
+    if (patch && !paths.includes(patch)) problems.push(`patch 文件 ${patch} 不在 tarball（files 白名单未覆盖？）`)
+    if (entry && !paths.some((f) => f === entry)) problems.push(`入口 ${entry} 不在 tarball`)
+    for (const need of [patch, entry]) {
+      const hit = files.find((f) => f.path === need)
+      if (hit && Number(hit.size ?? 0) === 0) problems.push(`${need} 为空文件`)
+    }
+    const expected = `${pkgName.replace(/^@/, '').replace('/', '-')}-${pkg.version}.tgz`
+    if (pack.filename && pack.filename !== expected) problems.push(`tarball 名 ${pack.filename} ≠ 期望 ${expected}`)
+    if (problems.length) return fail(problems.join('\n'))
+    return pass(`tarball ${pack.filename} 含入口与 patch（共 ${files.length} 个文件）`)
+  })
+
+  doctor.add(GROUP, 'R3 cordis.patch.yml 结构（启发式）', () => {
+    const patch = stripDot(pkg.dsh?.bundle?.patch ?? '')
+    if (!patch) return skip('无 dsh.bundle.patch')
+    const p = path.resolve(repoPath, patch)
+    if (!existsSync(p)) return fail(`patch 文件不存在: ${patch}`)
+    const text = readFileSync(p, 'utf8')
+    const problems = []
+    if (!/-\s+insert\s*:/.test(text)) problems.push('未找到 "- insert:" 结构')
+    const ids = [...text.matchAll(/(?:^|\n)\s*-?\s*id:\s*["']?([^"'\s]+)/g)].map((m) => m[1])
+    if (!ids.length) problems.push('未找到 id 行（行 id 必须存在，供上层整行替换定位）')
+    const names = [...text.matchAll(/(?:^|\n)\s*name:\s*["']?([^"'\s,]+)|[,\s]name:\s*["']?([^"'\s,]+)/g)]
+      .map((m) => m[1] ?? m[2]).filter(Boolean)
+    const badNames = names.filter((n) => n !== pkgName && !n.startsWith(`${pkgName}/`))
+    if (names.length && badNames.length) problems.push(`行 name 与包名不一致: ${[...new Set(badNames)].join(', ')}（name 必须经 profile node_modules 解析，应为包名）`)
+    if (problems.length) return fail(problems.join('\n'))
+    return pass(`解析到 insert 结构、${ids.length} 个 id、name 与包名一致（启发式；以 D2 --dump-config 为准）`)
+  })
+
+  doctor.add(GROUP, 'R4 入口契约（name/apply 导出 + inject 字面量）', () => {
+    const entry = normalizeEntry(pkg)
+    const entryAbs = path.resolve(repoPath, entry)
+    if (!existsSync(entryAbs)) return fail(`入口文件 ${entry} 不存在（需先 pnpm run build）`)
+    const src = readFileSync(entryAbs, 'utf8')
+    const hasApply = /exports\s*\.\s*apply|module\.exports\s*=\s*\{[\s\S]{0,400}\bapply\b|export\s+(?:const|function)\s+apply/.test(src)
+    const hasName = /exports\s*\.\s*name|module\.exports\s*=\s*\{[\s\S]{0,400}\bname\b|export\s+const\s+name/.test(src)
+    const problems = []
+    if (!hasApply) problems.push('入口未检出 apply 导出')
+    if (!hasName) problems.push('入口未检出 name 导出')
+    // TS 源兜底（入口是编译产物时）
+    const srcFiles = findFiles(repoPath, 'src', /\.(ts|mts|tsx|mjs|js)$/)
+    const srcText = srcFiles.map((f) => { try { return readFileSync(f, 'utf8') } catch { return '' } }).join('\n')
+    if (!hasApply && /export\s+(?:const|function)\s+apply|apply\s*\(ctx/.test(srcText)) {
+      problems.splice(problems.indexOf('入口未检出 apply 导出'), 1)
+    }
+    if (!hasName && /export\s+const\s+name\b/.test(srcText)) {
+      problems.splice(problems.indexOf('入口未检出 name 导出'), 1)
+    }
+    const injectDecl = srcText.match(/(?:export\s+)?(?:const\s+)?inject\s*[:=]\s*\[([^\]]*)\]/)
+    if (injectDecl) {
+      const inner = injectDecl[1].trim()
+      const junk = inner.replace(/['"][^'"]*['"]/g, '').replace(/[\s,]/g, '')
+      if (junk) problems.push(`inject 数组含非字符串字面量: [${inner}]`)
+    }
+    if (problems.length) return warn(problems.join('\n') + '\n（启发式扫描；若为 default 对象/class 形式请人工确认）')
+    return pass(`入口 ${entry} 检出 name/apply 导出${injectDecl ? '，inject 为字符串数组' : ''}`)
+  })
+
+  doctor.add(GROUP, 'R5 依赖口径（rescope cordis / 禁裸上游名）', () => {
+    const problems = []
+    for (const field of ['dependencies', 'peerDependencies', 'devDependencies']) {
+      const deps = pkg[field] ?? {}
+      if ('cordis' in deps) problems.push(`${field} 出现裸 cordis@${deps.cordis}（应使用 rescope @deepseek-ai/cordis）`)
+      if ('schemastery' in deps) problems.push(`${field} 出现裸 schemastery@${deps.schemastery}（应使用 @deepseek-ai/schemastery）`)
+    }
+    const peer = pkg.peerDependencies?.['@deepseek-ai/cordis']
+    const dep = pkg.dependencies?.['@deepseek-ai/cordis']
+    const srcFiles = findFiles(repoPath, 'src', /\.(ts|mts|tsx|mjs|js)$/)
+    const importsCordis = srcFiles.some((f) => { try { return /from\s+['"]@deepseek-ai\/cordis['"]|require\(['"]@deepseek-ai\/cordis['"]\)/.test(readFileSync(f, 'utf8')) } catch { return false } })
+    if (!peer && !dep) {
+      if (importsCordis) problems.push('源码 import @deepseek-ai/cordis 但未声明任何依赖')
+      else problems.push('未声明 @deepseek-ai/cordis（若源码不 import 可忽略）')
+    } else if (!peer) {
+      problems.push('@deepseek-ai/cordis 只在 dependencies（官方口径：peerDependencies + devDependencies 同时声明）')
+    }
+    if (pkg.dependencies?.['@deepseek-ai/dsh']) problems.push('dependencies 直接依赖 @deepseek-ai/dsh（宿主已提供，应走 peer/dev 口径）')
+    if (problems.length) return fail(problems.join('\n'))
+    return pass(`cordis 口径正确（${peer ?? dep}）`)
+  })
+
+  doctor.add(GROUP, 'R6 Node 引擎声明', () => {
+    const e = pkg.engines?.node
+    if (!e) return warn('未声明 engines.node（建议 "^22.19.0 || >=24.0.0"；npm 线宿主不强制，属建议门）')
+    const only23 = /23/.test(e) && !/22/.test(e) && !/24/.test(e) && !/>=\s*2[5-9]/.test(e)
+    if (only23) return fail(`engines.node=${e} 宣称 Node 23（官方整线排除 23，要求 ^22.19.0 || >=24.0.0）`)
+    if (/22\.19/.test(e) && /24/.test(e)) return pass(`engines.node=${e} 与官方 ^22.19.0 || >=24.0.0 一致`)
+    return warn(`engines.node=${e} 与官方 ^22.19.0 || >=24.0.0 的相交性请人工确认`)
+  })
+
+  doctor.add(GROUP, 'R7 预构建与 files 覆盖', () => {
+    const entry = normalizeEntry(pkg)
+    const problems = []
+    if (entry.includes('src/')) problems.push(`main 指向源码 ${entry}（npm 发布必须预构建，main 应指向 lib/ 产物）`)
+    const filesField = pkg.files
+    if (Array.isArray(filesField) && filesField.length) {
+      const covered = (f) => filesField.some((item) => {
+        const base = item.replace(/\/$/, '')
+        return f === item || f.startsWith(`${base}/`)
+      })
+      if (!covered(entry)) problems.push(`files 白名单未覆盖入口 ${entry}`)
+      const patch = stripDot(pkg.dsh?.bundle?.patch ?? '')
+      if (patch && !covered(patch)) problems.push('files 白名单未覆盖 cordis.patch.yml')
+    } else {
+      problems.push('未声明 files 白名单')
+    }
+    const note = pkg.scripts?.prepare ? '（含 prepare 脚本，支持 git 直装自构建）' : '（无 prepare，git 直装不可用，npm/tarball 不受影响）'
+    if (problems.length) return fail(problems.join('\n') + '\n' + note)
+    return pass(`main 指向构建产物且 files 覆盖入口与 patch ${note}`)
+  })
+
+  doctor.add(GROUP, 'R8 peer 范围旧 rc 残留（双基线教训）', () => {
+    const peers = Object.entries(pkg.peerDependencies ?? {})
+      .filter(([k]) => k.startsWith('@deepseek-ai/dsh') || k === 'cordis' || k.startsWith('@deepseek-ai/cordis'))
+    if (!peers.length) return skip('无 dsh 相关 peer 声明')
+    const problems = []
+    for (const [k, v] of peers) {
+      if (/(0\.1\.0-rc\.8|0\.1\.1-rc\.2)/.test(String(v))) problems.push(`${k}: ${v} 含旧 rc 版本（2026-09-05 起全仓统一为 >=0.1.2-rc.1 <0.2.0）`)
+      if (/^>=\s*0\.1\.0-rc\.\d+\s*<\s*0\.2\.0/.test(String(v))) problems.push(`${k}: ${v} 是旧 prerelease-tuple 区间（裸解析只匹配 0.1.0-rc.8 单行）`)
+    }
+    if (problems.length) return fail(problems.join('\n'))
+    return pass(peers.map(([k, v]) => `${k} ${v}`).join('；'))
+  })
+}

package/lib/checks-smoke.mjs

@@ -0,0 +1,93 @@
+// 动态·沙箱冒烟（D0–D3 + 清场）
+// 依据：dsh compat.yml 正典配方（MISSING_CREDENTIAL 判据）+ 2026-09-07 harness 调研 +
+// 工作区红线 3（一切测试全沙箱：%TEMP% mkdtemp DSH_HOME）
+import path from 'node:path'
+import { makeSandbox, cleanSandbox, runStep, pass, fail, skip, tail, readJson, writeJson, exists } from './util.mjs'
+
+export const GROUP = '动态·沙箱冒烟'
+
+export function addSmokeChecks(doctor, ctx, opts = {}) {
+  const { repoPath, pkgName, logDir } = ctx
+  const dshVersion = opts.dshVersion ?? '0.1.2-rc.1'
+  const state = {}
+
+  doctor.add(GROUP, 'D0 打包 tarball（npm pack）', () => {
+    state.sb = makeSandbox('smoke')
+    const r = runStep('d0-pack', 'npm', ['pack', '--json', '--ignore-scripts'], { cwd: repoPath, logDir, timeout: 300_000 })
+    if (!r.ok) return fail(`npm pack 失败（exit ${r.code}）:\n${tail(r.err)}`)
+    let pack
+    try {
+      const json = r.out.replace(/^\uFEFF/, '').trim()
+      pack = JSON.parse(json.slice(json.indexOf('['), json.lastIndexOf(']') + 1))[0]
+    } catch {
+      return fail('npm pack --json 解析失败')
+    }
+    state.tgz = path.join(repoPath, pack.filename)
+    if (!exists(state.tgz)) return fail(`tarball 未生成: ${state.tgz}`)
+    return pass(`已打包 ${pack.filename}（${pack.files?.length ?? '?'} 文件）`)
+  })
+
+  doctor.add(GROUP, 'D1 安装冒烟（plugin add + bundles 断言）', () => {
+    if (!state.tgz) return skip('D0 未通过')
+    writeJson(path.join(state.sb.root, 'package.json'), { name: 'dsh-doctor-runtime', version: '0.0.0', private: true })
+    const i = runStep('d1-install', 'npm', ['install', '--no-audit', '--no-fund', '--loglevel=error', `@deepseek-ai/dsh@${dshVersion}`], {
+      cwd: state.sb.root, logDir, timeout: 900_000,
+    })
+    if (!i.ok) return fail(`安装 @deepseek-ai/dsh@${dshVersion} 失败（exit ${i.code}）:\n${tail(i.err)}`)
+    const hostPkgPath = path.join(state.sb.root, 'node_modules', '@deepseek-ai', 'dsh', 'package.json')
+    if (!exists(hostPkgPath)) return fail('@deepseek-ai/dsh 未安装成功')
+    const host = readJson(hostPkgPath)
+    const rel = host.bin?.dsh
+    const bin = rel ? path.resolve(state.sb.root, 'node_modules', '@deepseek-ai', 'dsh', rel) : null
+    if (!bin || !exists(bin)) return fail(`未找到 dsh bin（package.json bin=${JSON.stringify(host.bin)}）`)
+    state.bin = bin
+    const dsh = (label, args, o = {}) => runStep(label, process.execPath, [bin, ...args], {
+      env: { DSH_HOME: state.sb.home, DSH_AGENTS_HOME: path.join(state.sb.home, '.agents'), ...(o.env ?? {}) },
+      cwd: state.sb.root, logDir, timeout: o.timeout ?? 120_000, shell: false,
+    })
+    state.dsh = dsh
+    const a = dsh('d1-add', ['plugin', '--profile', 'headless', 'add', state.tgz], { timeout: 900_000 })
+    const envBlock = /ERR_PNPM_IGNORED_BUILDS|approve-builds|ignored builds/i.test(a.err)
+    if (!a.ok) {
+      if (envBlock) {
+        return warn(`pnpm approve-builds/ignored-builds 环境门阻断（属环境配方问题，非插件缺陷，参照 compat.yml allowBuilds 配方）:\n${tail(a.err)}`)
+      }
+      return fail(`plugin add 失败（exit ${a.code}）:\n${tail(a.err)}`)
+    }
+    if (/declares no dsh\.bundle|not activated/i.test(a.err)) return fail('宿主 stderr 出现未激活警告（dsh.bundle 声明未被识别）')
+    const profilePkgPath = path.join(state.sb.home, 'profiles', 'headless', 'package.json')
+    if (!exists(profilePkgPath)) return fail('profile package.json 未生成')
+    const profilePkg = readJson(profilePkgPath)
+    const bundles = profilePkg?.dsh?.profile?.bundles ?? []
+    if (!bundles.includes(pkgName)) return fail(`dsh.profile.bundles 不含 ${pkgName}（实际: ${JSON.stringify(bundles)}）`)
+    return pass(`已加入 dsh.profile.bundles: ${bundles.join(', ')}`)
+  })
+
+  doctor.add(GROUP, 'D2 层验证（--dump-config，不 boot）', () => {
+    if (!state.dsh) return skip('D1 未通过')
+    const r = state.dsh('d2-dump', ['--profile', 'headless', '--dump-config'], { timeout: 120_000 })
+    if (!r.ok) return fail(`--dump-config 失败（exit ${r.code}）:\n${tail(r.err)}`)
+    if (!r.out.includes(`# == ${pkgName}`)) return fail(`dump-config 未见层标记 "# == ${pkgName}"`)
+    return pass(`层标记 "# == ${pkgName}" 出现（patch 已进入组合层）`)
+  })
+
+  doctor.add(GROUP, 'D3 keyless headless 冒烟（MISSING_CREDENTIAL 判据）', () => {
+    if (!state.dsh) return skip('D1 未通过')
+    const r = state.dsh('d3-run', ['--profile', 'headless', 'Reply with exactly: ok'], { timeout: 90_000 })
+    const combined = `${r.out}\n${r.err}`
+    if (r.signal || r.spawnError) return fail(`进程异常终止（signal=${r.signal}${r.spawnError ? ' ' + r.spawnError : ''}）`)
+    const bad = combined.match(/.*(NO_ADAPTER|ERR_MODULE_NOT_FOUND|SyntaxError|TypeError|ReferenceError|Cannot find module).*/g)
+    if (bad) return fail(`组合未 boot 到请求阶段，出现致命错误:\n${bad.slice(0, 5).join('\n')}`)
+    if (r.code === 1 && /dsh:\s*MISSING_CREDENTIAL/.test(combined)) {
+      return pass('exit 1 + dsh: MISSING_CREDENTIAL —— bundle 层生效、插件 apply 成功、组合到达模型请求阶段（严格匹配 code，防正则假阳性）')
+    }
+    if (r.code === 0) return pass('exit 0（环境中存在凭据，完整跑通）')
+    return fail(`期望 exit 1 + MISSING_CREDENTIAL，实际 exit ${r.code}:\n${tail(combined)}`)
+  })
+
+  doctor.add(GROUP, 'D9 沙箱清理', () => {
+    const wasRun = !!state.sb
+    cleanSandbox(state.sb)
+    return pass(wasRun ? '临时 DSH_HOME 沙箱已删除（%TEMP% mkdtemp）' : '未创建沙箱')
+  })
+}