@bruc3van/dsh-doctor 0.1.2 → 0.1.3

package/README.en.md

@@ -0,0 +1,140 @@
+# DSH Doctor
+
+[中文](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.
+
+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. 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.

package/README.md

@@ -1,5 +1,7 @@
 # DSH Doctor
 
+中文 | [English](README.en.md)
+
 DSH Doctor 用来定位 DeepSeek Harness 无法启动、配置损坏和第三方插件不兼容等常见问题。默认运行完全只读；只有显式使用 `--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`，第三方插件仍可能访问网络、绝对路径或启动外部进程，不能宣称无副作用。
 
 ## 从源码开发
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bruc3van/dsh-doctor",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Diagnostics and confirmed recovery for DeepSeek Harness profiles and third-party plugins",
   "license": "MIT",
   "type": "module",
@@ -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
@@ -351,11 +352,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.`,
     }))
@@ -576,16 +578,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 +587,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 +596,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 +605,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 +804,270 @@ 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 Harness source tree.`, {
+        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} still declares Harness packages that no longer exist in the active source tree.`, {
+        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 source tree.`, {
+        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})`)
   }
   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,
+    findings.push(finding('warning', 'HARNESS_PEER_VERSION_MISMATCH', `${packageName} has Harness peer ranges that do not accept the active versions.`, {
+      package: packageName,
       evidence: mismatches.join(', '),
-      suggestion: `Update ${name} to a release compatible with the active Harness.`,
-      repair: updateRepair(profile, name, commandRepair),
+      suggestion: `Update ${packageName} to a release compatible with the active Harness.`,
+      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 +1118,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 +1166,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 +1226,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 +1264,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 +1278,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,6 +1308,13 @@ 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 }
 }
 
@@ -952,7 +1338,10 @@ export function formatReport(report, options = {}) {
     `${zh ? 'DSH 主目录' : 'Home'}: ${report.context.home}`,
     `Harness: ${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)}`,
     '',
   ]

package/src/i18n.mjs

@@ -74,11 +74,19 @@ const ZH_MESSAGES = {
   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 源码中已不存在的旧包。`,
   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 凭据文件无法解析。',
@@ -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 中，但当前 Harness 源码已不再包含它。`,
+  PROFILE_HARNESS_SCOPE_UNREADABLE: () => 'Profile 内的 @deepseek-ai 包作用域无法作为目录读取。',
 }
 
 const ZH_SUGGESTIONS = {
@@ -115,12 +137,20 @@ 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 永远不会输出或重写秘密值。',
@@ -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) {

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,