@bruc3van/dsh-doctor 0.1.2 → 0.1.4

package/README.en.md

@@ -0,0 +1,142 @@
+# DSH Doctor
+
+[中文](README.md) | English
+
+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.
+
+## Installation
+
+Node.js `22.19+` or `24+` is required:
+
+```sh
+npm install --global @bruc3van/dsh-doctor
+dsh-doctor
+```
+
+You can also run it without a global installation:
+
+```sh
+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.
+
+## How it works
+
+A complete diagnosis and repair flow has four steps:
+
+1. `dsh-doctor` inspects the active DSH Home, profile, plugins, and Harness versions without making changes.
+2. Doctor reports evidence and recommendations by severity and plugin compatibility state.
+3. `dsh-doctor --fix` shows the exact file edits or DSH command plan and waits for confirmation.
+4. After applying confirmed repairs, Doctor runs the full diagnosis again and determines the exit code from the final state.
+
+Doctor never loads inspected plugins and does not modify configuration during a normal diagnosis. Operations without one deterministic answer—such as guessing credentials, rewriting damaged YAML, or removing a plugin—remain recommendations only.
+
+## Output language
+
+Text output supports English and Chinese. Doctor resolves the language in this order:
+
+1. `--lang zh|en`
+2. `DSH_DOCTOR_LANG`
+3. `locale.preference` in the active DSH Home's `settings.yaml`
+4. Terminal or system locale
+
+```sh
+dsh-doctor --lang zh
+dsh-doctor --lang en
+DSH_DOCTOR_LANG=zh dsh-doctor
+```
+
+`--json` always keeps stable English messages and diagnostic codes so language changes do not break automation.
+
+## Common commands
+
+```sh
+# Read-only diagnosis
+dsh-doctor
+dsh-doctor --profile web
+dsh-doctor --home /path/to/.dsh
+dsh-doctor --dsh-command /path/to/@deepseek-ai/dsh/lib/bin.js
+
+# Machine-readable read-only report with no prompts
+dsh-doctor --json
+
+# Show a repair plan, apply it after confirmation, and diagnose again
+dsh-doctor --fix
+
+# Explicitly confirm the current plan in automation
+dsh-doctor --fix --yes --json
+```
+
+`--repair` is an alias for `--fix`. `--yes` is valid only together with `--fix`.
+
+## Plugin compatibility after a DSH upgrade
+
+After DSH is updated, Doctor assigns every direct profile plugin one explicit state and summarizes the result in both text and JSON reports:
+
+- `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.
+- `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`.
+
+## Current checks
+
+- JSON root structure, dependency maps, bundle lists, and reload lifecycle in the profile `package.json`
+- Syntax and top-level structure of profile, home, and bundle `cordis.patch.yml` files, including `!!js` expressions
+- Safe structural checks for `settings.yaml` and `.credentials.yaml`; credential diagnostics never expose secret values
+- Presence of profile dependencies, bundle declarations, patch files, and client bundles
+- Consistency among the profile `package.json`, the `pnpm-lock.yaml` importer, and installed versions
+- Node.js `engines`, Harness peer ranges, and obsolete DSH dependencies for all direct plugins, including bundle-only and server-side plugins
+- Version drift and stale top-level `@deepseek-ai/dsh-*` packages across the active DSH CLI, Harness workspace, and profile
+- The `platform`, `immediately`, `inject`, `external`, and `./client` export contract for `dsh.client`
+- Consistency between literal `require()` calls in client bundles and external or module suppliers
+- References to removed Harness client packages
+- Third-party plugin peer ranges against actual active Harness versions
+- Real resolution precedence where the Harness installation wins over a profile-local bundle with the same name
+- Static composition of bundle, profile, and home patches in official Harness order, including missing targets, invalid group inserts, and name assertions, without loading plugins
+
+## Repair safety
+
+Every executable repair has a stable ID, risk level, description, and exact target:
+
+- File repairs show their paths before confirmation and verify the SHA-256 fingerprint again before writing.
+- Doctor creates a `.dsh-doctor-<timestamp>.bak` backup before replacing a file atomically through a temporary file in the same directory.
+- 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.
+- 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.
+
+The initial release automatically performs only deterministic operations, such as restoring an installed bundle to the manifest list or running an exact profile install or update command. Damaged JSON or YAML, credential values, and plugin removal remain recommendations because Doctor cannot safely guess the intended result.
+
+## Exit codes
+
+- `0`: No blocking errors were found; warnings may still be present
+- `1`: Doctor found a problem that may prevent Harness from starting
+- `2`: Invalid arguments, an operational failure, or a failed repair
+
+## Current limitations
+
+- 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.
+- 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.
+
+## Development
+
+```sh
+npm install
+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.
+
+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

@@ -1,6 +1,8 @@
 # DSH Doctor
 
-DSH Doctor 用来定位 DeepSeek Harness 无法启动、配置损坏和第三方插件不兼容等常见问题。默认运行完全只读；只有显式使用 `--fix`，查看精确的文件或命令计划并确认后，它才会实施可回滚的修复。
+中文 | [English](README.en.md)
+
+DSH Doctor 面向 DSH 与插件使用者，帮助快速找出导致 DSH 启动异常或升级后不可用的插件，集中说明每个插件的问题、影响与处理方式，并检查常见的 profile 配置和版本漂移。诊断默认完全只读；只有显式使用 `--fix`、核对并确认精确的修复计划后才会执行，文件修改会先创建备份。
 
 这是社区维护的第三方工具，不属于 DeepSeek 官方项目。它不会加载或执行待检查插件的代码。
 
@@ -23,6 +25,17 @@ npx @bruc3van/dsh-doctor
 
 Doctor 不要求 `dsh` 必须是全局命令。它会按顺序查找 PATH、当前项目安装、profile 共享安装或 npx 缓存留下的链接、已构建的 Harness 源码工作区。DSH Desktop 内置运行时或其他特殊安装可以通过 `--dsh-command /path/to/dsh`（也接受官方包的 `lib/bin.js`）明确指定。找不到 CLI 时仍会完成只读诊断，但不会提供或执行无法验证的命令型修复。
 
+## 工作方式
+
+一次完整流程分为四步：
+
+1. `dsh-doctor` 只读检查当前 DSH Home、profile、插件和 Harness 版本。
+2. Doctor 按错误、警告和插件兼容状态展示证据与建议。
+3. `dsh-doctor --fix` 先展示精确的文件修改或 DSH 命令计划，并等待用户确认。
+4. 修复完成后自动重新诊断，以最终状态决定退出码。
+
+Doctor 不会加载待检查插件，也不会在普通诊断时修改配置。无法确定正确结果的操作，例如猜测凭据、重写损坏 YAML 或直接移除插件，只会给出建议。
+
 ## 输出语言
 
 文本输出支持中文和英文。默认依次读取：
@@ -40,6 +53,17 @@ DSH_DOCTOR_LANG=zh dsh-doctor
 
 `--json` 始终保留稳定的英文消息与诊断 code，避免语言变化破坏脚本。
 
+## DSH 升级后的插件兼容性
+
+DSH 更新后，Doctor 会把每个 profile 插件归入一个明确状态，并在文本与 JSON 报告中汇总：
+
+- `incompatible`：已经发现会阻断插件加载或 Harness 启动的错误，例如插件未安装，或注入了已删除的 client runtime。
+- `risk`：发现当前版本风险，例如 Harness peer range 不接受新版本、仍依赖已删除的 DSH 包、Node.js 不兼容，或安装版本发生漂移。
+- `unknown`：插件没有通过 `peerDependencies` 声明 Harness 兼容范围；Doctor 无法证明它支持升级后的 DSH，但不会把未知误报成故障。
+- `compatible`：插件声明的兼容范围接受当前 Harness，且没有发现插件相关错误或警告。
+
+兼容性检查覆盖所有 profile 直接插件，不再只检查带 `dsh.client` 的前端插件；纯 bundle 或服务端插件引用旧 Harness API 也会被报告。建议 DSH 升级后先运行一次 `dsh-doctor`，再根据精确的 update 建议决定是否执行 `dsh-doctor --fix`。
+
 ## 常用命令
 
 ```sh
