@bruc3van/dsh-doctor 0.1.3 → 0.1.4

package/README.en.md

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

package/README.md

@@ -2,7 +2,7 @@
 
 中文 | [English](README.en.md)
 
-DSH Doctor 用来定位 DeepSeek Harness 无法启动、配置损坏和第三方插件不兼容等常见问题。默认运行完全只读；只有显式使用 `--fix`，查看精确的文件或命令计划并确认后，它才会实施可回滚的修复。
+DSH Doctor 面向 DSH 与插件使用者，帮助快速找出导致 DSH 启动异常或升级后不可用的插件，集中说明每个插件的问题、影响与处理方式，并检查常见的 profile 配置和版本漂移。诊断默认完全只读；只有显式使用 `--fix`、核对并确认精确的修复计划后才会执行，文件修改会先创建备份。
 
 这是社区维护的第三方工具，不属于 DeepSeek 官方项目。它不会加载或执行待检查插件的代码。
 
@@ -137,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.3",
-  "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": {

package/src/doctor.mjs

@@ -39,6 +39,7 @@ function finding(severity, code, message, options = {}) {
     message,
     ...options.package === undefined ? {} : { package: options.package },
     ...options.evidence === undefined ? {} : { evidence: options.evidence },
+    ...options.details === undefined ? {} : { details: options.details },
     ...options.suggestion === undefined ? {} : { suggestion: options.suggestion },
     ...options.repair === undefined ? {} : { repair: options.repair },
   }
@@ -293,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.',
   }))
