@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/lib/dsh-web-probe.mjs

@@ -0,0 +1,214 @@
+/**
+ * dsh-web-probe.mjs —— 「运行中的 dsh web 到底带了哪些 --trusted-host」的唯一判据（2026-10-01）
+ *
+ * ## 为什么单独抽一个模块
+ * `scripts/dsh-restart.sh` 与 `scripts/dsh-remote-check.sh` 都要回答同一个问题：
+ * **launchd 里声明的 trusted-host，运行中的进程真的采用了吗？**（改了 plist ≠ 生效：
+ * `kickstart -k` 会用缓存的旧定义，2026-09-22 实测新地址继续 403。）
+ *
+ * 之前两处各写一遍、而且都只看**一个**进程，实测两类假警报：
+ *   ① **只看第一个匹配**（`head -1`）⇒ dsh web 是**父子两段**：
+ *      启动器 `node scripts/dsh-web-launch.mjs web …`（做鉴权/围栏参数拼装）
+ *      + 真正的服务 `node …/@deepseek-ai/dsh/lib/bin.js web …`（采用参数的那个）。
+ *      父进程带了、子进程没带（或反之）时，单看一个进程必然误判。
+ *   ② **正则锚在 `^node `**：launchd 起的进程 argv[0] 是**绝对路径**（`/opt/homebrew/bin/node`）
+ *      ⇒ `^node ` 永不匹配，`RUN_ARGS` 恒为空 ⇒ 每个地址都被报成"未采用"（实测假警报）。
+ *
+ * 现在的判据只有一条：**收集全部 dsh web 相关进程，取 trusted-host 并集**，再与期望值比对。
+ * 「并集」在语义上是对的 —— 整个服务栈采用了的地址，就是这两段进程里出现过的地址。
+ *
+ * ## 判据的边界（宁可不报，也不误报）
+ * · 只认 argv[0] 是 `node`（基名）的进程 ⇒ **调用本脚本的那个 bash 命令行**（命令行文本里
+ *   恰好含 "dsh web" 字样）不会被算进来（2026-09-29 踩过的那个假阳性）；
+ * · 认不出任何 dsh web 进程 ≠ "没采用"：那是 **not-running / probe-failed**，分开报，
+ *   绝不打印空白的"进程="让人误解（2026-09-30 用户实际遇到的输出）。
+ *
+ * ## 用法
+ * ```bash
+ * node scripts/lib/dsh-web-probe.mjs --want "10.126.126.2:3080 10.126.126.1:3080"
+ * node scripts/lib/dsh-web-probe.mjs --want "…" --json          # 机器可读
+ * node scripts/lib/dsh-web-probe.mjs --want "…" --ps-file fix.txt  # 夹具（测试用，不跑真 ps）
+ * ```
+ * 退出码：0 通过（含"期望值为空 ⇒ 无需核对"）｜ 1 真的缺失（唯一该告警的情形）
+ *          ｜ 2 没有运行中的 dsh web 进程 ｜ 3 探测失败（ps 跑不了）
+ */
+import { spawnSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+
+/** 地址形状（`ip:port`）—— plist 与进程参数都用它。 */
+export const HOST_RE = /^\d{1,3}(?:\.\d{1,3}){3}:\d+$/
+
+/** 进程种类：launcher = 启动器（脚本）；web = 真正跑服务的 dsh 子进程。 */
+export const PROC_KINDS = ['launcher', 'web']
+
+const str = (v, d = '') => (v === null || v === undefined ? d : String(v))
+
+/** argv[0] 的基名是不是 node（launchd 起的 argv[0] 是**绝对路径**，形如 `<node 前缀>/bin/node`）。 */
+function isNodeArgv0(argv0) {
+  const b = str(argv0).split('/').pop().toLowerCase()
+  return b === 'node' || b === 'node.exe'
+}
+
+/**
+ * 这个命令行是不是「dsh web 相关进程」？返回 `'launcher' | 'web' | ''`。
+ * 刻意只认三个形态（宁可漏认、不可把无关进程算进来）：
+ *   · `<…>/dsh-web-launch.mjs web …`  —— 启动器（父）
+ *   · `<…>/dsh/lib/bin.js web …`      —— 真正的服务（子；`@deepseek-ai/dsh` 的 bin）
+ *   · `dsh web …`                     —— 有人直接敲 CLI 的形态
+ */
+export function classifyDshWeb(command) {
+  const c = str(command)
+  if (/(?:^|[/\s])dsh-web-launch\.mjs(?:\s|$)/.test(c)) return 'launcher'
+  if (/dsh\/(?:lib\/)?bin\.js\s+web(?:\s|$)/.test(c)) return 'web'
+  if (/(?:^|\s)dsh\s+web(?:\s|$)/.test(c)) return 'web'
+  return ''
+}
+
+/** 从一个命令行里抽出全部 `--trusted-host` 取值（`--trusted-host X` 与 `--trusted-host=X` 都认）。 */
+export function extractTrustedHosts(command) {
+  const out = []
+  const c = str(command)
+  const re = /--trusted-host(?:=|\s+)([^\s'"]+)/g
+  let m
+  while ((m = re.exec(c)) !== null) {
+    const v = m[1].replace(/^['"]|['"]$/g, '')
+    if (HOST_RE.test(v)) out.push(v)
+  }
+  return out
+}
+
+/**
+ * 解析 `ps -ww -Ao pid=,ppid=,command=` 的输出（`ps` 的默认格式：pid、ppid 各占一列，
+ * 之后整行都是 command）。夹具测试直接喂文本，不跑真 ps。
+ * 返回**全部**进程行（含无关进程），过滤在 {@link pickDshWebProcs} 里做 —— 两件事分开才好测。
+ */
+export function parsePsOutput(text) {
+  const rows = []
+  for (const line of str(text).split('\n')) {
+    const m = /^\s*(\d+)\s+(\d+)\s+(.*\S)\s*$/.exec(line)
+    if (!m) continue
+    rows.push({ pid: Number(m[1]), ppid: Number(m[2]), command: m[3] })
+  }
+  return rows
+}
+
+/** 从进程行里挑出 dsh web 相关进程（argv[0] 必须是 node），带 kind 与该进程自己带的 trusted-host。 */
+export function pickDshWebProcs(rows, { selfPid = 0 } = {}) {
+  const out = []
+  for (const r of rows) {
+    if (selfPid && r.pid === selfPid) continue          // 探测脚本自己：不算
+    const argv0 = str(r.command).split(/\s+/)[0] || ''
+    if (!isNodeArgv0(argv0)) continue                   // bash -c / grep / 编辑器 … 一律不算
+    const kind = classifyDshWeb(r.command)
+    if (!kind || !PROC_KINDS.includes(kind)) continue
+    out.push({ pid: r.pid, ppid: r.ppid, kind, command: r.command, hosts: extractTrustedHosts(r.command) })
+  }
+  // 先启动器后服务（读起来顺；pid 升序兜底），便于排障时按父子顺序看
+  out.sort((a, b) => (a.pid - b.pid))
+  return out
+}
+
+/**
+ * 核心判据：**全部相关进程的 trusted-host 并集** vs 期望值。
+ * @returns {{state:'ok'|'missing'|'not-running'|'probe-failed', want:string[], union:string[],
+ *            missing:string[], procs:Array, detail:string}}
+ *   · `ok`          —— 期望值都在并集里（或期望值为空 = 无需核对）
+ *   · `missing`     —— **真的没采用**（唯一该告警的情形）
+ *   · `not-running` —— 一个 dsh web 进程都没找到（未运行 / 进程名不符）
+ *   · `probe-failed`—— ps 跑不了（探测失败）——与"没采用"是两回事
+ */
+export function probeTrustedHosts(psText, wantHosts, opts = {}) {
+  const want = (Array.isArray(wantHosts) ? wantHosts : str(wantHosts).split(/\s+/))
+    .map((h) => str(h).trim()).filter(Boolean)
+  const rows = parsePsOutput(psText)
+  const procs = pickDshWebProcs(rows, opts)
+  const union = [...new Set(procs.flatMap((p) => p.hosts))]
+  const missing = want.filter((h) => !union.includes(h))
+  if (!procs.length) {
+    return {
+      state: 'not-running', want, union, missing: [], procs,
+      detail: want.length
+        ? `没找到运行中的 dsh web 进程（未运行，或进程名/启动方式与判据不符）⇒ **无法核对** ${want.join(' ')}；这不是「未采用」`
+        : '没找到运行中的 dsh web 进程（未运行）',
+    }
+  }
+  if (missing.length) {
+    return {
+      state: 'missing', want, union, missing, procs,
+      detail: `运行中的 dsh web 进程**确实没带**这些 trusted-host：${missing.join(' ')}`,
+    }
+  }
+  return {
+    state: 'ok', want, union, missing: [], procs,
+    detail: want.length
+      ? `${procs.length} 个 dsh web 进程的 trusted-host 并集已覆盖 plist 声明的全部地址`
+      : 'plist 未声明 trusted-host（无需核对）',
+  }
+}
+
+/** 真跑一次 `ps`（`-ww` = 不截断命令行，macOS/Linux 都认）。 */
+export function runPs() {
+  const r = spawnSync('ps', ['-ww', '-Ao', 'pid=,ppid=,command='], { encoding: 'utf8', timeout: 10000 })
+  if (r.error || r.status !== 0) {
+    return { ok: false, text: '', error: str(r.error && r.error.message) || `ps 退出码 ${r.status}` }
+  }
+  return { ok: true, text: str(r.stdout), error: '' }
+}
+
+/** 人读输出（两个脚本共用同一套文案，避免第二份口径）。 */
+export function formatProbe(res, { prefix = '   ' } = {}) {
+  const lines = []
+  const procs = res.procs || []
+  if (res.state === 'ok') {
+    lines.push(`${prefix}✅ trusted-host 核对通过：${(res.want || []).join(' ') || '（plist 未声明）'}`)
+    for (const p of procs) {
+      lines.push(`${prefix}   · pid ${p.pid}（${p.kind === 'launcher' ? '启动器' : 'dsh web 主体'}）：${p.hosts.join(' ') || '（无 --trusted-host）'}`)
+    }
+    return lines.join('\n')
+  }
+  if (res.state === 'missing') {
+    lines.push(`${prefix}❌ ${res.detail}`)
+    lines.push(`${prefix}   期望（plist）：${(res.want || []).join(' ')}`)
+    lines.push(`${prefix}   实际并集（${procs.length} 个进程）：${(res.union || []).join(' ') || '（空）'}`)
+    for (const p of procs) {
+      const miss = (res.want || []).filter((h) => !p.hosts.includes(h))
+      lines.push(`${prefix}   · pid ${p.pid}（${p.kind === 'launcher' ? '启动器' : 'dsh web 主体'}）：`
+        + `${p.hosts.join(' ') || '（无 --trusted-host）'}${miss.length ? `  ← 缺 ${miss.join(' ')}` : '  ← 该进程已带全'}`)
+    }
+    lines.push(`${prefix}   ↳ 说明 launchd 仍在用旧定义；可再跑一次 dsh-restart.sh，或用 bash scripts/dsh-remote-check.sh 复核`)
+    return lines.join('\n')
+  }
+  // not-running / probe-failed：**明确**说清"没核对上"，不许留空白
+  lines.push(`${prefix}⚠️ ${res.detail}`)
+  return lines.join('\n')
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────
+function main(argv) {
+  const args = argv.slice(2)
+  const val = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : '' }
+  const want = val('--want')
+  const psFile = val('--ps-file')
+  const asJson = args.includes('--json')
+  const wantList = want.split(/\s+/).filter(Boolean)
+  // plist 里没有 trusted-host ⇒ 没有可核对的东西：直接通过（不要因为"没找到进程"报警）
+  if (!wantList.length) {
+    const res = { state: 'ok', want: [], union: [], missing: [], procs: [], detail: '期望值为空（plist 未声明 trusted-host）⇒ 无需核对' }
+    process.stdout.write(asJson ? `${JSON.stringify(res)}\n` : `${formatProbe(res)}\n`)
+    return 0
+  }
+  const ps = psFile ? { ok: true, text: readFileSync(psFile, 'utf8'), error: '' } : runPs()
+  if (!ps.ok) {
+    const res = { state: 'probe-failed', want: wantList, union: [], missing: [], procs: [], detail: `ps 跑不了（${ps.error}）⇒ 无法核对运行参数` }
+    process.stdout.write(asJson ? `${JSON.stringify(res)}\n` : `${formatProbe(res)}\n`)
+    return 3
+  }
+  const res = probeTrustedHosts(ps.text, wantList, { selfPid: process.pid })
+  process.stdout.write(asJson ? `${JSON.stringify(res)}\n` : `${formatProbe(res)}\n`)
+  if (res.state === 'missing') return 1
+  if (res.state === 'not-running') return 2
+  return 0
+}
+
+const invokedDirectly = process.argv[1] && process.argv[1].endsWith('dsh-web-probe.mjs')
+if (invokedDirectly) process.exit(main(process.argv))

package/engine/scripts/lib/is-direct-run.mjs

@@ -0,0 +1,61 @@
+/**
+ * is-direct-run.mjs —— **"本文件是否被直接执行"的唯一判据**（2026-10-04）
+ *
+ * ══════════════════════════════════════════════════════════════════════════
+ * 一、为什么需要它（一个**静默**的坑：脚本"跑了"却什么都没发生）
+ * ══════════════════════════════════════════════════════════════════════════
+ * 本仓库的 CLI 脚本几乎都是"可当模块 import（给测试用纯函数）+ 可直接执行（跑主逻辑）"两用形态，
+ * 于是每个文件末尾都有一道入口守卫。历史上它被写成四种形态，其中三种在**符号链接路径**下**假否定**：
+ *
+ * | 形态 | 软链下 | 说明 |
+ * |---|---|---|
+ * | `import.meta.url === pathToFileURL(process.argv[1]).href` | ❌ 假否定 | `argv[1]` 是**逻辑**路径（软链），`import.meta.url` 是 Node **已 realpath** 的物理路径 |
+ * | ``import.meta.url === `file://${process.argv[1]}` `` | ❌ 假否定 | 同上，且没做 URL 编码（路径含空格/中文时更早出错） |
+ * | `resolve(argv[1]) === resolve(fileURLToPath(import.meta.url))` | ❌ 假否定 | `resolve()` 只做 `..`/相对路径归一，**不解析软链** |
+ * | `import.meta.url.endsWith(basename(argv[1]))` | ⚠️ 碰巧能跑 | 但判据退化成"文件名相同"（同名文件即假肯定） |
+ *
+ * 为什么"软链路径"在本项目是**常态而非边角**：macOS 上 `/tmp` → `/private/tmp`、
+ * `/var/folders/...` → `/private/var/folders/...`（`mktemp -d` 的默认落点！），
+ * 而 Node 对**主模块**默认做 realpath（除非 `--preserve-symlinks-main`）
+ * ⇒ 任何"在 /tmp（逻辑路径）下执行脚本"的场景都会命中，**表现为脚本静默不干活**（没有报错、没有输出、
+ * 退出码 0）—— 2026-10-04 实测：升级器的夹具里 CLI 就是这么静默不跑的。
+ *
+ * 正确判据 = **两边都归一成物理路径再比**（`realpathSync`）；比不了（文件不存在 / 权限 / 已删）⇒ `false`
+ * （"不确定"必须落到"不执行主逻辑"，绝不落到"猜着执行"）。
+ *
+ * ## 二、唯一实现（⛔ 不要在每个脚本里各写一份）
+ * 入口守卫是**判据**：四份实现就是四种行为，而它们的差异只在软链下才暴露（最难复现的那类）。
+ * 故抽到本文件，所有 `scripts/*.mjs` 的 CLI 一律 `import { isDirectRun } from './lib/is-direct-run.mjs'`。
+ * 回归：`scripts/tests/is-direct-run.test.mjs`（纯夹具：mkdtemp 里造软链，证明"修复前静默、修复后执行"）。
+ *
+ * 用法：
+ * ```js
+ * import { isDirectRun } from './lib/is-direct-run.mjs'   // scripts/lib 下则 './is-direct-run.mjs'
+ * if (isDirectRun(import.meta.url)) main()      // ⚠️ 必须显式传 import.meta.url（见下）
+ * ```
+ *
+ * ⚠️ **第一个参数是必填的**：缺省值只能是"本 helper 自己的 URL"，那会让判据**静默变错**
+ * （`if (isDirectRun()) main()` ⇒ 拿 helper 的路径去比调用方的 `argv[1]` ⇒ 恒 false ⇒ CLI 又不跑了）。
+ * 2026-10-04 实测踩到过一次，故缺参**直接抛错**（响亮，绝不静默）。
+ *
+ * @param {string} importMetaUrl 调用方的 `import.meta.url`（**必填**）
+ * @param {string} [argv1]       调用方的 `process.argv[1]`（缺省 `process.argv[1]`）
+ * @returns {boolean} 真的是"直接执行"才 `true`
+ */
+import { realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+export function isDirectRun(importMetaUrl, argv1 = process.argv[1]) {
+  if (typeof importMetaUrl !== 'string' || !importMetaUrl) {
+    throw new TypeError('isDirectRun(importMetaUrl) 必须显式传 import.meta.url —— '
+      + '缺参会退化成"拿 helper 自己的 URL 比调用方的 argv[1]"，判据静默变错（入口守卫恒 false）')
+  }
+  if (!argv1) return false
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(importMetaUrl))
+  } catch {
+    return false      // 归一失败（不存在/无权限/已删）⇒ 不执行主逻辑（fail-closed）
+  }
+}
+
+export default isDirectRun

package/engine/scripts/lib/patch-compose.mjs

@@ -0,0 +1,241 @@
+/**
+ * cordis profile 组合编辑（**唯一真源**，纯字符串函数、可离线测试）。
+ *
+ * profile 组合是"多来源手工拼装"的（bundles + cordis.patch.yml + dependencies +
+ * node_modules），而 `cordis.patch.yml` 是**会把服务写崩**的地方：
+ * 重复挂载 ⇒ `duplicate loader entry id` ⇒ dsh web 启动即失败（KeepAlive 下 crash loop）。
+ * 所以这段编辑逻辑必须能被离线夹具反复验证，不能只活在升级器的内联代码里。
+ *
+ * 三条规则（2026-09-28 客户机 P3 实测逐条踩过）：
+ *   ① **bundle 层插件**（如 argent-skin）：patch 行一律摘掉 —— 它由 `dsh.profile.bundles`
+ *      加载，patch 层再来一行就是重复挂载。⚠️ 这条必须**先于**「在目标组合里就保留」判断，
+ *      否则目标组合包含它时会被反复补回 patch 层（升级器补、doctor 删 ⇒ 乒乓，实测）。
+ *   ② **退役行 / 悬挂行**（源码已删、包也没装）：摘掉，否则启动时
+ *      `failed to apply loader entry`（doctor 报 row-pkg-missing）。
+ *   ③ **缺失的目标插件**：补一行（新装机器需要）。
+ *
+ * 幂等：把输出再喂回来必须一字不变。
+ *
+ * ── 2026-10-12 P1-3 追加：`- insert:` 块的**唯一渲染器**与**空块清理**（审计 §C.1 #1）─────────
+ * `- insert:` 后面一个子项都没有时，它在 YAML 里就是 `insert: null` —— 0.2 宿主每次启动都报一条
+ * `patch: id is required for non-insert patches`（未来 rc 可能升级成硬错）。此前"渲染"这件事在
+ * 仓库里有**两份**（本文件的 `composeNew` 内联 + `install-argent.mjs#patchSelfcheck` 的局部
+ * `insertBlock`），两份都**不考虑空数组** ⇒ 真实 profile 里留下了空块（本机实测：`web` 1 条 /
+ * `rows-trial` 1 条 / `headless` 0 / `tui` 0；⚠️ 审计原记的 `5/4/1/0` 是 `- insert:` 的**总条数**，
+ * 不是空块数）。
+ * 现在渲染收口到 {@link renderInsertBlock}（空 ⇒ 空串），清理收口到
+ * {@link stripEmptyInsertBlocks}（只删"真空白"的块，⛔ 不碰有子项的）。
+ */
+
+/**
+ * 把「目标组合」条目归一到 `{id, name}`（**唯一归一化实现**）。
+ *
+ * 为什么目标可以是两种形态（W9，2026-10-12）：插件发 npm 后，组合条目的
+ * **id**（`argent-core`）与 **name**（`@whyshu/argent-core`）不再是同一个串
+ * （口径见 `scripts/lib/plugin-packages.mjs`）。老调用方/夹具传纯字符串 ⇒
+ * id 与 name 同值（逐字保留老语义，⛔ 不"善意补 scope"）。
+ * @param {Iterable<string|{id:string,name?:string}>} items
+ * @returns {Array<{id: string, name: string}>}
+ */
+export function normalizeTargetRows(items) {
+  const out = []
+  for (const it of items ?? []) {
+    if (it === null || it === undefined) continue
+    if (typeof it === 'string') { out.push({ id: it, name: it }); continue }
+    const id = String(it.id ?? '')
+    if (!id) continue
+    out.push({ id, name: String(it.name ?? id) })
+  }
+  return out
+}
+
+/**
+ * @param {object} o
+ * @param {string} o.text   现有 cordis.patch.yml 内容
+ * @param {Array<string|{id:string,name?:string}>} o.target 目标组合（patch 层应存在的插件）
+ * @param {Iterable<string>} [o.bundleLayer] 由 bundles 加载、不该出现在 patch 层的插件
+ * @param {Iterable<string>} [o.retired]     已退役插件（patch 行要摘掉）
+ * @param {(plugin: string) => boolean} [o.dangling] 悬挂判定（包与源码都不存在）
+ * @param {string} [o.today] 追加段落用的日期（测试注入）
+ * @returns {{ text: string, changed: boolean, dropped: string[], migrated: string[], added: string[], renamed: Array<{id:string,from:string,to:string}> }}
+ */
+export function composeFix({ text, target, bundleLayer = [], retired = [], dangling = () => false, today = null }) {
+  const rows = normalizeTargetRows(target)
+  const canonicalName = new Map(rows.map((r) => [r.id, r.name]))
+  const targetIds = rows.map((r) => r.id)
+  const inTarget = new Set(targetIds)
+  const inBundleLayer = new Set(bundleLayer)
+  const isRetired = retired instanceof Set ? retired : new Set(retired)
+  const lines = String(text ?? '').split('\n')
+  const kept = []
+  const seen = new Set()
+  const dropped = []
+  const migrated = []
+  const renamed = []
+
+  let i = 0
+  while (i < lines.length) {
+    const m = /^(\s*)- id: (argent-[\w-]+)\s*$/.exec(lines[i])
+    if (!m) { kept.push(lines[i]); i++; continue }
+    const plugin = m[2]
+    let j = i + 1
+    let nameLine = -1
+    if (j < lines.length && /^\s+name:/.test(lines[j])) { nameLine = j; j++ } // 吃掉紧随的 name 行
+    if (inBundleLayer.has(plugin)) {
+      migrated.push(plugin) // 规则①：bundle 层加载 ⇒ patch 行必摘
+    } else if (inTarget.has(plugin)) {
+      kept.push(lines[i])
+      // 规则④（W9）：目标行的 `name:` 归一到**规范包名**（存量裸名 ⇒ npm 名；幂等）。
+      // 这是**迁移**而不是"补一行"：id 不动、只改 name ⇒ 组合 id 稳定、依赖图可换名字。
+      const want = canonicalName.get(plugin)
+      const hasOwn = want !== undefined
+      if (nameLine >= 0) {
+        const cur = (/^\s+name:\s*['"]?([^'"]*)['"]?\s*$/.exec(lines[nameLine]) || [])[1]
+        if (hasOwn && cur !== want) {
+          const indent = lines[nameLine].match(/^\s*/)[0]
+          kept.push(`${indent}name: '${want}'`)
+          renamed.push({ id: plugin, from: cur ?? '', to: want })
+        } else {
+          kept.push(lines[nameLine])
+        }
+      } else if (hasOwn) {
+        const indent = lines[i].match(/^\s*/)[0]
+        kept.push(`${indent}  name: '${want}'`)
+        renamed.push({ id: plugin, from: '(缺失)', to: want })
+      }
+      seen.add(plugin)
+    } else if (isRetired.has(plugin) || dangling(plugin)) {
+      dropped.push(plugin) // 规则②
+    } else {
+      for (let k = i; k < j; k++) kept.push(lines[k]) // 未知/非目标：保留（不越权）
+    }
+    i = j
+  }
+
+  // 规则③：缺的目标插件补上；已在 bundle 层的**不补**（否则又变重复挂载）
+  const missing = targetIds.filter((p) => !seen.has(p) && !inBundleLayer.has(p))
+  if (missing.length) {
+    const day = today || new Date().toISOString().slice(0, 10)
+    kept.push('')
+    kept.push(`# ── v0.9 完整升级自动补齐（${day}）──`)
+    kept.push(renderInsertBlock(missing.map((id) => ({ id, name: canonicalName.get(id) ?? id }))))   // 唯一渲染器（missing 非空 ⇒ 必产出块）
+  }
+
+  const changed = dropped.length > 0 || migrated.length > 0 || missing.length > 0 || renamed.length > 0
+  if (!changed) {
+    // 修复侧（2026-10-12 P1-3）：本轮**没有**编辑，但文件里可能**已经**有空 `- insert:`
+    // （历史安装器/升级器留下的）⇒ 顺手清掉。清不掉任何东西时**逐字回原文**（⛔ 不做无谓重写，
+    // 否则"没改动也重写"会破坏调用方的 mtime/幂等判据）。
+    const r = stripEmptyInsertBlocks(String(text ?? ''))
+    return { text: r.removed ? r.text : String(text ?? ''), changed: r.removed > 0, dropped, migrated, added: missing, removedEmptyInserts: r.removed, renamed }
+  }
+  const out = kept.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n'
+  // ⚠️ **编辑本身可能把某个 `- insert:` 的最后一个子项摘掉**（实测 2026-10-12：bundle 层迁移
+  //    摘掉 `argent-skin` 之后，那个 `- insert:` 就成了空块 ⇒ 0.2 宿主启动告警）。
+  //    ⇒ 写回前一律过一遍清理器（幂等；没有空块时**逐字节不回归**）。
+  const stripped = stripEmptyInsertBlocks(out)
+  return { text: stripped.text, changed: true, dropped, migrated, added: missing, removedEmptyInserts: stripped.removed, renamed }
+}
+
+/**
+ * 把 patch 里**已知插件行**的 `name:` 归一到规范包名（W9 迁移；**幂等**）。
+ *
+ * 与 {@link composeFix} 的分工：`composeFix` 管"目标组合该有哪些行"，本函数只管
+ * "已存在的行名字对不对" —— 安装器（`patchSelfcheck`）只做后者，⛔ 不引入第二份组合判据。
+ * 与 `composeFix` 的规则④**同一语义**（id 不动、只改 name），实现各自独立是因为两者的
+ * 输入不同（前者是"目标表 + 保留/摘除判据"，后者是"所有已知 id 一律归一"）。
+ *
+ * `nameOf(id)` 返回 `undefined`/`''` ⇒ **该行原样保留**（未知插件不越权）。
+ * @param {{text: string, nameOf: (id: string) => (string|undefined)}} o
+ * @returns {{text: string, renamed: Array<{id:string,from:string,to:string}>, changed: boolean}}
+ */
+export function migratePluginRowNames({ text, nameOf }) {
+  const lines = String(text ?? '').split('\n')
+  const out = []
+  const renamed = []
+  let i = 0
+  while (i < lines.length) {
+    const m = /^(\s*)- id: (argent-[\w-]+)\s*$/.exec(lines[i])
+    if (!m) { out.push(lines[i]); i += 1; continue }
+    const id = m[2]
+    const indent = m[1]
+    out.push(lines[i])
+    i += 1
+    let want = ''
+    try { want = String(nameOf(id) ?? '') } catch { want = '' }
+    if (i < lines.length && /^\s+name:/.test(lines[i])) {
+      const cur = (/^\s+name:\s*['"]?([^'"]*)['"]?\s*$/.exec(lines[i]) || [])[1] ?? ''
+      if (want && cur !== want) {
+        out.push(`${lines[i].match(/^\s*/)[0]}name: '${want}'`)
+        renamed.push({ id, from: cur, to: want })
+      } else {
+        out.push(lines[i])
+      }
+      i += 1
+      continue
+    }
+    if (want) { out.push(`${indent}  name: '${want}'`); renamed.push({ id, from: '(缺失)', to: want }) }
+  }
+  return { text: out.join('\n'), renamed, changed: renamed.length > 0 }
+}
+
+/**
+ * 渲染一个 `- insert:` 块（**唯一实现**；`composeNew` 与 `install-argent.mjs` 都用它）。
+ *
+ * ⚠️ **空数组 ⇒ 返回空串**（2026-10-12 P1-3，审计 §C.1 #1）：一个子项都没有的 `- insert:`
+ * 在 YAML 里是 `insert: null`，0.2 宿主每次启动报一条
+ * `patch: id is required for non-insert patches`。⇒ 调用方据此**不要**把空块写进文件
+ * （`if (!block) …`），而不是"渲染出来再想办法擦掉"。
+ *
+ * @param {Iterable<string|{id:string,name?:string}>} items 要 insert 的条目
+ *   （纯字符串 ⇒ id 与 name 同值，老语义逐字保留；`{id,name}` ⇒ npm 名与组合 id 分开）
+ * @returns {string} `"- insert:\n    - id: X\n      name: 'X'…"`；`items` 为空 ⇒ `''`
+ */
+export function renderInsertBlock(items) {
+  const rows = normalizeTargetRows(items)
+  if (!rows.length) return ''
+  return `- insert:\n${rows.map((r) => `    - id: ${r.id}\n      name: '${r.name}'`).join('\n')}`
+}
+
+
+/**
+ * 清理**空** `- insert:` 条目（修复侧；审计 §C.1 #1）。
+ *
+ * 判据（刻意保守 —— 只删"真空白"的块，⛔ **绝不**碰有子项的 insert）：
+ * 「某行是 `- insert:`（行尾无值）」且「它之后**第一个非空行**不存在（EOF），或缩进 **不比自己深**」。
+ *   · `- insert:` + 空行 + 下一条目 / EOF ⇒ **删**（本机 `web` / `rows-trial` 各 1 条就是这两种形态）；
+ *   · `- insert:` + 更深缩进的子项（含注释）⇒ **留**（哪怕子项只有注释 —— 宁可不动）。
+ *
+ * 幂等：产物再喂进来必须一字不变（第二次跑 `removed === 0`、文本逐字节相同）。
+ * 顺带把 3 个以上连续换行压成 1 个空行（删行留下的空行），同样幂等。
+ *
+ * @param {string} text
+ * @returns {{text: string, removed: number, removedLines: number[]}} `removedLines` = 1-based 行号
+ */
+export function stripEmptyInsertBlocks(text) {
+  const lines = String(text ?? '').split('\n')
+  const kept = []
+  const removedLines = []
+  for (let i = 0; i < lines.length; i += 1) {
+    const m = /^(\s*)-\s*insert:\s*$/.exec(lines[i])
+    if (m) {
+      const indent = m[1].length
+      let j = i + 1
+      while (j < lines.length && lines[j].trim() === '') j += 1   // 跳过空行
+      const next = j < lines.length ? lines[j] : undefined
+      const nextIndent = next === undefined ? -1 : next.match(/^\s*/)[0].length
+      const hasChild = next !== undefined && nextIndent > indent
+      if (!hasChild) { removedLines.push(i + 1); continue }
+    }
+    kept.push(lines[i])
+  }
+  return { text: kept.join('\n').replace(/\n{3,}/g, '\n\n'), removed: removedLines.length, removedLines }
+}
+
+/** 生成全新的组合文件内容（首次安装/文件缺失时）。⛔ 目标为空时**不出**空 `- insert:`。 */
+export function composeNew({ target, type, bundleLayer = [] }) {
+  const rows = normalizeTargetRows(target).filter((r) => !bundleLayer.includes(r.id))
+  const block = renderInsertBlock(rows)
+  const head = `# Argent on DSH（v0.9 完整升级生成的目标组合：${type}）\n`
+  return block ? `${head}${block}\n` : head
+}

package/engine/scripts/lib/patch-target.mjs

@@ -0,0 +1,35 @@
+/**
+ * 补丁目标路径重定位（**唯一真源**）。
+ *
+ * 事故（2026-09-28 客户机 P3）：`scripts/patches/*.patch` 是在**开发机**打的，
+ * 头里写死了 `/opt/homebrew/lib/node_modules/@deepseek-ai/...`；客户机 dsh 装在
+ * `~/node/lib/node_modules/` ⇒ 升级器 `existsSync(headerPath)` 恒 false ⇒
+ * 三个 hotfix（含会话毒化加固）**静默跳过**，只打印一行 warn，人不在现场根本看不见。
+ * 现场绕法是 sed 改补丁头，但那会让工作区变脏（升级器预检直接拒绝跑）。
+ *
+ * 正解：头里 `@deepseek-ai/` 之后的部分是**包内相对路径**，与机器无关；
+ * 拼到当前机器的 scope 上即可。本函数据此重定位，并对"头里不是 scope 内文件"
+ * 与"本机确实缺该文件"两种情况分别回落，避免误伤。
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+const MARKER = '@deepseek-ai/'
+
+/**
+ * @param {string} header 补丁头里的路径（`+++ ` 行）
+ * @param {string} scopeDir 当前机器的 `@deepseek-ai` 目录
+ * @param {(p: string) => boolean} exists 存在性判定（测试可注入）
+ * @returns {string} 实际应当打补丁的目标文件路径；无法解析时返回 ""
+ */
+export function relocatePatchTarget(header, scopeDir, exists = existsSync) {
+  const h = (header || '').trim()
+  if (!h) return ''
+  const idx = h.lastIndexOf(MARKER)
+  if (idx === -1) return h // 非 scope 内文件（如 /tmp/xxx.orig 之类）⇒ 原样交给调用方判断
+  const candidate = join(scopeDir, h.slice(idx + MARKER.length))
+  if (exists(candidate)) return candidate
+  // 回落：头里那条路径在本机**恰好**存在（例如仍在开发机上跑）⇒ 直接用原路径。
+  if (exists(h)) return h
+  return candidate // 两条都不存在：返回重定位结果，让调用方按"上游已改动"报错
+}