@@ -67,11 +91,15 @@ dsh-doctor --fix --yes --json
 - profile、home 和 bundle 的 `cordis.patch.yml` 语法与顶层结构，包括 `!!js` 表达式
 - `settings.yaml` 和 `.credentials.yaml` 的安全结构检查；凭据诊断不输出秘密值
 - profile 依赖、bundle 声明、patch 文件和 client bundle 是否存在
+- profile `package.json`、`pnpm-lock.yaml` importer 与实际安装版本是否一致
+- 所有直接插件（包括纯 bundle/服务端插件）的 Node.js `engines`、Harness peer range、旧 DSH 依赖与当前运行时是否兼容
+- 当前 DSH CLI、Harness 工作区和 profile 顶层 `@deepseek-ai/dsh-*` 包是否发生版本漂移或残留
 - `dsh.client` 的 `platform`、`immediately`、`inject`、`external` 和 `./client` export contract
 - client bundle 中字面量 `require()` 与 external/module supplier 的一致性
 - 已删除的 Harness client package 引用
 - 第三方插件 peer range 与当前 Harness 实际版本的兼容性
 - Harness installation 优先于 profile 同名 bundle 的真实解析顺序
+- 按 Harness 官方层级顺序静态组合 bundle、profile 和 home patch，检查缺失 target、错误 group insert 与 name assertion；不会加载插件
 
 ## 修复安全边界
 
@@ -80,6 +108,7 @@ dsh-doctor --fix --yes --json
 - 文件修复在确认前展示路径，确认后再次校验 SHA-256 指纹。
 - 写入前创建 `.dsh-doctor-<timestamp>.bak` 备份，再通过同目录临时文件原子替换。
 - 外部命令使用固定 argv 调用，不拼接 shell 命令。
+- `--json --fix --yes` 会捕获子命令输出并放入修复结果，保证 stdout 始终只有一个合法 JSON 文档。
 - 命令修复绑定当前诊断的 `DSH_HOME`，并展示解析出的真实 CLI 路径；不会假定 PATH 中存在 `dsh`。
 - 任一步失败即停止后续修复，并保留已经创建的备份。
 - 完成后重新运行全部诊断，以最终状态决定退出码。
@@ -95,9 +124,10 @@ dsh-doctor --fix --yes --json
 ## 当前限制
 
 - 静态扫描只识别代码中的字面量 `require("package")`；动态依赖需要未来的 bundle 元数据协议。
-- 配置检查覆盖语法和 Doctor 能稳定对齐的结构，但不执行 `!!js`，也不启动第三方插件。
+- 配置检查覆盖语法和 Doctor 能稳定对齐的结构，并按当前 Harness patch 算法做无执行组合检查；不会求值 `!!js`，也不会加载第三方插件。
 - 版本兼容以插件 `peerDependencies` 和当前可解析 Harness package 版本为依据；未声明兼容范围的插件只能做结构检查。
-- 真实启动探针尚未默认启用，因为启动第三方插件可能产生网络、进程或持久化副作用。优先使用只读配置组合检查。
+- lockfile 检查只对 profile 的直接依赖 importer 做确定性交叉验证，不递归扫描整个 npm 依赖树。
+- 真实启动探针尚未启用；即使复制 `DSH_HOME`，第三方插件仍可能访问网络、绝对路径或启动外部进程，不能宣称无副作用。
 
 ## 从源码开发
 
@@ -107,4 +137,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.2",
-  "description": "Diagnostics and confirmed recovery for DeepSeek Harness profiles and third-party plugins",
+  "version": "0.1.4",
+  "description": "Diagnose DSH plugins broken by upgrades, startup blockers, and profile issues with explicit, confirmed repairs",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -18,6 +18,7 @@
   "files": [
     "src",
     "README.md",
+    "README.en.md",
     "LICENSE"
   ],
   "scripts": {

package/src/cli.mjs

@@ -118,7 +118,7 @@ async function main() {
           confirmed = /^(?:y(?:es)?|是|确认)$/i.test(answer.trim())
         }
         if (confirmed) {
-          repairs = applyRepairs(actions)
+          repairs = applyRepairs(actions, { captureOutput: options.json })
           if (repairs.every(item => item.status === 'applied')) report = diagnose(options)
         }
       }

package/src/doctor.mjs

