@bruc3van/dsh-doctor 0.1.4 → 0.1.6

package/README.en.md

@@ -23,7 +23,7 @@ npx @bruc3van/dsh-doctor
 
 By default, Doctor checks `$DSH_HOME/profiles/web`. If `DSH_HOME` is unset, it uses `~/.dsh`.
 
-Doctor does not require `dsh` to be installed as a global command. It searches PATH, the current project, shared profile installations, links left by the npx cache, and built Harness source checkouts, in that order. For a bundled DSH Desktop runtime or another custom installation, pass `--dsh-command /path/to/dsh`; the official package's `lib/bin.js` is also accepted. If no CLI can be found, Doctor still completes its read-only checks but does not offer or run command-based repairs that it cannot verify.
+Doctor does not require `dsh` to be installed as a global command. It searches, in order, an explicit `--dsh-command` or `DSH_DOCTOR_DSH_COMMAND`, the CLI under an explicit `--harness-root`, the shared profile installation or links left by the npx cache, the current project, PATH, and finally an automatically detected Harness source checkout. For a bundled DSH Desktop runtime or another custom installation, pass `--dsh-command /path/to/dsh`; the official package's `lib/bin.js` is also accepted. If no CLI can be found, Doctor still completes its read-only checks but does not offer or run command-based repairs that it cannot verify.
 
 ## How it works
 
@@ -80,7 +80,7 @@ After DSH is updated, Doctor assigns every direct profile plugin one explicit st
 
 - `incompatible`: Doctor found an error that can prevent the plugin or Harness from loading, such as a missing plugin or an injection targeting a removed client runtime.
 - `risk`: Doctor found a current-version risk, such as a Harness peer range that rejects the new version, a dependency on a removed DSH package, an unsupported Node.js version, or installation drift.
-- `unknown`: The plugin does not declare a Harness compatibility range through `peerDependencies`. Doctor cannot prove it supports the upgraded DSH, but does not report uncertainty as a failure.
+- `unknown`: The plugin does not declare a Harness compatibility range through `peerDependencies`, or the active package version for a declared peer cannot be resolved. Doctor cannot prove it supports the upgraded DSH, but does not report uncertainty as a failure.
 - `compatible`: The declared compatibility ranges accept the active Harness and no plugin-related errors or warnings were found.
 
 Compatibility checks cover every direct profile plugin, not only frontend plugins with `dsh.client`. References to removed Harness APIs in bundle-only or server-side plugins are reported as well. After upgrading DSH, run `dsh-doctor` first, review the exact update recommendations, and then decide whether to continue with `dsh-doctor --fix`.
@@ -110,6 +110,7 @@ Every executable repair has a stable ID, risk level, description, and exact targ
 - External commands use fixed argument arrays and never construct shell commands.
 - `--json --fix --yes` captures subprocess output in the repair result so stdout remains exactly one valid JSON document.
 - Command repairs bind the diagnosed `DSH_HOME` and show the resolved CLI path instead of assuming `dsh` exists on PATH.
+- Each command repair has a 10-minute limit; a timeout terminates that action and marks subsequent actions as skipped.
 - A failed repair stops later actions and preserves backups already created.
 - Doctor runs every diagnostic again after repairs and uses the final state for its exit code.
 
@@ -125,7 +126,7 @@ The initial release automatically performs only deterministic operations, such a
 
 - Static scanning recognizes only literal `require("package")` calls. Dynamic dependencies require a future bundle metadata contract.
 - Configuration checks cover syntax and structures that Doctor can align deterministically. Patch composition follows the current Harness algorithm, but Doctor does not evaluate `!!js` or load third-party plugins.
