@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/argent-capabilities.mjs

@@ -0,0 +1,776 @@
+#!/usr/bin/env node
+/**
+ * argent-capabilities —— 「按能力交付」的纯逻辑层（批 B3/B4，2026-09-21）
+ *
+ * ## 为什么单独一个文件
+ * 安装器 `install-argent.mjs` 是**单文件分发物**（`release-argent.sh` 的 CORE_FILES →
+ * 官网 `curl -fsSL …/install-argent.mjs | node`）：它只能在克隆完仓库之后**动态**加载本模块，
+ * 不能静态 import（否则单文件分发断链）。而医生 `scripts/profile-doctor.mjs` 要读同一份
+ * install.json、跑同一个 `capability_pack.py --describe`。把「装机记录的构造 / 合并 / 校验」
+ * 放在这里，安装器与医生**共用一份**，避免两处各写一遍（第二份真相 = 漂移）。
+ *
+ * ## 分工
+ * - 纯函数（可单测、无 IO）：`computeTicketFingerprint` / `parseCapabilityList` /
+ *   `validateAddCapabilities` / `normalizePack` / `mergeCapabilityPacks` /
+ *   `buildInstallJson` / `parseCapabilityManifest`
+ * - 轻 IO：`installJsonPath` / `readInstallJson` / `writeInstallJson` /
+ *   `sha16File` / `describeCapability`
+ *
+ * ## 两条红线
+ * 1. **票据/API Key 绝不落盘**：install.json 只写 `ticketFingerprint`
+ *    （= `sha256(整张 ticket)` 的前 12 位十六进制）。本模块不接受"把原票据写进去"的用法。
+ * 2. **多包共用引擎 sha 必须一致**：同一份文件在两个能力包里内容不同 ⇒ `mergeCapabilityPacks` 抛错
+ *    （同一台机器上的所有能力包必须来自同一版代码）。**唯一例外**是包内注册表投影
+ *    （`PACK.json#sourceRegistry`，按能力过滤 ⇒ 跨包必然不同）—— 判据 = `isRegistryProjection()`，
+ *    计划阶段（`planPackInstall`）/ 落盘阶段（`installPackFiles`）/ 合并与本模块的消费者**共用同一个函数**。
+ *
+ * 测试：`node scripts/tests/install-capabilities.test.mjs`
+ */
+import { createHash } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { dirname, join, posix, resolve } from 'node:path'
+import { resolveInterpreterPath } from './lib/python-runtime.mjs'
+
+let _resolvedPython
+
+/**
+ * 能力包工具用哪个 Python（与 `capability_pack.py --describe` 对齐；测试/换解释器可用 ARGENT_PY 覆盖）。
+ *
+ * P0-⑦（2026-10-08）：此前硬编码裸 `python3` —— 而 **Windows 上 `python3` 通常是 Microsoft Store
+ * 的占位符**（运行即失败/弹商店）⇒ 所有 `describeCapability` 失败 ⇒ 装机清单 `integrity: unverified`、
+ * `files` 空（实测现场见 docs/Argent-Windows-安装与HR能力验证-2026-10-08.md §3.5）。
+ * 仓库**早已有**多候选 + 版本门禁的口径（scripts/lib/python-runtime.mjs，含 win32 分支），这里接上它；
+ * 结果**记住**（describe 按能力被调用多次，不必每次重探十几个候选）。
+ */
+export function pythonBin() {
+  if (process.env.ARGENT_PY) return process.env.ARGENT_PY
+  if (_resolvedPython === undefined) _resolvedPython = resolveInterpreterPath({})
+  // 一个都跑不起来时保留旧兜底名：错误由调用方 catch 后**如实报告**（不静默判过）
+  return _resolvedPython || 'python3'
+}
+
+/** 装机清单路径：`<dsh-home>/argent/install.json`（默认 `~/.dsh/argent/install.json`）。 */
+export function installJsonPath(dshHome) {
+  return join(resolve(dshHome || join(process.env.HOME || '', '.dsh')), 'argent', 'install.json')
+}
+
+// ── 纯函数 ────────────────────────────────────────────────────────────
+
+/**
+ * 票据指纹：`sha256(ticket 的前 12 字符)` 取前 12 位十六进制。
+ * 只用于"这次装的是哪张票"的对照，**不可**据此反推票据（也绝不写原票据）。
+ */
+export function computeTicketFingerprint(ticket) {
+  // 2026-09-21 修正：早前按"票据前 12 字符"算 —— 票据是 `base64(payload).hexSig`，
+  // payload 前缀（版本/账号结构）在多张票上**经常相同** ⇒ 不同票据会撞同一个指纹，
+  // "这台机器装的时候用的是哪张票"就核不准了。改为对**整张票据**求摘要。
+  const s = String(ticket || '')
+  if (!s) return ''
+  return createHash('sha256').update(s, 'utf8').digest('hex').slice(0, 12)
+}
+
+/**
+ * `--add-capability <id>[,<id>…]` 的参数解析：逗号分隔、去空白、**去重保序**。
+ * 空串/只有一个逗号 ⇒ 抛错（加购是个明确动作，不接受空参数）。
+ */
+export function parseCapabilityList(raw) {
+  const ids = String(raw ?? '')
+    .split(',')
+    .map((x) => x.trim())
+    .filter(Boolean)
+  const seen = new Set()
+  const out = []
+  for (const id of ids) {
+    if (seen.has(id)) continue
+    seen.add(id)
+    out.push(id)
+  }
+  if (!out.length) throw new Error('--add-capability 需要至少一个能力 id（逗号分隔，如 full,invoice）')
+  return out
+}
+
+/**
+ * 加购的**授权校验**：参数里出现清单未授予的能力 ⇒ 拒绝（调用方据此响亮退出）。
+ *
+ * `granted` 语义：
+ * - 字符串数组 = 服务端清单里该账号有权的能力 id；
+ * - `null`/非数组 = 服务端没给清单（旧服务端 / 未部署）⇒ `checked:false`，**不判死**
+ *   （与"缺字段时按旧行为继续"一致），由调用方打印告警。
+ */
+export function validateAddCapabilities(requested, granted) {
+  const req = [...new Set((requested || []).map((x) => String(x).trim()).filter(Boolean))]
+  if (!req.length) return { ok: false, ungranted: [], checked: false, reason: 'empty-request' }
+  if (!Array.isArray(granted)) return { ok: true, ungranted: [], checked: false, reason: 'manifest-unavailable' }
+  const have = new Set(granted.map((x) => String(x)))
+  const ungranted = req.filter((id) => !have.has(id))
+  return { ok: ungranted.length === 0, ungranted, checked: true }
+}
+
+/**
+ * 包内相对路径的**唯一归一入口**：一律 POSIX 形态（正斜杠）。
+ *
+ * 为什么必须有它（2026-10-08，Windows 装机验证）：包内路径的全部下游用法都假定正斜杠 ——
+ * `PACK.json#files` / 版本锁 / `install.json#files` 的键、Node 侧 `join(packDir, rel)`、
+ * Python 侧 `_rel()`/`_expand_files()`。而 Windows 上（`path.relative`/`str(Path)`）给的是
+ * **反斜杠** ⇒ 两种故障：① 路径解析崩（`split("/")[1]` 类）；② **反斜杠键与正斜杠键永不相等**，
+ * 于是"与锁/基线逐文件比对"被**静默绕过**（`mergeCapabilityPacks` 的共用引擎守卫、
+ * 医生侧 sha 核对都会因此变成空判）。
+ * ⇒ 归一化是这一层唯一正确的做法；`path.posix.normalize` 顺带压掉 `./`、`//`、`a/../b`。
+ * ⛔ 不要自己拼字符串（先替换分隔符再 split 会漏掉 `a//b`、`./a` 这类形态）。
+ *
+ * @param {string} rel 包内相对路径（正斜杠或反斜杠形态）
+ * @returns {string} POSIX 形态（空串原样返回空串）
+ */
+export function normalizePackPath(rel) {
+  const s = String(rel == null ? '' : rel)
+  if (!s) return ''
+  const norm = posix.normalize(s.replaceAll('\\', '/'))
+  // 与 Python 侧 `PurePosixPath(...).as_posix()` **逐字同口径**：尾斜杠也要压掉
+  // （`posix.normalize` 会保留尾斜杠，而 PurePosixPath 不会 ⇒ 不压就会让两侧算出不同的键）
+  return norm.length > 1 ? norm.replace(/\/+$/u, '') : norm
+}
+
+/** 把一个"文件 → sha16"映射的键统一成 POSIX 形态（历史产物可能是反斜杠：Windows 上装/盖过章）。 */
+export function normalizePackPaths(files) {
+  const out = {}
+  for (const [k, v] of Object.entries(files && typeof files === 'object' ? files : {})) {
+    out[normalizePackPath(k)] = v == null ? '' : String(v)
+  }
+  return out
+}
+
+/**
+ * 把一个"包"归一成合并用的形状。接受的输入形态：
+ * - `{ id|capability, version, files: {relPath: sha16} }`（装机记录 / 本地 describe 的并集形态）
+ * - `{ integrity: {relPath: sha16} }`（`capability_pack.py --describe --json` 的原样输出）
+ * - `{ sha256: '' }`（服务端清单未填 sha256 ⇒ 该包整体 unverified）
+ * - 数组形态的 `capabilities: [{id, version}]`（install.json 顶层）
+ *
+ * 键一律过 `normalizePackPath()`（见上：分隔符不统一 = 比对被绕过）。
+ */
+export function normalizePack(pack, fallbackId = '') {
+  const src = pack || {}
+  const filesRaw =
+    src.files && typeof src.files === 'object' ? src.files
+      : src.integrity && typeof src.integrity === 'object' ? src.integrity
+        : {}
+  const files = normalizePackPaths(filesRaw)
+  const caps = Array.isArray(src.capabilities)
+    ? src.capabilities.map((c) => ({ id: String((c || {}).id || ''), version: String((c || {}).version || '') })).filter((c) => c.id)
+    : []
+  const id = String(src.capability || src.id || fallbackId || '')
+  const version = String(src.version || '')
+  // `sourceRegistry` 原样带过来：它是"包内注册表投影路径"的**声明**（`packProjectionPath()` 读它）⇒
+  // 归一后的形状也要能喂给 `isRegistryProjection()`（合并/装载的投影豁免都靠它）。缺声明 ⇒ 空串，
+  // 由 `packProjectionPath()` 落回历史约定的默认路径。
+  const sourceRegistry = String(src.sourceRegistry || '')
+  if (!caps.length && (id || version)) caps.push({ id: id || fallbackId || '（未命名）', version })
+  // unverified 的三种来源：显式标记 / 服务端 sha256 为空串 / 文件 sha 有空值
+  const unverified =
+    src.integrity === 'unverified' ||
+    src.integrityState === 'unverified' ||
+    (Object.prototype.hasOwnProperty.call(src, 'sha256') && String(src.sha256 || '') === '') ||
+    Object.values(files).some((v) => !v)
+  return { id, version, files, caps, unverified, sourceRegistry }
+}
+
+function packLabel(p) {
+  return `${p.id || '（未命名）'}${p.version ? ` v${p.version}` : ''}`
+}
+
+/**
+ * 合并两个能力包清单（**多包共用引擎 sha 必须一致**）。
+ *
+ * 规则（批 B3 验收）：
+ * 1. 同一文件在两侧都出现、两边 sha 都非空且不同 ⇒ **抛错**（点名文件与两侧版本）；
+ *    **例外（⑤）**：`isRegistryProjection()` 认下的**注册表投影**（每包一份、按能力过滤）⇒
+ *    差异是设计使然，跳过（取并集时保留先出现的那份 sha）。判据与计划/落盘两阶段**同一个函数**。
+ * 2. 任一侧文件 sha 为空串（服务端尚未填 / 本地取不到）⇒ **跳过**该校验，结果 `integrity: 'unverified'`；
+ * 3. 其余取并集（文件、能力条目按 id 去重）。
+ *
+ * @returns {{files: Object<string,string>, capabilities: Array<{id:string,version:string}>, integrity: 'verified'|'unverified'}}
+ */
+export function mergeCapabilityPacks(existing, incoming) {
+  const a = normalizePack(existing, 'existing')
+  const b = normalizePack(incoming, 'incoming')
+  const files = { ...a.files }
+  for (const [f, sha] of Object.entries(b.files)) {
+    if (!sha) {
+      if (!(f in files)) files[f] = sha
+      continue
+    }
+    const prev = files[f]
+    if (prev === undefined) {
+      files[f] = sha
+      continue
+    }
+    if (!prev) {
+      files[f] = sha
+      continue
+    }
+    if (prev !== sha) {
+      // ⑤ 同源（判据 = `isRegistryProjection()`，**唯一真源**）：注册表投影按能力过滤 ⇒ 两个能力的
+      // 投影**必然**不同 sha。而调用方（`install-argent.mjs#packOf()`）会把**多个能力**的文件拍平
+      // 成一个映射 ⇒ 这里若不豁免，同一台机器装了 ≥2 个能力后 `--add-capability`（add 模式 = die）
+      // 必失败，且报错点名的是"注册表投影"这个**设计使然**的差异（同根因的第三处落点）。
+      if (isRegistryProjection(f, [a, b])) continue
+      throw new Error(
+        `能力包共用文件 sha 不一致：${f}（${packLabel(a)} = ${prev} vs ${packLabel(b)} = ${sha}）` +
+        '—— 同一份文件在两个包里内容不同，拒绝装配（同机所有能力包必须来自同一版代码）',
+      )
+    }
+  }
+  const unverified = a.unverified || b.unverified || Object.values(files).some((v) => !v)
+  const seen = new Map()
+  for (const c of [...a.caps, ...b.caps]) if (!seen.has(c.id)) seen.set(c.id, c)
+  return { files, capabilities: [...seen.values()], integrity: unverified ? 'unverified' : 'verified' }
+}
+
+/**
+ * 解析 install-ticket 响应里的能力清单（**兼容旧服务端**：没有 `plan`/`capabilities`
+ * 就返回 `available:false`，不报错——调用方按旧行为继续）。
+ */
+export function parseCapabilityManifest(payload) {
+  const p = payload || {}
+  const hasPlan = typeof p.plan === 'string' && p.plan.length > 0
+  const hasCaps = Array.isArray(p.capabilities)
+  const capabilities = hasCaps
+    ? p.capabilities
+        .map((c) => {
+          const s = c || {}
+          return {
+            id: String(s.id || s.capability || ''),
+            minPlan: String(s.minPlan || ''),
+            version: String(s.version || ''),
+            sha256: String(s.sha256 ?? ''),
+            url: String(s.url || ''),
+          }
+        })
+        .filter((c) => c.id)
+    : []
+  return {
+    available: hasPlan || hasCaps,
+    plan: hasPlan ? p.plan : '',
+    capabilities,
+    // ⭐「服务端**确实**回了 capabilities 数组」的判据（2026-10-09）：空数组 = 服务端明确说"该账号
+    //   当前一个能力都没有"（合法状态：没买 / 档位不够），而**没有这个字段** = 服务端还是旧版本、
+    //   压根没实现 B2 ⇒ 两件事都表现为 `capabilities.length === 0`，只看长度必然把前者误报成后者的
+    //   故障（`--check-update` 曾因此 exit 1 报"拿不到服务端能力清单"）。判据必须是"字段在不在"。
+    capabilitiesPresent: hasCaps,
+    manifestError: typeof p.capabilityManifestError === 'string' ? p.capabilityManifestError : '',
+  }
+}
+
+/**
+ * 构造 `install.json` 的内容（**纯函数**，便于单测）。
+ *
+ * 只接受票据**原文**用于算指纹：返回值里只会出现 `ticketFingerprint`，
+ * 绝不会出现票据/API Key 原文（红线见文件头）。
+ *
+ * 每个能力条目：`{id, minPlan, version, sha256, url}` + 本地可核对时的 `files`（文件 → sha16）
+ * 与 `integrity`（`verified` / `unverified`，后者附 `integrityNote` 说明降级原因）。
+ */
+export function buildInstallJson({
+  plan, capabilities, profile, installedAt, ticket, ticketFingerprint, versions, existing,
+} = {}) {
+  const caps = (capabilities || []).map((c) => {
+    const src = c || {}
+    const sha256 = String(src.sha256 ?? '')
+    // 键归一（⑧）：install.json 的 files 是后来与 `--describe` 输出/锁文件比对的**同一张表**，
+    // 分隔符不统一 ⇒ 比对恒不命中（Windows 反斜杠键静默绕过校验）。
+    const files = normalizePackPaths(src.files && typeof src.files === 'object' ? src.files : {})
+    const out = {
+      id: String(src.id || src.capability || ''),
+      minPlan: String(src.minPlan || ''),
+      version: String(src.version || ''),
+      sha256,
+      url: String(src.url || ''),
+    }
+    if (Object.keys(files).length) out.files = files
+    let integrity = 'verified'
+    let note = ''
+    if (sha256 === '') {
+      integrity = 'unverified'
+      note = '服务端清单未填 sha256（待发布流程填充）'
+    } else if (!Object.keys(files).length) {
+      integrity = 'unverified'
+      note = '本地未取到文件 sha（缺 capability_pack.py / 该能力无文件清单）'
+    } else if (Object.values(files).some((v) => !v)) {
+      integrity = 'unverified'
+      note = '部分文件 sha 为空'
+    }
+    if (src.integrityNote) note = String(src.integrityNote)
+    out.integrity = src.integrity === 'unverified' ? 'unverified' : integrity
+    if (note) out.integrityNote = note
+    return out
+  })
+  const doc = { plan: String(plan || (existing && existing.plan) || 'unknown'), capabilities: caps }
+  if (profile) doc.profile = String(profile)
+  doc.installedAt = installedAt || new Date().toISOString()
+  const fp = ticketFingerprint || computeTicketFingerprint(ticket) || String((existing && existing.ticketFingerprint) || '')
+  if (fp) doc.ticketFingerprint = fp
+  doc.integrity = caps.length > 0 && caps.every((c) => c.integrity === 'verified') ? 'verified' : 'unverified'
+  const vers = {}
+  for (const [k, v] of Object.entries(versions || {})) if (v) vers[String(k)] = String(v)
+  if (Object.keys(vers).length) doc.versions = vers
+  return doc
+}
+
+// ── 轻 IO ─────────────────────────────────────────────────────────────
+
+/** 读装机清单；不存在 / 解析失败 ⇒ `null`（调用方自行决定 WARN 还是 FAIL）。 */
+export function readInstallJson(file) {
+  try {
+    const doc = JSON.parse(readFileSync(file, 'utf8'))
+    return doc && typeof doc === 'object' ? doc : null
+  } catch {
+    return null
+  }
+}
+
+/** 写装机清单：目录 0700（新建时）、文件 0600（已存在且更宽时收紧）。返回写入路径。 */
+export function writeInstallJson(file, doc) {
+  const dir = dirname(file)
+  const existed = existsSync(dir)
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  if (!existed) {
+    try { chmodSync(dir, 0o700) } catch { /* umask/平台差异：不阻断 */ }
+  }
+  writeFileSync(file, JSON.stringify(doc, null, 2) + '\n', { mode: 0o600 })
+  try { chmodSync(file, 0o600) } catch { /* 同上 */ }
+  return file
+}
+
+/** 文件 sha256 的前 16 位十六进制（与 `capability_pack.py` 的 `_sha()` 同口径）；读不到 ⇒ null。 */
+export function sha16File(abs) {
+  try {
+    return createHash('sha256').update(readFileSync(abs)).digest('hex').slice(0, 16)
+  } catch {
+    return null
+  }
+}
+
+/** 能力包工具路径。 */
+export function capabilityPackScript(repoDir) {
+  return join(repoDir, 'scripts', 'capability_pack.py')
+}
+
+/**
+ * 跑 `capability_pack.py --describe <id> --json` 取本地能力包清单（派生自仓库当前文件）。
+ * 失败一律返回 `{ok:false, error}`——调用方只 WARN，不判死（客户机上可能没装 python）。
+ */
+export function describeCapability(repoDir, id, { python = pythonBin(), timeoutMs = 120000 } = {}) {
+  const script = capabilityPackScript(repoDir)
+  if (!existsSync(script)) return { ok: false, error: `未找到能力包工具 ${script}` }
+  try {
+    const out = execFileSync(python, [script, '--describe', String(id), '--json'], {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      env: { ...process.env, PYTHONDONTWRITEBYTECODE: '1' },
+    })
+    const m = JSON.parse(out)
+    return {
+      ok: true,
+      manifest: m,
+      version: String(m.version || ''),
+      minPlan: String(m.minPlan || ''),
+      files: Array.isArray(m.files) ? m.files : Object.keys(m.integrity || {}),
+      integrity: m.integrity && typeof m.integrity === 'object' ? m.integrity : {},
+      missing: Array.isArray(m.missing) ? m.missing : [],
+    }
+  } catch (e) {
+    const msg = String((e && (e.stderr || e.message)) || e).trim().split('\n').filter(Boolean).pop() || '未知错误'
+    return { ok: false, error: msg.slice(0, 200) }
+  }
+}
+
+// ── 批 B5（2026-09-21）：从能力包**真装**（解包 + 逐文件校验 + 落盘）──────────────
+// 为什么需要：`--add-capability` 只登记/校验，包内容仍来自 git 克隆 ⇒ "只买 HR 的机器上
+// 不该有 FULL 的脚本"这句话当时并不成立。这一层让安装器从 PACK.json 描述的 tgz/目录装，
+// 客户机因此**不需要 git**，且"装了哪几个能力的哪些文件"可逐文件核对。
+
+/** 读 PACK.json；缺失/损坏 ⇒ throw（调用方给人工指引）。
+ *
+ *  **包的文件边界**：`files` 的键在这里就归一成 POSIX 形态（见 `normalizePackPath()`）——
+ *  下游（`verifyPackDir` / `planPackInstall` / `installPackFiles` / `cachePack` /
+ *  `packContentDigest`）全部假定正斜杠；Windows 上生成的包若带反斜杠键，
+ *  在 POSIX 机器上解包会"找不到文件"、在 Windows 上则会与锁/基线**绕过比对**。
+ */
+export function readPackJson(packDir) {
+  const p = join(packDir, 'PACK.json')
+  let doc
+  try { doc = JSON.parse(readFileSync(p, 'utf8')) } catch (e) {
+    throw new Error(`能力包缺 PACK.json 或无法解析：${p}（${String(e.message || e)}）`)
+  }
+  if (!doc || typeof doc !== 'object' || !doc.capability) throw new Error(`PACK.json 结构不对（缺 capability）：${p}`)
+  if (doc.files && typeof doc.files === 'object') doc.files = normalizePackPaths(doc.files)
+  return doc
+}
+
+/** 校验包内每个文件的 sha16 是否与 PACK.json 一致 ⇒ {ok, files, bad:[{file,want,got}]}。 */
+export function verifyPackDir(packDir, packJson) {
+  const want = (packJson && packJson.files) || {}
+  const bad = []
+  for (const [rel, sha] of Object.entries(want)) {
+    if (!sha) continue
+    const got = sha16File(join(packDir, rel))
+    if (got !== String(sha)) bad.push({ file: rel, want: String(sha), got: got === null ? '(缺失)' : got })
+  }
+  return { ok: bad.length === 0, files: Object.keys(want).length, bad }
+}
+
+/**
+ * 多包合并计划：文件 → 来源包。**同一文件在不同包里 sha 不同 ⇒ 抛错**（点名文件与两侧版本），
+ * **注册表投影除外**（见 `isRegistryProjection()`：它按能力过滤，两个包的投影必然不同 sha）。
+ * 这是"同一台机器上的能力包必须来自同一版代码"的守卫 —— 引擎文件被两个包各带一份。
+ *
+ * ⚠️ 判据只有一份：本函数与 `installPackFiles()` 都只经 `isRegistryProjection()` 决定"哪些路径
+ * 属投影"。2026-10-08 的事故正是**判据写了两份**——⑤ 只给执行阶段加了豁免，计划阶段仍是裸 sha
+ * 比对 ⇒ 安装器**自己推荐**的 `--from-packs a.tgz,b.tgz` 必失败（新旧两代引擎都栽在这里）。
+ */
+export function planPackInstall(packs) {
+  const files = {}
+  for (const p of packs || []) {
+    const id = String((p.packJson && p.packJson.capability) || p.capability || '')
+    const ver = String((p.packJson && p.packJson.version) || '')
+    for (const [rel, sha] of Object.entries((p.packJson && p.packJson.files) || {})) {
+      const prev = files[rel]
+      if (prev && String(prev.sha) !== String(sha)) {
+        if (isRegistryProjection(rel, [prev.packJson, p.packJson])) {
+          // ⑤：注册表投影（`PACK.json#sourceRegistry`）按能力过滤 ⇒ 跨包 sha **必然**不同，
+          // 不是"混版"。（落盘阶段由 `installPackFiles()` 按 保留/合并 处理 ⇒ 结果是各投影的并集。）
+          // 计划里保留**首个**包的那份 sha，并记下还有谁带这个投影（诊断用；不参与后续判定）。
+          prev.projection = true
+          prev.divergent = [...(prev.divergent || []), `${id} v${ver}`]
+          continue
+        }
+        throw new Error(`能力包引擎文件版本不一致：${rel}（${prev.id} v${prev.version} sha=${prev.sha} ≠ ${id} v${ver} sha=${sha}）`
+          + ' —— 同一台机器上的能力包必须来自同一版代码，请用同一批发布的包')
+      }
+      if (!prev) files[rel] = { sha: String(sha), id, version: ver, packJson: p.packJson }
+    }
+  }
+  return files
+}
+
+// ── ⑤（2026-10-08）：包内注册表是**投影**，不是"冲突" ────────────────────────────
+// 事故：`--from-packs` 在**已装机器**上必然失败 —— 包内 `scripts/flow-requirements.json` 是
+// `capability_pack.py#packed_registry()` 按能力**过滤后的注册表投影**（设计如此），而目标机上那份
+// 是**完整注册表**（git 克隆树）或**另一批能力的投影** ⇒ 两者 sha **永不相等** ⇒ 旧实现把它当"文件冲突"
+// 拒绝安装；而 `force` 只在"该能力已登记"时为真 ⇒ **首次安装必冲突**，报错还让你用一个不存在的 `--force`。
+//
+// 口径（本项目期确定，三条状态都不误判）：
+//   ① 首次安装（目标机没有注册表）⇒ 写入包内投影；
+//   ② 已装机器重装同一能力 / ③ 已装机器装新能力 ⇒ 目标机那份**覆盖**包内投影时**保留目标机的**
+//      （绝不用一份单能力投影去盖掉完整注册表 —— 那会把别家能力的流程/声明一起抹掉）；
+//      覆盖不了（缺本包的流程/能力）⇒ **合并**：目标机独有的条目原样保留、本包条目以本包为准。
+
+/** 包内**注册表投影**的仓库相对路径（`PACK.json#sourceRegistry`；缺省按历史约定）。 */
+export function packProjectionPath(packJson) {
+  const declared = String((packJson && packJson.sourceRegistry) || '').trim()
+  return normalizePackPath(declared || 'scripts/flow-requirements.json')
+}
+
+/**
+ * 「该路径是不是注册表投影」—— **唯一真源**（⑤，2026-10-09 收口）。
+ *
+ * `planPackInstall()`（多包计划阶段）与 `installPackFiles()`（落盘阶段）**都只经这一个函数**
+ * 决定"哪些路径属投影、因而不算冲突"：计划阶段要豁免的、执行阶段要 保留/合并 的，必须是
+ * **同一个路径集合**。两处各写一份判断 = 2026-10-08 的老 bug（⑤ 只修了执行阶段 ⇒ 安装器自己
+ * 推荐的"一起装"路径必失败）；这条注释就是防它再漂移的护栏。
+ *
+ * @param {string} rel 仓库相对路径（`PACK.json#files` 的键）
+ * @param {Array<object>} packJsons 参与本次比较的能力包声明。
+ *   · 计划阶段传**两侧**（两个包都是 PACK.json 声明，"任一侧声明它是投影"即属投影）；
+ *   · 执行阶段只传落盘的那一个包（目标机上的那份没有声明，判据由**写入方**给出）。
+ * @returns {boolean} true = 注册表投影（差异是设计使然）；false = 普通文件（不同 sha 即冲突）
+ */
+export function isRegistryProjection(rel, packJsons) {
+  const want = normalizePackPath(rel)
+  for (const pj of (Array.isArray(packJsons) ? packJsons : [packJsons])) {
+    if (pj && packProjectionPath(pj) === want) return true
+  }
+  return false
+}
+
+/** 读一份注册表文档（对象）；读不了 ⇒ null（判据要区分"读不懂"与"内容不同"）。 */
+function readRegistryDoc(abs) {
+  try {
+    const d = JSON.parse(readFileSync(abs, 'utf8'))
+    return d && typeof d === 'object' && !Array.isArray(d) ? d : null
+  } catch { return null }
+}
+
+/** 注册表里"对外可见"的 id 集合（`_` 前缀是内部键，不参与覆盖判定）。 */
+function registryIds(doc, key) {
+  const src = doc && typeof doc[key] === 'object' && doc[key] ? doc[key] : {}
+  return new Set(Object.keys(src).filter((k) => !k.startsWith('_')))
+}
+
+/**
+ * 目标机的注册表是否**覆盖**包内投影：包里的每条 flow / capability / 别名都能在目标机找到。
+ * 覆盖 ⇒ 目标机那份是超集（完整注册表 / 多能力合并后的），**保留它**（否则会抹掉别家能力）。
+ */
+export function registryCovers(destDoc, packDoc) {
+  if (!destDoc || !packDoc) return false
+  for (const key of ['flows', 'capabilities', 'aliases']) {
+    const have = registryIds(destDoc, key)
+    for (const id of registryIds(packDoc, key)) if (!have.has(id)) return false
+  }
+  return true
+}
+
+/** 合并标记（幂等：重复合并不会越加越长）。 */
+const REGISTRY_MERGE_MARK = '（本机已与既有注册表条目合并：保留别家能力的流程/声明，本包条目以本包为准）'
+
+// ── P2a 不变量（2026-10-09，P0 修复）：**引擎级 base 不含 flow 声明** ─────────────────
+// 投影的落点 `scripts/flow-requirements.json` 是 P2a 契约里的**引擎级 base**（引擎契约/错误词表/
+// lease/billing/pack.engine）；flow 声明属业务线 `verticals/<id>/flows.json`（由包同批带上）。
+// 而 2026-10-09 之前的包把 flow 抄进了投影 ⇒ 落到 base 上就与业务线那份**重复定义** ⇒
+// `flow_registry.py --json` exit 2（源码树）；纯包装机则因包没带 flows.json 而 exit 2。
+// ⇒ 写入 base 前**先规整**：把不属于 base 的段摘掉（并说明）。这条只作用于安装/回滚的**写入边界**，
+// **不动** `flow_registry.py` 的冲突判据（base 里真出现重复定义时仍然是响亮的红，见门禁用例【⑤】）。
+// 对**新格式包**（投影里这两个段恒为空）本函数是**空操作** ⇒ 逐字节落盘、重装幂等、sha 与 PACK.json 一致。
+
+/** 不属于引擎级 base 的段（判据只有这一份，`installPackFiles()` 与回归都用它）。 */
+export const BASE_FOREIGN_SECTIONS = ['flows', 'aliases']
+
+/**
+ * 把包内投影规整成"引擎级 base"形态 ⇒ `{doc, dropped}`（`dropped` 非空 = 该包是**旧格式**）。
+ * @param {object} packDoc 包内 `scripts/flow-requirements.json` 解析后的对象
+ */
+export function baseProjectionDoc(packDoc) {
+  const doc = { ...(packDoc || {}) }
+  const dropped = []
+  for (const key of BASE_FOREIGN_SECTIONS) {
+    const v = doc[key]
+    if (!v || typeof v !== 'object') continue
+    const n = Object.keys(v).filter((k) => !k.startsWith('_')).length
+    if (!n) continue
+    dropped.push(`${key}（${n} 条）`)
+    delete doc[key]
+  }
+  return { doc, dropped }
+}
+
+/**
+ * 投影合并：`flows`/`capabilities`/`aliases` 逐段并集（**包内胜** = 同一能力重装即升级），
+ * 其余引擎级段以包内为准，目标机独有的键保留。
+ *
+ * ⚠️ P2a（2026-10-09）起调用方传进来的 `packDoc` 已经过 `baseProjectionDoc()` 规整（flows/aliases 为空），
+ * 所以写进 base 的 `flows` 恒等于目标机原有的那份（= 通常是空）；这里保留并集语义只为兼容旧调用方/旧包。
+ */
+export function mergeRegistryProjections(destDoc, packDoc) {
+  const out = { ...(destDoc || {}) }
+  for (const key of ['flows', 'capabilities', 'aliases']) {
+    const b = packDoc && packDoc[key]
+    if (!b || typeof b !== 'object') continue
+    out[key] = { ...((destDoc && destDoc[key] && typeof destDoc[key] === 'object') ? destDoc[key] : {}), ...b }
+  }
+  for (const [k, v] of Object.entries(packDoc || {})) {
+    if (k === 'flows' || k === 'capabilities' || k === 'aliases') continue
+    out[k] = v
+  }
+  const base = typeof (packDoc || {})._doc === 'string' ? packDoc._doc : ''
+  out._doc = base.includes(REGISTRY_MERGE_MARK) ? base : base + REGISTRY_MERGE_MARK
+  return out
+}
+
+/**
+ * 目标机已有一份注册表（且与包内投影不同 sha）时怎么办 ⇒ `{action:'keep'|'merged'|'conflict', note}`。
+ * · `keep`：目标机那份覆盖本包 ⇒ 一个字都不写（保持机器口径；这就是"已知差异"的正解）；
+ * · `merged`：目标机那份缺本包条目 ⇒ 写回并集（不丢别家能力，也不让本包跑不起来）；
+ * · `conflict`：有一侧读不懂（不是 JSON 对象）⇒ 不猜，交给调用方按既有冲突/force 路径处理。
+ *
+ * `packDoc`/`targetDoc` 可直接给**已解析**的文档（`installPackFiles()` 用：包侧已按 `baseProjectionDoc()`
+ * 规整过，不能再从盘上读原始字节）；不给则按路径读。
+ */
+export function reconcileRegistryProjection({ packRegistry, targetRegistry, packDoc, targetDoc }) {
+  const pd = packDoc || readRegistryDoc(packRegistry)
+  const dd = targetDoc || readRegistryDoc(targetRegistry)
+  if (!pd || !dd) {
+    return { action: 'conflict', note: '注册表读不懂（不是 JSON 对象）⇒ 不当"已知差异"处理，走冲突/force 路径' }
+  }
+  if (registryCovers(dd, pd)) {
+    return {
+      action: 'keep',
+      note: '目标机已有**覆盖**本包的注册表（完整注册表或另一批能力的投影）⇒ 保留它（属已知差异，不是冲突）',
+    }
+  }
+  const merged = mergeRegistryProjections(dd, pd)
+  return {
+    action: 'merged',
+    doc: merged,
+    note: '目标机的注册表缺本包的流程/能力条目 ⇒ **合并**写入（别家能力的条目原样保留）',
+  }
+}
+
+/**
+ * 把包内文件落到 targetHome（**只写不冲突的文件**：同 sha 视为已装并跳过，不同 sha 需 force）。
+ *
+ * 例外（⑤，见上）：`PACK.json#sourceRegistry` 指的那份**注册表投影**按"覆盖/合并"判定，
+ * **永不**计入 `conflicts`（它与目标机的差异是设计使然）。判据 = `isRegistryProjection()`
+ * —— **与计划阶段 `planPackInstall()` 同一个函数**（唯一真源，见该函数注释）。
+ *
+ * @returns {{written:number, skipped:number, projected:number, merged:number,
+ *            conflicts:Array<{file:string,existing:string,incoming:string}>, notes:string[], total:number}}
+ *   `projected` = 因"目标机已覆盖"而**有意保留**的文件数；`merged` = 投影合并写入的数；`notes` = 人读说明。
+ */
+export function installPackFiles({ packDir, packJson, targetHome, force = false }) {
+  const planned = planPackInstall([{ packDir, packJson }])
+  let written = 0, skipped = 0, projected = 0, merged = 0
+  const conflicts = []
+  const notes = []
+  for (const [rel, meta] of Object.entries(planned)) {
+    const src = join(packDir, rel)
+    const dst = join(targetHome, rel)
+    const cur = sha16File(dst)
+    if (cur === meta.sha) { skipped++; continue }
+    // 判据与计划阶段**同一个**（`isRegistryProjection`，唯一真源）——不得在此另写一份。
+    if (isRegistryProjection(rel, [packJson])) {
+      const packDoc = readRegistryDoc(src)
+      if (packDoc) {
+        // P2a 不变量：写进 base 的那份**只留引擎级段**（见 `baseProjectionDoc()` 的事故说明）。
+        // 新格式包的投影里 flows/aliases 恒为空 ⇒ `dropped` 为空 ⇒ 下面走逐字节落盘（幂等不变）。
+        const { doc: incoming, dropped } = baseProjectionDoc(packDoc)
+        if (dropped.length) {
+          notes.push(`${rel}：包内投影把 ${dropped.join('、')} 写进了**引擎级 base**（P2a 起 base 不含 flow 声明）`
+            + '⇒ 这几段未写入；flow 由 `verticals/<id>/flows.json` 提供（本批发布的包会带上它）——'
+            + '这是**旧格式包**，建议重装本批发布')
+        }
+        if (cur === null) {
+          // 首次安装：新格式包逐字节落盘（sha 与 PACK.json 一致 ⇒ 重装幂等）；旧格式包落规整后的 base
+          mkdirSync(dirname(dst), { recursive: true })
+          if (dropped.length) writeFileSync(dst, `${JSON.stringify(incoming, null, 2)}\n`)
+          else copyFileSync(src, dst)
+          written++
+          continue
+        }
+        const r = reconcileRegistryProjection({ packDoc: incoming, targetDoc: readRegistryDoc(dst) })
+        if (r.action === 'keep') { projected++; notes.push(`${rel}：${r.note}`); continue }
+        if (r.action === 'merged') {
+          mkdirSync(dirname(dst), { recursive: true })
+          writeFileSync(dst, `${JSON.stringify(r.doc, null, 2)}\n`)
+          written++; merged++
+          notes.push(`${rel}：${r.note}`)
+          continue
+        }
+        // action === 'conflict'：读不懂就不猜 —— 落到下面的既有 conflict/force 路径
+        notes.push(`${rel}：${r.note}`)
+      }
+    }
+    if (cur !== null && !force) { conflicts.push({ file: rel, existing: cur, incoming: meta.sha }); continue }
+    mkdirSync(dirname(dst), { recursive: true })
+    copyFileSync(src, dst)
+    written++
+  }
+  return { written, skipped, projected, merged, conflicts, notes, total: Object.keys(planned).length }
+}
+
+/** 解包 tgz 到 destDir（系统 tar；确定性包无软链/绝对路径，安全）。 */
+export function extractPack(tgz, destDir) {
+  mkdirSync(destDir, { recursive: true })
+  execFileSync('tar', ['-xzf', tgz, '-C', destDir], { stdio: ['ignore', 'pipe', 'pipe'] })
+  return destDir
+}
+
+/** 一个来源（.tgz 或已解开的目录）→ { packDir, packJson }。 */
+export function openPackSource(spec, tmpRoot) {
+  if (existsSync(spec) && readFileSync && spec.endsWith('.tgz')) {
+    const dir = join(tmpRoot, `pack-${createHash('sha256').update(spec).digest('hex').slice(0, 8)}`)
+    extractPack(spec, dir)
+    return { packDir: dir, packJson: readPackJson(dir) }
+  }
+  return { packDir: spec, packJson: readPackJson(spec) }
+}
+
+/** 从 URL 下载能力包（带重试 + 可选整包 sha256 校验）⇒ 本地 .tgz 路径。 */
+export async function downloadPack(url, destDir, { expectSha256 = '', retries = 3 } = {}) {
+  mkdirSync(destDir, { recursive: true })
+  const name = (url.split('?')[0].split('/').pop() || 'pack.tgz')
+  const dest = join(destDir, name)
+  let lastErr = null
+  for (let i = 0; i < Math.max(1, retries); i++) {
+    try {
+      const res = await fetch(url, { redirect: 'follow' })
+      if (!res.ok) throw new Error(`HTTP ${res.status}`)
+      const buf = Buffer.from(await res.arrayBuffer())
+      if (buf.length < 100) throw new Error(`下载内容过小（${buf.length} 字节）`)
+      writeFileSync(dest, buf)
+      const got = createHash('sha256').update(buf).digest('hex')
+      if (expectSha256 && got !== String(expectSha256).toLowerCase()) {
+        rmSync(dest, { force: true })
+        throw new Error(`整包 sha256 不符（期望 ${String(expectSha256).slice(0, 16)}… 实际 ${got.slice(0, 16)}…）`)
+      }
+      return { file: dest, sha256: got, bytes: buf.length }
+    } catch (e) {
+      lastErr = e
+      if (i < retries - 1) await new Promise((r) => setTimeout(r, 1500 * (i + 1)))
+    }
+  }
+  throw new Error(`下载失败（已重试 ${retries} 次）：${url} —— ${String(lastErr && lastErr.message)}`)
+}
+
+/** 整包内容摘要（与 python `capability_pack.pack_digest()` 同口径：对 `文件:sha16` 排序后求 sha256）。
+ *  服务端清单里的 `sha256` 就是它 ⇒ 下载后可比一次，确认"包内容与服务端发布的一致"。 */
+export function packContentDigest(packJson) {
+  const lines = Object.entries((packJson && packJson.files) || {})
+    .map(([rel, sha]) => `${rel}:${sha}`)
+    .sort()
+  return createHash('sha256').update(lines.join('\n'), 'utf8').digest('hex')
+}
+
+// ── 升级/回滚（缺口④，2026-09-21）：把"装过的包"留在 packs-cache，随时能装回去 ──────────
+// 设计取舍：不做"逐文件差异备份"（复杂、易错），而是**整包留档** —— 每次装包把该包原样拷进
+// `<dataDir>/packs-cache/<cap>-<ver>/`（包本来就带 PACK.json 的逐文件 sha，回滚时走同一条
+// 校验+落盘路径）⇒ 回滚 = "用旧包再装一次"，行为与正向安装完全一致。
+
+/** 把装过的包留档（同版本已存在则跳过）。返回留档目录。 */
+export function cachePack(packDir, packJson, dataDir) {
+  const id = String(packJson.capability || '')
+  const ver = String(packJson.version || '')
+  if (!id || !ver) return ''
+  const dest = join(dataDir, 'packs-cache', `${id}-${ver}`)
+  if (existsSync(join(dest, 'PACK.json'))) return dest
+  mkdirSync(dest, { recursive: true, mode: 0o700 })
+  for (const rel of Object.keys(packJson.files || {})) {
+    const src = join(packDir, rel)
+    if (!existsSync(src)) continue
+    const dst = join(dest, rel)
+    mkdirSync(dirname(dst), { recursive: true })
+    copyFileSync(src, dst)
+  }
+  writeFileSync(join(dest, 'PACK.json'), JSON.stringify(packJson, null, 2) + '\n', { mode: 0o600 })
+  return dest
+}
+
+/** 列出某个能力在 cache 里的版本（新→旧）。 */
+export function cachedVersions(capability, dataDir) {
+  const root = join(dataDir, 'packs-cache')
+  let names = []
+  try { names = readdirSync(root) } catch { return [] }
+  const prefix = `${capability}-`
+  return names.filter((n) => n.startsWith(prefix) && existsSync(join(root, n, 'PACK.json')))
+    .map((n) => ({ version: n.slice(prefix.length), dir: join(root, n) }))
+    .sort((a, b) => cmpVersion(b.version, a.version))
+}
+
+/** 语义化版本比较（只认数字段，够用；返回 -1/0/1）。 */
+export function cmpVersion(a, b) {
+  const pa = String(a).split('.').map((x) => parseInt(x, 10) || 0)
+  const pb = String(b).split('.').map((x) => parseInt(x, 10) || 0)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0)
+    if (d) return d > 0 ? 1 : -1
+  }
+  return 0
+}
+
+/** 选回滚目标：给了 --to 用它；否则取 cache 里"与当前不同"的最新版本。 */
+export function pickRollback(capability, dataDir, { current = '', to = '' } = {}) {
+  const list = cachedVersions(capability, dataDir)
+  if (!list.length) return null
+  if (to) return list.find((x) => x.version === String(to)) || null
+  return list.find((x) => x.version !== String(current)) || null
+}