@@ -22,10 +22,11 @@ const BUILTIN_MODULES = new Set(builtinModules.map(name => name.replace(/^node:/
 const SEVERITY_ORDER = { error: 0, warning: 1, info: 2 }
 const JS_EXPRESSION = new yaml.Type('tag:yaml.org,2002:js', {
   kind: 'scalar',
-  resolve: value => typeof value === 'string' && value.trim().length > 0,
-  construct: value => value,
+  resolve: value => typeof value === 'string',
+  construct: value => ({ __jsExpr: value }),
 })
-const PATCH_SCHEMA = yaml.DEFAULT_SCHEMA.extend([JS_EXPRESSION])
+// Keep this dialect aligned with Harness entryListSchema: JSON values plus !!js.
+const PATCH_SCHEMA = yaml.JSON_SCHEMA.extend([JS_EXPRESSION])
 
 function objectRecord(value) {
   return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined
@@ -38,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 },
   }
@@ -292,7 +294,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.',
   }))
@@ -351,11 +353,12 @@ function clientExport(manifest) {
   return undefined
 }
 
-function dependencyEntries(value, field, file, findings) {
+function dependencyEntries(value, field, file, findings, packageName) {
   if (value === undefined) return []
   const record = objectRecord(value)
   if (record === undefined || Object.values(record).some(item => typeof item !== 'string')) {
     findings.push(finding('error', 'INVALID_DEPENDENCY_MAP', `${field} must be an object of package names to string ranges.`, {
+      package: packageName,
       evidence: file,
       suggestion: `Repair ${field} before managing or starting this profile.`,
     }))
@@ -554,7 +557,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,
@@ -567,7 +570,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,
@@ -576,16 +579,6 @@ function inspectClientPackage(record, context) {
       }
     }
 
-    const legacyPeers = Object.keys(record.manifest.peerDependencies ?? {})
-      .filter(peer => peer.startsWith('@deepseek-ai/dsh-') && !harnessPackages.has(peer))
-      .sort()
-    if (legacyPeers.length > 0) {
-      findings.push(finding('warning', 'LEGACY_HARNESS_PEERS', `${name} still declares Harness packages that no longer exist in the active source tree.`, {
-        package: name,
-        evidence: legacyPeers.join(', '),
-        suggestion: 'Treat this plugin as compatibility-risky and update it before the next Harness upgrade.',
-      }))
-    }
   }
 }
 
@@ -595,7 +588,7 @@ function inspectBundle(name, record, findings) {
       package: name,
       suggestion: 'Install the profile dependencies with the active DSH installation, upgrade the bundle, or remove it from the profile.',
     }))
-    return
+    return undefined
   }
   const patch = record.manifest?.dsh?.bundle?.patch
   if (typeof patch !== 'string' || patch.length === 0) {
@@ -604,7 +597,7 @@ function inspectBundle(name, record, findings) {
       evidence: record.file,
       suggestion: 'Upgrade or remove this bundle from dsh.profile.bundles.',
     }))
-    return
+    return undefined
   }
   const file = safePackageFile(record.directory, patch)
   if (file === undefined || !regularFile(file)) {
@@ -613,25 +606,135 @@ function inspectBundle(name, record, findings) {
       evidence: file ?? `${record.file}: dsh.bundle.patch = ${JSON.stringify(patch)}`,
       suggestion: 'Reinstall or upgrade this bundle, or remove it from the profile.',
     }))
-  } else inspectPatchFile(file, `${name} bundle patch`, findings)
+    return undefined
+  }
+  const patches = inspectPatchFile(file, `${name} bundle patch`, findings, name)
+  return patches === undefined ? undefined : { label: name, file, patches, package: name }
 }
 