-- Version compatibility is based on plugin `peerDependencies` and resolvable active Harness package versions. A plugin without a declared range can receive only structural checks and an `unknown` compatibility state.
+- Version compatibility is based on plugin `peerDependencies` and resolvable active Harness package versions. A plugin without a declared range, or whose corresponding active version cannot be resolved, can receive only structural checks and an `unknown` compatibility state.
 - Lockfile checks deterministically cross-check the direct profile importer only; they do not recursively scan the complete npm dependency graph.
 - A runtime startup probe is not enabled. Even a copied `DSH_HOME` would not make arbitrary third-party plugin code side-effect-free because it could access the network, absolute paths, or external processes.
 

package/README.md

@@ -23,7 +23,7 @@ npx @bruc3van/dsh-doctor
 
 默认检查 `$DSH_HOME/profiles/web`；未设置 `DSH_HOME` 时使用 `~/.dsh`。
 
-Doctor 不要求 `dsh` 必须是全局命令。它会按顺序查找 PATH、当前项目安装、profile 共享安装或 npx 缓存留下的链接、已构建的 Harness 源码工作区。DSH Desktop 内置运行时或其他特殊安装可以通过 `--dsh-command /path/to/dsh`（也接受官方包的 `lib/bin.js`）明确指定。找不到 CLI 时仍会完成只读诊断，但不会提供或执行无法验证的命令型修复。
+Doctor 不要求 `dsh` 必须是全局命令。它会按顺序查找 `--dsh-command` 或 `DSH_DOCTOR_DSH_COMMAND` 指定的命令、显式 `--harness-root` 中的 CLI、profile 共享安装或 npx 缓存留下的链接、当前项目安装、PATH，最后是自动识别出的 Harness 源码工作区。DSH Desktop 内置运行时或其他特殊安装可以通过 `--dsh-command /path/to/dsh`（也接受官方包的 `lib/bin.js`）明确指定。找不到 CLI 时仍会完成只读诊断，但不会提供或执行无法验证的命令型修复。
 
 ## 工作方式
 
@@ -59,7 +59,7 @@ DSH 更新后，Doctor 会把每个 profile 插件归入一个明确状态，并
 
 - `incompatible`：已经发现会阻断插件加载或 Harness 启动的错误，例如插件未安装，或注入了已删除的 client runtime。
 - `risk`：发现当前版本风险，例如 Harness peer range 不接受新版本、仍依赖已删除的 DSH 包、Node.js 不兼容，或安装版本发生漂移。
-- `unknown`：插件没有通过 `peerDependencies` 声明 Harness 兼容范围；Doctor 无法证明它支持升级后的 DSH，但不会把未知误报成故障。
+- `unknown`：插件没有通过 `peerDependencies` 声明 Harness 兼容范围，或声明对应的当前 package 版本无法解析；Doctor 无法证明它支持升级后的 DSH，但不会把未知误报成故障。
 - `compatible`：插件声明的兼容范围接受当前 Harness，且没有发现插件相关错误或警告。
 
 兼容性检查覆盖所有 profile 直接插件，不再只检查带 `dsh.client` 的前端插件；纯 bundle 或服务端插件引用旧 Harness API 也会被报告。建议 DSH 升级后先运行一次 `dsh-doctor`，再根据精确的 update 建议决定是否执行 `dsh-doctor --fix`。
@@ -110,6 +110,7 @@ dsh-doctor --fix --yes --json
 - 外部命令使用固定 argv 调用，不拼接 shell 命令。
 - `--json --fix --yes` 会捕获子命令输出并放入修复结果，保证 stdout 始终只有一个合法 JSON 文档。
 - 命令修复绑定当前诊断的 `DSH_HOME`，并展示解析出的真实 CLI 路径；不会假定 PATH 中存在 `dsh`。
+- 单个命令修复最长运行 10 分钟，超时会终止该动作并把后续动作标记为跳过。
 - 任一步失败即停止后续修复，并保留已经创建的备份。
 - 完成后重新运行全部诊断，以最终状态决定退出码。
 
