@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/profile-doctor.mjs

@@ -0,0 +1,686 @@
+#!/usr/bin/env node
+/**
+ * profile-doctor —— dsh profile「组合体检 + 自愈」
+ *
+ * ## 为什么存在（三类真实事故，2026-09-14 一天内全踩）
+ *
+ * 1. **重复挂载**：`argent-skin` 既在 `dsh.profile.bundles`，又在 `cordis.patch.yml` 有 insert 行
+ *    ⇒ 加载器报 `duplicate loader entry id: argent-skin` ⇒ dsh web **启动即失败**，
+ *    在 LaunchAgent KeepAlive 下变成 crash loop（用户若不先验证就重启，服务直接起不来）。
+ * 2. **依赖指向已删除的临时目录**：`file:/tmp/kb061-repo/plugins/argent-core`（/tmp 被清后）
+ *    ⇒ **任何 pnpm 操作都失败**（`[ENOENT] scandir …`）⇒ `dsh plugin add/remove`、安装器全废。
+ * 3. **退役插件仍在必需清单里**：老安装器把 `argent-files`（原生 dsh 已覆盖）当必需 patch 行，
+ *    会自动补回 ⇒ 等于反复埋雷。
+ *
+ * 共同根因：**profile 组合是"多来源手工拼装"的（bundles + cordis.patch.yml + dependencies + node_modules），
+ * 任何一处漂移都不会立刻报错，只在"下次重启"或"下次 pnpm"时爆**。所以必须有一道
+ * 廉价、可自动修、且在安装/升级时强制跑的门禁。
+ *
+ * ## 用法
+ *   node scripts/profile-doctor.mjs                     # 体检当前 web profile（只报告，不改）
+ *   node scripts/profile-doctor.mjs --profile tui
+ *   node scripts/profile-doctor.mjs --json              # 机器可读报告（含"若加 --fix 会做什么"的计划）
+ *   node scripts/profile-doctor.mjs --fix               # 自动修复组合（改前备份到 ~/.dsh/argent/backup/）
+ *   node scripts/profile-doctor.mjs --fix --allow-package-manager   # 重指依赖后**才**跑包管理器
+ *   node scripts/profile-doctor.mjs --fix --bootcheck   # 修完再跑启动冒烟
+ *   node scripts/profile-doctor.mjs --profile-dir /tmp/x   # 对任意 profile 目录体检（测试用）
+ *   node scripts/profile-doctor.mjs --fix --backup-dir /tmp/bak   # 备份改指（测试**必须**这样隔离）
+ *
+ * ## 两条与备份有关的纪律（2026-10-04）
+ *
+ * ① **调用者取证**：每次落备份时，在**备份旁侧**追加一行到 `<备份根>/doctor-callers.jsonl`
+ *    （`{at, pid, ppid, parentCmd, ancestors, argv, cwd, profile, backedUp, backupFile}`）。
+ *    由来：真实备份目录里堆了 **1023 份** `*.doctor-<ts>`（自 2026-09-14），而 web profile 的
+ *    mtime 纹丝不动 ⇒ 谁都说不清"谁在周期性跑 doctor"。doctor 自己看不见调用者，而调用方
+ *    通常隔着好几层（会话 → bash → 测试 → node）—— 只有把**进程祖先链**记下来才定位得到。
+ *    纪律：**只记进程线索，绝不记环境变量**（那里有密钥）；`argv`/命令行一律脱敏；
+ *    **取证失败绝不影响主流程**（全程 try/catch）。
+ * ② **空转抑制**：将要写入的内容与现文件**逐字节相同** ⇒ **不写、也不产备份**（打印
+ *    "内容无变化，跳过备份"）。有变化时行为与旧实现完全一致：**先备份再写**。
+ *    ⛔ 这条抑制的是"同一目录被反复修成同一个样子"，**不削弱**"写前必有备份"。
+ * ③ 备份文件名唯一（`<名字>.doctor-<时间戳>`，同秒冲突时后缀 `.2`/`.3`…）：同一次运行会对
+ *    同一个文件备份多次，而时间戳只到秒 ⇒ 旧实现里**最早那份（未改动）会被后来者覆盖**，
+ *    "写前必有备份"在最关键的一次反而丢了。
+ *
+ * ⚠️ **测试必须改指备份根**（`--backup-dir` / `ARGENT_BACKUP_DIR`）：doctor 的备份根默认是
+ *    `<dsh-home>/argent/backup`，而 `--profile-dir` 只改 profile 目录 —— 夹具 profile 的备份
+ *    会**落进真实数据目录**。2026-10-04 取证的 1023 份堆料就是这么来的（见测试用例 ⑧/⑨）。
+ *
+ * ## ⛔ 包管理器必须显式授权（2026-10-03）
+ * 重指 `file:` 依赖后为了让 `node_modules` 与 manifest 一致，旧实现会**自动**
+ * `dsh plugin --profile <p> install`（= pnpm install）。这条在 `--fix` 里是**静默副作用**：
+ * `argent-upgrade.mjs run` 的第 7.5 步无条件带 `--fix` ⇒ 每次升级都会在 **web profile**
+ * （`~/.dsh/AGENTS.md` 明令避免跑 pnpm 的那棵树）上跑一次包管理器，并把 5 条 `file:`
+ * 依赖从已消失的临时目录重指到仓库。现在：**没有 `--allow-package-manager` 就不跑**，
+ * 只把"依赖已重指、包管理器已跳过、下一步该敲什么"如实打出来。
+ *
+ * 除 profile 组合外，还会核对**装机清单里的能力包完整性**（批 B4，只报不改）：
+ *   `<dsh-home>/argent/install.json` 的逐文件 sha16 vs 当前文件实际 sha ⇒ 不符即 FAIL；
+ *   环境变量 `ARGENT_INSTALL_JSON` 可覆盖清单路径（测试/多实例用）。
+ *
+ * ## 退出码
+ *   0 = 无问题（或已全部修复）   1 = 发现问题（未加 --fix 时）/ 修复失败
+ */
+import { execFileSync } from 'node:child_process'
+import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { homedir, tmpdir } from 'node:os'
+import { basename, dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describeCapability, isRegistryProjection, readInstallJson, sha16File } from './argent-capabilities.mjs'
+// bundle 层名单与升级器**共用一份**（2026-09-28：两处知识分叉过 —— doctor 报红而升级器
+// 以为正常，客户机 P3 卡在体检门禁上）
+import { bundleLayerMap, pluginRowName, retiredRowMap } from './lib/plugin-lifecycle.mjs'
+import { exactPluginIdOf, migrateBundleNames, pluginIdOf } from './lib/plugin-packages.mjs'
+import { renderInsertBlock } from './lib/patch-compose.mjs'
+import { resolveDshBin } from './lib/dsh-scope.mjs'
+
+const SELF = fileURLToPath(import.meta.url)
+const REPO = resolve(dirname(SELF), '..')
+const HOME = homedir()
+const DSH_HOME = process.env.DSH_HOME || join(HOME, '.dsh')
+
+/** 规范插件根：所有 file: 依赖都应当落在这里（或下面的 packs-cache）。 */
+const CANONICAL_ROOTS = [join(REPO, 'plugins')]
+/** 允许的例外：市场包缓存（.tgz）等。 */
+const ALLOWED_PREFIXES = [join(DSH_HOME, 'argent', 'packs-cache')]
+/** 已退役插件：{id: 原因}；patch 行里出现即移除。名单见 lib/plugin-lifecycle.mjs。 */
+const RETIRED = retiredRowMap()
+/** 已迁移到 bundle 层的插件：出现在 patch 行即为重复挂载。名单见 lib/plugin-lifecycle.mjs。 */
+const BUNDLE_MIGRATED = bundleLayerMap()
+/** 必须存在的 patch 行。 */
+const REQUIRED_ROWS = ['argent-core']
+
+// ── 参数 ──────────────────────────────────────────────────────────────
+const argv = process.argv.slice(2)
+const flag = (n) => argv.includes(n)
+const opt = (n, d) => { const i = argv.indexOf(n); return i >= 0 && argv[i + 1] ? argv[i + 1] : d }
+const FIX = flag('--fix')
+const RUN_BOOTCHECK = flag('--bootcheck')
+/** 机器可读输出（升级器在决定"要不要 --fix"前先跑一次只读体检拿计划）。 */
+const JSON_OUT = flag('--json')
+/** **显式**授权在真实 profile 上跑包管理器（= `dsh plugin install` → pnpm install）。缺省不给。 */
+const ALLOW_PACKAGE_MANAGER = flag('--allow-package-manager')
+const PROFILE = opt('--profile', 'web')
+const PROFILE_DIR = opt('--profile-dir', join(DSH_HOME, 'profiles', PROFILE))
+/**
+ * 备份根（`<dsh-home>/argent/backup`）：改前留档 + 调用者线索都落这里。
+ * `--backup-dir` / `ARGENT_BACKUP_DIR` 可改指 —— **测试一律要改指**，否则夹具 profile 的备份
+ * 会写进真实数据目录（2026-10-04 取证的 1023 份堆料正是这么来的）。
+ */
+const BACKUP_DIR = resolve(opt('--backup-dir', process.env.ARGENT_BACKUP_DIR || join(DSH_HOME, 'argent', 'backup')))
+/** 是否就是 dsh 真正挂载的那个 profile 目录；只有它才允许跑 pnpm（否则会误改线上 profile）。 */
+const IS_REAL_PROFILE = resolve(PROFILE_DIR) === resolve(join(DSH_HOME, 'profiles', PROFILE))
+
+const problems = []   // {level:'error'|'warn', code, msg, fix?}
+const fixes = []      // 已执行的修复
+const add = (level, code, msg, fix) => problems.push({ level, code, msg, fix })
+
+// ── 读取 ──────────────────────────────────────────────────────────────
+const manifestPath = join(PROFILE_DIR, 'package.json')
+const patchPath = join(PROFILE_DIR, 'cordis.patch.yml')
+if (!existsSync(manifestPath)) {
+  console.error(`[doctor] 找不到 profile manifest：${manifestPath}`)
+  process.exit(1)
+}
+const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+const deps = manifest.dependencies || {}
+const bundles = manifest?.dsh?.profile?.bundles || []
+let patchText = existsSync(patchPath) ? readFileSync(patchPath, 'utf8') : ''
+const patchLines = patchText.split('\n')
+
+// ── 工具 ──────────────────────────────────────────────────────────────
+const under = (p, root) => p === root || p.startsWith(root + '/')
+const hasPackageJson = (dir) => { try { return existsSync(join(dir, 'package.json')) } catch { return false } }
+
+/**
+ * 某插件在 `dsh.profile.bundles` 里**有没有登记**。
+ * ⚠️ W9（2026-10-13）：条目是**包名**（`@whyshu/argent-skin`），存量机器上是裸名
+ * （`argent-skin`，见 migrateBundleNames）⇒ 只按 `row.id` 字面比对会**漏判"重复挂载"**，
+ * 而漏判的后果是加载器 `duplicate loader entry id` ⇒ **dsh web 启动即失败**。
+ * 判据经唯一真源归一：**严格**认「裸 id」与「本仓 npm 名」两种精确写法（⛔ 别的 scope 不算我们
+ * 的重复挂载 —— `@acme/argent-skin` 与 `argent-skin` 是**两个不同的包**）。
+ */
+function bundleLanded(rowId) {
+  return bundles.some((b) => exactPluginIdOf(b) === rowId)
+}
+
+/** patch 行名 → 包名 / 子路径（`argent-core/llm-whyshu` → `argent-core` + `llm-whyshu`）。 */
+function splitRowName(spec) {
+  const parts = String(spec).split('/')
+  const pkg = String(spec).startsWith('@') ? parts.slice(0, 2).join('/') : parts[0]
+  return { pkg, sub: String(spec).slice(pkg.length).replace(/^\//, '') }
+}
+
+/**
+ * patch 行引用的包**是否真的装了**（判据**不放宽**，只补子路径导出这一形态）。
+ *
+ * 事故（2026-10-03，假阳性）：旧实现只看字面目录 `node_modules/<row.name>`
+ * ⇒ 行名是**子路径导出**时（`name: 'argent-core/llm-whyshu'`，真实解析到
+ * `node_modules/argent-core/src/llm-whyshu.js`，见包内 `exports["./llm-whyshu"]`）
+ * 那个"目录"根本不存在 ⇒ 每次体检都报 `row-pkg-missing`（且 `--fix` 给出
+ * `dsh plugin add file:<repo>/plugins/argent-core/llm-whyshu` 这种**错误的**修法）。
+ *
+ * 判据：
+ *   · 无子路径 ⇒ 仍按字面目录存在（原判据，一字不改）；
+ *   · 有子路径 ⇒ ① 以 profile 为锚 `require.resolve`（走 exports 映射）；
+ *                 ② 退回读包的 `exports` 是否声明该子路径（含 `./*` 通配）；
+ *                 ③ 无 `exports` 字段时才退回字面文件判定。
+ *   ⇒ "子路径导出"不再报缺；真缺包（目录/包名不存在、exports 未声明该子路径）**照样报**。
+ */
+function rowPackageInstalled(profileDir, spec, deps = { createRequire, existsSync, readFileSync }) {
+  const { pkg, sub } = splitRowName(spec)
+  const pkgDir = join(profileDir, 'node_modules', pkg)
+  if (!sub) return deps.existsSync(pkgDir)
+  try {
+    deps.createRequire(join(profileDir, 'package.json')).resolve(spec)
+    return true
+  } catch { /* 继续看 exports 声明 */ }
+  let pj = null
+  try { pj = JSON.parse(deps.readFileSync(join(pkgDir, 'package.json'), 'utf8')) } catch { return false }
+  const ex = pj && pj.exports
+  if (ex && typeof ex === 'object') {
+    const keys = Object.keys(ex)
+    if (keys.includes(`./${sub}`)) return true
+    for (const k of keys) {
+      if (!k.includes('*')) continue
+      const re = new RegExp('^' + k.split('*').map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*') + '$')
+      if (re.test(`./${sub}`)) return true
+    }
+    return false // 有 exports 却没声明该子路径 ⇒ 加载必失败，照报
+  }
+  return deps.existsSync(join(pkgDir, sub)) || deps.existsSync(join(pkgDir, `${sub}.js`))
+}
+
+// ── 备份（写前留档）+ 调用者取证 ────────────────────────────────────────
+/**
+ * 命令行脱敏：把"看起来是密钥"的片段换成 `***`。
+ * ⛔ 取证**不许**把密钥写进日志 —— 祖先链里的命令行可能带着 token/api-key（别的进程的）。
+ */
+function redact(text) {
+  return String(text ?? '')
+    .replace(/((?:--?)?(?:api[-_]?key|access[-_]?token|token|secret|password|passwd)[=\s:]+)\S+/gi, '$1***')
+    .replace(/\bBearer\s+\S+/gi, 'Bearer ***')
+    .replace(/\bsk-[A-Za-z0-9_-]{8,}\b/g, 'sk-***')
+    .replace(/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/g, '***jwt***')
+}
+
+/** 单行化 + 脱敏 + 截断（日志只留可读线索，不留大块文本）。 */
+function clip(text, max = 400) {
+  const t = redact(text).replace(/\s+/g, ' ').trim()
+  return t.length > max ? `${t.slice(0, max)}…` : t
+}
+
+/** Linux：读 `/proc` 拿 cmdline + ppid。macOS 没有 `/proc` ⇒ 返回 null，调用方退回 `ps`。 */
+function procInfo(pid) {
+  try {
+    const command = readFileSync(`/proc/${pid}/cmdline`, 'utf8').split('\0').filter(Boolean).join(' ')
+    const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+    const ppid = Number(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1])
+    return { pid: Number(pid), ppid: Number.isFinite(ppid) ? ppid : 0, command }
+  } catch { return null }
+}
+
+/** 兜底：`ps -o pid=,ppid=,command= -p <pid>`（macOS / Linux 同形）。失败 ⇒ null（取证失败不得影响主流程）。 */
+function psInfo(pid) {
+  try {
+    const out = execFileSync('ps', ['-o', 'pid=,ppid=,command=', '-p', String(pid)],
+      { encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'] })
+    const line = String(out).split('\n').map((l) => l.trim()).filter(Boolean)[0]
+    const m = line ? /^(\d+)\s+(\d+)\s+(.*)$/.exec(line) : null
+    return m ? { pid: Number(m[1]), ppid: Number(m[2]), command: m[3] } : null
+  } catch { return null }
+}
+
+/** 进程祖先链（最多 depth 层）：`[父, 祖父, …]`。取不到就返回已经拿到的部分。 */
+function ancestorChain(startPid, depth = 4) {
+  const chain = []
+  let pid = Number(startPid)
+  for (let i = 0; i < depth && Number.isFinite(pid) && pid > 1; i++) {
+    const info = procInfo(pid) || psInfo(pid)
+    if (!info) break
+    chain.push({ pid: info.pid, command: clip(info.command, 300) })
+    pid = info.ppid
+  }
+  return chain
+}
+
+/**
+ * 把**一条**调用者线索追加到 `<备份根>/doctor-callers.jsonl`（JSONL：一行一条，便于 `tail`/`jq`）。
+ * **best-effort**：任何失败都吞掉并返回 null —— ⛔ 取证失败绝不允许影响体检/修复主流程。
+ */
+function recordCaller(entry) {
+  try {
+    const chain = ancestorChain(process.ppid)
+    const rec = {
+      at: new Date().toISOString(),
+      pid: process.pid,
+      ppid: process.ppid,
+      parentCmd: chain.length > 0 ? chain[0].command : null,   // = 谁直接 spawn 了 doctor
+      ancestors: chain,                                        // 再往上：bash / 会话 / 测试入口
+      argv: process.argv.slice(1).map((a) => clip(a, 200)),     // doctor 自己的参数（脱敏）
+      cwd: process.cwd(),
+      profile: PROFILE_DIR,
+      backupDir: BACKUP_DIR,
+      ...entry,
+    }
+    mkdirSync(BACKUP_DIR, { recursive: true })
+    appendFileSync(join(BACKUP_DIR, 'doctor-callers.jsonl'), JSON.stringify(rec) + '\n')
+    return rec
+  } catch { return null }
+}
+
+const backupStamp = () => new Date().toISOString().replace(/[-:T]/g, '').slice(0, 15)
+
+/**
+ * 写前留档：把 `file` 原样复制成 `<备份根>/<名字>.doctor-<时间戳>`，并记一行调用者线索。
+ * 时间戳只到秒，而同一次运行会对同一文件备份多次（重指 → 删行 → 补必需行）⇒ 撞名时后缀
+ * `.2`/`.3`…：⛔ 绝不让后来者覆盖最早那份（那才是"未改动"的原件）。
+ */
+function backup(file) {
+  mkdirSync(BACKUP_DIR, { recursive: true })
+  const base = `${basename(file)}.doctor-${backupStamp()}`
+  let target = join(BACKUP_DIR, base)
+  for (let n = 2; existsSync(target); n++) target = join(BACKUP_DIR, `${base}.${n}`)
+  cpSync(file, target)
+  recordCaller({ backedUp: file, backupFile: target })
+  return target
+}
+
+/** 本轮因"内容无变化"而跳过的写入（供报告/`--json` 如实回显）。 */
+const skippedWrites = []
+
+/**
+ * **写前必有备份**，但**只在内容真的要变**时才写（2026-10-04 空转抑制）：
+ *   · 逐字节相同 ⇒ **不写、不产备份**（记一行"内容无变化，跳过备份"）；
+ *   · 有变化 ⇒ 与旧实现**完全一致**：先 `backup()`，再 `writeFileSync()`。
+ * ⛔ 不要把它改成"先备份再比较"——那正是白堆备份的形态。
+ */
+function writeIfChanged(file, nextText) {
+  let current = null
+  try { current = readFileSync(file, 'utf8') } catch { current = null }
+  if (current !== null && current === nextText) {
+    skippedWrites.push(basename(file))
+    return false
+  }
+  backup(file)
+  writeFileSync(file, nextText)
+  return true
+}
+
+function parsePatchRows(lines) {
+  // 逐行扫描 `- id: X` / 紧随的 `name: 'Y'`，返回行号（0 基）便于精确删改。
+  //
+  // ⚠️ 两种条目语义不同（2026-09-29 修）：
+  //   · **insert 行**：`- id: X` + `name: 'pkg'` ⇒ 引入一个包，要检查它装没装；
+  //   · **覆盖行（override）**：只有 `- id: X` + `config:`，没有 `name` ⇒ 按 id 改**已存在**
+  //     那一行的配置（cordis patch 的标准写法）。旧实现把 name 兜底成 id ⇒ 于是
+  //     `- id: agent-preset-registry / config:` 这种覆盖行被当成 insert 行，报
+  //     "row-pkg-missing：包 agent-preset-registry 未安装" ⇒ 升级门禁卡死（本轮实测）。
+  const rows = []
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^\s*-\s*id:\s*([A-Za-z0-9_.@/-]+)\s*$/.exec(lines[i])
+    if (!m) continue
+    const nameM = i + 1 < lines.length ? /^\s*name:\s*['"]?([\w@/.-]+)['"]?\s*$/.exec(lines[i + 1]) : null
+    rows.push({ index: i, lines: nameM ? 2 : 1, id: m[1], name: nameM ? nameM[1] : null, isOverride: !nameM })
+  }
+  return rows
+}
+
+// ── 检查 1：dependencies 的 file: 规格是否指向存在且规范的路径 ──────────
+const repoint = {}
+/** 修复计划：**执行前**把"会改什么、要不要跑包管理器"如实报出来（升级器 / --json 消费）。 */
+const fixPlan = { depsToRepoint: [], bundlesToRename: [], patchRowsToDrop: 0, requiredRowsToAdd: [], runsPackageManager: false, packageManagerCommand: null }
+/**
+ * 依赖键 → 规范插件目录（`<REPO>/plugins/<插件 id>`）。
+ * ⚠️ W9（2026-10-13）：键现在是**包名**（`@whyshu/argent-core`），⛔ 目录名恒是**裸 id**
+ * ⇒ 只用键当目录名会算出 `<REPO>/plugins/@whyshu/argent-core`（不存在）⇒ 该依赖被判成
+ * "目标不存在且规范路径也没有"（`dep-missing-unfixable`，无法自愈）。
+ */
+const canonicalDirOf = (name) => join(REPO, 'plugins', pluginIdOf(name) || String(name))
+for (const [name, spec] of Object.entries(deps)) {
+  const s = String(spec)
+  if (!s.startsWith('file:')) continue
+  const p = s.slice(5)
+  if (!existsSync(p)) {
+    // 目标已不存在：若能映射回规范根则重指，否则只能报错
+    const guess = canonicalDirOf(name)
+    if (hasPackageJson(guess)) {
+      repoint[name] = `file:${guess}`
+      fixPlan.depsToRepoint.push({ name, from: p, to: guess })
+      add('error', 'dep-missing', `依赖 ${name} → ${p}（**目标不存在**）`,
+        `重指到规范路径 ${guess}`)
+    } else {
+      add('error', 'dep-missing-unfixable', `依赖 ${name} → ${p}（目标不存在，且 ${guess} 也没有该插件）`,
+        '需人工确认该插件是否还存在')
+    }
+    continue
+  }
+  if (ALLOWED_PREFIXES.some((r) => under(p, r))) continue
+  if (!CANONICAL_ROOTS.some((r) => under(p, r))) {
+    const guess = canonicalDirOf(name)
+    if (hasPackageJson(guess)) {
+      repoint[name] = `file:${guess}`
+      fixPlan.depsToRepoint.push({ name, from: p, to: guess })
+      add('warn', 'dep-foreign', `依赖 ${name} → ${p}（**不在规范插件根内**；临时目录/别处副本会在清理后失效）`,
+        `重指到 ${guess}`)
+    } else {
+      add('warn', 'dep-foreign', `依赖 ${name} → ${p}（不在规范插件根内，且规范路径无此插件）`, '请人工确认')
+    }
+  }
+}
+
+// ── 检查 2/3/4：patch 行——退役、重复挂载、必需缺失、包缺失 ────────────
+const rows = parsePatchRows(patchLines)
+const dropIndexes = new Set()
+for (const row of rows) {
+  // 覆盖行只改已存在行的 config，不引入包 ⇒ 与"包是否存在/是否退役"无关
+  if (row.isOverride) continue
+  if (RETIRED[row.id] || RETIRED[row.name]) {
+    for (let k = 0; k < row.lines; k++) dropIndexes.add(row.index + k)
+    add('error', 'row-retired', `patch 行 ${row.id}：${RETIRED[row.id] || RETIRED[row.name]}`, `移除该行`)
+    continue
+  }
+  if (BUNDLE_MIGRATED[row.id] && bundleLanded(row.id)) {
+    for (let k = 0; k < row.lines; k++) dropIndexes.add(row.index + k)
+    add('error', 'row-duplicate',
+      `patch 行 ${row.id} 与 dsh.profile.bundles 重复（${BUNDLE_MIGRATED[row.id]}）`
+      + ` ⇒ 加载器会报 duplicate loader entry id，**dsh web 启动即失败**`, '移除该 patch 行')
+    continue
+  }
+  if (BUNDLE_MIGRATED[row.id]) {
+    add('warn', 'row-migrated', `patch 行 ${row.id}：${BUNDLE_MIGRATED[row.id]}，但它不在 bundles 里`, `确认是否应登记进 bundles`)
+  }
+  // 行存在但包没装 → 启动时会 failed to apply loader entry
+  // ⚠️ 判据是"**能不能解析到**"，不是"字面目录在不在"：行名允许**子路径导出**
+  //    （`argent-core/llm-whyshu` → 包内 exports["./llm-whyshu"]）；旧实现按字面目录判
+  //    ⇒ 2026-10-03 之前每次都误报 row-pkg-missing。见 rowPackageInstalled()。
+  if (!rowPackageInstalled(PROFILE_DIR, row.name) && !row.name.startsWith('@deepseek-ai/')) {
+    add('error', 'row-pkg-missing', `patch 行 ${row.id} 的包 ${row.name} 未安装（node_modules 里解析不到）`,
+      `dsh plugin --profile ${PROFILE} add file:${join(REPO, 'plugins', splitRowName(row.name).pkg)}`)
+  }
+}
+for (const id of REQUIRED_ROWS) {
+  if (!rows.some((r) => r.id === id)) {
+    add('error', 'row-required-missing', `缺少必需 patch 行 ${id}（缺失会导致重启后对应端点 404）`, `补上该行`)
+  }
+}
+// 修复计划（供 --json / 升级器"执行前明示"）：包管理器只有在**依赖被重指**时才需要跑
+fixPlan.patchRowsToDrop = dropIndexes.size
+fixPlan.requiredRowsToAdd = REQUIRED_ROWS.filter((id) => !rows.some((r) => r.id === id))
+fixPlan.runsPackageManager = fixPlan.depsToRepoint.length > 0
+fixPlan.packageManagerCommand = `dsh plugin --profile ${PROFILE} install（= pnpm install；⛔ 只对真实 profile，且需显式 --allow-package-manager）`
+
+// ── 修复 ──────────────────────────────────────────────────────────────
+let manifestDirty = false
+if (FIX && Object.keys(repoint).length > 0) {
+  for (const [name, spec] of Object.entries(repoint)) deps[name] = spec
+  manifest.dependencies = deps
+  // 内容无变化 ⇒ 不写也不备份（有变化时先 backup 再写，与旧实现一致）
+  if (writeIfChanged(manifestPath, JSON.stringify(manifest, null, 2) + '\n')) {
+    for (const [name, spec] of Object.entries(repoint)) fixes.push(`依赖 ${name} 重指到 ${spec.slice(5)}`)
+    manifestDirty = true
+  }
+}
+// ── W9（2026-10-13）`dsh.profile.bundles`：裸名 ⇒ npm 名（迁移的**第三处**；幂等 + 写前备份）──
+// 裸名条目（`argent-skin`）在 profile 里**解析不到**（实体在 `node_modules/@whyshu/argent-skin`）
+// ⇒ 该 bundle 加载不到 ⇒ **皮肤/UI 壳静默不加载**（装完零报错）。判据/迁移走唯一真源。
+// 与依赖重指**分开**处理：bundles 改的是**键名**，不需要包管理器 ⇒ 不置 manifestDirty（否则会
+// 连带触发 pnpm 那一步），但仍走 writeIfChanged（写前必有备份）。
+const bundlesMig = migrateBundleNames(bundles)
+fixPlan.bundlesToRename = bundlesMig.renamed.map((r) => ({ from: r.from, to: r.to }))
+// 读侧也**响亮点名**（⛔ 不静默）：真机现场"只读体检只剩一条 install.json WARN"，
+// 而真正致命的裸名条目**一个字都没报** —— 用户据此以为装好了。
+for (const r of bundlesMig.renamed) {
+  add('warn', 'bundle-bare-name',
+    `dsh.profile.bundles 里的 ${r.from} 是**裸名**（应为 ${r.to}）⇒ 该 bundle 在 profile 里**解析不到**、不会加载`
+    + '（皮肤/UI 壳静默不生效）', `--fix 迁移到 ${r.to}`)
+}
+for (const s of bundlesMig.stale) {
+  add('warn', 'bundle-stale-alias',
+    `dsh.profile.bundles 里的 ${s} 与同一个 bundle 的**规范名并存** ⇒ 会重复挂载`, `--fix 摘掉 ${s}`)
+}
+if (FIX && (bundlesMig.renamed.length > 0 || bundlesMig.stale.length > 0)) {
+  manifest.dsh = manifest.dsh || {}
+  manifest.dsh.profile = manifest.dsh.profile || {}
+  manifest.dsh.profile.bundles = bundlesMig.bundles
+  if (writeIfChanged(manifestPath, JSON.stringify(manifest, null, 2) + '\n')) {
+    for (const r of bundlesMig.renamed) fixes.push(`bundles 条目 ${r.from} → ${r.to}（npm 名）`)
+    if (bundlesMig.stale.length) fixes.push(`摘掉 bundles 里的陈旧别名 ${bundlesMig.stale.join(', ')}（同一 bundle 不许留两个名字）`)
+  }
+}
+if (FIX && dropIndexes.size > 0) {
+  const nextText = patchLines.filter((_, i) => !dropIndexes.has(i)).join('\n')
+  if (writeIfChanged(patchPath, nextText)) {
+    patchText = nextText
+    fixes.push(`移除 ${dropIndexes.size} 行退役/重复 patch 行`)
+  }
+}
+if (FIX && problems.some((p) => p.code === 'row-required-missing')) {
+  const missing = REQUIRED_ROWS.filter((id) => !rows.some((r) => r.id === id))
+  if (missing.length > 0) {
+    // ⚠️ W9：`name:` 是**包名**（`@whyshu/argent-core`），`id:` 仍是裸 id —— 旧实现在这里
+    // 写 `name: '<裸 id>'`，是"profile 面向字符串漏迁 scope"的**第四个写入点**（装完那一行解析不到）。
+    // 渲染一律走**唯一实现** `patch-compose.mjs#renderInsertBlock()`（⛔ 不在本文件里再拼一份）。
+    const block = renderInsertBlock(missing.map((id) => ({ id, name: pluginRowName(id) })))
+    let t = readFileSync(patchPath, 'utf8')
+    t = t.replace(/^\s*\[\]\s*$/gm, '').replace(/\n{3,}$/, '\n\n')
+    if (writeIfChanged(patchPath, t.trimEnd() + '\n\n' + block + '\n')) fixes.push(`补上必需行 ${missing.join(', ')}`)
+  }
+}
+if (FIX && manifestDirty) {
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n')
+  // 规格变了必须让 node_modules 跟上（否则 manifest 与磁盘不一致）。
+  // ⚠ 只对 dsh 真正挂载的 profile 执行——`--profile-dir` 指向别处时（测试/合成目录）
+  //   跑 pnpm 会误改线上 profile。
+  // ⚠⚠ 2026-10-03：**必须显式授权**（--allow-package-manager）才跑包管理器。
+  //    旧实现只要 --fix 就会跑 ⇒ `argent-upgrade.mjs run` 的第 7.5 步无条件带 --fix，
+  //    于是每次升级都在 web profile 上跑了一次 pnpm install（`~/.dsh/AGENTS.md` 明令避免），
+  //    还把 5 条 file: 依赖从已消失的临时目录重指到仓库 —— 全是**静默副作用**。
+  //    现在的规矩：改 manifest 照旧，但**包管理器这一步不替用户做主**。
+  if (!IS_REAL_PROFILE) {
+    fixes.push('（非真实 profile 目录，跳过 pnpm install；真实场景会自动重链）')
+  } else if (!ALLOW_PACKAGE_MANAGER) {
+    const cmd = `dsh plugin --profile ${PROFILE} install`
+    add('warn', 'pkg-manager-skipped',
+      `依赖已重指，但**未运行包管理器**（缺显式 --allow-package-manager）：node_modules 可能与 manifest 不一致`,
+      `确认后自行执行：${cmd}（= pnpm install；web profile 上是红线动作，先读 ~/.dsh/AGENTS.md）`)
+    fixes.push(`已跳过包管理器（未给 --allow-package-manager）⇒ 需要时手动跑：${cmd}`)
+  } else {
+    try {
+      // 2026-09-28：写死 homebrew 路径 ⇒ 客户机上这里直接 ENOENT，自愈失效。用共享解析。
+      execFileSync(resolveDshBin(), ['plugin', '--profile', PROFILE, 'install'],
+        { stdio: 'pipe', cwd: HOME, timeout: 300000 })
+      fixes.push('已 pnpm install 使 node_modules 与 manifest 一致（--allow-package-manager 已显式授权）')
+    } catch (error) {
+      add('error', 'pnpm-failed', `修复后 pnpm install 失败：${String(error.stderr || error.message).slice(0, 300)}`, '需人工介入')
+    }
+  }
+}
+
+// ── 检查 5：装机清单「包完整性」（批 B4；只报不改）──────────────────────
+// 依据 `<dsh-home>/argent/install.json`（ARGENT_INSTALL_JSON 可覆盖）：
+//   ① 逐文件 sha16：装机时记录的 sha vs 当前文件实际 sha ⇒ 不符/缺失即 FAIL（改一个脚本就能报出来）；
+//   ② 服务端清单 sha256 为空的条目 ⇒ 只 WARN（发布流程待填），**不算 FAIL**；
+//   ③ 能力包工具缺失 / 能力不在本地注册表 ⇒ WARN 并跳过（客户机上不能因为工具不在就判死）。
+const INSTALL_JSON = process.env.ARGENT_INSTALL_JSON || join(DSH_HOME, 'argent', 'install.json')
+const CAP_PACK = join(REPO, 'scripts', 'capability_pack.py')
+const packLines = []   // [['PASS'|'WARN'|'FAIL', 文案]]，报告区统一打印
+
+function checkPackIntegrity() {
+  const line = (tag, msg) => packLines.push([tag, msg])
+  // 与其它检查一致：登记进 problems 参与退出码判定，但由本区自己打印（printed=true 防重复）
+  const record = (level, code, msg, fix) => {
+    add(level, code, msg, fix)
+    problems[problems.length - 1].printed = true
+  }
+  if (!existsSync(INSTALL_JSON)) {
+    const msg = '未找到 install.json（可能未按能力清单安装）'
+    line('WARN', msg)
+    record('warn', 'pkg-install-json-missing', msg,
+      `按能力安装：node install-argent.mjs --api-key <账号 API Key>（或核对 --dsh-home / ARGENT_INSTALL_JSON=${INSTALL_JSON}）`)
+    return
+  }
+  const doc = readInstallJson(INSTALL_JSON)
+  if (!doc) {
+    const msg = `install.json 解析失败：${INSTALL_JSON}`
+    line('WARN', msg)
+    record('warn', 'pkg-install-json-broken', msg, '删除该文件后用安装器重写（它只是装机记录，不是配置）')
+    return
+  }
+  const caps = (Array.isArray(doc.capabilities) ? doc.capabilities : []).filter((c) => c && c.id)
+  line('INFO', `套餐 ${doc.plan || '未记录'}｜能力 ${caps.length} 个${doc.installedAt ? `｜安装于 ${doc.installedAt}` : ''}`)
+  if (!caps.length) {
+    line('WARN', '装机清单里没有能力（免费版或服务端清单为空）—— 跳过包完整性核对')
+    return
+  }
+  // 能力包工具缺失：只 WARN。**但装机记录里若已有逐文件 sha，照样核对**
+  // （降级不等于放弃：客户机上没有 python 时，至少还能发现"文件被改过"）
+  const hasTool = existsSync(CAP_PACK)
+  if (!hasTool) {
+    const msg = `未找到能力包工具 ${CAP_PACK}（按装机记录核对，跳过本地包清单）`
+    line('WARN', msg)
+    record('warn', 'pkg-tool-missing', msg, '确认仓库完整（scripts/capability_pack.py 应随 git 分发）')
+  }
+  for (const c of caps) {
+    const id = String(c.id)
+    const recorded = c.files && typeof c.files === 'object' ? c.files : {}
+    const useRecorded = Object.keys(recorded).length > 0
+    const d = hasTool ? describeCapability(REPO, id) : { ok: false, error: '未找到能力包工具' }
+    if (!d.ok && !useRecorded) {
+      const msg = `能力 ${id} 包清单取不到（${d.error}）`
+      line('WARN', msg)
+      record('warn', 'pkg-describe-failed', msg, `手工核对：python3 ${CAP_PACK} --describe ${id}`)
+      continue
+    }
+    if (!d.ok) line('INFO', `能力 ${id} 包清单取不到（${d.error}）—— 退回按装机记录核对`)
+    const expected = useRecorded ? recorded : (d.integrity || {})
+    const basis = useRecorded ? '装机记录' : '本地能力包清单'
+    // 整包 sha256 缺失是**独立**的一档（2026-09-21 修）：早前它被塞在"文件清单为空"分支里，
+    // 而目录展开后每个能力都有逐文件 sha ⇒ 这个告警变成**不可达**（服务端未填 sha 的真实现场反而看不见）。
+    let shaMissing = false
+    if (String(c.sha256 ?? '') === '') {
+      const msg = `能力 ${id} 未提供 sha256（服务端清单待发布流程填充）`
+      line('WARN', msg)
+      record('warn', 'pkg-sha256-missing', msg, '服务端清单填充 sha256 后重跑安装器刷新 install.json')
+      shaMissing = true
+    }
+    if (!Object.keys(expected).length) {
+      if (!shaMissing) {
+        const msg = `能力 ${id} 无可核对的文件清单（装机记录无 files，本地包清单也为空）`
+        line('WARN', msg)
+        record('warn', 'pkg-no-filelist', msg, `python3 ${CAP_PACK} --describe ${id}`)
+      }
+      continue
+    }
+    let failed = 0
+    let empty = 0
+    let projected = 0
+    for (const [rel, want] of Object.entries(expected)) {
+      if (!want) { empty++; continue }
+      // ⑤ 同源：`--from-packs` 装出来的记录里含**包内注册表投影**（`PACK.json#sourceRegistry`），
+      // 而落盘时它按"目标机覆盖 ⇒ 保留 / 缺本包条目 ⇒ 合并"处理（`installPackFiles()` 的既有语义）
+      // ⇒ 盘上那份与记录里那份 sha **设计上就不同**。判据用能力清单模块的**同一个**函数
+      // （`isRegistryProjection()`，唯一真源）；否则每次 `--from-packs` 安装后医生都误报 FAIL
+      // `pkg-sha-mismatch`，还给一条走不通的修法（"回退该文件或重跑安装器" —— 重跑还是这份差异）。
+      if (isRegistryProjection(rel, [c])) { projected++; continue }
+      const got = sha16File(resolve(REPO, rel))
+      if (got === null) {
+        failed++
+        const msg = `能力 ${id} 包完整性：${rel} 文件缺失（期望 ${want}）`
+        line('FAIL', msg)
+        record('error', 'pkg-file-missing', msg, `该文件不在当前代码树里（基准＝${basis}）—— 请 git pull 或重跑安装器`)
+      } else if (got !== String(want)) {
+        failed++
+        const msg = `能力 ${id} 包完整性：${rel} sha 不符（期望 ${want} vs 实际 ${got}）`
+        line('FAIL', msg)
+        record('error', 'pkg-sha-mismatch', msg, `文件已被改动/降级（基准＝${basis}）—— 回退该文件或重跑安装器刷新记录`)
+      }
+    }
+    if (failed) continue
+    if (empty) {
+      const msg = `能力 ${id} 有 ${empty} 个文件 sha 为空（未校验）`
+      line('WARN', msg)
+      record('warn', 'pkg-sha-empty', msg, '服务端清单/装机记录补全 sha 后复检')
+      continue
+    }
+    line('PASS', `能力 ${id} v${d.version || c.version || '?'} 包完整性：${Object.keys(expected).length - projected} 个文件 sha 一致（基准＝${basis}）`
+      + (projected ? `；另有 ${projected} 个注册表投影差异按设计跳过（⑤）` : ''))
+  }
+}
+checkPackIntegrity()
+
+// ── 报告 ──────────────────────────────────────────────────────────────
+// --fix 能自动处理的 code；不在集合里的 error 修完仍然存在 ⇒ 必须非零退出（门禁不可被绕过）
+const AUTO_FIXABLE = new Set(['dep-missing', 'dep-foreign', 'row-retired', 'row-duplicate', 'row-required-missing'])
+const errs = problems.filter((p) => p.level === 'error')
+const warns = problems.filter((p) => p.level === 'warn')
+const remaining = FIX ? errs.filter((p) => !AUTO_FIXABLE.has(p.code)) : errs
+/** 报告行：人类模式逐行打印；`--json` 模式原样放进 JSON（升级器读它做摘要，不再解析文本）。 */
+const reportLines = []
+const say = (line = '') => reportLines.push(line)
+say(`[doctor] profile = ${PROFILE_DIR}`)
+say(`[doctor] 规范插件根 = ${CANONICAL_ROOTS[0]}`)
+say(`[doctor] 备份根 = ${BACKUP_DIR}`)
+say(`[doctor] 包完整性 = ${INSTALL_JSON}`)
+say(`[doctor] 模式 = ${FIX ? '--fix（自动修复）' : '只报告（未给 --fix）'}`
+  + `${FIX && IS_REAL_PROFILE && ALLOW_PACKAGE_MANAGER ? ' + 包管理器已显式授权（--allow-package-manager）' : ''}`)
+for (const [tag, msg] of packLines) say(`  [${tag}] ${msg}`)
+if (problems.length === 0) {
+  say('  ✅ 体检通过：依赖路径规范、无重复挂载、无退役行、必需行齐全')
+} else {
+  for (const p of problems) {
+    if (p.printed) continue   // 包完整性一节已自行打印（[PASS]/[WARN]/[FAIL]），避免重复
+    const mark = FIX && AUTO_FIXABLE.has(p.code) && p.level === 'error' ? '🔧已修' : (p.level === 'error' ? '✗' : '⚠')
+    say(`  ${mark} [${p.code}] ${p.msg}\n      → ${p.fix}`)
+  }
+}
+for (const f of fixes) say(`  🔧 ${f}`)
+// 空转抑制：内容与现文件逐字节相同 ⇒ 不写、不产备份（如实打印，别让"没动"看起来像"动了"）
+for (const s of skippedWrites) say(`  ⏭ 内容无变化，跳过备份：${s}`)
+
+// 启动冒烟：人类模式随报告打印；JSON 模式只把结论塞进 JSON（否则 stdout 会掺进非 JSON 文本）
+let bootcheck = null
+if (RUN_BOOTCHECK && (FIX || problems.length === 0)) {
+  try {
+    const out = execFileSync('node', [join(REPO, 'scripts', 'plugin-bootcheck.mjs')], { encoding: 'utf8', timeout: 600000 })
+    const line = (out.split('\n').find((l) => l.includes('PASS') || l.includes('FAIL')) || '(无结论)').trim()
+    bootcheck = { ok: line.includes('PASS'), line }
+    say(`[doctor] 启动冒烟（plugin-bootcheck）：${line}`)
+  } catch (error) {
+    const line = String(error.stdout || error.message).split('\n').slice(-4).join(' | ')
+    bootcheck = { ok: false, line }
+    say(`[doctor] 启动冒烟（plugin-bootcheck）：✗ ${line}`)
+  }
+}
+
+if (errs.length > 0 && !FIX) {
+  say(`\n[doctor] 发现 ${errs.length} 个致命问题、${warns.length} 个警告 —— 加 --fix 自动修复，或按上面提示人工处理`)
+}
+if (remaining.length > 0 && FIX) {
+  say(`\n[doctor] 仍有 ${remaining.length} 个问题无法自动修复（${remaining.map((p) => p.code).join(', ')}）——请按提示人工处理`)
+}
+const exitCode = ((errs.length > 0 && !FIX) || remaining.length > 0 || (bootcheck && !bootcheck.ok)) ? 1 : 0
+
+if (JSON_OUT) {
+  console.log(JSON.stringify({
+    ok: exitCode === 0,
+    profile: PROFILE_DIR,
+    realProfile: IS_REAL_PROFILE,
+    backupDir: BACKUP_DIR,
+    callerLog: join(BACKUP_DIR, 'doctor-callers.jsonl'),
+    fix: FIX,
+    allowPackageManager: ALLOW_PACKAGE_MANAGER,
+    problems,
+    fixPlan,
+    fixes,
+    skippedWrites,
+    errCodes: errs.map((p) => p.code),
+    warnCodes: warns.map((p) => p.code),
+    bootcheck,
+    reportLines,
+  }, null, 2))
+  process.exit(exitCode)
+}
+for (const line of reportLines) console.log(line)
+process.exit(exitCode)