-function inspectPatchFile(file, subject, findings) {
+function inspectPatchFile(file, subject, findings, packageName) {
   let parsed
   try {
     parsed = yaml.load(readFileSync(file, 'utf8'), { schema: PATCH_SCHEMA })
   } catch (error) {
     findings.push(finding('error', 'INVALID_PATCH_YAML', `${subject} cannot be parsed.`, {
+      package: packageName,
       evidence: `${file}: ${error instanceof Error ? error.message : String(error)}`,
       suggestion: 'Repair the YAML syntax before starting this profile.',
     }))
-    return
+    return undefined
   }
   if (!Array.isArray(parsed) || parsed.some(item => objectRecord(item) === undefined)) {
     findings.push(finding('error', 'INVALID_PATCH_LIST', `${subject} must be a top-level YAML array of mappings.`, {
+      package: packageName,
       evidence: file,
       suggestion: 'Repair the patch structure before starting this profile.',
     }))
+    return undefined
+  }
+  let valid = true
+  parsed.forEach((patch, index) => {
+    if (patch.id !== undefined && typeof patch.id !== 'string') {
+      valid = false
+      findings.push(finding('error', 'INVALID_PATCH_ID', `${subject} entry ${String(index + 1)} has a non-string id.`, {
+        package: packageName,
+        evidence: file,
+        suggestion: 'Use a string row id or omit id for a root insert patch.',
+      }))
+    }
+    if (patch.name !== undefined && typeof patch.name !== 'string') {
+      valid = false
+      findings.push(finding('error', 'INVALID_PATCH_NAME', `${subject} entry ${String(index + 1)} has a non-string name assertion.`, {
+        package: packageName,
+        evidence: file,
+        suggestion: 'Use a string plugin name assertion or omit the name field.',
+      }))
+    }
+    if (patch.insert !== undefined
+      && (!Array.isArray(patch.insert) || patch.insert.some(item => objectRecord(item) === undefined))) {
+      valid = false
+      findings.push(finding('error', 'INVALID_PATCH_INSERT', `${subject} entry ${String(index + 1)} insert must be an array of mappings.`, {
+        package: packageName,
+        evidence: file,
+        suggestion: 'Repair the insert list before starting this profile.',
+      }))
+    }
+  })
+  return valid ? parsed : undefined
+}
+
+// Mirrors the current Harness applyEntryPatches control flow without importing
+// code from (or executing code inside) the installation being diagnosed.
+function inspectPatchComposition(layers, findings) {
+  const entryMap = new Map()
+  const indexEntries = (values) => {
+    for (const entry of values) {
+      if (typeof entry.id === 'string' && entry.id.length > 0) entryMap.set(entry.id, entry)
+      if (entry.group && Array.isArray(entry.config)) indexEntries(entry.config)
+    }
+  }
+  for (const layer of layers) {
+    layer.patches.forEach((patch, index) => {
+      const evidence = `${layer.file}: entry ${String(index + 1)}`
+      const hasInsert = patch.insert !== undefined
+      if (hasInsert) {
+        if (!Array.isArray(patch.insert)) return
+        if (patch.id !== undefined) {
+          const target = entryMap.get(patch.id)
+          if (target === undefined) {
+            findings.push(finding('warning', 'PATCH_TARGET_NOT_FOUND', `${layer.label} insert targets missing row ${patch.id}.`, {
+              package: layer.package,
+              evidence,
+              suggestion: 'Check whether this overlay is intended for the selected profile and bundle order.',
+            }))
+            return
+          }
+          if (!target.group) {
+            findings.push(finding('warning', 'PATCH_TARGET_NOT_GROUP', `${layer.label} inserts into row ${patch.id}, which is not a group.`, {
+              package: layer.package,
+              evidence,
+              suggestion: 'Target a group row or use a root insert.',
+            }))
+            return
+          }
+          if (!Array.isArray(target.config)) target.config = []
+          target.config.push(...structuredClone(patch.insert))
+          indexEntries(target.config.slice(-patch.insert.length))
+        } else {
+          const inserted = structuredClone(patch.insert)
+          indexEntries(inserted)
+        }
+        return
+      }
+      if (patch.id === undefined) {
+        findings.push(finding('warning', 'PATCH_ID_REQUIRED', `${layer.label} has a non-insert patch without an id.`, {
+          package: layer.package,
+          evidence,
+          suggestion: 'Add the target row id or turn the entry into an insert patch.',
+        }))
+        return
+      }
+      const target = entryMap.get(patch.id)
+      if (target === undefined) {
+        findings.push(finding('warning', 'PATCH_TARGET_NOT_FOUND', `${layer.label} targets missing row ${patch.id}.`, {
+          package: layer.package,
+          evidence,
+          suggestion: 'Check whether this overlay is intended for the selected profile and bundle order.',
+        }))
+        return
+      }
+      if (patch.name !== undefined && patch.name !== target.name) {
+        findings.push(finding('warning', 'PATCH_NAME_MISMATCH', `${layer.label} name assertion does not match row ${patch.id}.`, {
+          package: layer.package,
+          evidence: `${evidence}: expected ${JSON.stringify(target.name)}, got ${JSON.stringify(patch.name)}`,
+          suggestion: 'Update the assertion or target the intended row.',
+        }))
+        return
+      }
+      for (const [key, value] of Object.entries(patch)) {
+        if (key !== 'id' && key !== 'insert' && key !== 'name') target[key] = structuredClone(value)
+      }
+    })
   }
 }
 
@@ -702,33 +805,288 @@ function inspectCredentials(file, findings) {
 }
 
 function inspectPatchFileIfPresent(file, subject, findings) {
-  if (existsSync(file)) inspectPatchFile(file, subject, findings)
+  return existsSync(file) ? inspectPatchFile(file, subject, findings) : undefined
+}
+
+function looksLikeSemverRange(value) {
+  return /^(?:\s*[v=~^<>*]|\s*\d)/.test(value)
+}
+
+function inspectPluginNodeEngine(record, nodeVersion, findings) {
+  const range = record.manifest?.engines?.node
+  if (range === undefined) return
+  const name = record.requestedName ?? record.manifest.name
+  if (typeof range !== 'string' || semver.validRange(range) === null) {
+    findings.push(finding('warning', 'INVALID_NODE_ENGINE_RANGE', `${name} declares an invalid Node.js engine range.`, {
+      package: name,
+      evidence: `${record.file}: engines.node = ${JSON.stringify(range)}`,
+      suggestion: 'The plugin author should publish a valid engines.node range.',
+    }))
+    return
+  }
+  if (nodeVersion === undefined) return
+  if (!semver.satisfies(nodeVersion, range, { includePrerelease: true })) {
+    findings.push(finding('warning', 'PLUGIN_NODE_VERSION_MISMATCH', `${name} does not support the Node.js version used by the active DSH CLI.`, {
+      package: name,
+      evidence: `engines.node ${range} (active ${nodeVersion})`,
+      suggestion: `Update ${name} or run DSH with a supported Node.js version.`,
+    }))
+  }
+}
+
+function lockedRegistryVersion(value) {
+  if (typeof value !== 'string') return undefined
+  const matched = value.match(/^(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)(?:\(|$)/)?.[1]
+  return matched !== undefined && semver.valid(matched) !== null ? matched : undefined
+}
+
+function inspectPnpmLock(profileDir, dependencyEntriesList, records, findings, commandRepair, profile) {
+  const file = join(profileDir, 'pnpm-lock.yaml')
+  const installRepair = () => commandRepair(
+    `install-profile:${profile}`,
+    `Install the declared dependencies for profile ${profile}.`,
+    ['plugin', '--profile', profile, 'install'],
+    { profile },
+  )
+  if (!existsSync(file)) return { file, present: false }
+  let root
+  try {
+    const document = parseDocument(readFileSync(file, 'utf8'), { prettyErrors: true, uniqueKeys: true })
+    if (document.errors.length > 0) throw new Error(document.errors.map(error => error.message).join('; '))
+    root = document.toJS()
+  } catch (error) {
+    findings.push(finding('error', 'INVALID_PNPM_LOCKFILE', 'The profile pnpm lockfile cannot be parsed.', {
+      evidence: `${file}: ${error instanceof Error ? error.message : String(error)}`,
+      suggestion: 'Run the exact profile install command after repairing or regenerating the lockfile.',
+      repair: commandRepair(
+        `install-profile:${profile}`,
+        `Install the declared dependencies for profile ${profile}.`,
+        ['plugin', '--profile', profile, 'install'],
+        { profile },
+      ),
+    }))
+    return { file, present: true, valid: false }
+  }
+  const importer = objectRecord(objectRecord(objectRecord(root)?.importers)?.['.'])
+  const locked = importer?.dependencies
+  const lockedDependencies = objectRecord(locked)
+  if (lockedDependencies === undefined) {
+    if (dependencyEntriesList.length === 0 && locked === undefined) {
+      return { file, present: true, valid: true }
+    }
+    findings.push(finding('warning', 'PNPM_LOCKFILE_IMPORTER_MISSING', 'The profile pnpm lockfile has no usable root dependencies map.', {
+      evidence: file,
+      suggestion: 'Use the exact profile install command to reconcile the lockfile.',
+      repair: installRepair(),
+    }))
+    return { file, present: true, valid: false }
+  }
+  const declaredNames = new Set(dependencyEntriesList.map(([name]) => name))
+  for (const [name, declared] of dependencyEntriesList) {
+    const entry = lockedDependencies[name]
+    if (entry === undefined) {
+      findings.push(finding('warning', 'LOCKFILE_DEPENDENCY_MISSING', `Profile dependency ${name} is absent from the pnpm lockfile importer.`, {
+        package: name,
+        evidence: file,
+        suggestion: 'Use the exact profile install command to reconcile the manifest and lockfile.',
+        repair: installRepair(),
+      }))
+      continue
+    }
+    const lockedEntry = typeof entry === 'string' ? { version: entry } : objectRecord(entry)
+    const specifier = lockedEntry?.specifier
+    if (typeof specifier === 'string' && specifier !== declared) {
+      findings.push(finding('warning', 'LOCKFILE_SPECIFIER_MISMATCH', `Profile dependency ${name} has a different specifier in pnpm-lock.yaml.`, {
+        package: name,
+        evidence: `package.json ${declared} (lockfile ${specifier})`,
+        suggestion: 'Use the exact profile install command to reconcile the manifest and lockfile.',
+        repair: installRepair(),
+      }))
+    }
+    const lockedVersion = lockedRegistryVersion(lockedEntry?.version)
+    const installedVersion = records.get(name)?.manifest?.version
+    if (lockedVersion !== undefined && typeof installedVersion === 'string'
+      && semver.valid(installedVersion) !== null && installedVersion !== lockedVersion) {
+      findings.push(finding('warning', 'LOCKFILE_INSTALLED_VERSION_MISMATCH', `Profile dependency ${name} does not match its locked version.`, {
+        package: name,
+        evidence: `locked ${lockedVersion} (installed ${installedVersion})`,
+        suggestion: 'Use the exact profile install command to restore the locked installation.',
+        repair: installRepair(),
+      }))
+    }
+  }
+  for (const name of Object.keys(lockedDependencies)) {
+    if (declaredNames.has(name)) continue
+    findings.push(finding('warning', 'LOCKFILE_DEPENDENCY_STALE', `pnpm-lock.yaml still lists undeclared profile dependency ${name}.`, {
+      package: name,
+      evidence: file,
+      suggestion: 'Use the exact profile install command to remove stale lockfile importer entries.',
+      repair: installRepair(),
+    }))
+  }
+  return { file, present: true, valid: true }
+}
+
+function inspectRuntimeAlignment(harness, dshCli, findings) {
+  // Harness release tooling uses the root manifest as the DSH release-family
+  // baseline and bumps apps/cli plus the published members to the same version.
+  if (typeof harness.version !== 'string' || typeof dshCli?.version !== 'string') return
+  if (semver.valid(harness.version) === null || semver.valid(dshCli.version) === null) return
+  if (harness.version === dshCli.version) return
+  findings.push(finding('warning', 'DSH_CLI_HARNESS_VERSION_MISMATCH', 'The active DSH CLI and diagnosed Harness installation have different versions.', {
+    evidence: `DSH CLI ${dshCli.version} (Harness ${harness.version})`,
+    suggestion: 'Diagnose with the DSH CLI and Harness checkout used by the same installation.',
+  }))
+}
+
+function inspectProfileHarnessPackages(profileDir, home, harness, findings) {
+  const profileScope = join(profileDir, 'node_modules', '@deepseek-ai')
+  if (!existsSync(profileScope)) return
+  let entries
+  try {
+    entries = readdirSync(profileScope, { withFileTypes: true })
+  } catch (error) {
+    findings.push(finding('warning', 'PROFILE_HARNESS_SCOPE_UNREADABLE', 'The profile-local @deepseek-ai package scope cannot be read as a directory.', {
+      evidence: `${profileScope}: ${error instanceof Error ? error.message : String(error)}`,
+      suggestion: 'Reinstall the profile with the active DSH CLI to repair its node_modules layout.',
+    }))
+    return
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
+    const name = `@deepseek-ai/${entry.name}`
+    if (!name.startsWith('@deepseek-ai/dsh-') && name !== '@deepseek-ai/dsh') continue
+    const profilePackage = join(profileScope, entry.name)
+    const profileManifestFile = join(profilePackage, 'package.json')
+    if (!existsSync(profileManifestFile)) continue
+    let profileManifest
+    try {
+      profileManifest = JSON.parse(readFileSync(profileManifestFile, 'utf8'))
+    } catch {
+      continue
+    }
+    const sharedPackage = join(home, 'profiles', 'node_modules', '@deepseek-ai', entry.name)
+    if (existsSync(join(sharedPackage, 'package.json'))) {
+      try {
+        if (realpathSync(profilePackage) !== realpathSync(sharedPackage)) {
+          const sharedManifest = JSON.parse(readFileSync(join(sharedPackage, 'package.json'), 'utf8'))
+          if (typeof profileManifest.version === 'string' && typeof sharedManifest.version === 'string'
+            && profileManifest.version !== sharedManifest.version) {
+            findings.push(finding('warning', 'DUPLICATE_HARNESS_PACKAGE_VERSION', `${name} exists in the profile and shared DSH installation at different versions.`, {
+              package: name,
+              evidence: `profile ${profileManifest.version} (${profilePackage}), shared ${sharedManifest.version} (${sharedPackage})`,
+              suggestion: 'Reinstall the profile with the active DSH CLI so its module resolution uses one compatible version.',
+            }))
+          }
+        }
+      } catch {
+        // Other manifest and filesystem checks report unreadable package state.
+      }
+    }
+    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 DSH.`, {
+        package: name,
+        evidence: profileManifestFile,
+        suggestion: 'Reinstall the profile with the active DSH CLI and review plugins that still require this package.',
+      }))
+    }
+  }
 }
 
 function inspectCompatibility(record, context) {
-  const { commandRepair, findings, harnessPackages, profile, resolvePackage } = context
-  const peers = dependencyEntries(record.manifest.peerDependencies, 'peerDependencies', record.file, findings)
+  const {
+    commandRepair, findings, harnessPackages, harnessPackagesAuthoritative, profile, resolvePackage,
+  } = context
+  const packageName = record.requestedName ?? record.manifest.name
+  const peers = dependencyEntries(record.manifest.peerDependencies, 'peerDependencies', record.file, findings, packageName)
+  const dependencies = dependencyEntries(record.manifest.dependencies, 'dependencies', record.file, findings, packageName)
+  if (harnessPackagesAuthoritative) {
+    const removedPeers = peers
+      .map(([name]) => name)
+      .filter(name => name.startsWith('@deepseek-ai/dsh-') && !harnessPackages.has(name))
+      .sort()
+    if (removedPeers.length > 0) {
+      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.',
+        repair: updateRepair(profile, packageName, commandRepair),
+      }))
+    }
+    const removedDependencies = dependencies
+      .map(([name]) => name)
+      .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 DSH.`, {
+        package: packageName,
+        evidence: removedDependencies.join(', '),
+        suggestion: 'Update this plugin; its bundled DSH APIs may be incompatible with the current release.',
+        repair: updateRepair(profile, packageName, commandRepair),
+      }))
+    }
+  }
   const mismatches = []
   for (const [name, range] of peers) {
     if (!name.startsWith('@deepseek-ai/') && name !== 'cordis') continue
+    if (semver.validRange(range) === null) {
+      findings.push(finding('warning', 'INVALID_HARNESS_PEER_RANGE', `${packageName} declares an invalid Harness peer range for ${name}.`, {
+        package: packageName,
+        evidence: `${name}: ${range}`,
+        suggestion: 'The plugin author should publish a valid peer dependency range.',
+      }))
+      continue
+    }
     const supplier = harnessPackages.get(name) ?? resolvePackage(name)
     if (supplier === undefined) continue
     const version = supplier.manifest?.version
-    if (typeof version !== 'string' || semver.valid(version) === null || semver.validRange(range) === null) continue
+    if (typeof version !== 'string' || semver.valid(version) === null) continue
     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) {
-    const name = record.requestedName ?? record.manifest.name
-    findings.push(finding('warning', 'HARNESS_PEER_VERSION_MISMATCH', `${name} has Harness peer ranges that do not accept the active versions.`, {
-      package: name,
-      evidence: mismatches.join(', '),
-      suggestion: `Update ${name} to a release compatible with the active Harness.`,
-      repair: updateRepair(profile, name, commandRepair),
+    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,
+      details: { peerVersionGroups: groups },
+      suggestion: `Update ${packageName} to a release compatible with the active DSH.`,
+      repair: updateRepair(profile, packageName, commandRepair),
     }))
   }
 }
 