@@ -556,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,
@@ -569,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,
@@ -983,7 +984,7 @@ function inspectProfileHarnessPackages(profileDir, home, harness, findings) {
       }
     }
     if (harness.authoritative && !harness.packages.has(name)) {
-      findings.push(finding('warning', 'STALE_PROFILE_HARNESS_PACKAGE', `${name} remains in the profile but is absent from the active Harness source tree.`, {
+      findings.push(finding('warning', 'STALE_PROFILE_HARNESS_PACKAGE', `${name} remains in the profile but is absent from the active DSH.`, {
         package: name,
         evidence: profileManifestFile,
         suggestion: 'Reinstall the profile with the active DSH CLI and review plugins that still require this package.',
@@ -1005,7 +1006,7 @@ function inspectCompatibility(record, context) {
       .filter(name => name.startsWith('@deepseek-ai/dsh-') && !harnessPackages.has(name))
       .sort()
     if (removedPeers.length > 0) {
-      findings.push(finding('warning', 'LEGACY_HARNESS_PEERS', `${packageName} still declares Harness packages that no longer exist in the active source tree.`, {
+      findings.push(finding('warning', 'LEGACY_HARNESS_PEERS', `${packageName} declares old interface packages that the active DSH has removed.`, {
         package: packageName,
         evidence: removedPeers.join(', '),
         suggestion: 'Update this plugin before relying on it with the current DSH release.',
@@ -1017,7 +1018,7 @@ function inspectCompatibility(record, context) {
       .filter(name => name.startsWith('@deepseek-ai/dsh-') && !harnessPackages.has(name))
       .sort()
     if (removedDependencies.length > 0) {
-      findings.push(finding('warning', 'LEGACY_HARNESS_DEPENDENCIES', `${packageName} depends on Harness packages that no longer exist in the active source tree.`, {
+      findings.push(finding('warning', 'LEGACY_HARNESS_DEPENDENCIES', `${packageName} depends on Harness packages that no longer exist in the active DSH.`, {
         package: packageName,
         evidence: removedDependencies.join(', '),
         suggestion: 'Update this plugin; its bundled DSH APIs may be incompatible with the current release.',
@@ -1041,13 +1042,31 @@ function inspectCompatibility(record, context) {
     const version = supplier.manifest?.version
     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) {
-    findings.push(finding('warning', 'HARNESS_PEER_VERSION_MISMATCH', `${packageName} has Harness peer ranges that do not accept the active versions.`, {
+    const grouped = new Map()
+    for (const mismatch of mismatches) {
+      const key = JSON.stringify([mismatch.required, mismatch.active])
+      const group = grouped.get(key) ?? {
+        required: mismatch.required, active: mismatch.active, packages: [],
+      }
+      group.packages.push(mismatch.name)
+      grouped.set(key, group)
+    }
+    const groups = [...grouped.values()]
+      .map(group => ({ ...group, packages: group.packages.sort() }))
+    const evidence = groups.flatMap((group, index) => [
+      ...(groups.length > 1 ? [`Group ${String(index + 1)}:`] : []),
+      `${groups.length > 1 ? '  ' : ''}Plugin requires: ${group.required}`,
+      `${groups.length > 1 ? '  ' : ''}Active DSH: ${group.active}`,
+      `${groups.length > 1 ? '  ' : ''}Affected ${String(group.packages.length)} package(s): ${group.packages.join(', ')}`,
+    ]).join('\n')
+    findings.push(finding('warning', 'HARNESS_PEER_VERSION_MISMATCH', `${packageName} declares compatibility ranges that exclude the active DSH version.`, {
       package: packageName,
-      evidence: mismatches.join(', '),
-      suggestion: `Update ${packageName} to a release compatible with the active Harness.`,
+      evidence,
+      details: { peerVersionGroups: groups },
+      suggestion: `Update ${packageName} to a release compatible with the active DSH.`,
       repair: updateRepair(profile, packageName, commandRepair),
     }))
   }
@@ -1318,6 +1337,20 @@ function finish(context, findings) {
   return { version: 1, ok: summary.errors === 0, context, summary, findings }
 }
 
+function appendReportField(lines, label, value, indent = '      ') {
+  const valueLines = String(value).split('\n')
+  if (valueLines.length === 1) {
+    lines.push(`${indent}${label}: ${valueLines[0]}`)
+    return
+  }
+  lines.push(`${indent}${label}:`)
+  lines.push(...valueLines.map(line => `${indent}  ${line}`))
+}
+
+function uniqueStrings(values) {
+  return [...new Set(values.filter(value => typeof value === 'string' && value.length > 0))]
+}
+
 export function formatReport(report, options = {}) {
   const color = options.color ?? false
   const language = options.language ?? 'en'
@@ -1336,7 +1369,7 @@ export function formatReport(report, options = {}) {
     'DSH Doctor',
     `${zh ? 'Profile' : 'Profile'}: ${report.context.profile}`,
     `${zh ? 'DSH 主目录' : 'Home'}: ${report.context.home}`,
-    `Harness: ${report.context.harness.version ?? 'unknown'}${report.context.harness.root ? ` (${report.context.harness.root})` : ''}`,
+    `${zh ? '当前使用的 DSH' : 'Active DSH'}: ${report.context.harness.version ?? 'unknown'}${report.context.harness.root ? ` (${report.context.harness.root})` : ''}`,
     `${zh ? 'DSH CLI' : 'DSH CLI'}: ${cliText}`,
     `${zh ? 'Profile 插件' : 'Profile plugins'}: ${String(report.context.packages.length)}`,
     zh
@@ -1345,19 +1378,130 @@ export function formatReport(report, options = {}) {
     `${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('')
     }
   }
@@ -1365,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,10 +71,10 @@ const ZH_MESSAGES = {
   CLIENT_BUNDLE_UNREADABLE: item => `无法读取 ${item.package} 的客户端 bundle。`,
   UNDECLARED_CLIENT_REQUIRE: item => `${item.package} 引用了 ${captured(item.message, / requires (.+) but does not/) ?? '未声明模块'}，但没有在 dsh.client.external 中声明。`,
   REDUNDANT_CLIENT_EXTERNAL: item => `${item.package} 把平台模块 ${captured(item.message, / module (.+) as an external/) ?? ''} 重复声明为 external。`,
-  CLIENT_EXTERNAL_WITHOUT_SUPPLIER: item => `${item.package} 请求了 ${captured(item.message, / requests (.+), but/) ?? '客户端模块'}，但当前 Harness 没有对应的模块提供方。`,
-  REMOVED_CLIENT_INJECT: item => `${item.package} 注入了 ${captured(item.message, / injects (.+), which/) ?? '已移除的模块'}，但当前 Harness 源码中已不存在该模块。`,
-  LEGACY_HARNESS_PEERS: item => `${item.package} 仍声明了当前 Harness 源码中已不存在的旧包。`,
-  LEGACY_HARNESS_DEPENDENCIES: item => `${item.package} 仍依赖当前 Harness 源码中已不存在的旧包。`,
+  CLIENT_EXTERNAL_WITHOUT_SUPPLIER: item => `${item.package} 请求了 ${captured(item.message, / requests (.+), but/) ?? '客户端模块'}，但当前使用的 DSH 没有对应的模块提供方。`,
+  REMOVED_CLIENT_INJECT: item => `${item.package} 注入了 ${captured(item.message, / injects (.+), which/) ?? '已移除的模块'}，但当前使用的 DSH 中已不存在该模块。`,
+  LEGACY_HARNESS_PEERS: item => `${item.package} 声明依赖当前使用的 DSH 已移除的旧接口包。`,
+  LEGACY_HARNESS_DEPENDENCIES: item => `${item.package} 仍依赖当前使用的 DSH 中已不存在的旧包。`,
   BUNDLE_NOT_INSTALLED: item => `配置中的 bundle ${item.package} 尚未安装。`,
   BUNDLE_DECLARATION_MISSING: item => `${item.package} 被列为 profile bundle，但没有声明 dsh.bundle.patch。`,
   BUNDLE_PATCH_MISSING: item => `${item.package} 的 bundle patch 文件缺失。`,
@@ -92,7 +92,7 @@ const ZH_MESSAGES = {
   INVALID_CREDENTIALS_DOCUMENT: () => 'Harness 凭据文件无法解析。',
   INVALID_CREDENTIALS_ROOT: () => 'Harness 凭据文件顶层必须是映射。',
   INVALID_CREDENTIALS_LAYOUT: () => 'Harness 凭据文件不是受支持的 version 1 结构。',
-  HARNESS_PEER_VERSION_MISMATCH: item => `${item.package} 声明的 Harness peer 版本范围不接受当前已安装版本。`,
+  HARNESS_PEER_VERSION_MISMATCH: item => `${item.package} 声明的兼容范围不包含当前使用的 DSH 版本。`,
   INVALID_PROFILE_NAME: item => `Profile 名称无效：${captured(item.message, /^Invalid profile name (.+)\.$/) ?? ''}`,
   PROFILE_NOT_FOUND: item => `Profile ${captured(item.message, /^Profile (.+) does not exist\.$/) ?? ''} 不存在。`,
   INVALID_DSH_CONFIGURATION: () => 'dsh 字段存在时必须是对象。',
@@ -114,7 +114,7 @@ const ZH_MESSAGES = {
   LOCKFILE_DEPENDENCY_STALE: item => `pnpm lockfile 仍包含未声明的依赖 ${item.package}。`,
   DSH_CLI_HARNESS_VERSION_MISMATCH: () => '当前 DSH CLI 与诊断到的 Harness 版本不一致。',
   DUPLICATE_HARNESS_PACKAGE_VERSION: item => `${item.package} 在 profile 与共享 DSH 安装中存在不同版本。`,
-  STALE_PROFILE_HARNESS_PACKAGE: item => `${item.package} 残留在 profile 中，但当前 Harness 源码已不再包含它。`,
+  STALE_PROFILE_HARNESS_PACKAGE: item => `${item.package} 残留在 profile 中，但当前使用的 DSH 已不再包含它。`,
   PROFILE_HARNESS_SCOPE_UNREADABLE: () => 'Profile 内的 @deepseek-ai 包作用域无法作为目录读取。',
 }
 
@@ -155,7 +155,7 @@ const ZH_SUGGESTIONS = {
   INVALID_SETTINGS_ROOT: () => '把顶层标量或数组替换为映射。',
   INVALID_CREDENTIALS_DOCUMENT: () => '只修复报告的结构；Doctor 永远不会输出或重写秘密值。',
   INVALID_CREDENTIALS_LAYOUT: () => '迁移文档结构，不要暴露或修改秘密值。',
-  HARNESS_PEER_VERSION_MISMATCH: item => `把 ${item.package} 更新到兼容当前 Harness 的版本。`,
+  HARNESS_PEER_VERSION_MISMATCH: item => `把 ${item.package} 更新到兼容当前使用的 DSH 的版本。`,
   PROFILE_NOT_FOUND: () => '先启动一次该 profile，或用当前 DSH 安装初始化它。',
   INVALID_DSH_CONFIGURATION: () => '启动 Harness 前，请先修复 dsh 配置对象。',
   INVALID_PROFILE_CONFIGURATION: () => '启动 Harness 前，请先修复 dsh.profile 配置对象。',
@@ -188,9 +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 }
 }