@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/skill-install.mjs

@@ -0,0 +1,629 @@
+#!/usr/bin/env node
+/**
+ * skill-install.mjs —— **技能外发安装器**（P3，2026-10-03）
+ *
+ * ## 它解决什么（缺口⑥ / R3）
+ * "装进客户已有的 agent"这句话，今天**没有命令入口**：dsh 侧靠 preset 零配置挂载 + 升级器全量同步，
+ * 其它宿主（Claude Code / Codex / Cursor）**一个都没有**。本脚本把"按宿主约定装技能"变成一条命令，
+ * 并且**只装该装的**：外发集 = 所有 `verticals/<id>/manifest.json#skills` 的**并集**（今天 5 个流程技能）。
+ *
+ * ## 归类判据**不在这里**（唯一实现在门禁里）
+ * `classify()` 从 `scripts/check-skill-classification.mjs` **import**（不是抄一份）：
+ * `skills/` 下任何既不在业务线声明、也不在 `skills/internal.json` 的目录 ⇒ 门禁红 ⇒ **本脚本拒绝安装**
+ * （"外发泄露内部角色"是本阶段唯一的高危项 ⇒ 宁可不装，不可装错）。
+ *
+ * ## 目标目录：**逐宿主实测/查证**（`HOSTS`；查不到的标 `verified` 并给 `--dir` 兜底）
+ * | 宿主 | 目录 | 证据等级 |
+ * |---|---|---|
+ * | `dsh` | `<dsh home>/skills`（缺省 `~/.dsh/skills`） | **实测 + 仓库判据**：preset 的 `skill-filesystem` 零配置挂载该根；本机该目录有 13 个技能 |
+ * | `codex` | `~/.codex/skills/` | **本机实测**：该目录存在，且里面就是 `<name>/SKILL.md` + `name`/`description` frontmatter（与本仓库同形） |
+ * | `claude-code` | `~/.claude/skills/` | **查证（官方文档）**：Claude Code 的 personal skills 目录；⚠️ 本机**无** `~/.claude` ⇒ **未实测** |
+ * | `cursor` | `~/.cursor/skills/` | **查证（官方文档 "Skill directories"）**：user-level 技能目录（另有 `.agents/skills/`）；⚠️ 本机**无** `~/.cursor` ⇒ **未实测** |
+ *
+ * > Cursor 官方文档另写明"为兼容也加载 `~/.claude/skills/` 与 `~/.codex/skills/`" ⇒ 装到 cursor 目录不是唯一路径。
+ * > **不确定就用 `--dir <path>` 显式指定**（本脚本的兜底，也是唯一不依赖"约定"的形态）。
+ *
+ * ## 与 dsh 的关系（§P3① 的实施约束）
+ * dsh 侧**仍走原路**（`presets/<preset>/agent.cordis.yml` 的 `skill-filesystem` 挂载 + `scripts/argent-upgrade.mjs`）
+ * ⇒ `--host dsh --apply` **被拒绝**（exit 2 + `host_owns_install`），只允许 `--list` / `--dry-run` 做**一致性校验**；
+ * 确要装到别处请用 `--host dsh --dir <path>`（显式 = 你的决定）。
+ *
+ * ## 版本记录与更新/卸载
+ *   · 装完写 `<target>/.argent-skills.json`：宿主 / 目标 / Argent 版本 / 每个技能的**内容摘要**（sha256）
+ *     + 逐文件 sha12 + 从 frontmatter 读到的 `version`（有则记）；
+ *   · 更新：与清单比对 —— **sha 一致 ⇒ `skipped`（幂等）**；不一致 ⇒ **先备份**（`<target>/.argent-skills-backup/<name>-<ts>/`）**再覆盖**；
+ *   · 卸载：`--uninstall` 只删**清单里列过**的技能目录与清单本身 —— 用户自建目录**一个都不碰**。
+ *
+ * ## `--prune-orphans`：**受守卫的**孤儿技能清理（2026-10-04，客户机 18 项残留的收敛动词）
+ * 背景：`scripts/argent-upgrade.mjs` 按纪律**只报告不删**宿主技能根里"多出"的目录 ⇒ 客户机实测
+ * `~/.dsh/skills/` 里积了 6 个内部角色技能 + 12 个旧 hermes 期技能（18 项），**没有安全手段**收敛。
+ * 本动词是那个手段，但把它做成**人工确认 + 逐项点名**的动作：
+ *   · **缺省 = dry-run**：只列"将删除 / 拒绝清理 / 未点名"三张清单，零副作用；
+ *   · 真删要 `--apply` **且** `--allow <name>`（可重复）**逐个点名** —— **未点名的绝不删**；
+ *   · **只允许删四条件同时满足的目录**（缺一即拒绝，见 `planPrune()`）：
+ *       ① 不在**外发集**（`verticals/<id>/manifest.json#skills` 并集）；
+ *       ② 不在 `skills/internal.json`（内部角色技能 = 宿主上"角色包已装"的判据）；
+ *       ③ 不在**安装器自建清单** `.argent-skills.json` 里（那是本脚本装的 ⇒ 该用 `--uninstall`）；
+ *       ④ 目录内**含 `SKILL.md`**（技能形态的证明 —— 用户自建的普通文件/目录一律不碰）。
+ *     额外拒绝：点开头的项（`.argent-skills.json` / 备份目录…本工具自管）、**软链**（删除会越界）。
+ *   · **先备份再删**：`<target>/.argent-skills-pruned-<ts>/<name>/`（回滚 = `cp -R` 回去）；
+ *     并写审计 JSONL `<target>/.argent-skills-prune-audit.jsonl`（追加型，一行一次动作）；
+ *   · `--host dsh` **仍不抢安装权**：清理默认拒绝（`host_owns_prune`），
+ *     除非给出显式 `--dir <path>`（= 你的决定）或 `--allow-host-dsh-prune`（客户机清理的入口）。
+ *   · 残留风险（**必须在人这一侧兜住**）：一个**用户手写的** `SKILL.md` 技能目录在形态上与旧残留
+ *     **无法区分** ⇒ 唯一的护栏就是"默认 dry-run 打印清单 + 必须逐项点名"。请**逐个核对名字**再点名。
+ *
+ * ## A1/A2（与 CLI verb 同口径，便于宿主统一处置）
+ *   · `0` 成功（含"成功但空"：技能一个都没装 = `empty:true`）；`1` 运行失败（写不下 / 目标非法 / 归类不过）；
+ *   · `2` 用法错误（未知宿主、未知参数、`--host dsh --apply` 未给 --dir、清单里没有可卸载项却在 `--uninstall`）；
+ *   · `--json` 时 stdout **只有一份 JSON**（人话一律走 stdout 的 human 形态；诊断走 stderr）。
+ *
+ * ## A3：默认动作 = **dry-run**（2026-10-03 收口；真装要显式 `--apply`）
+ * 本脚本此前**默认真装**（`--apply` 只是同义词），这与 P0-A A3"**凡 write 类必须默认 dry-run**、
+ * 真写要显式确权"直接冲突 —— 而且它写的是**别人的 agent 目录**（`~/.claude/skills` 之类），
+ * 一条 `--host` 敲下去就落盘，没有回头路。现在：
+ *   · **缺省 = dry-run**（只出计划 + `willWrite` 列表，**零副作用**）；
+ *   · `--apply` = 真装（sha 一致 ⇒ `skipped`；不一致 ⇒ **先备份再覆盖**）；
+ *   · `--dry-run` 保留为**显式同义**（脚本/文档里写全更清楚，行为与缺省一致）；
+ *   · `--list` 行为不变（只看宿主约定目录 + 外发清单 + 目标现状，不读计划）。
+ * ⇒ 实施方案 §P3 的三条验收命令**同批补齐 `--apply`**（不带它现在只会预演）。
+ */
+import { appendFileSync, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
+import { homedir } from 'node:os'
+import { dirname, join, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+import { classify, INTERNAL_MANIFEST, SKILL_FILE } from './check-skill-classification.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+
+/** 安装清单文件名（**只此一处**：更新/卸载都读它）。 */
+export const MANIFEST_NAME = '.argent-skills.json'
+/** 覆盖前备份目录名。 */
+export const BACKUP_DIRNAME = '.argent-skills-backup'
+/** 清理（`--prune-orphans`）前备份目录名**前缀**（真删前先备份 ⇒ 可回滚；目录名带时间戳）。 */
+export const PRUNE_BACKUP_PREFIX = '.argent-skills-pruned-'
+/** 清理审计 JSONL（**追加型**，一行一次动作；与 `.argent-skills.json` 同族命名，随目标目录走）。 */
+export const PRUNE_AUDIT_NAME = '.argent-skills-prune-audit.jsonl'
+
+/**
+ * 宿主 → 技能目录约定（**数据表**，路径不写死在逻辑里 —— 约定会变，改这里一行）。
+ * `verified`：证据等级（实测 / 查证 / 待实测），`--list` 会**原样打给人看**（不许把"约定"说成"实测"）。
+ */
+export function hostTable({ home = homedir(), dshHome = '' } = {}) {
+  const dsh = dshHome || join(home, '.dsh')
+  return {
+    dsh: {
+      id: 'dsh', dir: join(dsh, 'skills'), ownsInstall: true,
+      verified: '实测 + 仓库判据',
+      evidence: '`presets/*/agent.cordis.yml` 的 `skill-filesystem` 零配置挂载 `<dsh home>/skills`；本机实测该目录在册（13 个技能）',
+    },
+    'claude-code': {
+      id: 'claude-code', dir: join(home, '.claude', 'skills'), ownsInstall: false,
+      verified: '查证（官方文档）；⛔ 本机无 ~/.claude ⇒ 未实测',
+      evidence: 'Claude Code 的 personal skills 目录 = `~/.claude/skills/<name>/SKILL.md`（Agent Skills 形态，与本仓库同形）；Cursor 官方文档亦把该目录列为兼容载入点',
+    },
+    codex: {
+      id: 'codex', dir: join(home, '.codex', 'skills'), ownsInstall: false,
+      verified: '本机实测',
+      evidence: '本机 `~/.codex/skills/` 实际存在，内部为 `<name>/SKILL.md` + `name`/`description` frontmatter（与本仓库格式同形）',
+    },
+    cursor: {
+      id: 'cursor', dir: join(home, '.cursor', 'skills'), ownsInstall: false,
+      verified: '查证（官方文档）；⛔ 本机无 ~/.cursor ⇒ 未实测',
+      evidence: 'Cursor 官方文档「Skill directories」：user-level = `~/.cursor/skills/`（另有 `~/.agents/skills/`）；并注明为兼容也载入 `~/.claude/skills/`、`~/.codex/skills/`',
+    },
+  }
+}
+export const HOST_IDS = Object.keys(hostTable())
+
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex')
+const sha12 = (buf) => sha256(buf).slice(0, 12)
+
+/** 技能目录 → 逐文件 sha12（相对路径排序，**内容寻址**；改一个字节就变）。 */
+export function skillFiles(skillDir) {
+  const files = {}
+  const walk = (dir, base = dir) => {
+    for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (e.name === '.DS_Store') continue
+      const p = join(dir, e.name)
+      const rel = p.slice(base.length + 1).split(sep).join('/')
+      if (statSync(p).isDirectory()) walk(p, base)
+      else if (statSync(p).isFile()) files[rel] = sha12(readFileSync(p))
+    }
+  }
+  walk(skillDir)
+  return files
+}
+
+/** 技能内容摘要：`路径:sha12` 排序后求 sha256（与 `capability_pack.py#pack_digest` 同形态）。 */
+export function skillDigest(skillDir) {
+  const files = skillFiles(skillDir)
+  const lines = Object.entries(files).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([f, s]) => `${f}:${s}`)
+  return { digest: sha256(lines.join('\n')), files, bytes: lines.reduce((n, l) => n + l.length, 0) }
+}
+
+/** 从 SKILL.md 的 frontmatter 里取 `version`（有则记；**不解析/不校验 frontmatter 合法性** —— 那是 fix-skill-frontmatter.py 的职责）。 */
+export function frontmatterVersion(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(String(text || ''))
+  if (!m) return null
+  const v = /^\s*version\s*:\s*(.+?)\s*$/m.exec(m[1])
+  return v ? v[1].replace(/^["']|["']$/g, '') : null
+}
+
+/** 目标目录 → 当前清单（不存在/坏文件 ⇒ null）。 */
+export function readManifest(target) {
+  const p = join(target, MANIFEST_NAME)
+  if (!existsSync(p)) return null
+  try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return { _corrupt: true, _path: p } }
+}
+
+/** 外发技能清单（来自业务线声明；**由 classify() 给出，安装器不自己读 manifest**）。 */
+export function externalSkills(root = REPO) {
+  const c = classify({ root })
+  return { ...c, skills: c.external }
+}
+
+/**
+ * 计划：对每个外发技能算出 `install` / `skip`（sha 一致）/ `update`（不一致，先备份再覆盖）。
+ */
+export function planInstall({ root = REPO, target, skills }) {
+  const man = readManifest(target)
+  const prev = (man && !man._corrupt && man.skills) || {}
+  const rows = []
+  for (const name of skills) {
+    const src = join(root, 'skills', name)
+    if (!existsSync(join(src, SKILL_FILE))) { rows.push({ name, action: 'missing_source', src }); continue }
+    const cur = skillDigest(src)
+    const dst = join(target, name)
+    const exists = existsSync(dst) && existsSync(join(dst, SKILL_FILE))
+    // ⚠️ 判据用**目标目录的实际内容**（不是清单里记的摘要）：客户/用户手改过、上游更新过，
+    // 都必须被认成 update（否则"改了却没生效"——那正是 §P3① 要的"sha 一致跳过、不一致先备份再覆盖"）。
+    const dstDigest = exists ? skillDigest(dst).digest : null
+    const recorded = prev[name] && prev[name].digest ? prev[name].digest : null
+    let action = 'install'
+    if (exists && dstDigest === cur.digest) action = 'skip'
+    else if (exists) action = 'update'
+    rows.push({
+      name, action, src, dst, digest: cur.digest.slice(0, 16), files: Object.keys(cur.files).length,
+      targetDigest: dstDigest ? dstDigest.slice(0, 16) : null, recordedDigest: recorded ? recorded.slice(0, 16) : null,
+      targetDrift: Boolean(recorded && dstDigest && recorded !== dstDigest),
+      version: frontmatterVersion(readFileSync(join(src, SKILL_FILE), 'utf8')),
+    })
+  }
+  return { rows, manifest: man, previous: prev }
+}
+
+/** 执行安装（先备份后覆盖；幂等）。 */
+export function applyInstall({ root = REPO, target, rows, host, argentVersion, now = new Date() }) {
+  const done = []
+  const backupRoot = join(target, BACKUP_DIRNAME)
+  const stamp = now.toISOString().replace(/[:.]/g, '-')
+  mkdirSync(target, { recursive: true })
+  const skills = {}
+  for (const r of rows) {
+    if (r.action === 'missing_source') { done.push({ ...r, ok: false, note: '源目录不存在（归类门禁本该拦住）' }); continue }
+    if (r.action === 'skip') {
+      const d = skillDigest(r.src)
+      skills[r.name] = { digest: d.digest, files: d.files, version: r.version, installedAt: (readManifest(target)?.skills?.[r.name]?.installedAt) || now.toISOString(), updatedAt: now.toISOString() }
+      done.push({ ...r, ok: true, note: 'skipped（内容 sha 一致，幂等）' })
+      continue
+    }
+    let backup = null
+    if (r.action === 'update') {                                   // 覆盖前先备份（§P3① 的硬要求）
+      backup = join(backupRoot, `${r.name}-${stamp}`)
+      mkdirSync(backup, { recursive: true })
+      cpSync(join(target, r.name), backup, { recursive: true })
+    }
+    rmSync(join(target, r.name), { recursive: true, force: true })
+    cpSync(r.src, join(target, r.name), { recursive: true })
+    const d = skillDigest(join(target, r.name))
+    const prev = readManifest(target)?.skills?.[r.name]
+    skills[r.name] = { digest: d.digest, files: d.files, version: r.version, installedAt: prev?.installedAt || now.toISOString(), updatedAt: now.toISOString() }
+    done.push({ ...r, ok: true, backup, note: r.action === 'update' ? 'updated（已先备份再覆盖）' : 'installed' })
+  }
+  // 清单：保留**不在本次外发集**里但上次装过的条目？——不保留：它们已不该外发（归类门禁会先拦），
+  // 但卸载要能清掉 ⇒ 把"上次有、这次没有"的记进 `orphans` 供人决定（不静默删用户目录）。
+  const prevAll = readManifest(target)?.skills || {}
+  const orphans = Object.keys(prevAll).filter((k) => !skills[k])
+  const manifest = {
+    _doc: '本文件由 `node scripts/skill-install.mjs` 写入：外发技能清单 + 内容摘要（更新/卸载的判据）。删除它 = 卸载器找不到自己装过什么。',
+    host, target, argent: argentVersion, updatedAt: now.toISOString(),
+    declaration: { source: 'verticals/<id>/manifest.json#skills（唯一真源；安装器不自己维护名单）' },
+    skills, orphans,
+  }
+  writeFileSync(join(target, MANIFEST_NAME), `${JSON.stringify(manifest, null, 2)}\n`)
+  return { done, manifest }
+}
+
+/** 卸载：只删清单里列过的目录 + 清单本身（用户自建目录一个都不碰）。 */
+export function applyUninstall({ target, now = new Date() }) {
+  const man = readManifest(target)
+  if (!man) return { ok: false, reason: 'no_manifest', error: `目标目录里没有 ${MANIFEST_NAME}：${target}（没装过，或清单被删）⇒ 不敢猜哪些该删` }
+  if (man._corrupt) return { ok: false, reason: 'bad_manifest', error: `${MANIFEST_NAME} 不可解析 ⇒ 不敢猜哪些该删（人工确认后再删）` }
+  const removed = []
+  const kept = []
+  for (const name of Object.keys(man.skills || {})) {
+    const p = join(target, name)
+    if (existsSync(p)) { rmSync(p, { recursive: true, force: true }); removed.push(name) } else kept.push(`${name}（目录不在，仅清清单）`)
+  }
+  rmSync(join(target, MANIFEST_NAME), { force: true })
+  const leftovers = readdirSync(target).filter((n) => n !== BACKUP_DIRNAME)
+  return { ok: true, removed, kept, leftovers, at: now.toISOString(), backupDir: existsSync(join(target, BACKUP_DIRNAME)) ? join(target, BACKUP_DIRNAME) : null }
+}
+
+// ── 孤儿技能清理（--prune-orphans；**受守卫、默认 dry-run、逐项点名**）────────────────
+/** SKILL.md 的 frontmatter `name`（只用于**给人看**的提示；判据不依赖它 —— 它不是可信信号）。 */
+function frontmatterName(text) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(String(text || ''))
+  if (!m) return null
+  const v = /^\s*name\s*:\s*(.+?)\s*$/m.exec(m[1])
+  return v ? v[1].replace(/^["']|["']$/g, '') : null
+}
+
+/**
+ * **清理候选评估**（只读，纯路径参数）。四条件**同时**满足才进 `candidates`，缺一即进 `refused`。
+ *
+ * @param {{root?:string, target:string, allow?:string[]}} o
+ * @returns {{candidates:Array, refused:Array, notAllowed:Array, skipped:Array,
+ *            namedRefused:string[], missingAllow:string[], external:string[], internal:string[],
+ *            recorded:string[], targetExists:boolean}}
+ *   · `candidates`   = 满足四条件**且已点名**（`--allow`）⇒ 真删时会被删的那些；
+ *   · `notAllowed`   = 满足四条件但**没点名** ⇒ 一律不删（"未点名的绝不删"）；
+ *   · `refused`      = 四条件缺一 / 点开头 / 软链 ⇒ **连点名都不删**，逐条给原因；
+ *   · `namedRefused` = 你**点名了**但被拒绝（或根本不存在）的名字 ⇒ 命令无法被满足（非零退出）。
+ */
+export function planPrune({ root = REPO, target, allow = [] } = {}) {
+  const cls = externalSkills(root)
+  const ext = new Set(cls.external)
+  const int = new Set(cls.internal)
+  const man = readManifest(target)
+  const recorded = new Set(Object.keys((man && !man._corrupt && man.skills) || {}))
+  const allowSet = new Set(allow)
+  const candidates = []
+  const notAllowed = []
+  const refused = []
+  const skipped = []
+  const seen = new Set()
+  const targetExists = existsSync(target)
+  for (const e of targetExists ? readdirSync(target, { withFileTypes: true }) : []) {
+    const name = e.name
+    seen.add(name)
+    if (name.startsWith('.')) { skipped.push({ name, reason: '点开头（工具自管：清单 / 备份 / 审计）⇒ 不碰' }); continue }
+    const p = join(target, name)
+    // 软链**单独一档**：删它要么删链接、要么越界删到目标树 —— 两种都不是本动词该干的事
+    if (e.isSymbolicLink()) { refused.push({ name, path: p, reasons: ['软链：删除会越界或语义不明 ⇒ 一律不碰'] }); continue }
+    if (!e.isDirectory()) { refused.push({ name, path: p, reasons: ['非技能形态：不是目录（用户自建文件）⇒ 不碰'] }); continue }
+    const reasons = []
+    if (ext.has(name)) reasons.push('① 在外发集（业务线声明的流程技能 ⇒ 归同步/安装管，清理不碰）')
+    if (int.has(name)) reasons.push(`② 在 ${INTERNAL_MANIFEST}（内部角色技能 ⇒ 宿主上它还是"角色包已装"的判据）`)
+    if (recorded.has(name)) reasons.push(`③ 在安装器清单 ${MANIFEST_NAME} 里（本脚本装的 ⇒ 请用 --uninstall 收敛）`)
+    const hasSkillFile = existsSync(join(p, SKILL_FILE))
+    if (!hasSkillFile) reasons.push(`④ 目录内没有 ${SKILL_FILE}（不是技能形态 ⇒ 可能是用户自建，一律不碰）`)
+    if (reasons.length) { refused.push({ name, path: p, reasons }); continue }
+    const row = {
+      name, path: p, allowed: allowSet.has(name),
+      files: Object.keys(skillFiles(p)).length,
+      skillName: frontmatterName(readFileSync(join(p, SKILL_FILE), 'utf8')),
+    }
+    if (row.allowed) candidates.push(row); else notAllowed.push(row)
+  }
+  const refusedNames = new Set(refused.map((r) => r.name))
+  const namedRefused = allow.filter((n) => refusedNames.has(n))
+  const missingAllow = allow.filter((n) => !seen.has(n))
+  return {
+    candidates, refused, notAllowed, skipped, namedRefused, missingAllow, targetExists,
+    external: cls.external, internal: cls.internal, recorded: [...recorded].sort(),
+  }
+}
+
+/**
+ * **执行清理**（真删）：逐个 **先备份到 `<target>/.argent-skills-pruned-<ts>/<name>/` 再删**，
+ * 完成后追加一行审计 JSONL。只接受 `planPrune()` 给出的 `candidates`（调用方不得自己拼名字）。
+ *
+ * @returns {{removed:string[], failed:Array, backupDir:string|null, auditPath:string|null, at:string}}
+ */
+export function applyPrune({ target, candidates, host, now = new Date() }) {
+  const stamp = now.toISOString().replace(/[:.]/g, '-')
+  const rows = []
+  const removed = []
+  const failed = []
+  let backupDir = null
+  if (candidates.length) {
+    backupDir = join(target, `${PRUNE_BACKUP_PREFIX}${stamp}`)
+    mkdirSync(backupDir, { recursive: true })
+    for (const c of candidates) {
+      const dst = join(backupDir, c.name)
+      try {
+        cpSync(c.path, dst, { recursive: true })     // ① 先备份（可回滚）
+        rmSync(c.path, { recursive: true, force: true })  // ② 再删
+        removed.push(c.name)
+        rows.push({ name: c.name, ok: true, backup: dst })
+      } catch (e) {
+        failed.push({ name: c.name, error: e && e.message ? e.message : String(e) })
+        rows.push({ name: c.name, ok: false, error: e && e.message ? e.message : String(e) })
+      }
+    }
+    if (!removed.length) rmSync(backupDir, { recursive: true, force: true })   // 全失败 ⇒ 不留空备份目录
+  }
+  // 审计（沿用既有 JSONL 追加风格：一行一次动作，含目标/备份/删除/失败）
+  let auditPath = null
+  if (removed.length || failed.length) {
+    auditPath = join(target, PRUNE_AUDIT_NAME)
+    const row = {
+      at: now.toISOString(), verb: 'skill-install', action: 'prune-orphans', host: host || null, target,
+      removed, failed, backupDir,
+      rollback: backupDir ? `cp -R ${backupDir}/<name> ${target}/<name>` : null,
+    }
+    try { appendFileSync(auditPath, `${JSON.stringify(row)}\n`, { mode: 0o600 }) } catch { auditPath = null }
+  }
+  return { rows, removed, failed, backupDir, auditPath, at: now.toISOString() }
+}
+
+/** 清理结果的 JSON 载荷（dry-run 与真删共用一套字段名）。 */
+function pruneJson(plan, { refusedCount, unhonored, applied = null }) {
+  return {
+    dryRun: !applied,
+    candidates: plan.candidates.map((c) => c.name),
+    candidatesDetail: plan.candidates,
+    notAllowed: plan.notAllowed.map((c) => c.name),
+    notAllowedDetail: plan.notAllowed,
+    refused: plan.refused,
+    skipped: plan.skipped,
+    refusedCount,
+    namedRefused: plan.namedRefused,
+    missingAllow: plan.missingAllow,
+    unhonored,
+    external: plan.external, internal: plan.internal, recorded: plan.recorded,
+    removed: applied ? applied.removed : [],
+    failed: applied ? applied.failed : [],
+    backupDir: applied ? applied.backupDir : null,
+    auditPath: applied ? applied.auditPath : null,
+    criteria: [
+      '① 不在外发集（verticals/<id>/manifest.json#skills 并集）',
+      '② 不在 skills/internal.json（内部角色技能）',
+      `③ 不在安装器清单 ${MANIFEST_NAME}`,
+      `④ 目录内含 ${SKILL_FILE}`,
+    ],
+  }
+}
+
+/** 清理的人话输出（dry-run / 真删共用；`将删除 N 项（点名）/ 拒绝清理 M 项（原因）` 是固定口径）。 */
+function pruneHuman({ plan, target, host, refusedCount, dryRun, explicit = false, unhonored = [], applied = null }) {
+  const lines = [dryRun
+    ? `🧪 [dry-run${explicit ? '' : '（缺省动作：A3 安全态）'}] 技能清理预演（宿主 ${host} → ${target}）`
+    : `🧹 技能清理（宿主 ${host} → ${target}）`]
+  lines.push(`   将删除 ${plan.candidates.length} 项（点名）${plan.candidates.length ? `：${plan.candidates.map((c) => c.name).join('、')}` : '（未点名，或没有符合条件的项）'}`)
+  for (const c of plan.candidates) {
+    lines.push(`     · ${c.name}（${c.files} 个文件${c.skillName ? `；SKILL.md name=${c.skillName}` : '；SKILL.md 无 name'}）`)
+  }
+  if (plan.notAllowed.length) {
+    lines.push(`   未点名 ${plan.notAllowed.length} 项（**不删**；四条件都满足，要删请用 --allow 逐个点名）：${plan.notAllowed.map((c) => c.name).join('、')}`)
+  }
+  lines.push(`   拒绝清理 ${refusedCount} 项（原因）：`)
+  for (const c of plan.refused) lines.push(`     · ${c.name} — ${c.reasons.join('；')}`)
+  for (const c of plan.skipped) lines.push(`     · ${c.name} — ${c.reason}`)
+  if (refusedCount === 0) lines.push('     （无）')
+  if (unhonored.length) {
+    lines.push(`   ⚠️ 你点名了但**没有删**（四条件不满足或目录不存在）：${unhonored.join('、')}`)
+  }
+  if (applied) {
+    lines.push(`   已删除 ${applied.removed.length} 项${applied.removed.length ? `：${applied.removed.join('、')}` : ''}`)
+    if (applied.failed.length) lines.push(`   ❌ 失败 ${applied.failed.length} 项：${applied.failed.map((f) => `${f.name}（${f.error}）`).join('；')}`)
+    if (applied.backupDir) lines.push(`   备份（可回滚）：${applied.backupDir}　回滚 = \`cp -R <备份>/<name> <目标>/<name>\``)
+    if (applied.auditPath) lines.push(`   审计：${applied.auditPath}（JSONL，追加型）`)
+    lines.push(`   小结：已删除 ${applied.removed.length} 项（点名）/ 拒绝清理 ${refusedCount} 项（原因）`)
+  } else {
+    lines.push('   ⛔ 未删任何目录（真删：`--apply --allow <name>`，逐个点名）')
+    lines.push(`   小结：将删除 ${plan.candidates.length} 项（点名）/ 拒绝清理 ${refusedCount} 项（原因）`)
+  }
+  return lines.join('\n')
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+const USAGE = [
+  '用法：node scripts/skill-install.mjs --host <dsh|claude-code|codex|cursor> [--list|--dry-run|--apply|--uninstall]',
+  '       [--dir <path>] [--json]',
+  '       node scripts/skill-install.mjs --host <宿主> --prune-orphans [--apply --allow <name> …] [--dir <path>] [--json]',
+  '',
+  '只装**外发白名单**技能（= 所有 verticals/<id>/manifest.json#skills 的并集，今天 5 个流程技能）。',
+  '  · --list      只看：宿主约定目录 + 外发清单 + 目标目录现状（不写盘）',
+  '  · --dry-run   / **缺省**  只看计划（install/skip/update），不写盘（A3：write 类默认安全态）',
+  '  · --apply     执行安装（sha 一致 ⇒ skipped；不一致 ⇒ 先备份再覆盖）',
+  '  · --uninstall 只删清单里列过的技能目录与清单本身（用户自建目录不碰）',
+  '  · --dir <path> 覆盖宿主约定目录（约定查不到/不适用时的兜底）',
+  '',
+  '孤儿技能清理（**人工确认**；客户机 6 内部 + 12 旧 hermes 期那类残留）：',
+  '  · --prune-orphans       列出「将删除（点名）/ 未点名（不删）/ 拒绝清理」三张清单；**缺省 dry-run**',
+  '  · --apply --allow <n>   真删：**必须逐个点名**（可重复）；未点名的**绝不删**；先备份再删 + 写审计',
+  '  · --allow-host-dsh-prune  `--host dsh` 下清理的显式放行（或改用 `--dir <path>` 显式给目标）',
+  '  · 只删**四条件同时满足**的目录：① 不在外发集 ② 不在 skills/internal.json ③ 不在安装器清单',
+  '    ④ 目录内含 SKILL.md；用户自建（非技能形态 / 点开头 / 软链）一律不碰并列入"拒绝清理"',
+  '',
+  '⛔ `--host dsh --apply`（装）被拒绝（dsh 侧走原路：preset 挂载 + scripts/argent-upgrade.mjs）；',
+  '   确要装到别处请用 `--host dsh --dir <path>`。清理同理：加 `--dir` 或 `--allow-host-dsh-prune`。',
+].join('\n')
+
+function parseArgs(argv) {
+  // A3：**缺省即 dry-run**（真装要显式 --apply）；`--dry-run` 是它的显式同义。
+  const o = { host: null, dir: null, action: 'dry-run', json: false, help: false, pruneOrphans: false, allow: [], allowHostDshPrune: false }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') { o.json = true; continue }
+    if (a === '-h' || a === '--help') { o.help = true; continue }
+    if (a === '--host' || a === '--host=') { const v = argv[++i]; if (!v || v.startsWith('--')) return { ok: false, error: '--host 缺值' }; o.host = v; continue }
+    if (a === '--dir' || a === '--target') { const v = argv[++i]; if (!v || v.startsWith('--')) return { ok: false, error: `${a} 缺值` }; o.dir = v; continue }
+    if (a === '--list') { o.action = 'list'; continue }
+    if (a === '--dry-run') { o.action = 'dry-run'; o.explicitDryRun = true; continue }
+    if (a === '--apply') { o.action = 'install'; continue }
+    if (a === '--uninstall' || a === 'remove' || a === '--remove') { o.action = 'uninstall'; continue }
+    if (a === '--prune-orphans' || a === '--prune') { o.pruneOrphans = true; continue }
+    if (a === '--allow-host-dsh-prune') { o.allowHostDshPrune = true; continue }
+    if (a === '--allow' || a === '--allow=') {
+      const v = argv[++i]
+      if (!v || v.startsWith('--')) return { ok: false, error: '--allow 缺值（要逐个点名，可重复）' }
+      // 允许 `--allow a,b` 逗号形态（人懒得敲多次），但仍**逐个**进名单 ⇒ 每个都显式
+      for (const n of String(v).split(',').map((s) => s.trim()).filter(Boolean)) o.allow.push(n)
+      continue
+    }
+    return { ok: false, error: `未知参数：${a}` }
+  }
+  return { ok: true, ...o }
+}
+
+function main(argv) {
+  const p = parseArgs(argv)
+  if (!p.ok) return { code: 2, human: `❌ usage_error：${p.error}\n${USAGE}`, json: { ok: false, empty: false, code: 2, reason: 'usage_error', error: p.error, verb: 'skill-install' } }
+  if (p.help) return { code: 0, human: USAGE, json: { ok: true, empty: false, code: 0, reason: null, verb: 'skill-install', usage: USAGE } }
+  if (!p.host) return { code: 2, human: `❌ usage_error：缺必填参数 --host（可用：${HOST_IDS.join('、')}）\n${USAGE}`, json: { ok: false, empty: false, code: 2, reason: 'usage_error', error: '缺 --host', hosts: HOST_IDS, verb: 'skill-install' } }
+  if (!HOST_IDS.includes(p.host)) return { code: 2, human: `❌ unknown_host：未知宿主 ${p.host}（可用：${HOST_IDS.join('、')}）`, json: { ok: false, empty: false, code: 2, reason: 'unknown_host', error: `未知宿主 ${p.host}`, hosts: HOST_IDS, verb: 'skill-install' } }
+
+  const table = hostTable({ dshHome: process.env.DSH_HOME || '' })
+  const host = table[p.host]
+  const target = p.dir ? resolve(p.dir) : host.dir
+  const cls = externalSkills(REPO)
+  const argent = (() => { try { return readFileSync(join(REPO, 'VERSION'), 'utf8').trim() } catch { return null } })()
+
+  const base = {
+    host: p.host, target, dirSource: p.dir ? 'explicit(--dir)' : 'host-convention',
+    hostVerified: host.verified, hostEvidence: host.evidence,
+    external: cls.external, internal: cls.internal, unclassified: cls.unclassified,
+    argent, action: p.action,
+  }
+
+  // 归类门禁：不过 ⇒ **拒绝安装**（外发泄露内部角色是本阶段唯一高危项）
+  if (!cls.ok) {
+    return {
+      code: 1,
+      human: `❌ 归类门禁不通过 ⇒ 拒绝安装（宁可不装，不可装错）：\n${cls.errors.map((e) => `   · [${e.rule}] ${e.message}`).join('\n')}`,
+      json: { ok: false, empty: false, code: 1, reason: 'skill_unclassified', error: cls.errors.map((e) => `[${e.rule}] ${e.message}`).join('；'), verb: 'skill-install', ...base },
+    }
+  }
+  if (!cls.external.length) {
+    return {
+      code: 0,
+      human: '（外发集为空：没有任何业务线声明流程技能 ⇒ 无事可做）',
+      json: { ok: true, empty: true, code: 0, reason: 'no_skill_declared', verb: 'skill-install', ...base, skills: [] },
+    }
+  }
+
+  // ── 孤儿技能清理（--prune-orphans）：受守卫、**缺省 dry-run**、真删要逐个点名 ──────────
+  if (p.pruneOrphans) {
+    if (p.action === 'list' || p.action === 'uninstall') {
+      const err = `--prune-orphans 与 --list/--uninstall 互斥（清理有自己的清单口径，混用会让人读错）`
+      return { code: 2, human: `❌ usage_error：${err}`, json: { ok: false, empty: false, code: 2, reason: 'usage_error', error: err, verb: 'skill-install', ...base } }
+    }
+    if (host.ownsInstall && !p.dir && !p.allowHostDshPrune) {
+      const err = '`--host dsh` 的技能**清理**同样不抢原路（技能根归 presets + `scripts/argent-upgrade.mjs`）'
+        + ' ⇒ 客户机清理请显式二选一：`--dir <path>`（推荐：目标写死、看得见）或 `--allow-host-dsh-prune`（承认你在动宿主技能根）'
+      return { code: 2, human: `⛔ host_owns_prune：${err}`, json: { ok: false, empty: false, code: 2, reason: 'host_owns_prune', error: err, verb: 'skill-install', ...base } }
+    }
+    const applyIt = p.action === 'install'      // `--apply`（清理语境 = 真删）
+    if (applyIt && !p.allow.length) {
+      const err = '真删必须**逐个点名**：`--apply --allow <name>`（可重复）；未点名的一律不删（防"一条命令清一片"）'
+      return { code: 2, human: `❌ allow_required：${err}`, json: { ok: false, empty: false, code: 2, reason: 'allow_required', error: err, verb: 'skill-install', ...base } }
+    }
+    if (!existsSync(target)) {
+      return { code: 2, human: `❌ target_missing：目标目录不存在：${target}`, json: { ok: false, empty: true, code: 2, reason: 'target_missing', error: `目标目录不存在：${target}`, verb: 'skill-install', ...base } }
+    }
+    const plan = planPrune({ root: REPO, target, allow: p.allow })
+    const refusedCount = plan.refused.length + plan.skipped.length
+    const unhonored = [...plan.namedRefused, ...plan.missingAllow]
+    if (!applyIt) {
+      return {
+        code: unhonored.length ? 1 : 0,
+        human: pruneHuman({ plan, target, host: p.host, refusedCount, dryRun: true, explicit: p.explicitDryRun, unhonored }),
+        json: {
+          ok: true, empty: plan.candidates.length === 0, code: unhonored.length ? 1 : 0,
+          reason: unhonored.length ? 'named_not_prunable' : null, verb: 'skill-install', ...base,
+          dryRun: true,
+          prune: pruneJson(plan, { refusedCount, unhonored }),
+        },
+      }
+    }
+    const r = applyPrune({ target, candidates: plan.candidates, host: p.host })
+    const code = (r.failed.length || unhonored.length) ? 1 : 0
+    return {
+      code,
+      human: pruneHuman({ plan, target, host: p.host, refusedCount, dryRun: false, unhonored, applied: r }),
+      json: {
+        ok: code === 0, empty: plan.candidates.length === 0, code,
+        reason: r.failed.length ? 'prune_failed' : (unhonored.length ? 'named_not_prunable' : null),
+        verb: 'skill-install', ...base,
+        dryRun: false,
+        prune: pruneJson(plan, { refusedCount, unhonored, applied: r }),
+        removed: r.removed, failed: r.failed.map((f) => f.name), backupDir: r.backupDir, auditPath: r.auditPath,
+      },
+    }
+  }
+
+  if (p.action === 'list') {
+    const lines = ['📦 技能外发清单（P3）', `   宿主：${p.host}（目标 ${target}；目录来源=${base.dirSource}；证据：${host.verified}）`,
+      `     · ${host.evidence}`, `   外发 ${cls.external.length} 个（真源：${cls.sources.map((s) => `verticals/${s.vertical}/manifest.json#skills`).join('、')}）：`]
+    for (const name of cls.external) {
+      const v = frontmatterVersion(readFileSync(join(REPO, 'skills', name, SKILL_FILE), 'utf8'))
+      lines.push(`     · ${name}${v ? `（v${v}）` : ''} —— skills/${name}/`)
+    }
+    lines.push(`   内部 ${cls.internal.length} 个**不外发**（${INTERNAL_MANIFEST}）：${cls.internal.join('、')}`)
+    const man = readManifest(target)
+    lines.push(`   目标目录现状：${existsSync(target) ? `${readdirSync(target).length} 项` : '不存在'}${man && !man._corrupt ? `｜已装 ${Object.keys(man.skills || {}).length} 个（${MANIFEST_NAME}）` : `｜无 ${MANIFEST_NAME}`}`)
+    return { code: 0, human: lines.join('\n'), json: { ok: true, empty: false, code: 0, reason: null, verb: 'skill-install', ...base, skills: cls.external, manifestPresent: Boolean(man) } }
+  }
+
+  if (p.action === 'uninstall') {
+    if (!existsSync(target)) return { code: 2, human: `❌ target_missing：目标目录不存在：${target}（没装过 ⇒ 无可卸载）`, json: { ok: false, empty: true, code: 2, reason: 'target_missing', error: `目标目录不存在：${target}`, verb: 'skill-install', ...base } }
+    const r = applyUninstall({ target })
+    if (!r.ok) return { code: 2, human: `❌ ${r.reason}：${r.error}`, json: { ok: false, empty: false, code: 2, reason: r.reason, error: r.error, verb: 'skill-install', ...base } }
+    const human = [`🧹 已卸载 ${r.removed.length} 个技能（只删清单里列过的）：${r.removed.join('、') || '（无）'}`,
+      r.kept.length ? `   清单里但目录不在：${r.kept.join('、')}` : null,
+      `   目标目录剩余 ${r.leftovers.length} 项（用户自建文件/目录**一个都没碰**）：${r.leftovers.join('、') || '（空）'}`,
+      r.backupDir ? `   备份目录保留（如需回滚可用）：${r.backupDir}` : null,
+    ].filter(Boolean).join('\n')
+    return { code: 0, human, json: { ok: true, empty: r.removed.length === 0, code: 0, reason: r.removed.length ? null : 'no_match', verb: 'skill-install', ...base, removed: r.removed, kept: r.kept, leftovers: r.leftovers, backupDir: r.backupDir } }
+  }
+
+  // dsh 宿主的安装权归原路（§P3① 的实施约束）——除非显式 --dir
+  if (host.ownsInstall && !p.dir && p.action === 'install') {
+    const err = 'dsh 宿主的技能安装权归**原路**（`presets/*/agent.cordis.yml` 的 skill-filesystem 挂载 + `scripts/argent-upgrade.mjs`）'
+      + ' ⇒ 本脚本不抢安装权，只做 `--list` / `--dry-run` 一致性校验；确要装到别处请用 `--host dsh --dir <path>`'
+    return { code: 2, human: `⛔ host_owns_install：${err}`, json: { ok: false, empty: false, code: 2, reason: 'host_owns_install', error: err, verb: 'skill-install', ...base } }
+  }
+
+  const plan = planInstall({ root: REPO, target, skills: cls.external })
+  if (p.action === 'dry-run') {
+    const human = [`🧪 [dry-run${p.explicitDryRun ? '' : '（缺省动作：A3 安全态）'}] 技能安装计划（宿主 ${p.host} → ${target}）`,
+      ...plan.rows.map((r) => `   · ${r.name.padEnd(24)} ${r.action}${r.action === 'skip' ? '（内容 sha 一致，幂等跳过）' : r.action === 'update' ? '（不一致 ⇒ 先备份再覆盖）' : ''}`),
+      '   ⛔ 未写任何文件（真装加 --apply）'].join('\n')
+    return { code: 0, human, json: { ok: true, empty: false, code: 0, reason: null, verb: 'skill-install', ...base, dryRun: true, plan: plan.rows, willWrite: plan.rows.filter((r) => r.action !== 'skip').map((r) => r.dst) } }
+  }
+
+  const { done, manifest } = applyInstall({ root: REPO, target, rows: plan.rows, host: p.host, argentVersion: argent })
+  const failed = done.filter((d) => !d.ok)
+  const human = [`📦 技能安装（宿主 ${p.host} → ${target}）`,
+    ...done.map((d) => `   · ${d.name.padEnd(24)} ${d.ok ? d.action : '❌ failed'}${d.backup ? `（备份 ${d.backup}）` : ''} ${d.note}`),
+    `   清单：${join(target, MANIFEST_NAME)}（记录 ${Object.keys(manifest.skills).length} 个技能的内容摘要；更新/卸载读它）`,
+    `   ⛔ 未触碰目标目录里用户自建的文件/目录`].join('\n')
+  return {
+    code: failed.length ? 1 : 0,
+    human,
+    json: {
+      ok: failed.length === 0, empty: done.length === 0, code: failed.length ? 1 : 0,
+      reason: failed.length ? 'install_failed' : null, verb: 'skill-install', ...base,
+      installed: done.filter((d) => d.action === 'install' && d.ok).map((d) => d.name),
+      updated: done.filter((d) => d.action === 'update' && d.ok).map((d) => d.name),
+      skipped: done.filter((d) => d.action === 'skip').map((d) => d.name),
+      failed: failed.map((d) => ({ name: d.name, note: d.note })),
+      manifest: { path: join(target, MANIFEST_NAME), skills: Object.keys(manifest.skills), orphans: manifest.orphans },
+      results: done,
+    },
+  }
+}
+
+if (isDirectRun(import.meta.url)) {
+  const { code, human, json } = main(process.argv.slice(2))
+  if (process.argv.includes('--json')) console.log(JSON.stringify(json, null, 2))
+  else console.log(human)
+  process.exit(code)
+}