+function hasHarnessCompatibilityDeclaration(record) {
+  const peers = objectRecord(record.manifest.peerDependencies)
+  return peers !== undefined && Object.keys(peers)
+    .some(name => name.startsWith('@deepseek-ai/') || name === 'cordis')
+}
+
+function pluginCompatibility(record, findings) {
+  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'
+  return 'compatible'
+}
+
 export function defaultDshHome(env = process.env) {
   const configured = env.DSH_HOME?.trim()
   if (configured !== undefined && configured.length > 0) {
@@ -779,6 +1137,15 @@ export function diagnose(options = {}) {
   const resolvePackage = packageResolver(profileDir, home, harness.packages, findings)
   const resolveBundle = bundleResolver(profileDir, home, harness.packages, findings)
   const dependencyEntriesList = dependencyEntries(profileManifest.dependencies, 'dependencies', profileManifestFile, findings)
+  for (const [name, range] of dependencyEntriesList) {
+    if (looksLikeSemverRange(range) && semver.validRange(range) === null) {
+      findings.push(finding('error', 'INVALID_PROFILE_DEPENDENCY_RANGE', `Profile dependency ${name} has an invalid semantic version range.`, {
+        package: name,
+        evidence: `${profileManifestFile}: ${range}`,
+        suggestion: 'Repair the dependency range before installing or starting this profile.',
+      }))
+    }
+  }
   const dependencyNames = dependencyEntriesList.map(([name]) => name)
   const dshConfig = profileManifest.dsh
   const dshConfigValid = dshConfig === undefined || objectRecord(dshConfig) !== undefined
@@ -818,6 +1185,11 @@ export function diagnose(options = {}) {
     const record = resolvePackage(name)
     if (record !== undefined) records.set(name, record)
   }
+  const lockfile = inspectPnpmLock(
+    profileDir, dependencyEntriesList, records, findings, commandRepair, profile,
+  )
+  inspectRuntimeAlignment(harness, dshCli, findings)
+  inspectProfileHarnessPackages(profileDir, home, harness, findings)
   const bundleRecords = new Map()
   for (const name of bundleNames) {
     const record = resolveBundle(name)
@@ -873,10 +1245,23 @@ export function diagnose(options = {}) {
       }))
     }
   }
