@bruc3van/dsh-doctor 0.1.5 → 0.5.0

package/src/doctor.mjs

@@ -6,7 +6,12 @@ import yaml from 'js-yaml'
 import semver from 'semver'
 import { parseDocument } from 'yaml'
 import { languageName, localizedFinding } from './i18n.mjs'
+import { buildConfigurationModel } from './config-model.mjs'
+import { buildPluginDiagnoses } from './recovery.mjs'
 
+// Mirrors packages/client/web/src/platform.ts in DeepSeek Harness. Installed
+// DSH packages do not expose this source list, so update this baseline when
+// Harness changes PLATFORM_MODULES.
 export const PLATFORM_MODULES = new Set([
   'react',
   'react/jsx-runtime',
@@ -45,6 +50,13 @@ function finding(severity, code, message, options = {}) {
   }
 }
 
+function yamlErrorLocation(error) {
+  const mark = error?.mark
+  return Number.isInteger(mark?.line) && Number.isInteger(mark?.column)
+    ? `at line ${String(mark.line + 1)}, column ${String(mark.column + 1)}`
+    : 'parse error'
+}
+
 function readJson(file, subject, findings) {
   let text
   try {
@@ -168,11 +180,12 @@ function manifestBin(packageDir) {
   }
 }
 
-function localDshPackage(start) {
+function localDshBin(start) {
   let current = resolve(start)
   while (true) {
     const packageDir = join(current, 'node_modules', '@deepseek-ai', 'dsh')
-    if (manifestBin(packageDir) !== undefined) return packageDir
+    const bin = manifestBin(packageDir)
+    if (bin !== undefined) return bin
     const parent = dirname(current)
     if (parent === current) return undefined
     current = parent
@@ -218,10 +231,9 @@ function resolveDshCli(options, harness, home) {
     if (bin !== undefined) return { command: [process.execPath, bin.bin], path: bin.bin, source: 'profile', version: bin.version }
   }
 
-  const localPackage = localDshPackage(cwd)
-  if (localPackage !== undefined) {
-    const bin = manifestBin(localPackage)
-    return { command: [process.execPath, bin.bin], path: bin.bin, source: 'project', version: bin.version }
+  const localBin = localDshBin(cwd)
+  if (localBin !== undefined) {
+    return { command: [process.execPath, localBin.bin], path: localBin.bin, source: 'project', version: localBin.version }
   }
 
   const pathCommand = executableOnPath('dsh', env)
@@ -422,6 +434,7 @@ function codePositions(source) {
   const code = new Uint8Array(source.length)
   let state = 'code'
   let regexClass = false
+  const templateExpressions = []
   for (let index = 0; index < source.length; index += 1) {
     const char = source[index]
     const next = source[index + 1]
@@ -432,11 +445,25 @@ function codePositions(source) {
       } else if (char === '/' && next === '*') {
         state = 'block-comment'
         index += 1
-      } else if (char === "'" || char === '"' || char === '`') {
+      } else if (char === "'" || char === '"') {
         state = char
+      } else if (char === '`') {
+        state = 'template'
       } else if (char === '/' && regexCanStart(source, index)) {
         state = 'regex'
         regexClass = false
+      } else if (templateExpressions.length > 0 && char === '{') {
+        templateExpressions[templateExpressions.length - 1] += 1
+        code[index] = 1
+      } else if (templateExpressions.length > 0 && char === '}') {
+        const last = templateExpressions.length - 1
+        templateExpressions[last] -= 1
+        if (templateExpressions[last] === 0) {
+          templateExpressions.pop()
+          state = 'template'
+        } else {
+          code[index] = 1
+        }
       } else {
         code[index] = 1
       }
@@ -456,6 +483,14 @@ function codePositions(source) {
       else if (char === ']') regexClass = false
       else if (char === '/' && !regexClass) state = 'code'
       else if (char === '\n' || char === '\r') state = 'code'
+    } else if (state === 'template') {
+      if (char === '\\') index += 1
+      else if (char === '`') state = 'code'
+      else if (char === '$' && next === '{') {
+        templateExpressions.push(1)
+        state = 'code'
+        index += 1
+      }
     } else if (char === '\\') {
       index += 1
     } else if (char === state) {
@@ -484,6 +519,39 @@ function stringArray(value) {
   return Array.isArray(value) && value.every(item => typeof item === 'string') ? value : undefined
 }
 
+function packageMainExport(manifest) {
+  const exported = manifest?.exports?.['.']
+  if (typeof exported === 'string') return exported
+  if (objectRecord(exported) !== undefined) {
+    for (const key of ['import', 'default', 'require']) {
+      if (typeof exported[key] === 'string') return exported[key]
+    }
+  }
+  return typeof manifest?.main === 'string' ? manifest.main : undefined
+}
+
+function inspectRuntimeServiceProvider(record) {
+  const candidates = [...new Set([packageMainExport(record.manifest), clientExport(record.manifest)].filter(value => typeof value === 'string'))]
+  const evidence = []
+  for (const exported of candidates) {
+    const file = safePackageFile(record.directory, exported)
+    if (file === undefined || !regularFile(file)) continue
+    try {
+      if (statSync(file).size > 16 * 1024 * 1024) continue
+      const source = readFileSync(file, 'utf8')
+      const code = codePositions(source)
+      const patterns = [
+        /\b(?:ctx|context)\s*\.\s*provide\s*\(/g,
+        /\bclass\s+[A-Za-z_$][\w$]*\s+extends\s+Service\b/g,
+      ]
+      if (patterns.some(pattern => [...source.matchAll(pattern)].some(match => code[match.index]))) evidence.push(file)
+    } catch {
+      // Existing package and client checks own unreadable-artifact findings.
+    }
+  }
+  return evidence.length === 0 ? { status: 'not-detected' } : { status: 'detected', evidence }
+}
+
 function inspectClientPackage(record, context) {
   const {
     commandRepair, findings, harnessPackages, harnessPackagesAuthoritative, profile, resolvePackage,
@@ -663,7 +731,9 @@ function inspectPatchFile(file, subject, findings, packageName) {
   } catch (error) {
     findings.push(finding('error', 'INVALID_PATCH_YAML', `${subject} cannot be parsed.`, {
       package: packageName,
-      evidence: `${file}: ${error instanceof Error ? error.message : String(error)}`,
+      // js-yaml messages include a source excerpt, which may contain plugin
+      // credentials. Preserve only the location needed to repair the syntax.
+      evidence: `${file}: ${yamlErrorLocation(error)}`,
       suggestion: 'Repair the YAML syntax before starting this profile.',
     }))
     return undefined
@@ -1084,7 +1154,8 @@ function inspectCompatibility(record, context) {
       }))
       continue
     }
-    const supplier = harnessPackages.get(name) ?? resolvePackage(name)
+    const supplier = harnessPackages.get(name)
+      ?? (harnessPackagesAuthoritative ? undefined : resolvePackage(name))
     if (supplier === undefined) continue
     const version = supplier.manifest?.version
     if (typeof version !== 'string' || semver.valid(version) === null) continue
@@ -1295,6 +1366,11 @@ export function diagnose(options = {}) {
           operation: { type: 'add-bundle', name },
         },
       }))
+      findings.push(finding('warning', 'BUNDLE_PROFILE_DECLARATION_CONFLICT', `${name} declares a bundle layer but the profile does not activate it.`, {
+        package: name,
+        evidence: profileManifestFile,
+        suggestion: 'Reconcile the direct dependency and dsh.profile.bundles declaration with the active DSH CLI.',
+      }))
     }
   }
   const patchLayers = []
@@ -1302,7 +1378,7 @@ export function diagnose(options = {}) {
   for (const name of bundleNames) {
     const layer = inspectBundle(name, bundleRecords.get(name), findings)
     if (layer === undefined) patchCompositionValid = false
-    else patchLayers.push(layer)
+    else patchLayers.push({ ...layer, kind: 'bundle' })
   }
 
   for (const [file, subject, label] of [
@@ -1310,10 +1386,87 @@ export function diagnose(options = {}) {
     [join(home, 'cordis.patch.yml'), 'home patch', 'home patch'],
   ]) {
     const patches = inspectPatchFileIfPresent(file, subject, findings)
-    if (patches !== undefined) patchLayers.push({ file, label, patches })
+    if (patches !== undefined) patchLayers.push({
+      file,
+      label,
+      patches,
+      kind: label === 'profile patch' ? 'profile' : 'home',
+    })
     else if (existsSync(file)) patchCompositionValid = false
   }
+  for (const [index, value] of (options.patchFiles ?? []).entries()) {
+    const file = resolve(expandUserPath(value))
+    const patches = inspectPatchFile(file, `CLI overlay ${String(index + 1)}`, findings)
+    if (patches !== undefined) patchLayers.push({ file, label: `CLI overlay ${String(index + 1)}`, patches, kind: 'overlay' })
+    else patchCompositionValid = false
+  }
   if (patchCompositionValid) inspectPatchComposition(patchLayers, findings)
+  const configuration = buildConfigurationModel(patchLayers, issue => {
+    const owner = issue.layer?.package ?? issue.details?.origin?.package ?? issue.entry?.name
+    const evidence = issue.layer === undefined
+      ? issue.details?.ids?.join(', ')
+      : `${issue.layer.file}: entry ${String((issue.patchIndex ?? 0) + 1)}`
+    const messages = {
+      DUPLICATE_ENTRY_ID: `Entry id ${issue.details.id} is inserted more than once in the effective configuration.`,
+      DUPLICATE_PLUGIN_MOUNT: `${issue.entry.name} is mounted by multiple active entries.`,
+      CORE_ENTRY_DISABLED_BY_HIGHER_LAYER: `A higher configuration layer disables entry ${issue.entry.id}.`,
+      ENTRY_STRUCTURE_OVERRIDDEN: `A higher configuration layer changes the structure of entry ${issue.entry.id}.`,
+      INVALID_GROUP_CONFIG: `Group entry ${issue.entry.id} has a non-array config value.`,
+      GROUP_CONTENT_REPLACED: `A higher configuration layer replaces the complete group content of entry ${issue.entry.id}.`,
+      CONFIG_REPLACED_BY_HIGHER_LAYER: `A higher configuration layer replaces the complete config of entry ${issue.entry.id}.`,
+    }
+    findings.push(finding(['DUPLICATE_ENTRY_ID', 'INVALID_GROUP_CONFIG'].includes(issue.code) ? 'error' : 'warning', issue.code, messages[issue.code], {
+      package: owner,
+      evidence,
+      details: issue.details,
+      suggestion: 'Review the named configuration layer and keep one unambiguous source for this entry.',
+    }))
+  })
+  configuration.profile = profile
+  configuration.layerDetails = patchLayers.map(layer => {
+    const insertedIds = new Set()
+    const collect = entries => entries.forEach(entry => {
+      if (typeof entry.id === 'string') insertedIds.add(entry.id)
+      if (entry.group && Array.isArray(entry.config)) collect(entry.config)
+    })
+    layer.patches.filter(patch => Array.isArray(patch.insert)).forEach(patch => collect(patch.insert))
+    return {
+      kind: layer.kind,
+      file: layer.file,
+      package: layer.package,
+      insertCount: layer.patches.filter(patch => Array.isArray(patch.insert)).length,
+      overrideCount: layer.patches.filter(patch => !Array.isArray(patch.insert) && !insertedIds.has(patch.id)).length,
+    }
+  })
+  configuration.patchReferences = patchLayers.flatMap(layer => layer.patches.flatMap((patch, patchIndex) =>
+    !Array.isArray(patch.insert) && typeof patch.id === 'string'
+      ? [{ id: patch.id, kind: layer.kind, file: layer.file, package: layer.package, patchIndex }]
+      : []))
+  if (patchCompositionValid) {
+    const defaultConfiguration = buildConfigurationModel(patchLayers.filter(layer => layer.kind === 'bundle'))
+    const knownIds = new Set(defaultConfiguration.entries.map(entry => entry.id).filter(id => typeof id === 'string' && id.length > 0))
+    const knownGroups = new Set(defaultConfiguration.entries
+      .filter(entry => entry.group === true && typeof entry.id === 'string' && entry.id.length > 0)
+      .map(entry => entry.id))
+    const indexInserted = entries => entries.forEach(entry => {
+      if (typeof entry.id === 'string' && entry.id.length > 0) knownIds.add(entry.id)
+      if (entry.group === true && typeof entry.id === 'string' && entry.id.length > 0) knownGroups.add(entry.id)
+      if (entry.group === true && Array.isArray(entry.config)) indexInserted(entry.config)
+    })
+    for (const layer of patchLayers.filter(item => item.kind !== 'bundle')) {
+      layer.patches.forEach((patch, patchIndex) => {
+        if (Array.isArray(patch.insert)) {
+          if (typeof patch.id !== 'string' || patch.id.length === 0 || knownGroups.has(patch.id)) indexInserted(patch.insert)
+          return
+        }
+        if (typeof patch.id !== 'string' || knownIds.has(patch.id)) return
+        findings.push(finding('warning', 'PATCH_INCOMPATIBLE_WITH_CURRENT_DSH', `${layer.label} still targets entry ${patch.id}, which is absent from the current default DSH tree.`, {
+          evidence: `${layer.file}: entry ${String(patchIndex + 1)}`,
+          suggestion: 'Adjust or remove this patch after comparing it with the current default configuration.',
+        }))
+      })
+    }
+  }
   inspectSettings(join(home, 'settings.yaml'), findings)
   inspectCredentials(join(home, '.credentials.yaml'), findings)
 
@@ -1346,32 +1499,65 @@ export function diagnose(options = {}) {
     )
   }
 
+  const activeHarnessVersions = Object.fromEntries([...harness.packages].flatMap(([name, record]) =>
+    typeof record.manifest?.version === 'string' ? [[name, record.manifest.version]] : []))
+  if (typeof harness.version === 'string') activeHarnessVersions['@deepseek-ai/dsh'] ??= harness.version
+  for (const record of thirdPartyRecords) {
+    const peers = objectRecord(record.manifest.peerDependencies)
+    if (peers === undefined) continue
+    for (const name of Object.keys(peers)) {
+      if (name !== 'cordis' && !name.startsWith('@deepseek-ai/')) continue
+      const supplier = harness.packages.get(name)
+        ?? (harness.authoritative ? undefined : resolvePackage(name))
+      if (typeof supplier?.manifest?.version === 'string') activeHarnessVersions[name] = supplier.manifest.version
+    }
+  }
+
+  const packages = dependencyNames.map(name => {
+    const record = records.get(name)
+    if (record === undefined) return { name, installed: false, compatibility: 'incompatible' }
+    return {
+      name: record.requestedName ?? record.manifest.name,
+      version: record.manifest.version,
+      directory: record.directory,
+      installed: true,
+      client: record.manifest?.dsh?.client !== undefined,
+      clientExternal: stringArray(record.manifest?.dsh?.client?.external) ?? [],
+      clientInject: stringArray(record.manifest?.dsh?.client?.inject) ?? [],
+      runtimeServiceProvider: inspectRuntimeServiceProvider(record),
+      bundle: record.manifest?.dsh?.bundle !== undefined,
+      compatibility: pluginCompatibility(
+        record,
+        findings,
+        compatibilityChecks.get(record.requestedName ?? record.manifest.name),
+      ),
+    }
+  })
+  const pluginDiagnoses = buildPluginDiagnoses({
+    packages,
+    findings,
+    configuration,
+    bundleNames,
+    profileManifest,
+    lockfile,
+    dshCli: { available: dshCli !== undefined },
+  })
   return finish({
     home,
     profile,
     profileDir,
-    harness: { root: harness.root, version: harness.version },
+    harness: {
+      root: harness.root,
+      version: harness.version,
+      packages: activeHarnessVersions,
+    },
     lockfile,
     dshCli: dshCli === undefined
       ? { available: false, commandRepairNeeded }
       : { available: true, commandRepairNeeded, ...dshCli },
-    packages: dependencyNames.map(name => {
-      const record = records.get(name)
-      if (record === undefined) return { name, installed: false, compatibility: 'incompatible' }
-      return {
-        name: record.requestedName ?? record.manifest.name,
-        version: record.manifest.version,
-        directory: record.directory,
-        installed: true,
-        client: record.manifest?.dsh?.client !== undefined,
-        bundle: record.manifest?.dsh?.bundle !== undefined,
-        compatibility: pluginCompatibility(
-          record,
-          findings,
-          compatibilityChecks.get(record.requestedName ?? record.manifest.name),
-        ),
-      }
-    }),
+    packages,
+    configuration,
+    pluginDiagnoses,
   }, findings)
 }
 
@@ -1392,7 +1578,7 @@ function finish(context, findings) {
     compatible: context.packages.filter(item => item.compatibility === 'compatible').length,
   }
   context = { ...context, compatibility }
-  return { version: 1, ok: summary.errors === 0, context, summary, findings }
+  return { version: 2, ok: summary.errors === 0, context, summary, findings }
 }
 
 function appendReportField(lines, label, value, indent = '      ') {
@@ -1425,7 +1611,7 @@ export function formatReport(report, options = {}) {
     : zh ? '未找到（命令型修复已禁用）' : 'not found (command-based repairs disabled)'
   const lines = [
     'DSH Doctor',
-    `${zh ? 'Profile' : 'Profile'}: ${report.context.profile}`,
+    `Profile: ${report.context.profile}`,
     `${zh ? 'DSH 主目录' : 'Home'}: ${report.context.home}`,
     `${zh ? '当前使用的 DSH' : 'Active DSH'}: ${report.context.harness.version ?? 'unknown'}${report.context.harness.root ? ` (${report.context.harness.root})` : ''}`,
     `${zh ? 'DSH CLI' : 'DSH CLI'}: ${cliText}`,
@@ -1437,6 +1623,7 @@ export function formatReport(report, options = {}) {
     '',
   ]
   const packageNames = new Set(report.context.packages.map(item => item.name))
+  const diagnoses = new Map((report.context.pluginDiagnoses ?? []).map(item => [item.name, item]))
   const pluginFindings = new Map()
   const environmentFindings = []
   for (const item of report.findings) {
@@ -1475,6 +1662,14 @@ export function formatReport(report, options = {}) {
         appendReportField(lines, zh ? '版本' : 'Version', plugin.installed === false
           ? zh ? '未安装' : 'not installed'
           : plugin.version ?? (zh ? '未知' : 'unknown'))
+        const diagnosis = diagnoses.get(plugin.name)
+        if (diagnosis !== undefined) {
+          appendReportField(lines, zh ? '原因类型' : 'Cause', diagnosis.cause.type)
+          appendReportField(lines, zh ? '配置来源' : 'Configuration origin', diagnosis.configuration.originLayer)
+          appendReportField(lines, zh ? '兼容版本' : 'Compatible version', diagnosis.update.status === 'not-checked'
+            ? zh ? '未检查 registry' : 'registry not checked'
+            : diagnosis.update.status)
+        }
         lines.push(zh
           ? `      问题（${String(originals.length)}）:`
           : `      Problems (${String(originals.length)}):`)
@@ -1506,6 +1701,15 @@ export function formatReport(report, options = {}) {
           lines.push(`      ${zh ? '可执行命令' : 'Available commands'}:`)
           commands.forEach(command => lines.push(`        $ ${command}`))
         }
+        if (diagnosis !== undefined) {
+          lines.push(`      ${zh ? '恢复选择' : 'Recovery options'}:`)
+          for (const option of diagnosis.recovery.options) {
+            lines.push(`        - ${option.kind}: ${option.availability}${option.recommended ? (zh ? '（推荐）' : ' (recommended)') : ''}`)
+          }
+          if (diagnosis.recovery.options.some(option => option.kind === 'remove')) {
+            lines.push(`        ${zh ? '动态 Service 依赖：未知，静态检查不能证明删除不影响其他功能。' : 'Dynamic Service dependencies: unknown; static checks cannot prove removal leaves every feature working.'}`)
+          }
+        }
         lines.push('')
       }
     }

package/src/i18n.mjs

@@ -87,6 +87,15 @@ const ZH_MESSAGES = {
   PATCH_TARGET_NOT_FOUND: item => `Patch 指向了不存在的配置行：${captured(item.message, / row ([^.]+)\.$/) ?? '未知'}。`,
   PATCH_TARGET_NOT_GROUP: item => `Patch 尝试向非 group 配置行 ${captured(item.message, / row ([^,]+),/) ?? '未知'} 插入内容。`,
   PATCH_NAME_MISMATCH: () => 'Patch 的 name 断言与目标配置行不一致。',
+  PATCH_INCOMPATIBLE_WITH_CURRENT_DSH: item => `配置层仍指向当前 DSH 默认树中不存在的行：${captured(item.message, /targets entry ([^,]+),/) ?? '未知'}。`,
+  DUPLICATE_ENTRY_ID: () => '生效配置中存在重复的 entry id。',
+  DUPLICATE_PLUGIN_MOUNT: item => `${item.package ?? '插件'}由多个启用状态的 entry 重复挂载。`,
+  CORE_ENTRY_DISABLED_BY_HIGHER_LAYER: () => '较高优先级配置层禁用了较低层提供的 entry。',
+  ENTRY_STRUCTURE_OVERRIDDEN: () => '较高优先级配置层改变了 entry 的结构。',
+  INVALID_GROUP_CONFIG: () => 'group entry 的 config 必须是数组。',
+  GROUP_CONTENT_REPLACED: () => '较高优先级配置层替换了 group 的完整内容。',
+  CONFIG_REPLACED_BY_HIGHER_LAYER: () => '较高优先级配置层替换了 entry 的完整 config。',
+  BUNDLE_PROFILE_DECLARATION_CONFLICT: item => `${item.package} 声明了 bundle 层，但当前 profile 没有启用它。`,
   INVALID_SETTINGS_DOCUMENT: () => 'Harness 设置文件无法解析。',
   INVALID_SETTINGS_ROOT: () => 'Harness 设置文件顶层必须是命名空间映射。',
   INVALID_CREDENTIALS_DOCUMENT: () => 'Harness 凭据文件无法解析。',
@@ -152,6 +161,15 @@ const ZH_SUGGESTIONS = {
   PATCH_TARGET_NOT_FOUND: () => '确认该 overlay 是否适用于当前 profile，并检查 bundle 顺序。',
   PATCH_TARGET_NOT_GROUP: () => '请选择 group 行，或使用根级 insert。',
   PATCH_NAME_MISMATCH: () => '请更新 name 断言，或改为指向正确的配置行。',
+  PATCH_INCOMPATIBLE_WITH_CURRENT_DSH: () => '请与当前默认配置对比后调整或移除这个旧 patch。',
+  DUPLICATE_ENTRY_ID: () => '请保留一个明确的 entry 来源，并为其他 entry 使用唯一 id。',
+  DUPLICATE_PLUGIN_MOUNT: () => '请检查 bundle 与手工 insert，只保留一个需要的插件挂载。',
+  CORE_ENTRY_DISABLED_BY_HIGHER_LAYER: () => '请确认该禁用是否仍适用于当前 DSH；需要恢复时撤销较高层覆盖。',
+  ENTRY_STRUCTURE_OVERRIDDEN: () => '请检查较高层 patch 是否仍适配当前 entry 结构。',
+  INVALID_GROUP_CONFIG: () => '请把 group entry 的 config 修复为 entry 数组。',
+  GROUP_CONTENT_REPLACED: () => '请检查被整体替换的 group 内容，避免删除当前 DSH 新增的子项。',
+  CONFIG_REPLACED_BY_HIGHER_LAYER: () => '请检查完整 config 替换造成的字段丢失，并按当前默认值调整。',
+  BUNDLE_PROFILE_DECLARATION_CONFLICT: () => '请使用当前 DSH CLI 对齐直接依赖与 dsh.profile.bundles。',
   INVALID_SETTINGS_DOCUMENT: () => '修复设置文件语法；Doctor 不会猜测凭据或模型配置值。',
   INVALID_SETTINGS_ROOT: () => '把顶层标量或数组替换为映射。',
   INVALID_CREDENTIALS_DOCUMENT: () => '只修复报告的结构；Doctor 永远不会输出或重写秘密值。',

package/src/migrate-verify.mjs

@@ -0,0 +1,195 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { basename, join, resolve } from 'node:path'
+import crossSpawn from 'cross-spawn'
+import { analyzeMigration, publicMigrationReport } from './migrate.mjs'
+import { sha256 } from './safe-write.mjs'
+
+function commandResult(command, args, options = {}) {
+  const started = Date.now()
+  const result = crossSpawn.sync(command, args, {
+    cwd: options.cwd,
+    env: options.env,
+    encoding: 'utf8',
+    timeout: options.timeout ?? 10 * 60 * 1000,
+    maxBuffer: 8 * 1024 * 1024,
+  })
+  return {
+    command: [command, ...args],
+    status: result.status,
+    signal: result.signal,
+    durationMs: Date.now() - started,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    passed: result.status === 0,
+    ...(result.error ? { error: result.error.message } : {}),
+  }
+}
+
+function commandEvidence(result) {
+  const { stdout, stderr, ...evidence } = result
+  return {
+    ...evidence,
+    stdoutBytes: Buffer.byteLength(stdout),
+    stderrBytes: Buffer.byteLength(stderr),
+    stdoutHash: sha256(stdout),
+    stderrHash: sha256(stderr),
+  }
+}
+
+function packageManager(root) {
+  if (existsSync(join(root, 'pnpm-lock.yaml'))) return { command: 'pnpm', run: script => ['run', script], pack: destination => ['pack', '--pack-destination', destination] }
+  if (existsSync(join(root, 'yarn.lock'))) return { command: 'yarn', run: script => [script], pack: destination => ['pack', '--out', join(destination, 'plugin.tgz')] }
+  return { command: 'npm', run: script => ['run', script], pack: destination => ['pack', '--json', '--pack-destination', destination] }
+}
+
+function discoverDsh(options) {
+  if (options.dshCommand) return resolve(options.dshCommand)
+  if (options.harnessRoot) {
+    const candidate = join(resolve(options.harnessRoot), 'apps', 'cli', 'lib', 'bin.js')
+    if (existsSync(candidate)) return candidate
+  }
+  throw new Error('runtime verification requires --dsh-command or a built --harness-root/apps/cli/lib/bin.js')
+}
+
+function dshInvocation(file, args) {
+  return /\.(?:mjs|cjs|js)$/i.test(file) ? [process.execPath, [file, ...args]] : [file, args]
+}
+
+function tarballFromPack(step, destination) {
+  try {
+    const parsed = JSON.parse(step.stdout)
+    const filename = Array.isArray(parsed) ? parsed[0]?.filename : parsed?.filename
+    if (filename) return join(destination, filename)
+  } catch {}
+  const match = step.stdout.match(/(?:^|\s)([^\s]+\.tgz)(?:\s|$)/m)
+  if (match) return resolve(destination, basename(match[1]))
+  const fallback = join(destination, 'plugin.tgz')
+  return existsSync(fallback) ? fallback : undefined
+}
+
+function runtimeProfileEvidence(dshHome, pluginName, dumpOutput) {
+  const profileDir = join(dshHome, 'profiles', 'web')
+  const manifestFile = join(profileDir, 'package.json')
+  const installedManifestFile = join(profileDir, 'node_modules', ...pluginName.split('/'), 'package.json')
+  try {
+    const profile = JSON.parse(readFileSync(manifestFile, 'utf8'))
+    const installed = JSON.parse(readFileSync(installedManifestFile, 'utf8'))
+    return {
+      profileCreated: true,
+      dependencyInstalled: profile.dependencies?.[pluginName] !== undefined,
+      bundleActivated: Array.isArray(profile.dsh?.profile?.bundles) && profile.dsh.profile.bundles.includes(pluginName),
+      installedPackageResolved: installed.name === pluginName,
+      effectiveConfigIncludesPlugin: dumpOutput.includes(pluginName),
+    }
+  } catch (error) {
+    return {
+      profileCreated: existsSync(manifestFile),
+      dependencyInstalled: false,
+      bundleActivated: false,
+      installedPackageResolved: false,
+      effectiveConfigIncludesPlugin: false,
+      evidenceError: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+export function verifyMigration(pluginRoot = process.cwd(), options = {}) {
+  const level = options.level ?? 'static'
+  if (!['static', 'build', 'runtime'].includes(level)) throw new Error(`unsupported verification level ${level}`)
+  if (level !== 'static' && options.yes !== true) throw new Error(`migrate verify --level ${level} executes project commands and requires --yes`)
+  const analysis = analyzeMigration(pluginRoot, options)
+  const result = {
+    schemaVersion: 1,
+    command: 'migrate verify',
+    level,
+    plugin: analysis.plugin,
+    migration: publicMigrationReport(analysis).migration,
+    stages: [{ name: level === 'static' ? 'static' : 'preflight-static', passed: analysis.summary.errors === 0, report: publicMigrationReport(analysis) }],
+    status: analysis.summary.errors === 0 ? 'source-migrated' : 'analyzed',
+    passed: analysis.summary.errors === 0,
+    manualBehaviorVerificationRequired: true,
+  }
+  if (level === 'static') return result
+
+  const root = analysis.plugin.root
+  const manifest = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'))
+  const manager = packageManager(root)
+  const scripts = ['typecheck', 'build', 'test', 'pack:check'].filter(name => typeof manifest.scripts?.[name] === 'string')
+  const commandRuns = []
+  for (const script of scripts) {
+    const run = { name: script, ...commandResult(manager.command, manager.run(script), { cwd: root }) }
+    commandRuns.push(run)
+    if (!run.passed) break
+  }
+  const commands = commandRuns.map(commandEvidence)
+  const artifactProducerDeclared = scripts.includes('build') || scripts.includes('pack:check')
+  const commandsPassed = artifactProducerDeclared && commandRuns.length === scripts.length && commandRuns.every(item => item.passed)
+  const buildNote = scripts.length === 0
+    ? 'No recognized verification scripts were declared.'
+    : !artifactProducerDeclared ? 'Artifact verification requires a build or pack:check script; typecheck/test alone are insufficient.' : undefined
+  result.stages.push({ name: 'build', passed: commandsPassed, packageManager: manager.command, commands, note: buildNote })
+  const postBuild = analyzeMigration(root, options)
+  const postBuildPassed = postBuild.summary.errors === 0
+  result.stages.push({ name: 'static-after-build', passed: postBuildPassed, report: publicMigrationReport(postBuild) })
+  const buildPassed = commandsPassed && postBuildPassed
+  result.passed = buildPassed
+  if (result.passed) result.status = 'artifact-verified'
+  if (level === 'build' || !result.passed) return result
+
+  const dsh = discoverDsh(options)
+  const verificationRoot = mkdtempSync(join(tmpdir(), 'dsh-doctor-migrate-'))
+  const packDir = join(verificationRoot, 'pack')
+  const dshHome = join(verificationRoot, 'dsh-home')
+  mkdirSync(packDir, { recursive: true })
+  mkdirSync(dshHome, { recursive: true })
+  const env = { ...process.env, DSH_HOME: dshHome }
+  const [versionCommand, versionArgs] = dshInvocation(dsh, ['--version'])
+  const versionRun = commandResult(versionCommand, versionArgs, { cwd: root, env })
+  const actualDshVersion = versionRun.stdout.trim()
+  const versionPassed = versionRun.passed && actualDshVersion === analysis.migration.to.version
+  const pack = commandResult(manager.command, manager.pack(packDir), { cwd: root })
+  const tarball = tarballFromPack(pack, packDir)
+  const runtimeCommands = []
+  if (versionPassed && pack.passed && tarball && existsSync(tarball)) {
+    for (const args of [
+      ['plugin', '--profile', 'web', 'add', tarball],
+      ['--profile', 'web', '--dump-config'],
+      ['--profile', 'web', '--help'],
+    ]) {
+      const [command, commandArgs] = dshInvocation(dsh, args)
+      const step = commandResult(command, commandArgs, { cwd: root, env })
+      runtimeCommands.push(step)
+      if (!step.passed) break
+    }
+  }
+  const profileEvidence = runtimeProfileEvidence(dshHome, analysis.plugin.name, runtimeCommands[1]?.stdout ?? '')
+  const evidencePassed = Object.entries(profileEvidence).filter(([key]) => key !== 'evidenceError').every(([, value]) => value === true)
+  const runtimePassed = versionPassed && pack.passed && tarball !== undefined && runtimeCommands.length === 3 && runtimeCommands.every(item => item.passed) && evidencePassed
+  result.stages.push({
+    name: 'runtime',
+    passed: runtimePassed,
+    dshVersion: { expected: analysis.migration.to.version, actual: actualDshVersion, passed: versionPassed, command: commandEvidence(versionRun) },
+    pack: commandEvidence(pack),
+    tarball,
+    commands: runtimeCommands.map(commandEvidence),
+    profileEvidence,
+    isolatedDshHome: dshHome,
+  })
+  result.passed = result.passed && runtimePassed
+  if (runtimePassed) result.status = 'runtime-verified'
+  if (runtimePassed && !options.keepTemp) {
+    rmSync(verificationRoot, { recursive: true, force: true })
+    result.stages.at(-1).isolatedDshHome = '(removed after successful verification)'
+  } else result.retainedTemporaryDirectory = verificationRoot
+  return result
+}
+
+export function formatVerification(result, language = 'en') {
+  const zh = language === 'zh'
+  const lines = [`${zh ? '升级验证' : 'Migration verification'}: ${result.plugin.name}`, `${zh ? '状态' : 'Status'}: ${result.status} (${result.passed ? 'PASS' : 'FAIL'})`]
+  for (const stage of result.stages) lines.push(`- ${stage.name}: ${stage.passed ? 'PASS' : 'FAIL'}`)
+  if (result.retainedTemporaryDirectory) lines.push(`${zh ? '失败现场保留在' : 'Failure workspace retained at'}: ${result.retainedTemporaryDirectory}`)
+  if (result.manualBehaviorVerificationRequired) lines.push(zh ? '仍需人工验证插件的交互、生命周期与业务行为。' : 'Interaction, lifecycle, and business behavior still require manual verification.')
+  return `${lines.join('\n')}\n`
+}