@@ -125,7 +126,7 @@ dsh-doctor --fix --yes --json
 
 - 静态扫描只识别代码中的字面量 `require("package")`；动态依赖需要未来的 bundle 元数据协议。
 - 配置检查覆盖语法和 Doctor 能稳定对齐的结构，并按当前 Harness patch 算法做无执行组合检查；不会求值 `!!js`，也不会加载第三方插件。
-- 版本兼容以插件 `peerDependencies` 和当前可解析 Harness package 版本为依据；未声明兼容范围的插件只能做结构检查。
+- 版本兼容以插件 `peerDependencies` 和当前可解析 Harness package 版本为依据；未声明兼容范围或无法解析对应当前版本的插件只能做结构检查。
 - lockfile 检查只对 profile 的直接依赖 importer 做确定性交叉验证，不递归扫描整个 npm 依赖树。
 - 真实启动探针尚未启用；即使复制 `DSH_HOME`，第三方插件仍可能访问网络、绝对路径或启动外部进程，不能宣称无副作用。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bruc3van/dsh-doctor",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Diagnose DSH plugins broken by upgrades, startup blockers, and profile issues with explicit, confirmed repairs",
   "license": "MIT",
   "type": "module",

package/src/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-import { defaultDshHome, formatReport, diagnose } from './doctor.mjs'
-import { applyRepairs, formatRepairPlan, repairsFromReport } from './repair.mjs'
+import { formatReport, diagnose, resolveDshHome } from './doctor.mjs'
+import { applyRepairs, formatRepairOutcome, formatRepairPlan, repairsFromReport } from './repair.mjs'
 import { resolveLanguage } from './i18n.mjs'
 import { readFileSync } from 'node:fs'
 import { dirname, resolve } from 'node:path'