-  for (const name of bundleNames) inspectBundle(name, bundleRecords.get(name), findings)
+  const patchLayers = []
+  let patchCompositionValid = true
+  for (const name of bundleNames) {
+    const layer = inspectBundle(name, bundleRecords.get(name), findings)
+    if (layer === undefined) patchCompositionValid = false
+    else patchLayers.push(layer)
+  }
 
-  inspectPatchFileIfPresent(join(profileDir, 'cordis.patch.yml'), 'profile patch', findings)
-  inspectPatchFileIfPresent(join(home, 'cordis.patch.yml'), 'home patch', findings)
+  for (const [file, subject, label] of [
+    [join(profileDir, 'cordis.patch.yml'), 'profile patch', 'profile patch'],
+    [join(home, 'cordis.patch.yml'), 'home patch', 'home patch'],
+  ]) {
+    const patches = inspectPatchFileIfPresent(file, subject, findings)
+    if (patches !== undefined) patchLayers.push({ file, label, patches })
+    else if (existsSync(file)) patchCompositionValid = false
+  }
+  if (patchCompositionValid) inspectPatchComposition(patchLayers, findings)
   inspectSettings(join(home, 'settings.yaml'), findings)
   inspectCredentials(join(home, '.credentials.yaml'), findings)
 
@@ -898,7 +1283,13 @@ export function diagnose(options = {}) {
       profile,
       resolvePackage,
       harnessPackages: harness.packages,
+      harnessPackagesAuthoritative: harness.authoritative,
     })
