@bruc3van/dsh-doctor 0.1.3 → 0.1.5

package/README.en.md

@@ -2,7 +2,7 @@
 
 [中文](README.md) | English
 
-DSH Doctor diagnoses common DeepSeek Harness failures, including startup errors, damaged configuration, and third-party plugin incompatibility. A normal run is entirely read-only. Repairs run only after you explicitly use `--fix`, inspect the exact file or command plan, and confirm it.
+DSH Doctor helps DSH and plugin users quickly identify plugins that break startup or stop working after a DSH upgrade. It groups each plugin's problems, impact, and recommended actions, while also checking common profile configuration and version-drift issues. Diagnosis is read-only by default; repairs run only after you explicitly use `--fix`, review the exact plan, and confirm it. File edits are backed up first.
 
 This is a community-maintained third-party tool and is not an official DeepSeek project. It does not load or execute code from the plugins it inspects.
 
@@ -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.
 
@@ -137,4 +138,6 @@ npm run check
 node src/cli.mjs --help
 ```
 
-The first publication of a new package must be performed by the npm account that owns the `@bruc3van` scope with `npm publish --access public`. Then configure a GitHub Actions Trusted Publisher in the npm package settings with Organization or user `bruc3van`, Repository `dsh-doctor`, Workflow filename `release.yml`, no Environment, and only the `npm publish` allowed action. Later releases are triggered by pushing a `vX.Y.Z` tag matching `package.json`; the workflow publishes through OIDC with npm provenance and requires no long-lived npm token.
+The first publication of a new package must be performed by the npm account that owns the `@bruc3van` scope with `npm publish --access public`. Then configure a GitHub Actions Trusted Publisher in the npm package settings with Organization or user `bruc3van`, Repository `dsh-doctor`, Workflow filename `release.yml`, no Environment, and only the `npm publish` allowed action.
+
+Before each later release, add a Chinese `## vX.Y.Z` entry matching the version tag to `CHANGELOG.md`. Pushing a tag that matches `package.json` makes the workflow publish through OIDC with npm provenance and automatically create or update the GitHub Release from that Chinese entry. The release fails if the entry is missing or contains no Chinese text. No long-lived npm token is required.

package/README.md

@@ -2,7 +2,7 @@
 
 中文 | [English](README.en.md)
 
-DSH Doctor 用来定位 DeepSeek Harness 无法启动、配置损坏和第三方插件不兼容等常见问题。默认运行完全只读；只有显式使用 `--fix`，查看精确的文件或命令计划并确认后，它才会实施可回滚的修复。
+DSH Doctor 面向 DSH 与插件使用者，帮助快速找出导致 DSH 启动异常或升级后不可用的插件，集中说明每个插件的问题、影响与处理方式，并检查常见的 profile 配置和版本漂移。诊断默认完全只读；只有显式使用 `--fix`、核对并确认精确的修复计划后才会执行，文件修改会先创建备份。
 
 这是社区维护的第三方工具，不属于 DeepSeek 官方项目。它不会加载或执行待检查插件的代码。
 
@@ -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`，第三方插件仍可能访问网络、绝对路径或启动外部进程，不能宣称无副作用。
 
@@ -137,4 +138,6 @@ npm run check
 node src/cli.mjs --help
 ```
 
