@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/lib/agent-install.mjs

@@ -0,0 +1,649 @@
+/**
+ * agent-install —— **界面内的「安装 / 升级 / 重装智能体」的唯一实现**（0.6.0 W7，2026-10-13）。
+ *
+ * ## 它是什么 / 不是什么（本文件的口径就是 W7 的契约 §3.1.3 第 8 条）
+ * **是**：① 智能体货架的**只读状态投影**（装了没 / 版本落后没 / 需不需要升级）；
+ *       ② **许可证前置**的服务端判定（`GET /api/argent/entitlements`，拿不到 ⇒ 拒绝，⛔ 不放行）；
+ *       ③ 以**子进程调用安装器本体**（`install-argent.mjs --agent <id>`）——**安装链只有那一份**；
+ *       ④ 装完的**只读收尾核对**（bundle 在依赖图内 / presets 是**直接依赖**且在 bundles 条目里 /
+ *          能力包按包内声明落位 / 角色与技能按声明落位）。
+ * **不是**：⛔ 不重写任何安装步骤（不自己拼 `dsh plugin add`、不自己写 package.json、
+ *       ⛔ 不自己装能力包）——那就是"第二套链"，正是本批明令禁止的。
+ *
+ * ## 为什么"复用"落成"调用安装器本体"而不是"把安装器的函数抽出来 import"
+ * `install-argent.mjs` 是**单文件分发物**（官网那行 `node install-argent.mjs` 只下一个文件）⇒
+ * 它里面的每一步都跑在模块级状态（`PLUGIN_REGISTRATION` / `AGENT_BUNDLES` / `PRESET_LANDING` /
+ * 借到的包管理器 shim / 落盘账本…）之上。把这条链"抽成可 import 的函数"要么改掉它的分发形态、
+ * 要么在插件里复制一遍它的状态机 —— 两者都比"**调用同一个可执行体**"更容易制造出第二份实现。
+ * 判据（可复核）：本文件里**没有任何** `dsh plugin add` / `pnpm add` / 能力包落盘代码；
+ *   唯一的写动作是 `spawn(process.execPath, [install-argent.mjs, '--agent', id, …])`。
+ *
+ * ## 幂等
+ * 已装且版本一致 ⇒ **零写入**（不 spawn、不碰任何文件），直接回「已是最新」。
+ * 升级/重装 ⇒ 只动该智能体相关面（安装器 `--agent` 的语义）。
+ *
+ * ## 纪律
+ * 纯 node 内建 + 同树 L1 模块（`scripts/argent-agents.mjs` / `scripts/lib/preset-install.mjs`）
+ * ⇒ ⛔ 零宿主 import（kernel-purity 管的就是这条）。所有函数**无模块级副作用**（可安全 import）。
+ *
+ * 测试：`scripts/tests/agent-ui-install.test.mjs`
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { spawn as nodeSpawn } from 'node:child_process'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { loadCatalog } from '../argent-agents.mjs'
+import { resolveBundleDir, SELECTION_FILE } from './preset-install.mjs'
+import { npmNameOf } from './plugin-packages.mjs'
+// 数据目录（`whyshu.env` 落点）的**唯一判据**在内核 —— ⛔ 本文件不另写一条链
+// （argent-datadir 门禁：`ARGENT_DATA_DIR ||` / `join('.dsh','argent')` 命中即红）。
+import { resolveDataDir } from './argent-datadir.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+/** 本文件所在仓库根（`scripts/lib/` → 仓库根）。 */
+export const REPO = resolve(HERE, '..', '..')
+
+/** 智能体 bundle 的 npm 名前缀（唯一真源仍是包自己的 `package.json#name`，这里只用于**找目录**）。 */
+export const AGENT_DIR_PREFIX = 'argent-agent-'
+/** 角色承载 bundle 的 npm 名 —— W7 的硬判据：它必须是 profile 的**直接依赖**且在 bundles 条目里。 */
+export const PRESETS_NPM = npmNameOf('argent-presets') || '@whyshu/argent-presets'
+/** 服务端判定端点（与安装器 `install-ticket` 同一身份：账号令牌 Bearer）。 */
+export const ENTITLEMENTS_PATH = '/api/argent/entitlements'
+/** 服务端基址：`ARGENT_API_BASE` → `whyshu.env#WHYSHU_API_URL` → 官方站点。 */
+export const DEFAULT_API_BASE = 'https://whyshu.com'
+
+const readJsonSafe = (p, d = null) => { try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return d } }
+const isStr = (x) => typeof x === 'string' && x.trim() !== ''
+
+/**
+ * 仓库根候选（与宿主侧既有的目录脚本解析**同一顺位**：就近优先 → 显式覆盖 → 安装克隆 → 开发仓库；
+ * 见 `plugins/argent-core/src/index.js#configRepoRoot` 与 `src/agent-install.mjs#repoRootCandidates`）。
+ * 判据 = 该根下同时有 `agents/catalog.json` 与 `scripts/lib/agent-install.mjs`。
+ * @returns {string|null} 找不到 ⇒ null（调用方**响亮**报错，⛔ 不猜）
+ */
+export function resolveRepoRoot({ startDir = HERE, env = process.env, home = homedir(), exists = existsSync } = {}) {
+  const cands = [
+    startDir,
+    env.ARGENT_DSH_REPO || '',
+    env.ARGENT_DISH_HOME || '',
+    join(home, '.argent-dsh'),
+    join(home, 'Code', 'argent-dsh'),
+  ].filter(Boolean)
+  const marker = (r) => exists(join(r, 'agents', 'catalog.json')) && exists(join(r, 'scripts', 'lib', 'agent-install.mjs'))
+  for (const r of cands) { try { if (marker(r)) return r } catch { /* 试下一个 */ } }
+  return null
+}
+
+/** 智能体 bundle 的目录（`<repo>/plugins/argent-agent-<id>`；没有 ⇒ null）。 */
+export function agentBundleDir({ repo, id }) {
+  const d = join(repo, 'plugins', `${AGENT_DIR_PREFIX}${String(id)}`)
+  return existsSync(join(d, 'package.json')) ? d : null
+}
+
+/**
+ * 读**包内声明**（`package.json#argent.agent`）——与安装器读的是**同一个字段**（⛔ 不读第二份映射）。
+ * @returns {{id:string,dir:string,name:string,version:string,decl:object}|null}
+ */
+export function readAgentBundle({ repo, id }) {
+  const dir = agentBundleDir({ repo, id })
+  if (!dir) return null
+  const m = readJsonSafe(join(dir, 'package.json'), null)
+  const decl = m && m.argent && m.argent.agent
+  if (!m || !decl || typeof decl !== 'object') return null
+  if (String(decl.id || '') !== String(id)) return null
+  return { id: String(id), dir, name: String(m.name || ''), version: String(m.version || ''), decl }
+}
+
+/**
+ * 货架（`agents/catalog.json`）⋈ 包内声明 ⇒ "本机可装的智能体"。
+ * 目录读不到 / 包缺失 ⇒ 如实进 `errors`（⛔ 不静默少几条 —— 少一条就会让"缺件"看起来像"没这个商品"）。
+ * @returns {{agents: object[], errors: string[]}}
+ */
+export function loadAgentShelf({ repo }) {
+  const errors = []
+  const doc = loadCatalog(repo)
+  if (!doc || !Array.isArray(doc.agents)) {
+    return { agents: [], errors: [`读不到智能体货架（${join(repo, 'agents/catalog.json')}）`] }
+  }
+  const agents = []
+  for (const a of doc.agents) {
+    if (!a || !isStr(a.id)) continue
+    const bundle = readAgentBundle({ repo, id: a.id })
+    if (!bundle) { errors.push(`智能体 \`${a.id}\` 在本机克隆里没有对应的 agent bundle（plugins/${AGENT_DIR_PREFIX}${a.id}）`); continue }
+    if (bundle.name !== `@whyshu/${AGENT_DIR_PREFIX}${a.id}`) {
+      errors.push(`智能体 \`${a.id}\` 的包名不是 \`@whyshu/${AGENT_DIR_PREFIX}${a.id}\`（实得 ${bundle.name || '（空）'}）`)
+      continue
+    }
+    const payload = (bundle.decl && bundle.decl.payload) || {}
+    agents.push({
+      id: String(a.id),
+      title: String(a.title || a.id),
+      summary: String(a.summary || ''),
+      minPlan: String(a.minPlan || ''),
+      capabilities: (Array.isArray(payload.capabilities) ? payload.capabilities : []).map(String),
+      roles: (Array.isArray(bundle.decl.roles) ? bundle.decl.roles : []).map(String),
+      skills: (Array.isArray(bundle.decl.skills) ? bundle.decl.skills : []).map(String),
+      scheduler: bundle.decl.scheduler === true,
+      name: bundle.name,
+      bundleVersion: bundle.version,
+    })
+  }
+  return { agents, errors }
+}
+
+/** 装机账本（`<dshHome>/argent/agents.json`）里已装的智能体 id。 */
+export function installedAgentIds({ dshHome }) {
+  const doc = readJsonSafe(join(dshHome, 'argent', 'agents.json'), null)
+  return (doc && Array.isArray(doc.agents) ? doc.agents : []).map((a) => a && a.id).filter(Boolean).map(String)
+}
+
+/** profile 落点（默认 `web`）。 */
+export function profileDirOf({ dshHome, profile = 'web' }) {
+  return join(dshHome, 'profiles', profile)
+}
+
+/** profile `package.json`（缺 ⇒ `{dependencies:{}, dsh:{profile:{bundles:[]}}}`）。 */
+export function readProfileManifest({ dshHome, profile = 'web' }) {
+  const pkgPath = join(profileDirOf({ dshHome, profile }), 'package.json')
+  const pkg = readJsonSafe(pkgPath, null) || {}
+  const deps = (pkg && pkg.dependencies) || {}
+  const bundles = ((pkg.dsh || {}).profile || {}).bundles
+  return { pkgPath, exists: existsSync(pkgPath), pkg, deps, bundles: Array.isArray(bundles) ? bundles : [] }
+}
+
+/** 一个包在 profile 里**落地的那份**（`node_modules/<name>/package.json`）。 */
+export function readLandedPackage({ dshHome, profile = 'web', name }) {
+  if (!isStr(name)) return null
+  return readJsonSafe(join(profileDirOf({ dshHome, profile }), 'node_modules', ...String(name).split('/'), 'package.json'), null)
+}
+
+/**
+ * **本机每个智能体的现状**（纯只读）。
+ * `state` 四态：`absent`（没装）/ `up-to-date`（已装且版本一致）/ `upgrade`（已装但版本落后）/
+ * `unknown`（装了但读不出落地版本 —— 也算"可重装"，但**不假装知道**版本差）。
+ * @returns {{agents: object[], errors: string[]}}
+ */
+export function agentRuntimeStatus({ repo, dshHome, profile = 'web' }) {
+  const shelf = loadAgentShelf({ repo })
+  const installed = new Set(installedAgentIds({ dshHome }))
+  const { deps } = readProfileManifest({ dshHome, profile })
+  const agents = shelf.agents.map((a) => {
+    const inDeps = !!deps[a.name]
+    const landed = readLandedPackage({ dshHome, profile, name: a.name })
+    const installedVersion = landed && isStr(landed.version) ? String(landed.version) : ''
+    const isInstalled = installed.has(a.id) || inDeps
+    const state = !isInstalled ? 'absent'
+      : !installedVersion ? 'unknown'
+        : installedVersion === String(a.bundleVersion) ? 'up-to-date' : 'upgrade'
+    return {
+      ...a,
+      installed: isInstalled,
+      inDependencies: inDeps,
+      installedVersion,
+      state,
+      /** 界面按钮的**唯一文案判据**（⛔ 前端不自己算）。 */
+      action: state === 'up-to-date' ? 'reinstall' : state === 'absent' ? 'install' : 'upgrade',
+    }
+  })
+  return { agents, errors: shelf.errors }
+}
+
+/**
+ * 动作 ⇒ 是否**短路**（幂等：已是最新且不是"重装" ⇒ 零写入）。判据只有这一处。
+ * @returns {{shortCircuit: boolean, message: string}}
+ */
+export function shortCircuitFor({ status, action }) {
+  if (action === 'reinstall') return { shortCircuit: false, message: '' }
+  if (status && status.state === 'up-to-date') {
+    return { shortCircuit: true, message: `已是最新（v${status.installedVersion}）——本次不做任何写入` }
+  }
+  return { shortCircuit: false, message: '' }
+}
+
+// ── 许可证前置（服务端判定）────────────────────────────────────────────
+
+/**
+ * 数据目录（`whyshu.env` 的落点）—— **委托内核的同一判据**（⛔ 不在这里重写三级链）。
+ * @returns {string}
+ */
+export function dataDirFor({ dshHome, env = process.env } = {}) {
+  const e = { ...env }
+  if (isStr(dshHome)) e.DSH_HOME = String(dshHome)
+  try { return resolveDataDir({ env: e }).dir } catch { return '' }
+}
+
+/** 读 `whyshu.env` 里的一个键（落点由内核判据给定；⛔ 不猜路径）。 */
+function readWhyShuEnvKey(key, { dshHome, env = process.env } = {}) {
+  const dir = dataDirFor({ dshHome, env })
+  if (!dir) return ''
+  const f = join(dir, 'whyshu.env')
+  if (!existsSync(f)) return ''
+  try {
+    const m = new RegExp(`^\\s*${key}\\s*=\\s*(.+?)\\s*$`, 'm').exec(readFileSync(f, 'utf8'))
+    return m && isStr(m[1]) ? m[1].replace(/^["']|["']$/g, '') : ''
+  } catch { return '' }
+}
+
+/**
+ * 账号令牌：`env.WHYSHU_API_KEY` → `<数据目录>/whyshu.env` → `<dshHome>/.credentials.yaml#refs`。
+ * ⛔ 只读；⛔ 绝不回写（写凭据的唯一入口是 dsh 官方 API / argent-core）。
+ * @returns {string} 找不到 ⇒ ''
+ */
+export function readAccountToken({ dshHome, env = process.env } = {}) {
+  if (isStr(env.WHYSHU_API_KEY)) return String(env.WHYSHU_API_KEY).trim()
+  const fromEnvFile = readWhyShuEnvKey('WHYSHU_API_KEY', { dshHome, env })
+  if (fromEnvFile) return fromEnvFile
+  const dh = isStr(dshHome) ? String(dshHome) : (isStr(env.DSH_HOME) ? String(env.DSH_HOME) : join(homedir(), '.dsh'))
+  const cred = join(dh, '.credentials.yaml')
+  if (existsSync(cred)) {
+    try {
+      // `version + refs + records` 三段格式：**只**在 `refs:` 段里按缩进取值（⛔ 不碰 records、⛔ 不重写）。
+      let inRefs = false
+      for (const line of readFileSync(cred, 'utf8').split('\n')) {
+        if (/^refs:\s*$/.test(line)) { inRefs = true; continue }
+        if (inRefs && /^\S/.test(line)) break          // 回到顶层键 ⇒ refs 段结束
+        if (!inRefs) continue
+        const m = /^\s+WHYSHU_API_KEY\s*:\s*(.+?)\s*$/.exec(line)
+        if (m && isStr(m[1])) return m[1].replace(/^["']|["']$/g, '')
+      }
+    } catch { /* 读不到 ⇒ 继续 */ }
+  }
+  return ''
+}
+
+/** 服务端基址（`ARGENT_API_BASE` → `whyshu.env#WHYSHU_API_URL` → 官方站点）。 */
+export function resolveApiBase({ dshHome, env = process.env } = {}) {
+  if (isStr(env.ARGENT_API_BASE)) return String(env.ARGENT_API_BASE).replace(/\/+$/, '')
+  const url = readWhyShuEnvKey('WHYSHU_API_URL', { dshHome, env })
+  return url ? url.replace(/\/+$/, '') : DEFAULT_API_BASE
+}
+
+/**
+ * 向服务端要**一次许可证/档位判定**（`GET /api/argent/entitlements`）。
+ * ⛔ 判据不可得（没令牌 / 网络失败 / 非 200 / 载荷不是对象）⇒ `{ok:false}` —— 调用方**必须拒绝**。
+ * @returns {Promise<{ok:boolean, reason:string, entitlement?:object, http?:number}>}
+ */
+export async function fetchEntitlement({ dshHome, env = process.env, fetchImpl = globalThis.fetch, timeoutMs = 8000 } = {}) {
+  const token = readAccountToken({ dshHome, env })
+  if (!token) {
+    return { ok: false, reason: '没有账号令牌（WHYSHU_API_KEY / `~/.dsh/argent/whyshu.env` / `~/.dsh/.credentials.yaml#refs` 都没有）' }
+  }
+  if (typeof fetchImpl !== 'function') return { ok: false, reason: '本机 Node 没有 fetch（无法向服务端要判定）' }
+  const base = resolveApiBase({ dshHome, env })
+  const ac = typeof AbortController === 'function' ? new AbortController() : null
+  const timer = ac ? setTimeout(() => ac.abort(), timeoutMs) : null
+  try {
+    const resp = await fetchImpl(`${base}${ENTITLEMENTS_PATH}`, {
+      method: 'GET',
+      headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+      signal: ac ? ac.signal : undefined,
+    })
+    if (!resp || !resp.ok) {
+      const code = resp ? resp.status : '?'
+      let detail = ''
+      try { detail = String(await resp.text()).slice(0, 200) } catch { /* 无正文 */ }
+      return { ok: false, reason: `服务端判定不可得：GET ${base}${ENTITLEMENTS_PATH} ⇒ HTTP ${code}${detail ? `（${detail}）` : ''}`, http: code }
+    }
+    const doc = await resp.json()
+    if (!doc || typeof doc !== 'object') return { ok: false, reason: '服务端判定不可得：载荷不是对象' }
+    if (doc.ok === false) return { ok: false, reason: `服务端判定不可得：${String(doc.error || doc.reason || '未知')}`, entitlement: doc }
+    return { ok: true, reason: '', entitlement: doc }
+  } catch (e) {
+    return { ok: false, reason: `服务端判定不可得：${String((e && e.message) || e)}` }
+  } finally {
+    if (timer) clearTimeout(timer)
+  }
+}
+
+const PLAN_RANK = { free: 0, pro: 1, enterprise: 2 }
+
+/**
+ * 判定某个智能体在当前账号下**能不能装**（判据全部来自服务端载荷，⛔ 前端零档位名单）。
+ * 三态：`allowed` true/false + `reason`（false 时**必须**是可照抄的原因）。
+ * @returns {{allowed:boolean, reason:string, needPlan:string, plan:string}}
+ */
+export function judgeEntitlement({ agent, entitlement }) {
+  if (!entitlement || typeof entitlement !== 'object') return { allowed: false, reason: '没有服务端判定（内部错误）', needPlan: agent.minPlan || '', plan: '' }
+  const plan = String(entitlement.plan || '')
+  const needPlan = String(agent.minPlan || '')
+  // ① 许可过期（服务端明确说 license_expired）⇒ 拒
+  if (entitlement.licenseActive === false) {
+    return { allowed: false, reason: `许可证未生效/已过期（服务端 reason=${String(entitlement.reason || 'license_expired')}）`, needPlan, plan }
+  }
+  // ② 档位：packs 的 unlocked 是服务端口径；再补一条"账号档位 < 智能体档位"的兜底（两处**都取自载荷**）
+  if (needPlan && PLAN_RANK[plan] !== undefined && PLAN_RANK[plan] < (PLAN_RANK[needPlan] || 0)) {
+    return { allowed: false, reason: `未达档位：该智能体需要 ${needPlan}，当前账号 ${plan}`, needPlan, plan }
+  }
+  // ③ 逐能力：服务端 packs[] 里的 unlocked
+  const packs = Array.isArray(entitlement.packs) ? entitlement.packs : []
+  const caps = Array.isArray(agent.capabilities) ? agent.capabilities : []
+  if (!packs.length) {
+    return { allowed: false, reason: '服务端判定里没有能力清单（packs 为空）——按"判定不可得"拒绝，⛔ 不离线放行', needPlan, plan }
+  }
+  for (const c of caps) {
+    const hit = packs.find((p) => p && (String(p.id) === String(c)
+      || (Array.isArray(p.capabilities) && p.capabilities.map(String).includes(String(c)))))
+    if (!hit) return { allowed: false, reason: `未达档位：账号能力清单里没有 \`${c}\`（服务端判定）`, needPlan, plan }
+    if (hit.unlocked !== true) {
+      const need = String(hit.minPlan || needPlan || 'pro')
+      return { allowed: false, reason: `未达档位：能力 \`${c}\` 需要 ${need}，当前账号 ${plan || '未知'}（服务端判定）`, needPlan, plan }
+    }
+  }
+  return { allowed: true, reason: '', needPlan, plan }
+}
+
+// ── 调用安装器（**唯一安装链**）────────────────────────────────────────
+
+/**
+ * **本次动作的落盘面**（快照/回滚的唯一判据；⛔ 不另写一份"哪些文件算落盘"的清单）。
+ *
+ * 由三部分拼成，每一部分都取自**既有真源**：
+ *   ① profile 的两个清单文件（`package.json` / `cordis.patch.yml`）—— 依赖图与组合行的落点；
+ *   ② 装机账本（`agents.json` / `install.json`）—— "装了哪些智能体 / 哪些能力包"的判据面；
+ *   ③ **包内声明**点名的落盘物：agent bundle 的 package.json、presets 的 `presets.selection.json`、
+ *      声明的技能（`<dshHome>/skills/<s>/SKILL.md`）、以及该智能体声明的**能力包的声明文件清单**
+ *      （`scripts/capability-packs.lock.json#capabilities.<c>.files`，仓库内相对路径）。
+ * ⛔ 不含整棵 node_modules / 整仓快照（那是分钟级与 GB 级）——面就是上面这些**判据文件**。
+ * @returns {{files: Array<{path:string, data:Buffer|null}>}} `data=null` ⇒ 动作前**不存在**
+ */
+export function snapshotAgentSurface({ repo, dshHome, profile = 'web', id }) {
+  const bundle = readAgentBundle({ repo, id })
+  const profileDir = profileDirOf({ dshHome, profile })
+  const rels = [
+    join(profileDir, 'package.json'),
+    join(profileDir, 'cordis.patch.yml'),
+    join(dshHome, 'argent', 'agents.json'),
+    join(dshHome, 'argent', 'install.json'),
+  ]
+  if (bundle) {
+    rels.push(join(profileDir, 'node_modules', ...bundle.name.split('/'), 'package.json'))
+    const pdir = resolveBundleDir(profileDir)
+    rels.push(join(pdir, SELECTION_FILE))
+    for (const sk of ((bundle.decl || {}).skills || []).map(String)) rels.push(join(dshHome, 'skills', sk, 'SKILL.md'))
+    // 能力包的**声明文件清单**（唯一真源 = 能力包版本锁）
+    const lock = readJsonSafe(join(repo, 'scripts', 'capability-packs.lock.json'), null) || {}
+    for (const c of (((bundle.decl || {}).payload || {}).capabilities || []).map(String)) {
+      const files = ((lock.capabilities || {})[c] || {}).files || {}
+      for (const rel of Object.keys(files)) rels.push(join(repo, rel))
+    }
+  }
+  const seen = new Set()
+  const files = []
+  for (const p of rels) {
+    if (seen.has(p)) continue
+    seen.add(p)
+    files.push({ path: p, data: existsSync(p) ? readFileSync(p) : null })
+  }
+  return { files, profileDir }
+}
+
+/**
+ * **回滚到动作前**（逐字节）——"⛔ 不写半截依赖图"的落点。
+ * 动作前不存在的 ⇒ 删掉（并清掉因此产生的空目录）；存在的 ⇒ 写回原字节（0600，与 profile 清单同档）。
+ * @returns {{restored:string[], removed:string[]}}
+ */
+export function restoreAgentSurface(snap) {
+  const restored = []
+  const removed = []
+  for (const f of (snap && snap.files) || []) {
+    try {
+      if (f.data === null) {
+        if (existsSync(f.path)) { rmSync(f.path, { force: true }); removed.push(f.path) }
+        // 顺手清掉"因本次动作才出现"的空目录（只清到 profile 根/技能根为止，⛔ 不递归删有内容的目录）
+        let d = dirname(f.path)
+        for (let i = 0; i < 4 && d && d.length > 1; i += 1) {
+          try {
+            if (!existsSync(d) || readdirSync(d).length) break
+            rmSync(d, { recursive: true, force: true })
+          } catch { break }
+          d = dirname(d)
+        }
+      } else {
+        mkdirSync(dirname(f.path), { recursive: true })
+        writeFileSync(f.path, f.data, { mode: 0o600 })
+        restored.push(f.path)
+      }
+    } catch { /* 单点失败不掩盖原始错误：回滚尽力而为，下面构造的失败里会带上 surface 差异 */ }
+  }
+  return { restored, removed }
+}
+
+/** 动作前后**逐字节**比对面（空数组 = 逐字节一致）。 */
+export function diffAgentSurface(snap) {
+  const changed = []
+  for (const f of (snap && snap.files) || []) {
+    const now = existsSync(f.path) ? readFileSync(f.path) : null
+    const before = f.data
+    if (now === null && before === null) continue
+    if (now === null || before === null || !now.equals(before)) changed.push(f.path)
+  }
+  return changed
+}
+
+/** 安装器 argv（判据面：测试逐字断言它含 `--agent <id>` 与 `--dsh-home <home>`）。 */
+export function agentInstallArgv({ repo, id, dshHome, yes = true }) {
+  return [join(repo, 'install-argent.mjs'), '--agent', String(id), ...(yes ? ['--yes'] : []), '--dsh-home', String(dshHome)]
+}
+
+/**
+ * 装一个智能体：**调用安装器本体**（`install-argent.mjs --agent <id>`）。
+ * 幂等短路由调用方（或本函数的 `status`）决定 —— 见 {@link shortCircuitFor}。
+ * @param {{repo:string,dshHome:string,id:string,profile?:string,env?:object,cwd?:string,timeoutMs?:number,spawn?:Function,
+ *   status?:object,action?:string}} o
+ * @returns {Promise<{ok:boolean, step:string, argv:string[], exitCode:number|null, stdout:string, stderr:string, out:string, fix:string, logs:string[]}>}
+ */
+export async function runAgentInstall({
+  repo, dshHome, id, profile = 'web', env = process.env, cwd,
+  timeoutMs = 15 * 60 * 1000, spawn = nodeSpawn, status = null, action = '',
+}) {
+  // ① 幂等短路：已装且版本一致（且不是"重装"）⇒ **零写入**
+  if (status) {
+    const sc = shortCircuitFor({ status, action })
+    if (sc.shortCircuit) {
+      return { ok: true, step: 'up-to-date', argv: [], exitCode: 0, stdout: sc.message, stderr: '', out: sc.message, fix: '', logs: [sc.message], wrote: false }
+    }
+  }
+  // ② **前置判据**：本机基座（壳）已在位 —— 与安装器同一条判据（bundle 依赖壳）。
+  const { deps } = readProfileManifest({ dshHome, profile })
+  const hasCore = Object.keys(deps).some((k) => k === '@whyshu/argent-core' || k === 'argent-core')
+  const hasSkin = Object.keys(deps).some((k) => k === '@whyshu/argent-skin' || k === 'argent-skin')
+  if (!hasCore || !hasSkin) {
+    return {
+      ok: false, step: 'base-not-landed', argv: [], exitCode: null, stdout: '', stderr: '', out: '',
+      fix: '本机基座（壳）还没装配：先跑一次整装（官网那条安装命令），再回来点这个按钮。⛔ 本次没有写任何东西。',
+      logs: ['基座（core + skin）不在 profile 依赖图里 ⇒ 本次不装 agent bundle（⛔ 不写半截依赖图）'], wrote: false,
+    }
+  }
+  // ③ 快照**本次落盘面**（跨进程事务；失败即逐字节回滚 —— "⛔ 不写半截依赖图"）
+  const surface = snapshotAgentSurface({ repo, dshHome, profile, id })
+  // ④ 调用**安装器本体**（唯一安装链）
+  const argv = agentInstallArgv({ repo, dshHome, id })
+  const child = spawn(process.execPath, argv, { env, cwd: cwd || repo, stdio: ['ignore', 'pipe', 'pipe'] })
+  const logs = []
+  let stdout = ''
+  let stderr = ''
+  child.stdout.on('data', (b) => { stdout += String(b); logs.push(String(b)) })
+  child.stderr.on('data', (b) => { stderr += String(b); logs.push(String(b)) })
+  const code = await new Promise((res) => {
+    const t = setTimeout(() => { try { child.kill('SIGKILL') } catch { /* 已退出 */ } }, timeoutMs)
+    child.on('error', (e) => { stderr += String((e && e.message) || e); clearTimeout(t); res(-1) })
+    child.on('close', (c) => { clearTimeout(t); res(c === null ? -1 : c) })
+  })
+  const out = `${stdout}${stderr}`.replace(/\x1b\[[0-9;]*m/g, '')
+  /** 失败收口：**回滚落盘面** → 返回结构化失败（哪一步 / 原文 / 怎么修 / 回滚痕迹）。 */
+  const fail = (step, extra = {}) => {
+    const rb = restoreAgentSurface(surface)
+    const left = diffAgentSurface(surface)
+    const fix = extra.fix || fixHintFor(out)
+    return {
+      ok: false, step, argv, exitCode: extra.exitCode === undefined ? code : extra.exitCode, stdout, stderr, out,
+      reason: extra.reason || problemsText(out, extra.problems, code),
+      fix, logs, wrote: !!(rb.restored.length || rb.removed.length), rollback: { ...rb, leftover: left },
+      ...(extra.problems ? { problems: extra.problems } : {}),
+    }
+  }
+  if (code !== 0) {
+    return fail('installer-failed')
+  }
+  // ⑤ 安装器自己会打印"基座没装配 ⇒ 本次不装 bundle"并以 0 退出 —— ⛔ 不许把它当成功
+  if (/基座（壳）还没装配/.test(out) && /本次\*\*不装\*\*|本次\*\*不装\*\* agent bundle/.test(out)) {
+    return fail('base-not-landed', {
+      exitCode: 0,
+      fix: '本机基座（壳）还没装配：先跑一次整装（官网那条安装命令），再回来点这个按钮。',
+    })
+  }
+  // ⑥ 收尾核对（**只读**）：bundle 在依赖图内 / presets 是直接依赖 + bundles 条目 / 能力包 / 角色 / 技能
+  const problems = verifyAgentLanded({ repo, dshHome, profile, id })
+  if (problems.length) {
+    return fail('selfcheck-failed', {
+      exitCode: 0,
+      fix: problems.map((p) => p.fix).filter(Boolean).join('；') || '按上面的逐条说明修好后重试',
+      problems,
+    })
+  }
+  return { ok: true, step: 'installed', argv, exitCode: 0, stdout, stderr, out, fix: '', problems: [], logs, wrote: true }
+}
+
+/**
+ * 失败**原文**（⛔ 不加工、不摘要）：优先用收尾核对问题的原文；否则取安装器输出里最后几条
+ * `✗` 行；再否则用退出码。用户要的是"照抄这段去搜/去修"，所以宁可原样给。
+ */
+export function problemsText(out, problems, code) {
+  if (Array.isArray(problems) && problems.length) return problems.map((p) => p.message).join('\n')
+  const lines = String(out || '').split('\n').map((l) => l.replace(/\x1b\[[0-9;]*m/g, '').trimEnd())
+  // ① 安装器自己的收尾自检块（最准：它就是判红的那一段）
+  const at = lines.findIndex((l) => /智能体 bundle 收尾自检未通过/.test(l))
+  if (at >= 0) {
+    const block = lines.slice(at, at + 12).map((l) => l.trim()).filter(Boolean)
+    return block.join('\n')
+  }
+  // ② 退一步：最后几条错误行 —— ⚠️ 排除**回执行**（如货架清单里的 `✗ <id> …（未点名）`），
+  //    那些不是错误，拿它们当"失败原因"会把用户带偏（本用例第一版现场命中）。
+  const errs = lines.map((l) => l.trim())
+    .filter((l) => /^[✗❌×]/.test(l) && !/（未点名）|\(未点名\)/.test(l))
+  if (errs.length) return errs.slice(-4).join('\n')
+  return `安装器退出码 ${code}（没有可解析的错误行，见 logs）`
+}
+
+/** 从安装器输出里挑一条可照抄的修法（⛔ 不编造：命中已知形态才给）。 */
+export function fixHintFor(text) {
+  const t = String(text || '')
+  if (/pnpm was not found|ENOENT|Command failed with ENOENT/.test(t)) {
+    return '装 pnpm 并让它在 PATH 上：`corepack enable pnpm`（Node 自带），或按 pnpm 官网安装；离线/送装可用 `file:` 回退。'
+  }
+  if (/dependencies.*里\*\*没有\*\*|不在依赖图内/.test(t)) {
+    return 'bundle 没进 profile 依赖图：`cd <profile 目录> && pnpm add <包名>` 后重试；离线用 `file:<克隆>/plugins/<包>`。'
+  }
+  if (/包内声明与货架声明不一致/.test(t)) {
+    return '包内声明 ≠ 货架声明：跑 `node scripts/gen-agent-bundles.mjs`（或在开发仓库重生成 bundle）后重试。'
+  }
+  return ''
+}
+
+/**
+ * **装完只读核对**（与安装器收尾自检**同一条口径**；W7 追上一条它没查的：
+ * "presets 必须是**直接依赖**且在 `dsh.profile.bundles` 里" —— W2 的坑：只 `dsh plugin add @whyshu/argent-shell`
+ * 会让 presets 只剩**传递依赖** ⇒ 它的 bundle 层不激活 ⇒ **角色行挂不上**）。
+ * @returns {Array<{code:string, message:string, fix:string}>} 空数组 = 通过
+ */
+export function verifyAgentLanded({ repo, dshHome, profile = 'web', id }) {
+  const problems = []
+  const bundle = readAgentBundle({ repo, id })
+  if (!bundle) { problems.push({ code: 'bundle-missing', message: `本机克隆里没有 plugins/${AGENT_DIR_PREFIX}${id}`, fix: 'git pull / 重跑同步脚本' }); return problems }
+  const { deps, bundles } = readProfileManifest({ dshHome, profile })
+  const profileDir = profileDirOf({ dshHome, profile })
+  // ① bundle 在依赖图内 + 能解析
+  if (!deps[bundle.name]) {
+    problems.push({ code: 'bundle-not-in-deps', message: `profile \`dependencies\` 里没有 ${bundle.name}（实体在 node_modules ≠ 在依赖图内）`, fix: `cd ${profileDir} && pnpm add ${bundle.name}@${bundle.version}` })
+  } else if (!existsSync(join(profileDir, 'node_modules', ...bundle.name.split('/'), 'package.json'))) {
+    problems.push({ code: 'bundle-unresolvable', message: `${bundle.name} 在依赖图里、但 node_modules 里没有实体（解析不到）`, fix: `cd ${profileDir} && pnpm install` })
+  }
+  // ② **presets 必须是直接依赖 + bundles 条目**（W2 的坑；W7 的硬判据）
+  if (!deps[PRESETS_NPM]) {
+    problems.push({
+      code: 'presets-not-direct-dep',
+      message: `profile \`dependencies\` 里**没有** ${PRESETS_NPM}（只有传递依赖 ⇒ 它的 bundle 层不激活 ⇒ 角色行挂不上）`,
+      fix: `cd ${profileDir} && pnpm add file:<克隆>/plugins/argent-presets`,
+    })
+  }
+  if (!bundles.includes(PRESETS_NPM)) {
+    problems.push({
+      code: 'presets-not-in-bundles',
+      message: `\`dsh.profile.bundles\` 里**没有** ${PRESETS_NPM}（不登记 ⇒ preset 行不被 insert）`,
+      fix: `把 "${PRESETS_NPM}" 补进 ${join(profileDir, 'package.json')} 的 dsh.profile.bundles（与其它条目并列）`,
+    })
+  }
+  // ③ 能力包按**包内声明**落位（装机账本）
+  const wantCaps = (((bundle.decl || {}).payload || {}).capabilities || []).map(String)
+  const ledger = readJsonSafe(join(dshHome, 'argent', 'install.json'), null)
+  const landed = ((ledger && ledger.capabilities) || []).map((c) => String((c && c.id) || '')).filter(Boolean)
+  for (const c of wantCaps) {
+    if (!landed.includes(c)) problems.push({ code: 'capability-missing', message: `声明的能力包 \`${c}\` 不在装机账本里（${join(dshHome, 'argent', 'install.json')}）`, fix: `重跑：node ${join(repo, 'install-argent.mjs')} --agent ${id} --yes --dsh-home ${dshHome}` })
+  }
+  // ④ 角色（presets.selection.json#kept）/ 技能（<dshHome>/skills/<s>/SKILL.md）
+  const bundleDir = resolveBundleDir(profileDir)
+  const sel = readJsonSafe(join(bundleDir, SELECTION_FILE), null)
+  const kept = (sel && Array.isArray(sel.kept)) ? sel.kept.map(String) : []
+  for (const r of (((bundle.decl || {}).roles) || []).map(String)) {
+    if (!kept.includes(r)) problems.push({ code: 'role-not-landed', message: `角色 \`${r}\` 不在落盘集合内（${SELECTION_FILE}#kept = ${kept.join('、') || '（空）'}）`, fix: `重跑：node ${join(repo, 'install-argent.mjs')} --agent ${id} --yes --dsh-home ${dshHome}` })
+  }
+  for (const sk of (((bundle.decl || {}).skills) || []).map(String)) {
+    if (!existsSync(join(dshHome, 'skills', sk, 'SKILL.md'))) problems.push({ code: 'skill-not-landed', message: `技能 \`${sk}\` 未落位（${join(dshHome, 'skills', sk, 'SKILL.md')} 不存在）`, fix: `重跑：node ${join(repo, 'install-argent.mjs')} --agent ${id} --yes --dsh-home ${dshHome}` })
+  }
+  return problems
+}
+
+// ── 编排：许可证前置 → 装 → 逐条结果（宿主工具/路由调这一个函数）──────────────
+
+/**
+ * **界面动作的完整语义**（宿主只调它，⛔ 不自己编排）：
+ *   ① 读现状（只读）→ ② 幂等短路（已是最新且非重装 ⇒ **零写入**，回「已是最新」）
+ *   → ③ **许可证前置**（服务端判定；不可得/未达档位 ⇒ **拒绝且零写入**）
+ *   → ④ 调安装器 → ⑤ 收尾核对 → 结构化结果。
+ * @returns {Promise<{ok:boolean, action:string, step:string, message:string, reason?:string,
+ *   fix?:string, logs:string[], argv:string[], wrote:boolean, status?:object, entitlement?:object}>}
+ */
+export async function installAgentAction({
+  repo, dshHome, id, profile = 'web', action = '', env = process.env,
+  fetchImpl = globalThis.fetch, spawn = nodeSpawn, timeoutMs,
+} = {}) {
+  const shelf = agentRuntimeStatus({ repo, dshHome, profile })
+  const status = shelf.agents.find((a) => a.id === String(id))
+  if (!status) {
+    return { ok: false, action, step: 'unknown-agent', message: `货架上没有智能体 \`${id}\``, reason: `货架上没有智能体 \`${id}\``, logs: shelf.errors, argv: [], wrote: false }
+  }
+  const act = isStr(action) ? action : status.action
+  // ② 幂等短路（**零写入**）—— ⚠️ 判据只能用**调用方点名**的 action（空 = 自动）：
+  // 用派生出来的 `status.action`（已是最新时是 `reinstall`）做判据会把短路**自己关掉**，
+  // 于是"已是最新"变成"每次都重装"（本用例 §3 现场命中）。
+  const sc = shortCircuitFor({ status, action: isStr(action) ? action : '' })
+  if (sc.shortCircuit) {
+    return { ok: true, action: 'up-to-date', step: 'up-to-date', message: sc.message, logs: [sc.message], argv: [], wrote: false, status }
+  }
+  // ③ 许可证前置（服务端判定）—— **动手之前**
+  const ent = await fetchEntitlement({ dshHome, env, fetchImpl })
+  if (!ent.ok) {
+    return {
+      ok: false, action: act, step: 'license-unavailable', message: `许可证判定不可得 ⇒ 拒绝安装（⛔ 不离线放行）`,
+      reason: ent.reason, fix: '检查账号是否已登录（WHYSHU_API_KEY）、网络是否可达 whyshu.com；必要时重跑安装器 --api-key <账号令牌>',
+      logs: [ent.reason], argv: [], wrote: false, status,
+    }
+  }
+  const verdict = judgeEntitlement({ agent: status, entitlement: ent.entitlement })
+  if (!verdict.allowed) {
+    return {
+      ok: false, action: act, step: 'license-denied', message: verdict.reason, reason: verdict.reason,
+      fix: `升级到 ${verdict.needPlan || status.minPlan} 后重试（当前账号 ${verdict.plan || '未知'}）`,
+      logs: [], argv: [], wrote: false, status, entitlement: ent.entitlement,
+    }
+  }
+  // ④⑤ 调用安装器（唯一安装链）+ 收尾核对
+  const r = await runAgentInstall({ repo, dshHome, id, profile, env, spawn, timeoutMs, status, action: act })
+  const after = agentRuntimeStatus({ repo, dshHome, profile }).agents.find((a) => a.id === String(id)) || null
+  return {
+    ok: !!r.ok, action: act, step: r.step, message: r.ok ? `智能体 \`${id}\` ${act === 'reinstall' ? '重装' : act === 'upgrade' ? '升级' : '安装'}完成（v${(after && after.installedVersion) || status.bundleVersion}）` : `安装失败（${r.step}）`,
+    reason: r.ok ? '' : (r.reason || r.fix || '安装失败'), fix: r.fix || '', logs: r.logs || [], argv: r.argv || [], wrote: r.wrote !== false,
+    problems: r.problems || [], rollback: r.rollback || null, status: after, entitlement: ent.entitlement,
+  }
+}