+    inspectPluginNodeEngine(
+      record,
+      dshCli?.command?.[0] === process.execPath ? process.version : undefined,
+      findings,
+    )
   }
 
   return finish({
@@ -906,16 +1297,23 @@ export function diagnose(options = {}) {
     profile,
     profileDir,
     harness: { root: harness.root, version: harness.version },
+    lockfile,
     dshCli: dshCli === undefined
       ? { available: false, commandRepairNeeded }
       : { available: true, commandRepairNeeded, ...dshCli },
-    packages: thirdPartyRecords.map(record => ({
-      name: record.requestedName ?? record.manifest.name,
-      version: record.manifest.version,
-      directory: record.directory,
-      client: record.manifest?.dsh?.client !== undefined,
-      bundle: record.manifest?.dsh?.bundle !== undefined,
-    })),
+    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),
+      }
+    }),
   }, findings)
 }
 
@@ -929,9 +1327,30 @@ function finish(context, findings) {
     warnings: findings.filter(item => item.severity === 'warning').length,
     info: findings.filter(item => item.severity === 'info').length,
   }
+  const compatibility = {
+    incompatible: context.packages.filter(item => item.compatibility === 'incompatible').length,
+    risk: context.packages.filter(item => item.compatibility === 'risk').length,
+    unknown: context.packages.filter(item => item.compatibility === 'unknown').length,
+    compatible: context.packages.filter(item => item.compatibility === 'compatible').length,
+  }
+  context = { ...context, compatibility }
   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'