-新包需要先由 `@bruc3van` 对应的 npm 账号完成一次 `npm publish --access public`，创建公开包页面。然后在 npm 包设置中添加 GitHub Actions Trusted Publisher：Organization or user 为 `bruc3van`，Repository 为 `dsh-doctor`，Workflow filename 为 `release.yml`，Environment 留空，Allowed actions 只启用 `npm publish`。后续推送与 `package.json` 版本一致的 `vX.Y.Z` tag，workflow 会通过 OIDC 发布并由 npm 自动生成 provenance，不需要保存长期 npm token。
+新包需要先由 `@bruc3van` 对应的 npm 账号完成一次 `npm publish --access public`，创建公开包页面。然后在 npm 包设置中添加 GitHub Actions Trusted Publisher：Organization or user 为 `bruc3van`，Repository 为 `dsh-doctor`，Workflow filename 为 `release.yml`，Environment 留空，Allowed actions 只启用 `npm publish`。
+
+后续发布前，需要在 `CHANGELOG.md` 中增加与版本 tag 同名的中文 `## vX.Y.Z` 条目。推送与 `package.json` 版本一致的 tag 后，workflow 会通过 OIDC 发布 npm 包、生成 provenance，并自动用该中文条目创建或更新 GitHub Release；缺少中文条目时发布流程会失败。不需要保存长期 npm token。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bruc3van/dsh-doctor",
-  "version": "0.1.3",
-  "description": "Diagnostics and confirmed recovery for DeepSeek Harness profiles and third-party plugins",
+  "version": "0.1.5",
+  "description": "Diagnose DSH plugins broken by upgrades, startup blockers, and profile issues with explicit, confirmed repairs",
   "license": "MIT",
   "type": "module",
   "repository": {

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,11 +44,6 @@ 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`)
@@ -75,31 +70,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 +121,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 +146,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

@@ -39,6 +39,7 @@ function finding(severity, code, message, options = {}) {
     message,
     ...options.package === undefined ? {} : { package: options.package },
     ...options.evidence === undefined ? {} : { evidence: options.evidence },
+    ...options.details === undefined ? {} : { details: options.details },
     ...options.suggestion === undefined ? {} : { suggestion: options.suggestion },
     ...options.repair === undefined ? {} : { repair: options.repair },
   }
@@ -86,6 +87,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
@@ -173,11 +180,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
@@ -205,7 +208,13 @@ 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 }
   }
 
@@ -269,7 +278,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,
@@ -283,7 +292,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)
@@ -293,7 +311,7 @@ function resolveHarnessContext(home, explicitRoot, findings) {
     return { root: canonical, packages: new Map(), version: manifest?.version, authoritative: false }
   }
 
-  findings.push(finding('warning', 'HARNESS_INSTALLATION_UNKNOWN', 'Could not locate the Harness installation used by this home.', {
+  findings.push(finding('warning', 'HARNESS_INSTALLATION_UNKNOWN', 'Could not locate the DSH installation currently used by this home.', {
     evidence: sharedDsh,
     suggestion: 'Pass --harness-root when diagnosing a source checkout.',
   }))
@@ -392,7 +410,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()
 }
@@ -400,6 +421,7 @@ export function extractStaticRequires(source) {
 function codePositions(source) {
   const code = new Uint8Array(source.length)
   let state = 'code'
+  let regexClass = false
   for (let index = 0; index < source.length; index += 1) {
     const char = source[index]
     const next = source[index + 1]
@@ -412,6 +434,9 @@ function codePositions(source) {
         index += 1
       } else if (char === "'" || char === '"' || char === '`') {
         state = char
+      } else if (char === '/' && regexCanStart(source, index)) {
+        state = 'regex'
+        regexClass = false
       } else {
         code[index] = 1
       }
@@ -425,6 +450,12 @@ 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 (char === '\\') {
       index += 1
     } else if (char === state) {
@@ -434,6 +465,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
 }
@@ -504,6 +546,7 @@ function inspectClientPackage(record, context) {
       package: name,
       evidence: record.file,
       suggestion: disableSuggestion,
+      repair: updateRepair(profile, name, commandRepair),
     }))
     return
   }
@@ -525,6 +568,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
   }