@@ -44,26 +44,34 @@ const HELP_ZH = `用法：dsh-doctor [选项]
 
 const help = language => language === 'zh' ? HELP_ZH : HELP_EN
 
-function fail(message, language = 'en') {
-  process.stderr.write(`dsh-doctor: ${message}\n\n${help(language)}`)
-  process.exitCode = 2
-}
-
 function valueAfter(args, index, name) {
   const value = args[index + 1]
   if (value === undefined || value.startsWith('-')) throw new Error(`${name} needs a value`)
   return value
 }
 
+function optionValue(arg, name) {
+  const prefix = `${name}=`
+  if (!arg.startsWith(prefix)) return undefined
+  const value = arg.slice(prefix.length)
+  if (value === '') throw new Error(`${name} needs a value`)
+  return value
+}
+
 function parse(args) {
   const options = {}
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index]
     if (arg === '--profile') options.profile = valueAfter(args, index++, arg)
+    else if (arg.startsWith('--profile=')) options.profile = optionValue(arg, '--profile')
     else if (arg === '--home') options.home = valueAfter(args, index++, arg)
+    else if (arg.startsWith('--home=')) options.home = optionValue(arg, '--home')
     else if (arg === '--harness-root') options.harnessRoot = valueAfter(args, index++, arg)
+    else if (arg.startsWith('--harness-root=')) options.harnessRoot = optionValue(arg, '--harness-root')
     else if (arg === '--dsh-command') options.dshCommand = valueAfter(args, index++, arg)
+    else if (arg.startsWith('--dsh-command=')) options.dshCommand = optionValue(arg, '--dsh-command')
     else if (arg === '--lang') options.lang = valueAfter(args, index++, arg)
+    else if (arg.startsWith('--lang=')) options.lang = optionValue(arg, '--lang')
     else if (arg === '--json') options.json = true
     else if (arg === '--fix' || arg === '--repair') options.fix = true
     else if (arg === '--yes') options.yes = true
@@ -75,31 +83,37 @@ function parse(args) {
 }
 
 async function main() {
-  let options
-  try {
-    options = parse(process.argv.slice(2))
-  } catch (error) {
-    fail(error instanceof Error ? error.message : String(error))
+  const options = parse(process.argv.slice(2))
+  if (options.version) {
+    const here = dirname(fileURLToPath(import.meta.url))
+    const manifest = JSON.parse(readFileSync(resolve(here, '..', 'package.json'), 'utf8'))
+    process.stdout.write(`${manifest.version}\n`)
+    return
+  }
+  if (options.help) {
+    const requested = ['auto', 'zh', 'en'].includes(options.lang) ? options.lang : undefined
+    const language = resolveLanguage({
+      requested,
+      home: resolveDshHome(options.home),
+      systemLocale: Intl.DateTimeFormat().resolvedOptions().locale,
+    })
+    process.stdout.write(help(language))
     return
   }
   const language = resolveLanguage({
     requested: options.lang,
-    home: resolve(options.home ?? defaultDshHome()),
+    home: resolveDshHome(options.home),
     systemLocale: Intl.DateTimeFormat().resolvedOptions().locale,
   })
   if (options.yes && !options.fix) throw new Error('--yes requires --fix')
   if (options.json && options.fix && !options.yes) throw new Error('--json --fix requires --yes because a prompt would corrupt JSON output')
-  if (options.help) {
-    process.stdout.write(help(language))
-  } else if (options.version) {
-    const here = dirname(fileURLToPath(import.meta.url))
-    const manifest = JSON.parse(readFileSync(resolve(here, '..', 'package.json'), 'utf8'))
-    process.stdout.write(`${manifest.version}\n`)
-  } else {
+  {
     let report = diagnose(options)
     let repairs = []
+    let actions = []
+    let repairDeclined = false
     if (options.fix) {
-      const actions = repairsFromReport(report)
+      actions = repairsFromReport(report)
       if (actions.length === 0 && report.context.dshCli?.commandRepairNeeded && !report.context.dshCli.available) {
         throw new Error(language === 'zh'
           ? '未找到可用的 DSH CLI，无法执行命令型修复；请使用 --dsh-command 指定当前安装的 dsh 或 lib/bin.js'
@@ -120,13 +134,20 @@ async function main() {
         if (confirmed) {
           repairs = applyRepairs(actions, { captureOutput: options.json })
           if (repairs.every(item => item.status === 'applied')) report = diagnose(options)
-        }
+        } else repairDeclined = true
       }
     }
     const output = options.fix ? { ...report, repairs } : report
+    const noRepairMessage = options.fix && repairs.length === 0 && !options.json
+      ? formatRepairOutcome(actions, repairs, {
+          declined: repairDeclined,
+          findingCount: report.findings.length,
+          language,
+        })
+      : ''
     process.stdout.write(options.json
       ? `${JSON.stringify(output, null, 2)}\n`
-      : `${formatReport(report, { color: process.stdout.isTTY, language })}${repairs.length > 0 ? `${language === 'zh' ? '修复结果' : 'Repairs'}: ${JSON.stringify(repairs, null, 2)}\n` : ''}`)
+      : `${formatReport(report, { color: process.stdout.isTTY, language })}${repairs.length > 0 ? `${language === 'zh' ? '修复结果' : 'Repairs'}: ${JSON.stringify(repairs, null, 2)}\n` : noRepairMessage}`)
     process.exitCode = repairs.some(item => item.status === 'failed') ? 2 : report.summary.errors > 0 ? 1 : 0
   }
 }
@@ -138,7 +159,7 @@ try {
   if (process.argv.includes('--json')) {
     process.stdout.write(`${JSON.stringify({ version: 1, operationalError: message }, null, 2)}\n`)
   } else {
-    process.stderr.write(`dsh-doctor: ${message}\n`)
+    process.stderr.write(`dsh-doctor: ${message}\n\n${help('en')}`)
   }
   process.exitCode = 2
 }

package/src/doctor.mjs

@@ -7,6 +7,9 @@ import semver from 'semver'
 import { parseDocument } from 'yaml'
 import { languageName, localizedFinding } from './i18n.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',
@@ -87,6 +90,12 @@ function packagePathParts(name) {
   return /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name) ? [name] : undefined
 }
 
+function expandUserPath(value) {
+  if (value === '~') return homedir()
+  if (value.startsWith('~/') || value.startsWith('~\\')) return resolve(homedir(), value.slice(2))
+  return value
+}
+
 function packageManifestAt(directory, expectedName, findings, source) {
   const file = join(directory, 'package.json')
   if (!existsSync(file)) return undefined
@@ -162,11 +171,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
@@ -174,11 +184,7 @@ function localDshPackage(start) {
 }
 
 function commandFromValue(value, env, cwd) {
-  const expanded = value === '~'
-    ? homedir()
-    : value.startsWith('~/') || value.startsWith('~\\')
-      ? resolve(homedir(), value.slice(2))
-      : value
+  const expanded = expandUserPath(value)
   const looksLikePath = isAbsolute(expanded) || expanded.includes('/') || expanded.includes('\\') || expanded.startsWith('.')
   const file = looksLikePath ? resolve(cwd, expanded) : executableOnPath(expanded, env)
   if (file === undefined) return undefined
@@ -206,14 +212,19 @@ function resolveDshCli(options, harness, home) {
 
   const sharedPackage = join(home, 'profiles', 'node_modules', '@deepseek-ai', 'dsh')
   if (existsSync(sharedPackage)) {
-    const bin = manifestBin(realpathSync(sharedPackage))
+    let canonical
+    try {
+      canonical = realpathSync(sharedPackage)
+    } catch {
+      canonical = undefined
+    }
+    const bin = canonical === undefined ? undefined : manifestBin(canonical)
     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)
@@ -270,7 +281,7 @@ function indexWorkspace(root, findings) {
 
 function resolveHarnessContext(home, explicitRoot, findings) {
   if (explicitRoot !== undefined) {
-    const root = resolve(explicitRoot)
+    const root = resolve(expandUserPath(explicitRoot))
     if (!existsSync(join(root, 'package.json')) || !existsSync(join(root, 'packages'))) {
       findings.push(finding('error', 'INVALID_HARNESS_ROOT', 'The configured Harness root is not a source checkout.', {
         evidence: root,
@@ -284,7 +295,16 @@ function resolveHarnessContext(home, explicitRoot, findings) {
 
   const sharedDsh = join(home, 'profiles', 'node_modules', '@deepseek-ai', 'dsh')
   if (existsSync(sharedDsh)) {
-    const canonical = realpathSync(sharedDsh)
+    let canonical
+    try {
+      canonical = realpathSync(sharedDsh)
+    } catch (error) {
+      findings.push(finding('warning', 'HARNESS_INSTALLATION_UNKNOWN', 'Could not resolve the DSH installation currently used by this home.', {
+        evidence: `${sharedDsh}: ${error instanceof Error ? error.message : String(error)}`,
+        suggestion: 'Repair the shared DSH installation or pass --harness-root for a source checkout.',
+      }))
+      return { root: undefined, packages: new Map(), version: undefined, authoritative: false }
+    }
     const root = findHarnessRoot(canonical)
     if (root !== undefined) {
       const manifest = readJson(join(root, 'package.json'), 'Harness root manifest', findings)
@@ -393,7 +413,10 @@ export function extractStaticRequires(source) {
     if (!code[match.index]) continue
     const specifier = match[2]
     if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('node:') || BUILTIN_MODULES.has(specifier)) continue
-    if (packagePathParts(specifier) !== undefined || specifier.startsWith('@')) values.add(specifier)
+    const packageName = specifier.startsWith('@')
+      ? specifier.split('/').slice(0, 2).join('/')
+      : specifier.split('/')[0]
+    if (packagePathParts(packageName) !== undefined) values.add(specifier)
   }
   return [...values].sort()
 }
@@ -401,6 +424,8 @@ export function extractStaticRequires(source) {
 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]
@@ -411,8 +436,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
       }
@@ -426,6 +468,20 @@ function codePositions(source) {
         state = 'code'
         index += 1
       }
+    } else if (state === 'regex') {
+      if (char === '\\') index += 1
+      else if (char === '[') regexClass = true
+      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) {
@@ -435,6 +491,17 @@ function codePositions(source) {
   return code
 }
 
+function regexCanStart(source, slashIndex) {
+  let index = slashIndex - 1
+  while (index >= 0 && /\s/.test(source[index])) index -= 1
+  if (index < 0) return true
+  if ('([{=,:;!&|?~+-*%^<>'.includes(source[index])) return true
+  if (!/[a-zA-Z0-9_$]/.test(source[index])) return false
+  const end = index + 1
+  while (index >= 0 && /[a-zA-Z0-9_$]/.test(source[index])) index -= 1
+  return /^(?:await|case|delete|do|else|in|instanceof|new|of|return|throw|typeof|void|yield)$/.test(source.slice(index + 1, end))
+}
+
 function stripClientSuffix(specifier) {
   return specifier.endsWith('/client') ? specifier.slice(0, -'/client'.length) : specifier
 }
@@ -505,6 +572,7 @@ function inspectClientPackage(record, context) {
       package: name,
       evidence: record.file,
       suggestion: disableSuggestion,
+      repair: updateRepair(profile, name, commandRepair),
     }))
     return
   }
@@ -526,6 +594,8 @@ function inspectClientPackage(record, context) {
     findings.push(finding('error', 'CLIENT_BUNDLE_UNREADABLE', `${name} client bundle cannot be read.`, {
       package: name,
       evidence: `${file}: ${error instanceof Error ? error.message : String(error)}`,
+      suggestion: disableSuggestion,
+      repair: updateRepair(profile, name, commandRepair),
     }))
     return
   }
@@ -1027,8 +1097,11 @@ function inspectCompatibility(record, context) {
     }
   }
   const mismatches = []
+  let declaredPeers = 0
+  let resolvedPeers = 0
   for (const [name, range] of peers) {
     if (!name.startsWith('@deepseek-ai/') && name !== 'cordis') continue
+    declaredPeers += 1
     if (semver.validRange(range) === null) {
       findings.push(finding('warning', 'INVALID_HARNESS_PEER_RANGE', `${packageName} declares an invalid Harness peer range for ${name}.`, {
         package: packageName,
@@ -1041,6 +1114,7 @@ function inspectCompatibility(record, context) {
     if (supplier === undefined) continue
     const version = supplier.manifest?.version
     if (typeof version !== 'string' || semver.valid(version) === null) continue
+    resolvedPeers += 1
     if (semver.satisfies(version, range, { includePrerelease: true })) continue
     mismatches.push({ name, required: range, active: version })
   }
@@ -1070,6 +1144,7 @@ function inspectCompatibility(record, context) {
       repair: updateRepair(profile, packageName, commandRepair),
     }))
   }
+  return { declaredPeers, resolvedPeers }
 }
 
 function hasHarnessCompatibilityDeclaration(record) {
@@ -1078,28 +1153,31 @@ function hasHarnessCompatibilityDeclaration(record) {
     .some(name => name.startsWith('@deepseek-ai/') || name === 'cordis')
 }
 
-function pluginCompatibility(record, findings) {
+function pluginCompatibility(record, findings, compatibilityCheck) {
   const name = record.requestedName ?? record.manifest.name
   const related = findings.filter(item => item.package === name)
   if (related.some(item => item.severity === 'error')) return 'incompatible'
   if (related.some(item => item.severity === 'warning')) return 'risk'
   if (!hasHarnessCompatibilityDeclaration(record)) return 'unknown'
+  if (compatibilityCheck.resolvedPeers < compatibilityCheck.declaredPeers) return 'unknown'
   return 'compatible'
 }
 
 export function defaultDshHome(env = process.env) {
   const configured = env.DSH_HOME?.trim()
   if (configured !== undefined && configured.length > 0) {
-    if (configured === '~') return homedir()
-    if (configured.startsWith('~/') || configured.startsWith('~\\')) return resolve(homedir(), configured.slice(2))
-    return resolve(configured)
+    return resolve(expandUserPath(configured))
   }
   return join(homedir(), '.dsh')
 }
 
+export function resolveDshHome(value, env = process.env) {
+  return resolve(expandUserPath(value ?? defaultDshHome(env)))
+}
+
 export function diagnose(options = {}) {
   const findings = []
-  const home = resolve(options.home ?? defaultDshHome(options.env))
+  const home = resolveDshHome(options.home, options.env)
   const profile = options.profile ?? 'web'
   if (profile === '' || profile === '.' || profile === '..' || profile.includes('/') || profile.includes('\\')) {
     findings.push(finding('error', 'INVALID_PROFILE_NAME', `Invalid profile name ${JSON.stringify(profile)}.`))
@@ -1268,6 +1346,7 @@ export function diagnose(options = {}) {
   const thirdPartyRecords = dependencyNames
     .map(name => records.get(name))
     .filter(record => record !== undefined)
+  const compatibilityChecks = new Map()
   for (const record of thirdPartyRecords) {
     inspectClientPackage(record, {
       findings,
@@ -1277,7 +1356,7 @@ export function diagnose(options = {}) {
       profile,
       resolvePackage,
     })
-    inspectCompatibility(record, {
+    const check = inspectCompatibility(record, {
       findings,
       commandRepair,
       profile,
@@ -1285,6 +1364,7 @@ export function diagnose(options = {}) {
       harnessPackages: harness.packages,
       harnessPackagesAuthoritative: harness.authoritative,
     })
+    compatibilityChecks.set(record.requestedName ?? record.manifest.name, check)
     inspectPluginNodeEngine(
       record,
       dshCli?.command?.[0] === process.execPath ? process.version : undefined,
@@ -1311,7 +1391,11 @@ export function diagnose(options = {}) {
         installed: true,
         client: record.manifest?.dsh?.client !== undefined,
         bundle: record.manifest?.dsh?.bundle !== undefined,
-        compatibility: pluginCompatibility(record, findings),
+        compatibility: pluginCompatibility(
+          record,
+          findings,
+          compatibilityChecks.get(record.requestedName ?? record.manifest.name),
+        ),
       }
     }),
   }, findings)
@@ -1367,7 +1451,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}`,
@@ -1400,7 +1484,7 @@ export function formatReport(report, options = {}) {
     .sort((left, right) => left.name.localeCompare(right.name))
 
   if (report.findings.length === 0 && unknownPackages.length === 0) {
-    lines.push(paint('info', zh ? '正常  当前检查范围内未发现问题。' : 'OK  No problems found by the MVP checks.'))
+    lines.push(paint('info', zh ? '正常  当前检查范围内未发现问题。' : 'OK  No problems found by the current checks.'))
   } else {
     if (problemPackages.length > 0) {
       lines.push(zh
@@ -1459,8 +1543,8 @@ export function formatReport(report, options = {}) {
       for (const plugin of unknownPackages) {
         lines.push(`[${zh ? '未知' : 'UNKNOWN'}] ${plugin.name}${plugin.version ? ` ${plugin.version}` : ''}`)
         appendReportField(lines, zh ? '原因' : 'Reason', zh
-          ? '插件没有声明当前 DSH 的兼容范围。'
-          : 'The plugin does not declare a compatibility range for the active DSH.')
+          ? '插件没有声明当前 DSH 的兼容范围，或 Doctor 无法解析声明所对应的当前版本。'
+          : 'The plugin declares no range for the active DSH, or Doctor could not resolve the active version for a declared peer.')
         appendReportField(lines, zh ? '建议' : 'Action', zh
           ? '升级 DSH 后请关注该插件的发布说明或向插件作者确认。'
           : 'After a DSH upgrade, review the plugin release notes or ask its author to confirm compatibility.')

package/src/i18n.mjs

@@ -133,6 +133,7 @@ const ZH_SUGGESTIONS = {
   INVALID_CLIENT_INJECT: update,
   CLIENT_EXPORT_MISSING: update,
   CLIENT_BUNDLE_MISSING: update,
+  CLIENT_BUNDLE_UNREADABLE: update,
   UNDECLARED_CLIENT_REQUIRE: update,
   CLIENT_EXTERNAL_WITHOUT_SUPPLIER: update,
   REMOVED_CLIENT_INJECT: update,

package/src/repair.mjs

@@ -3,6 +3,9 @@ import { copyFileSync, readFileSync, renameSync, statSync, writeFileSync } from
 import { dirname, join } from 'node:path'
 import crossSpawn from 'cross-spawn'
 
+export const COMMAND_TIMEOUT_MS = 10 * 60 * 1000
+const COMMAND_MAX_BUFFER = 16 * 1024 * 1024
+
 function hash(value) {
   return createHash('sha256').update(value).digest('hex')
 }
@@ -40,6 +43,16 @@ export function formatRepairPlan(actions, options = {}) {
     : `${plan}${zh ? '执行这些修复吗？[y/N] ' : 'Apply these repairs? [y/N] '}`
 }
 
+export function formatRepairOutcome(actions, results, options = {}) {
+  if (results.length > 0) return ''
+  const zh = options.language === 'zh'
+  if (options.declined === true) return zh ? '修复结果：用户已取消。\n' : 'Repairs: cancelled by the user.\n'
+  if (actions.length > 0) return ''
+  return options.findingCount === 0
+    ? zh ? '修复结果：当前无需修复。\n' : 'Repairs: no repairs are needed.\n'
+    : zh ? '修复结果：没有可安全自动执行的修复，请按诊断建议手动处理。\n' : 'Repairs: no safe automatic repairs are available; follow the diagnostic suggestions manually.\n'
+}
+
 function localizedDescription(action, zh) {
   if (!zh) return action.description
   if (action.id.startsWith('update-package:')) return `更新 profile ${action.profile} 中的 ${action.package}。`
@@ -90,11 +103,15 @@ function limitedOutput(value, limit = 8192) {
 function applyCommand(action, options) {
   const [command, ...args] = action.command
   const captureOutput = options.captureOutput === true
+  const timeout = options.commandTimeoutMs ?? COMMAND_TIMEOUT_MS
+  if (!Number.isFinite(timeout) || timeout <= 0) throw new Error('command repair timeout must be a positive number')
   const result = crossSpawn.sync(command, args, {
     stdio: captureOutput ? ['ignore', 'pipe', 'pipe'] : 'inherit',
-    ...captureOutput ? { encoding: 'utf8' } : {},
+    ...captureOutput ? { encoding: 'utf8', maxBuffer: COMMAND_MAX_BUFFER } : {},
     env: action.env === undefined ? process.env : { ...process.env, ...action.env },
+    timeout,
   })
+  if (result.error?.code === 'ETIMEDOUT') throw new Error(`${command} timed out after ${String(timeout)} ms`)
   if (result.error != null) throw result.error
   if (result.status !== 0) {
     const reason = result.signal === null
@@ -115,7 +132,8 @@ function applyCommand(action, options) {
 
 export function applyRepairs(actions, options = {}) {
   const results = []
-  for (const action of actions) {
+  for (let index = 0; index < actions.length; index += 1) {
+    const action = actions[index]
     try {
       results.push(action.kind === 'json-edit' ? applyJsonEdit(action) : applyCommand(action, options))
     } catch (error) {
@@ -124,6 +142,9 @@ export function applyRepairs(actions, options = {}) {
         status: 'failed',
         error: error instanceof Error ? error.message : String(error),
       })
+      for (const skipped of actions.slice(index + 1)) {
+        results.push({ id: skipped.id, status: 'skipped' })
+      }
       break
     }
   }