@@ -950,25 +1369,139 @@ 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 ? '已检查第三方包' : 'Checked third-party packages'}: ${String(report.context.packages.length)}`,
+    `${zh ? 'Profile 插件' : 'Profile plugins'}: ${String(report.context.packages.length)}`,
+    zh
+      ? `插件兼容性: ${String(report.context.compatibility.incompatible)} 个不兼容，${String(report.context.compatibility.risk)} 个风险，${String(report.context.compatibility.unknown)} 个未知，${String(report.context.compatibility.compatible)} 个兼容`
+      : `Plugin compatibility: ${String(report.context.compatibility.incompatible)} incompatible, ${String(report.context.compatibility.risk)} risk, ${String(report.context.compatibility.unknown)} unknown, ${String(report.context.compatibility.compatible)} compatible`,
     `${zh ? '输出语言' : 'Output language'}: ${languageName(language)}`,
     '',
   ]
-  if (report.findings.length === 0) {
+  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 MVP 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 的兼容范围。'
+          : 'The plugin does not declare a compatibility range for the active DSH.')
+        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('')
     }
   }
@@ -976,7 +1509,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,20 +71,28 @@ 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 源码中已不存在的旧包。`,
+  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 文件缺失。`,
   INVALID_PATCH_YAML: item => `${captured(item.message, /^(.+) cannot be parsed\.$/) ?? 'Patch 文件'}无法解析。`,
   INVALID_PATCH_LIST: item => `${captured(item.message, /^(.+) must be/) ?? 'Patch 文件'}的顶层必须是由映射组成的 YAML 数组。`,
+  INVALID_PATCH_ID: () => 'Patch 条目的 id 必须是字符串。',
+  INVALID_PATCH_NAME: () => 'Patch 条目的 name 断言必须是字符串。',
+  INVALID_PATCH_INSERT: () => 'Patch 条目的 insert 必须是由映射组成的数组。',
+  PATCH_ID_REQUIRED: () => '非 insert patch 缺少目标 id。',
+  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 断言与目标配置行不一致。',
   INVALID_SETTINGS_DOCUMENT: () => 'Harness 设置文件无法解析。',
   INVALID_SETTINGS_ROOT: () => 'Harness 设置文件顶层必须是命名空间映射。',
   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 字段存在时必须是对象。',
@@ -94,6 +102,20 @@ const ZH_MESSAGES = {
   DEPENDENCY_NOT_INSTALLED: item => `Profile 依赖 ${item.package} 尚未安装。`,
   PROFILE_DEPENDENCY_VERSION_MISMATCH: item => `${item.package} 的声明版本范围与当前安装版本不兼容。`,
   INSTALLED_BUNDLE_INACTIVE: item => `${item.package} 已作为 bundle 安装，但不在 dsh.profile.bundles 中。`,
+  INVALID_PROFILE_DEPENDENCY_RANGE: item => `Profile 依赖 ${item.package} 的语义版本范围无效。`,
+  INVALID_HARNESS_PEER_RANGE: item => `${item.package} 声明了无效的 Harness peer 版本范围。`,
+  INVALID_NODE_ENGINE_RANGE: item => `${item.package} 声明了无效的 Node.js engines 范围。`,
+  PLUGIN_NODE_VERSION_MISMATCH: item => `${item.package} 不支持当前 DSH CLI 使用的 Node.js 版本。`,
+  INVALID_PNPM_LOCKFILE: () => 'Profile 的 pnpm lockfile 无法解析。',
+  PNPM_LOCKFILE_IMPORTER_MISSING: () => 'Profile 的 pnpm lockfile 缺少可用的根 dependencies 映射。',
+  LOCKFILE_DEPENDENCY_MISSING: item => `Profile 依赖 ${item.package} 未出现在 pnpm lockfile importer 中。`,
+  LOCKFILE_SPECIFIER_MISMATCH: item => `${item.package} 在 package.json 与 pnpm lockfile 中的声明不一致。`,
+  LOCKFILE_INSTALLED_VERSION_MISMATCH: item => `${item.package} 的实际安装版本与 lockfile 不一致。`,
+  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 中，但当前使用的 DSH 已不再包含它。`,
+  PROFILE_HARNESS_SCOPE_UNREADABLE: () => 'Profile 内的 @deepseek-ai 包作用域无法作为目录读取。',
 }
 
 const ZH_SUGGESTIONS = {
@@ -115,17 +137,25 @@ const ZH_SUGGESTIONS = {
   CLIENT_EXTERNAL_WITHOUT_SUPPLIER: update,
   REMOVED_CLIENT_INJECT: update,
   REDUNDANT_CLIENT_EXTERNAL: () => '插件作者应删除重复的 dsh.client.external 条目。',
-  LEGACY_HARNESS_PEERS: () => '该插件存在兼容风险，请在下次升级 Harness 前更新。',
+  LEGACY_HARNESS_PEERS: () => '该插件存在兼容风险，请更新到支持当前 DSH 的版本。',
+  LEGACY_HARNESS_DEPENDENCIES: () => '请更新该插件；它依赖的 DSH API 可能与当前版本不兼容。',
   BUNDLE_NOT_INSTALLED: () => '使用当前 DSH 安装补齐 profile 依赖、升级 bundle，或从 profile 中移除它。',
   BUNDLE_DECLARATION_MISSING: () => '升级该 bundle，或把它从 dsh.profile.bundles 中移除。',
   BUNDLE_PATCH_MISSING: () => '重新安装或升级该 bundle，或者从 profile 中移除它。',
   INVALID_PATCH_YAML: () => '启动该 profile 前，请修复 YAML 语法。',
   INVALID_PATCH_LIST: () => '启动该 profile 前，请修复 patch 顶层结构。',
+  INVALID_PATCH_ID: () => '请使用字符串行 id；根级 insert 可以省略 id。',
+  INVALID_PATCH_NAME: () => '请使用字符串插件名称断言，或删除 name 字段。',
+  INVALID_PATCH_INSERT: () => '启动该 profile 前，请修复 insert 列表。',
+  PATCH_ID_REQUIRED: () => '请补充目标行 id，或把该条目改为 insert patch。',
+  PATCH_TARGET_NOT_FOUND: () => '确认该 overlay 是否适用于当前 profile，并检查 bundle 顺序。',
+  PATCH_TARGET_NOT_GROUP: () => '请选择 group 行，或使用根级 insert。',
+  PATCH_NAME_MISMATCH: () => '请更新 name 断言，或改为指向正确的配置行。',
   INVALID_SETTINGS_DOCUMENT: () => '修复设置文件语法；Doctor 不会猜测凭据或模型配置值。',
   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 配置对象。',
@@ -134,6 +164,20 @@ const ZH_SUGGESTIONS = {
   DEPENDENCY_NOT_INSTALLED: () => '使用下方精确命令安装该 profile 声明的依赖。',
   PROFILE_DEPENDENCY_VERSION_MISMATCH: () => '使用下方精确命令重新同步该 profile 的安装。',
   INSTALLED_BUNDLE_INACTIVE: () => '重新执行匹配的插件添加或更新操作，或者移除未使用的依赖。',
+  INVALID_PROFILE_DEPENDENCY_RANGE: () => '安装或启动 profile 前，请修复依赖版本范围。',
+  INVALID_HARNESS_PEER_RANGE: () => '插件作者应发布有效的 peer dependency 版本范围。',
+  INVALID_NODE_ENGINE_RANGE: () => '插件作者应发布有效的 engines.node 版本范围。',
+  PLUGIN_NODE_VERSION_MISMATCH: item => `更新 ${item.package}，或使用该插件支持的 Node.js 版本运行 DSH。`,
+  INVALID_PNPM_LOCKFILE: () => '修复或重新生成 lockfile 后，再执行精确的 profile 安装命令。',
+  PNPM_LOCKFILE_IMPORTER_MISSING: () => '使用精确的 profile 安装命令重新同步 lockfile。',
+  LOCKFILE_DEPENDENCY_MISSING: () => '使用下方精确命令重新同步 manifest 与 lockfile。',
+  LOCKFILE_SPECIFIER_MISMATCH: () => '使用下方精确命令重新同步 manifest 与 lockfile。',
+  LOCKFILE_INSTALLED_VERSION_MISMATCH: () => '使用下方精确命令恢复 lockfile 锁定的安装。',
+  LOCKFILE_DEPENDENCY_STALE: () => '使用下方精确命令移除 lockfile importer 中的残留条目。',
+  DSH_CLI_HARNESS_VERSION_MISMATCH: () => '请使用属于同一安装的 DSH CLI 与 Harness 工作区进行诊断。',
+  DUPLICATE_HARNESS_PACKAGE_VERSION: () => '使用当前 DSH CLI 重新安装 profile，确保模块解析只使用一个兼容版本。',
+  STALE_PROFILE_HARNESS_PACKAGE: () => '使用当前 DSH CLI 重新安装 profile，并检查仍依赖该旧包的插件。',
+  PROFILE_HARNESS_SCOPE_UNREADABLE: () => '请使用当前 DSH CLI 重新安装 profile，以修复 node_modules 布局。',
 }
 
 function update(item) {
@@ -144,9 +188,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

@@ -82,26 +82,42 @@ function applyJsonEdit(action) {
   return { id: action.id, status: 'applied', backup }
 }
 
-function applyCommand(action) {
+function limitedOutput(value, limit = 8192) {
+  if (typeof value !== 'string' || value.length === 0) return undefined
+  return value.length <= limit ? value : `${value.slice(0, limit)}\n... output truncated by DSH Doctor ...`
+}
+
+function applyCommand(action, options) {
   const [command, ...args] = action.command
+  const captureOutput = options.captureOutput === true
   const result = crossSpawn.sync(command, args, {
-    stdio: 'inherit',
+    stdio: captureOutput ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+    ...captureOutput ? { encoding: 'utf8' } : {},
     env: action.env === undefined ? process.env : { ...process.env, ...action.env },
   })
   if (result.error != null) throw result.error
   if (result.status !== 0) {
-    throw new Error(result.signal === null
+    const reason = result.signal === null
       ? `${command} exited with status ${String(result.status)}`
-      : `${command} was terminated by signal ${result.signal}`)
+      : `${command} was terminated by signal ${result.signal}`
+    const details = captureOutput ? limitedOutput(result.stderr) ?? limitedOutput(result.stdout) : undefined
+    throw new Error(details === undefined ? reason : `${reason}: ${details.trimEnd()}`)
+  }
+  const stdout = captureOutput ? limitedOutput(result.stdout) : undefined
+  const stderr = captureOutput ? limitedOutput(result.stderr) : undefined
+  return {
+    id: action.id,
+    status: 'applied',
+    ...(stdout === undefined ? {} : { stdout }),
+    ...(stderr === undefined ? {} : { stderr }),
   }
-  return { id: action.id, status: 'applied' }
 }
 
-export function applyRepairs(actions) {
+export function applyRepairs(actions, options = {}) {
   const results = []
   for (const action of actions) {
     try {
-      results.push(action.kind === 'json-edit' ? applyJsonEdit(action) : applyCommand(action))
+      results.push(action.kind === 'json-edit' ? applyJsonEdit(action) : applyCommand(action, options))
     } catch (error) {
       results.push({
         id: action.id,