@@ -556,7 +601,7 @@ function inspectClientPackage(record, context) {
       ? harnessPackages.get(supplier)
       : harnessPackages.get(supplier) ?? resolvePackage(supplier)
     if (supplied === undefined || supplied.manifest?.dsh?.client === undefined) {
-      findings.push(finding('error', 'CLIENT_EXTERNAL_WITHOUT_SUPPLIER', `${name} requests ${specifier}, but the active Harness has no client module supplier.`, {
+      findings.push(finding('error', 'CLIENT_EXTERNAL_WITHOUT_SUPPLIER', `${name} requests ${specifier}, but the active DSH has no client module supplier.`, {
         package: name,
         evidence: record.file,
         suggestion: disableSuggestion,
@@ -569,7 +614,7 @@ function inspectClientPackage(record, context) {
     for (const dependency of inject ?? []) {
       if (!dependency.startsWith('@deepseek-ai/dsh-')) continue
       if (!harnessPackages.has(stripClientSuffix(dependency))) {
-        findings.push(finding('error', 'REMOVED_CLIENT_INJECT', `${name} injects ${dependency}, which is absent from the active Harness source tree.`, {
+        findings.push(finding('error', 'REMOVED_CLIENT_INJECT', `${name} injects ${dependency}, which is absent from the active DSH.`, {
           package: name,
           evidence: record.file,
           suggestion: disableSuggestion,
@@ -983,7 +1028,7 @@ function inspectProfileHarnessPackages(profileDir, home, harness, findings) {
       }
     }
     if (harness.authoritative && !harness.packages.has(name)) {
-      findings.push(finding('warning', 'STALE_PROFILE_HARNESS_PACKAGE', `${name} remains in the profile but is absent from the active Harness source tree.`, {
+      findings.push(finding('warning', 'STALE_PROFILE_HARNESS_PACKAGE', `${name} remains in the profile but is absent from the active DSH.`, {
         package: name,
         evidence: profileManifestFile,
         suggestion: 'Reinstall the profile with the active DSH CLI and review plugins that still require this package.',
@@ -1005,7 +1050,7 @@ function inspectCompatibility(record, context) {
       .filter(name => name.startsWith('@deepseek-ai/dsh-') && !harnessPackages.has(name))
       .sort()
     if (removedPeers.length > 0) {
-      findings.push(finding('warning', 'LEGACY_HARNESS_PEERS', `${packageName} still declares Harness packages that no longer exist in the active source tree.`, {
+      findings.push(finding('warning', 'LEGACY_HARNESS_PEERS', `${packageName} declares old interface packages that the active DSH has removed.`, {
         package: packageName,
         evidence: removedPeers.join(', '),
         suggestion: 'Update this plugin before relying on it with the current DSH release.',
@@ -1017,7 +1062,7 @@ function inspectCompatibility(record, context) {
       .filter(name => name.startsWith('@deepseek-ai/dsh-') && !harnessPackages.has(name))
       .sort()
     if (removedDependencies.length > 0) {
-      findings.push(finding('warning', 'LEGACY_HARNESS_DEPENDENCIES', `${packageName} depends on Harness packages that no longer exist in the active source tree.`, {
+      findings.push(finding('warning', 'LEGACY_HARNESS_DEPENDENCIES', `${packageName} depends on Harness packages that no longer exist in the active DSH.`, {
         package: packageName,
         evidence: removedDependencies.join(', '),
         suggestion: 'Update this plugin; its bundled DSH APIs may be incompatible with the current release.',
@@ -1026,8 +1071,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,
@@ -1040,17 +1088,37 @@ 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} ${range} (active ${version})`)
+    mismatches.push({ name, required: range, active: version })
   }
   if (mismatches.length > 0) {
-    findings.push(finding('warning', 'HARNESS_PEER_VERSION_MISMATCH', `${packageName} has Harness peer ranges that do not accept the active versions.`, {
+    const grouped = new Map()
+    for (const mismatch of mismatches) {
+      const key = JSON.stringify([mismatch.required, mismatch.active])
+      const group = grouped.get(key) ?? {
+        required: mismatch.required, active: mismatch.active, packages: [],
+      }
+      group.packages.push(mismatch.name)
+      grouped.set(key, group)
+    }
+    const groups = [...grouped.values()]
+      .map(group => ({ ...group, packages: group.packages.sort() }))
+    const evidence = groups.flatMap((group, index) => [
+      ...(groups.length > 1 ? [`Group ${String(index + 1)}:`] : []),
+      `${groups.length > 1 ? '  ' : ''}Plugin requires: ${group.required}`,
+      `${groups.length > 1 ? '  ' : ''}Active DSH: ${group.active}`,
+      `${groups.length > 1 ? '  ' : ''}Affected ${String(group.packages.length)} package(s): ${group.packages.join(', ')}`,
+    ]).join('\n')
+    findings.push(finding('warning', 'HARNESS_PEER_VERSION_MISMATCH', `${packageName} declares compatibility ranges that exclude the active DSH version.`, {
       package: packageName,
-      evidence: mismatches.join(', '),
-      suggestion: `Update ${packageName} to a release compatible with the active Harness.`,
+      evidence,
+      details: { peerVersionGroups: groups },
+      suggestion: `Update ${packageName} to a release compatible with the active DSH.`,
       repair: updateRepair(profile, packageName, commandRepair),
     }))
   }
+  return { declaredPeers, resolvedPeers }
 }
 
 function hasHarnessCompatibilityDeclaration(record) {
@@ -1059,28 +1127,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)}.`))
@@ -1249,6 +1320,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,
@@ -1258,7 +1330,7 @@ export function diagnose(options = {}) {
       profile,
       resolvePackage,
     })
-    inspectCompatibility(record, {
+    const check = inspectCompatibility(record, {
       findings,
       commandRepair,
       profile,
@@ -1266,6 +1338,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,
@@ -1292,7 +1365,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)
@@ -1318,6 +1395,20 @@ function finish(context, findings) {
   return { version: 1, ok: summary.errors === 0, context, summary, findings }
 }
 
+function appendReportField(lines, label, value, indent = '      ') {
+  const valueLines = String(value).split('\n')
+  if (valueLines.length === 1) {
+    lines.push(`${indent}${label}: ${valueLines[0]}`)
+    return
+  }
+  lines.push(`${indent}${label}:`)
+  lines.push(...valueLines.map(line => `${indent}  ${line}`))
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter(value => typeof value === 'string' && value.length > 0))]
+}
+
 export function formatReport(report, options = {}) {
   const color = options.color ?? false
   const language = options.language ?? 'en'
@@ -1336,7 +1427,7 @@ export function formatReport(report, options = {}) {
     'DSH Doctor',
     `${zh ? 'Profile' : 'Profile'}: ${report.context.profile}`,
     `${zh ? 'DSH 主目录' : 'Home'}: ${report.context.home}`,
-    `Harness: ${report.context.harness.version ?? 'unknown'}${report.context.harness.root ? ` (${report.context.harness.root})` : ''}`,
+    `${zh ? '当前使用的 DSH' : 'Active DSH'}: ${report.context.harness.version ?? 'unknown'}${report.context.harness.root ? ` (${report.context.harness.root})` : ''}`,
     `${zh ? 'DSH CLI' : 'DSH CLI'}: ${cliText}`,
     `${zh ? 'Profile 插件' : 'Profile plugins'}: ${String(report.context.packages.length)}`,
     zh
@@ -1345,19 +1436,130 @@ export function formatReport(report, options = {}) {
     `${zh ? '输出语言' : 'Output language'}: ${languageName(language)}`,
     '',
   ]
-  if (report.findings.length === 0) {
-    lines.push(paint('info', zh ? '正常  当前检查范围内未发现问题。' : 'OK  No problems found by the MVP checks.'))
+  const packageNames = new Set(report.context.packages.map(item => item.name))
+  const pluginFindings = new Map()
+  const environmentFindings = []
+  for (const item of report.findings) {
+    if (item.package !== undefined && packageNames.has(item.package)) {
+      const items = pluginFindings.get(item.package) ?? []
+      items.push(item)
+      pluginFindings.set(item.package, items)
+    } else environmentFindings.push(item)
+  }
+  const problemPackages = report.context.packages
+    .filter(item => (item.compatibility === 'incompatible' || item.compatibility === 'risk')
+      && pluginFindings.has(item.name))
+    .sort((left, right) => {
+      const rank = { incompatible: 0, risk: 1 }
+      return rank[left.compatibility] - rank[right.compatibility] || left.name.localeCompare(right.name)
+    })
+  const unknownPackages = report.context.packages
+    .filter(item => item.compatibility === 'unknown')
+    .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 current checks.'))
   } else {
-    for (const original of report.findings) {
+    if (problemPackages.length > 0) {
+      lines.push(zh
+        ? `插件问题（${String(problemPackages.length)} 个）`
+        : `Plugin problems (${String(problemPackages.length)})`)
+      lines.push('')
+      for (const plugin of problemPackages) {
+        const originals = pluginFindings.get(plugin.name)
+        const status = plugin.compatibility === 'incompatible'
+          ? zh ? '不兼容' : 'INCOMPATIBLE'
+          : zh ? '有风险' : 'RISK'
+        const severity = plugin.compatibility === 'incompatible' ? 'error' : 'warning'
+        lines.push(paint(severity, `[${status}] ${plugin.name}`))
+        appendReportField(lines, zh ? '版本' : 'Version', plugin.installed === false
+          ? zh ? '未安装' : 'not installed'
+          : plugin.version ?? (zh ? '未知' : 'unknown'))
+        lines.push(zh
+          ? `      问题（${String(originals.length)}）:`
+          : `      Problems (${String(originals.length)}):`)
+        originals.forEach((original, index) => {
+          const item = localizedFinding(original, language)
+          const prefix = `${plugin.name} `
+          const message = item.message.startsWith(prefix) ? item.message.slice(prefix.length) : item.message
+          lines.push(`        ${String(index + 1)}. [${item.code}] ${message}`)
+          if (item.evidence !== undefined) appendReportField(
+            lines, zh ? '证据' : 'Evidence', item.evidence, '          ',
+          )
+        })
+        const suggestionGroups = new Map()
+        for (const original of originals) {
+          const suggestion = localizedFinding(original, language).suggestion
+          if (suggestion === undefined) continue
+          const key = original.repair?.id ?? `suggestion:${suggestion}`
+          if (!suggestionGroups.has(key)) suggestionGroups.set(key, suggestion)
+        }
+        const suggestions = [...suggestionGroups.values()]
+        if (suggestions.length > 0) {
+          lines.push(`      ${zh ? '处理建议' : 'Recommended actions'}:`)
+          suggestions.forEach(item => lines.push(`        - ${item}`))
+        }
+        const commands = uniqueStrings(originals
+          .filter(item => item.repair?.kind === 'command')
+          .map(item => item.repair.command.map(quote).join(' ')))
+        if (commands.length > 0) {
+          lines.push(`      ${zh ? '可执行命令' : 'Available commands'}:`)
+          commands.forEach(command => lines.push(`        $ ${command}`))
+        }
+        lines.push('')
+      }
+    }
+
+    if (unknownPackages.length > 0) {
+      lines.push(zh
+        ? `兼容性未确认（${String(unknownPackages.length)} 个插件）`
+        : `Compatibility unknown (${String(unknownPackages.length)} plugin(s))`)
+      for (const plugin of unknownPackages) {
+        lines.push(`[${zh ? '未知' : 'UNKNOWN'}] ${plugin.name}${plugin.version ? ` ${plugin.version}` : ''}`)
+        appendReportField(lines, zh ? '原因' : 'Reason', zh
+          ? '插件没有声明当前 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.')
+      }
+      lines.push('')
+    }
+
+    const stale = environmentFindings.filter(item => item.code === 'STALE_PROFILE_HARNESS_PACKAGE')
+    const otherEnvironment = environmentFindings.filter(item => item.code !== 'STALE_PROFILE_HARNESS_PACKAGE')
+    if (stale.length > 0 || otherEnvironment.length > 0) {
+      lines.push(zh ? 'DSH 环境问题' : 'DSH environment problems')
+      lines.push('')
+    }
+    if (stale.length > 0) {
+      lines.push(paint('warning', zh
+        ? `[警告] [STALE_PROFILE_HARNESS_PACKAGE ×${String(stale.length)}] 检测到当前 DSH 已不再包含的 profile 残留包。`
+        : `[WARN] [STALE_PROFILE_HARNESS_PACKAGE ×${String(stale.length)}] Profile packages remain that the active DSH no longer includes.`))
+      lines.push(`      ${zh ? '残留包' : 'Stale packages'}:`)
+      for (const original of stale) {
+        const item = localizedFinding(original, language)
+        lines.push(`        - ${item.package ?? (zh ? '未知包' : 'unknown package')}`)
+        if (item.evidence !== undefined) appendReportField(
+          lines, zh ? '位置' : 'Location', item.evidence, '          ',
+        )
+      }
+      const suggestions = uniqueStrings(stale.map(item => localizedFinding(item, language).suggestion))
+      suggestions.forEach(item => appendReportField(lines, zh ? '处理建议' : 'Recommended action', item))
+      lines.push('')
+    }
+    for (const original of otherEnvironment) {
       const item = localizedFinding(original, language)
       const label = zh
         ? item.severity === 'error' ? '错误' : item.severity === 'warning' ? '警告' : '信息'
-        : item.severity === 'error' ? 'ERROR' : item.severity === 'warning' ? 'WARN ' : 'INFO '
+        : item.severity === 'error' ? 'ERROR' : item.severity === 'warning' ? 'WARN' : 'INFO'
       lines.push(paint(item.severity, `${label} [${item.code}] ${item.message}`))
-      if (item.package !== undefined) lines.push(`      ${zh ? '包' : 'Package'}: ${item.package}`)
-      if (item.evidence !== undefined) lines.push(`      ${zh ? '证据' : 'Evidence'}: ${item.evidence}`)
-      if (item.suggestion !== undefined) lines.push(`      ${zh ? '建议' : 'Action'}: ${item.suggestion}`)
-      if (item.repair?.kind === 'command') lines.push(`      ${zh ? '更新命令' : 'Update command'}: ${item.repair.command.map(quote).join(' ')}`)
+      if (item.package !== undefined) appendReportField(lines, zh ? '包' : 'Package', item.package)
+      if (item.evidence !== undefined) appendReportField(lines, zh ? '证据' : 'Evidence', item.evidence)
+      if (item.suggestion !== undefined) appendReportField(lines, zh ? '处理建议' : 'Recommended action', item.suggestion)
+      if (item.repair?.kind === 'command') appendReportField(
+        lines, zh ? '可执行命令' : 'Available command', `$ ${item.repair.command.map(quote).join(' ')}`,
+      )
       lines.push('')
     }
   }
@@ -1365,7 +1567,11 @@ export function formatReport(report, options = {}) {
     ? `汇总：${String(report.summary.errors)} 个错误，${String(report.summary.warnings)} 个警告`
     : `Summary: ${String(report.summary.errors)} error(s), ${String(report.summary.warnings)} warning(s)`)
   if (report.summary.errors > 0) lines.push(zh
-    ? 'Harness 可能无法启动。请优先更新或停用产生错误的插件。'
-    : 'Harness may fail to start. Upgrade or disable the error-producing plugin first.')
+    ? 'DSH 可能无法启动。请优先更新或停用产生错误的插件。'
+    : 'DSH may fail to start. Upgrade or disable the error-producing plugin first.')
+  lines.push('')
+  lines.push(zh
+    ? '本诊断结果由 @bruc3van/dsh-doctor 生成，仅供参考。欢迎在 GitHub Star 或反馈问题：https://github.com/bruc3van/dsh-doctor'
+    : 'This diagnostic report was generated by @bruc3van/dsh-doctor for reference only. Star the project or share feedback on GitHub: https://github.com/bruc3van/dsh-doctor')
   return `${lines.join('\n')}\n`
 }

package/src/i18n.mjs

@@ -59,7 +59,7 @@ const ZH_MESSAGES = {
   PACKAGE_NAME_MISMATCH: item => `${item.package ?? '依赖'}解析到了名称不匹配的包。`,
   INVALID_HARNESS_ROOT: () => '指定的 Harness 根目录不是有效的源码工作区。',
   INVALID_WORKSPACE_MANIFEST: () => '已忽略一个无效的 Harness workspace 包清单。',
-  HARNESS_INSTALLATION_UNKNOWN: () => '无法定位这个 DSH Home 实际使用的 Harness。',
+  HARNESS_INSTALLATION_UNKNOWN: () => '无法定位这个 DSH Home 当前使用的 DSH 安装。',
   INVALID_DEPENDENCY_MAP: item => `${captured(item.message, /^(\S+) must be/) ?? '依赖字段'}必须是“包名到版本范围”的对象。`,
   INVALID_CLIENT_DECLARATION: item => `${item.package} 的 dsh.client 声明无效。`,
   INVALID_CLIENT_PLATFORM: item => `${item.package} 的 dsh.client.platform 必须是字符串。`,
@@ -71,10 +71,10 @@ const ZH_MESSAGES = {
   CLIENT_BUNDLE_UNREADABLE: item => `无法读取 ${item.package} 的客户端 bundle。`,
   UNDECLARED_CLIENT_REQUIRE: item => `${item.package} 引用了 ${captured(item.message, / requires (.+) but does not/) ?? '未声明模块'}，但没有在 dsh.client.external 中声明。`,
   REDUNDANT_CLIENT_EXTERNAL: item => `${item.package} 把平台模块 ${captured(item.message, / module (.+) as an external/) ?? ''} 重复声明为 external。`,
-  CLIENT_EXTERNAL_WITHOUT_SUPPLIER: item => `${item.package} 请求了 ${captured(item.message, / requests (.+), but/) ?? '客户端模块'}，但当前 Harness 没有对应的模块提供方。`,
-  REMOVED_CLIENT_INJECT: item => `${item.package} 注入了 ${captured(item.message, / injects (.+), which/) ?? '已移除的模块'}，但当前 Harness 源码中已不存在该模块。`,
-  LEGACY_HARNESS_PEERS: item => `${item.package} 仍声明了当前 Harness 源码中已不存在的旧包。`,
-  LEGACY_HARNESS_DEPENDENCIES: item => `${item.package} 仍依赖当前 Harness 源码中已不存在的旧包。`,
+  CLIENT_EXTERNAL_WITHOUT_SUPPLIER: item => `${item.package} 请求了 ${captured(item.message, / requests (.+), but/) ?? '客户端模块'}，但当前使用的 DSH 没有对应的模块提供方。`,
+  REMOVED_CLIENT_INJECT: item => `${item.package} 注入了 ${captured(item.message, / injects (.+), which/) ?? '已移除的模块'}，但当前使用的 DSH 中已不存在该模块。`,
+  LEGACY_HARNESS_PEERS: item => `${item.package} 声明依赖当前使用的 DSH 已移除的旧接口包。`,
+  LEGACY_HARNESS_DEPENDENCIES: item => `${item.package} 仍依赖当前使用的 DSH 中已不存在的旧包。`,
   BUNDLE_NOT_INSTALLED: item => `配置中的 bundle ${item.package} 尚未安装。`,
   BUNDLE_DECLARATION_MISSING: item => `${item.package} 被列为 profile bundle，但没有声明 dsh.bundle.patch。`,
   BUNDLE_PATCH_MISSING: item => `${item.package} 的 bundle patch 文件缺失。`,
@@ -92,7 +92,7 @@ const ZH_MESSAGES = {
   INVALID_CREDENTIALS_DOCUMENT: () => 'Harness 凭据文件无法解析。',
   INVALID_CREDENTIALS_ROOT: () => 'Harness 凭据文件顶层必须是映射。',
   INVALID_CREDENTIALS_LAYOUT: () => 'Harness 凭据文件不是受支持的 version 1 结构。',
-  HARNESS_PEER_VERSION_MISMATCH: item => `${item.package} 声明的 Harness peer 版本范围不接受当前已安装版本。`,
+  HARNESS_PEER_VERSION_MISMATCH: item => `${item.package} 声明的兼容范围不包含当前使用的 DSH 版本。`,
   INVALID_PROFILE_NAME: item => `Profile 名称无效：${captured(item.message, /^Invalid profile name (.+)\.$/) ?? ''}`,
   PROFILE_NOT_FOUND: item => `Profile ${captured(item.message, /^Profile (.+) does not exist\.$/) ?? ''} 不存在。`,
   INVALID_DSH_CONFIGURATION: () => 'dsh 字段存在时必须是对象。',
@@ -114,7 +114,7 @@ const ZH_MESSAGES = {
   LOCKFILE_DEPENDENCY_STALE: item => `pnpm lockfile 仍包含未声明的依赖 ${item.package}。`,
   DSH_CLI_HARNESS_VERSION_MISMATCH: () => '当前 DSH CLI 与诊断到的 Harness 版本不一致。',
   DUPLICATE_HARNESS_PACKAGE_VERSION: item => `${item.package} 在 profile 与共享 DSH 安装中存在不同版本。`,
-  STALE_PROFILE_HARNESS_PACKAGE: item => `${item.package} 残留在 profile 中，但当前 Harness 源码已不再包含它。`,
+  STALE_PROFILE_HARNESS_PACKAGE: item => `${item.package} 残留在 profile 中，但当前使用的 DSH 已不再包含它。`,
   PROFILE_HARNESS_SCOPE_UNREADABLE: () => 'Profile 内的 @deepseek-ai 包作用域无法作为目录读取。',
 }
 
@@ -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,
@@ -155,7 +156,7 @@ const ZH_SUGGESTIONS = {
   INVALID_SETTINGS_ROOT: () => '把顶层标量或数组替换为映射。',
   INVALID_CREDENTIALS_DOCUMENT: () => '只修复报告的结构；Doctor 永远不会输出或重写秘密值。',
   INVALID_CREDENTIALS_LAYOUT: () => '迁移文档结构，不要暴露或修改秘密值。',
-  HARNESS_PEER_VERSION_MISMATCH: item => `把 ${item.package} 更新到兼容当前 Harness 的版本。`,
+  HARNESS_PEER_VERSION_MISMATCH: item => `把 ${item.package} 更新到兼容当前使用的 DSH 的版本。`,
   PROFILE_NOT_FOUND: () => '先启动一次该 profile，或用当前 DSH 安装初始化它。',
   INVALID_DSH_CONFIGURATION: () => '启动 Harness 前，请先修复 dsh 配置对象。',
   INVALID_PROFILE_CONFIGURATION: () => '启动 Harness 前，请先修复 dsh.profile 配置对象。',
@@ -188,9 +189,21 @@ export function localizedFinding(item, language) {
   if (language !== 'zh') return item
   const message = ZH_MESSAGES[item.code]?.(item) ?? item.message
   const suggestion = item.suggestion === undefined ? undefined : (ZH_SUGGESTIONS[item.code]?.(item) ?? item.suggestion)
-  const evidence = typeof item.evidence === 'string'
-    ? item.evidence.replaceAll('(active ', '(当前 ').replace(/ at line (\d+), column (\d+)/g, '，第 $1 行第 $2 列')
-    : item.evidence
+  const peerGroups = item.details?.peerVersionGroups
+  const evidence = Array.isArray(peerGroups)
+    ? peerGroups.flatMap((group, index) => [
+      ...(peerGroups.length > 1 ? [`第 ${String(index + 1)} 组：`] : []),
+      `${peerGroups.length > 1 ? '  ' : ''}插件要求：${group.required}`,
+      `${peerGroups.length > 1 ? '  ' : ''}当前 DSH：${group.active}`,
+      `${peerGroups.length > 1 ? '  ' : ''}涉及 ${String(group.packages.length)} 个包：${group.packages.join('、')}`,
+    ]).join('\n')
+    : typeof item.evidence === 'string'
+      ? (item.code === 'LEGACY_HARNESS_PEERS' || item.code === 'LEGACY_HARNESS_DEPENDENCIES'
+          ? item.evidence.replaceAll(', ', '、')
+          : item.evidence)
+        .replaceAll('(active ', '(当前 ')
+        .replace(/ at line (\d+), column (\d+)/g, '，第 $1 行第 $2 列')
+      : item.evidence
   return { ...item, message, suggestion, evidence }
 }
 

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
     }
   }