@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/argent-agents.mjs

@@ -0,0 +1,527 @@
+#!/usr/bin/env node
+/**
+ * argent-agents —— 「按**智能体**装」的声明解析与清单构造（A 批，2026-10-10）。
+ *
+ * ## 为什么单独一个文件
+ * 与 `scripts/argent-capabilities.mjs` 同因：`install-argent.mjs` 是**单文件分发物**
+ * （`release-argent.sh` 的 CORE_FILES），只能在克隆完仓库之后**动态**加载本模块，
+ * 不能静态 import（否则单文件分发断链）。而门禁 `scripts/check-agent-catalog.mjs`
+ * 要读**同一份**目录声明并做更强的交叉校验 ⇒ 解析/校验/清单构造必须是**一份实现**。
+ *
+ * ## 分工
+ * - **声明**：`agents/catalog.json`（L0 货架声明：agent → capability + flows 子集 + 角色 + 插件/技能/集成/凭据槽）。
+ * - **本模块**：纯函数（`validateCatalog` / `planForAgents` / `presetSelectionForAgents` / `composeReceipt`）
+ *   + 轻 IO（`loadCatalog` / `buildContext` / 账本读写）。
+ * - **落盘**：`install-argent.mjs`（`--agent` / `--list-agents` / `--capability remove`）。
+ *
+ * ## 三条红线
+ * 1. **⛔ 凭据槽不得含值**：`credentials[]` 只写 `{slot,target,why}`；`validateCatalog` 递归扫描
+ *    禁止键（value/secret/default/token/password…）与密钥形态串 ⇒ 报红。
+ * 2. **⛔ 不含判据逻辑**：本模块只做「声明 → 清单」的机械投影，业务判据仍在 L1（scripts/flow_*.py）。
+ * 3. **⛔ 单一真源**：能力/流程/档位一律读**既有**声明（`scripts/capability-packs.lock.json` +
+ *    `scripts/flow-requirements.json` + `plugins/argent-presets/presets.json`），本模块与目录
+ *    **都不新建第二份**；门禁侧再拿**活注册表**（`flow_registry.py --json`）核对锁是否过期。
+ *
+ * 测试：`scripts/tests/agent-catalog.test.mjs`
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+export const REPO = join(HERE, '..')
+
+/** 目录声明（L0）的相对路径 —— **只此一处**；改名要同时改本模块、门禁与安装器。 */
+export const CATALOG_REL = 'agents/catalog.json'
+/** 装机账本（智能体维度）：`<dshHome>/argent/agents.json`。 */
+export const LEDGER_REL = join('argent', 'agents.json')
+
+/** 共享壳插件：**任何**智能体都必须带它们，且移除时**永不**删（其它智能体还要用）。 */
+export const SHARED_SHELL_PLUGINS = ['argent-core', 'argent-skin']
+/** 恒装入口角色（每个智能体的 `roles` 必须含它）。 */
+export const ALWAYS_ROLE = 'argent-general'
+
+/** 档位序（判据：智能体档位不得低于其能力包的档位下限）。 */
+export const PLAN_RANK = { free: 0, pro: 1, enterprise: 2 }
+
+/** `credentials[]` 的**唯一**合法键集（多一个键即红）。 */
+export const CREDENTIAL_KEYS = ['slot', 'target', 'why']
+/** 凭据槽里**禁止出现**的键（写进去就等于把密钥带进仓库/收据）。 */
+export const FORBIDDEN_CRED_KEYS = ['value', 'values', 'secret', 'secrets', 'default', 'token', 'password', 'pass', 'key', 'apikey', 'apiKey']
+/** 密钥形态串（扫描凭据槽的**所有**字符串值；命中即红）。 */
+export const SECRET_SHAPED = [
+  /sk-[A-Za-z0-9]{16,}/,                    // DeepSeek 官方形态
+  /\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}/, // JWT
+  /\b[0-9a-f]{32,}\b/i,                     // 长十六进制
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+]
+/** 智能体条目**允许**的键（未知键 ⇒ 红）。 */
+export const AGENT_KEYS = [
+  'id', 'title', 'summary', 'capability', 'capabilities', 'flows', 'roles',
+  'plugins', 'skills', 'integrations', 'credentials', 'minPlan', 'scheduler', 'notes',
+]
+/** 目录文档**允许**的顶层键。 */
+export const DOC_KEYS = ['_doc', '_layer', '_why', '_invariants', 'version', 'plans', 'plugins', 'integrations', 'agents']
+
+// ── 能力声明的**宿主资产**字段（`capabilities.<c>.pack.hostAssets`）──────────────
+// 由来（A 批）：能力包此前**没有任何宿主侧资产的声明位** —— "要不要定时器 / 怎么装"只能由安装器
+// **写死**推断（写死的判据散在安装器文案里，没有单一真源可查）。这里把它变成**声明 + 门禁**。
+/** `hostAssets` 允许的资产键。 */
+export const HOST_ASSET_KEYS = ['_note', 'scheduler', 'loginAutostart', 'desktopShortcut']
+/** 每项资产允许的子键（`_note` 之外的键必须落在各自的白名单里 —— 未知子键 ⇒ 红）。 */
+export const HOST_ASSET_FIELDS = {
+  scheduler: ['required', 'install', 'perFlow', 'command', '_note'],
+  loginAutostart: ['required', 'install', 'flag', '_note'],
+  desktopShortcut: ['required', 'install', '_note'],
+}
+/** `install` 的合法取值（**现状只有这三种**；新增必须同时改门禁与安装器文案）。 */
+export const HOST_ASSET_INSTALL = ['print-only', 'auto', 'none', 'opt-in-flag']
+
+/**
+ * 校验能力声明的宿主资产字段（⛔ 与智能体目录的 `scheduler` 必须一致 —— 那是本批"不装定时器"的判据源）。
+ * @param {object} ctx `buildContext()` 输出
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateHostAssets(ctx) {
+  const errors = []
+  const warnings = []
+  for (const [cap, c] of Object.entries(ctx.capabilities || {})) {
+    const ha = c.hostAssets
+    const at = `capabilities.${cap}.pack.hostAssets`
+    if (!ha || typeof ha !== 'object') { errors.push(`${at} 缺声明（每个能力必须声明宿主侧资产：定时器/自启/桌面项）`); continue }
+    for (const k of Object.keys(ha)) if (!HOST_ASSET_KEYS.includes(k)) errors.push(`${at} 出现未知键 \`${k}\`（允许：${HOST_ASSET_KEYS.join('、')}）`)
+    for (const k of HOST_ASSET_KEYS) {
+      if (k === '_note') continue
+      const a = ha[k]
+      if (!a || typeof a !== 'object') { errors.push(`${at}.${k} 缺声明`); continue }
+      const allow = HOST_ASSET_FIELDS[k]
+      for (const kk of Object.keys(a)) if (!allow.includes(kk)) errors.push(`${at}.${k} 出现未知键 \`${kk}\`（允许：${allow.join('、')}）`)
+      if (typeof a.required !== 'boolean') errors.push(`${at}.${k} 缺 \`required\`（布尔：该能力是否需要这项宿主资产）`)
+      if (!HOST_ASSET_INSTALL.includes(a.install)) errors.push(`${at}.${k} 的 \`install\` 非法：${a.install}（允许：${HOST_ASSET_INSTALL.join('、')}）`)
+    }
+    const s = ha.scheduler
+    if (s && typeof s === 'object') {
+      const nFlows = (c.flows || []).length
+      if (s.required === true && nFlows === 0) errors.push(`${at}.scheduler.required=true 但该能力没有 flow —— 没有可定时的东西`)
+      if (s.required === false && nFlows > 0) errors.push(`${at}.scheduler.required=false 但该能力有 ${nFlows} 条 flow —— 声明与事实矛盾`)
+      if (s.required === true && !isStr(s.command)) errors.push(`${at}.scheduler 需要 \`command\`（用户可照抄的安装命令模板）`)
+      if (s.required === true && s.install !== 'print-only') warnings.push(`${at}.scheduler.install=${s.install} —— 今天安装器**只打印**命令（⛔ 不自动装）；若确实要自动装，请同时改安装器并写进设计文档`)
+    }
+    if (ha.loginAutostart && ha.loginAutostart.required === true && ha.loginAutostart.install !== 'auto') {
+      warnings.push(`${at}.loginAutostart.required=true 但 install=${ha.loginAutostart.install} —— 今天只有 \`--win-autostart\` 这条显式 opt-in 通道`)
+    }
+  }
+  return { errors, warnings }
+}
+
+// ── 轻 IO ────────────────────────────────────────────────────────────
+
+function readJson(p) {
+  try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return null }
+}
+
+/** 读目录声明（找不到 ⇒ 返回 null，由调用方**响亮**报错，⛔ 不静默补一份）。 */
+export function loadCatalog(root = REPO) {
+  return readJson(join(root, CATALOG_REL))
+}
+
+/** 装机账本路径。 */
+export function agentLedgerPath(dshHome) {
+  return join(dshHome || join(process.env.HOME || '', '.dsh'), LEDGER_REL)
+}
+
+/** 读装机账本（缺失/坏文件 ⇒ `{agents: []}`，由调用方决定是否告警）。 */
+export function readAgentLedger(dshHome) {
+  const d = readJson(agentLedgerPath(dshHome))
+  if (!d || typeof d !== 'object') return { agents: [] }
+  return { ...d, agents: Array.isArray(d.agents) ? d.agents.filter((a) => a && a.id) : [] }
+}
+
+/**
+ * 由**既有声明**拼出校验上下文（⛔ 本模块不新建名单）。
+ * @param {string} root 仓库根
+ * @param {(s: string) => void} [warn] 缺件时的告警出口（缺件不静默）
+ */
+export function buildContext(root = REPO, warn = () => {}) {
+  const lock = readJson(join(root, 'scripts', 'capability-packs.lock.json')) || {}
+  const base = readJson(join(root, 'scripts', 'flow-requirements.json')) || {}
+  const shelf = readJson(join(root, 'plugins', 'argent-presets', 'presets.json')) || {}
+  const lockCaps = (lock && lock.capabilities) || {}
+  const baseCaps = (base && base.capabilities) || {}
+  if (!Object.keys(lockCaps).length) warn(`读不到能力包版本锁（${join(root, 'scripts', 'capability-packs.lock.json')}）——能力清单为空`)
+  if (!Object.keys(shelf).length) warn(`读不到角色清单（${join(root, 'plugins', 'argent-presets', 'presets.json')}）——角色清单为空`)
+
+  const capabilities = {}
+  const flows = {}
+  for (const [id, c] of Object.entries(lockCaps)) {
+    const files = Object.keys(c.files || {})
+    const packPresets = [...new Set(files.filter((f) => f.startsWith('presets/')).map((f) => f.split('/')[1]).filter(Boolean))]
+    const packSkills = [...new Set(files.filter((f) => f.startsWith('skills/')).map((f) => f.split('/')[1]).filter(Boolean))]
+    const declared = ((baseCaps[id] || {}).pack || {})
+    capabilities[id] = {
+      id,
+      version: c.version || '',
+      minPlan: (baseCaps[id] || {}).minPlan || '',
+      hostAssets: declared.hostAssets || null,
+      flows: Array.isArray(c.flows) ? [...c.flows] : [],
+      packPresets: [...new Set([...packPresets, ...((declared.presets || []).map((p) => String(p).replace(/^presets\//, '')))])],
+      packSkills: [...new Set([...packSkills, ...(declared.skills || []).map(String)])],
+      files: c.files || {},
+    }
+    for (const f of capabilities[id].flows) flows[f] = { ...(flows[f] || {}), capability: id }
+  }
+  // 业务线侧的角色/技能声明（flow → role/skill）：注册表才是合并真源，这里只读**单线文件**的原始字段，
+  // 供门禁做"flow ↔ role"双射交叉校验；装机器不需要它（见 validateCatalog 的 opts.flowRole）。
+  // ⚠️ `flows.json#role` 是**短角色名**（`ml-fulfillment`），而 preset id 是 `argent-<短名>`
+  // （唯一派生规则见 `scripts/capability_pack.py#manifest()`：`presets/argent-{role}`）⇒ 这里归一成
+  // **preset id**，否则交叉校验会用短名去比 preset 清单（恒不命中 ⇒ 判据形同虚设）。
+  const presetIdOfRole = (r) => (String(r || '').startsWith('argent-') ? String(r) : `argent-${r}`)
+  const verticalsDir = join(root, 'verticals')
+  if (existsSync(verticalsDir)) {
+    for (const d of readdirSync(verticalsDir)) {
+      const f = join(verticalsDir, d, 'flows.json')
+      if (!existsSync(f)) continue
+      const doc = readJson(f)
+      for (const [local, spec] of Object.entries((doc && doc.flows) || {})) {
+        const canonical = `${d}.${local}`
+        flows[canonical] = { ...(flows[canonical] || {}), role: presetIdOfRole((spec || {}).role), skill: (spec || {}).skill || '' }
+      }
+    }
+  }
+
+  const plugins = existsSync(join(root, 'plugins')) ? readdirSync(join(root, 'plugins')).filter((d) => !d.startsWith('.')) : []
+  const skillsDir = join(root, 'skills')
+  const skills = existsSync(skillsDir)
+    ? readdirSync(skillsDir).filter((d) => {
+      try { return statSync(join(skillsDir, d)).isDirectory() && existsSync(join(skillsDir, d, 'SKILL.md')) } catch { return false }
+    })
+    : []
+
+  return { capabilities, flows, presets: shelf, plugins, skills }
+}
+
+// ── 纯函数：校验 ──────────────────────────────────────────────────────
+
+const isStr = (x) => typeof x === 'string' && x.trim() !== ''
+const isArr = (x) => Array.isArray(x)
+
+/**
+ * 目录 schema 校验（**门禁与安装器共用同一份**）。
+ *
+ * @param {object} doc 目录文档（`agents/catalog.json` 解析结果）
+ * @param {object} ctx `buildContext()` 的输出
+ * @param {{flowRole?: Record<string,string>}} [opts] `flowRole`：规范 flow id → 角色名（**可选的更强交叉校验**，
+ *   只有拿得到活注册表时才给；给了就查 "每条 flow 的角色必须在 roles 里 ∧ 每个专属角色必须对应一条已声明 flow"）。
+ * @returns {{errors: string[], warnings: string[]}}
+ */
+export function validateCatalog(doc, ctx, opts = {}) {
+  const errors = []
+  const warnings = []
+  const E = (m) => errors.push(m)
+  const W = (m) => warnings.push(m)
+  if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
+    E(`${CATALOG_REL} 不是对象（或读不到）`)
+    return { errors, warnings }
+  }
+  for (const k of Object.keys(doc)) if (!DOC_KEYS.includes(k)) E(`目录文档出现未知字段 \`${k}\`（允许：${DOC_KEYS.join('、')}）`)
+  if (!Array.isArray(doc.agents)) {
+    E('目录文档缺 `agents` 数组')
+    return { errors, warnings }
+  }
+  const plans = isArr(doc.plans) && doc.plans.length ? doc.plans : Object.keys(PLAN_RANK)
+  const declPlugins = (doc.plugins && typeof doc.plugins === 'object') ? doc.plugins : {}
+  const declIntegrations = (doc.integrations && typeof doc.integrations === 'object') ? doc.integrations : {}
+  const capIds = Object.keys(ctx.capabilities || {})
+  const allFlows = Object.keys(ctx.flows || {})
+  const presetIds = Object.keys(ctx.presets || {})
+
+  const seen = new Set()
+  doc.agents.forEach((a, i) => {
+    const at = `agents[${i}]${a && a.id ? `(${a.id})` : ''}`
+    if (!a || typeof a !== 'object' || Array.isArray(a)) { E(`${at} 不是对象`); return }
+    for (const k of Object.keys(a)) if (!AGENT_KEYS.includes(k)) E(`${at} 出现未知字段 \`${k}\`（允许：${AGENT_KEYS.join('、')}）`)
+    if (!isStr(a.id)) E(`${at} 缺 \`id\``)
+    else if (seen.has(a.id)) E(`${at} \`id\` 重复：${a.id}`)
+    else seen.add(a.id)
+    if (!isStr(a.title)) E(`${at} 缺 \`title\``)
+    if (!isStr(a.summary)) E(`${at} 缺 \`summary\``)
+
+    // ① capability / capabilities 二选一
+    const hasOne = isStr(a.capability)
+    const hasMany = isArr(a.capabilities)
+    if (hasOne === hasMany) E(`${at} \`capability\` 与 \`capabilities\` 必须**二选一**（单能力用前者、组合用后者）`)
+    const caps = hasMany ? a.capabilities.map(String) : (hasOne ? [String(a.capability)] : [])
+    if (!caps.length) E(`${at} 没有声明任何能力`)
+    for (const c of caps) if (!capIds.includes(c)) E(`${at} 未知能力 \`${c}\`（在册：${capIds.join('、') || '（无）'}）`)
+    if (hasMany && caps.length < 2) E(`${at} 用了 \`capabilities\` 却只有 ${caps.length} 项 —— 单能力请写 \`capability\``)
+    if (caps.some((c) => !capIds.includes(c))) return // 未知能力 ⇒ 后续推导不可靠，早退（错误已记）
+
+    // ② flows ⊆ 已声明能力名下的规范 id 子集；scheduler 一致性
+    if (!isArr(a.flows)) { E(`${at} 缺 \`flows\` 数组（没有流程就给 \`[]\`）`); return }
+    const own = new Set(caps.flatMap((c) => ctx.capabilities[c].flows || []))
+    for (const f of a.flows.map(String)) {
+      if (!allFlows.includes(f)) E(`${at} 未知 flow \`${f}\`（在册：${allFlows.join('、') || '（无）'}）`)
+      else if (!own.has(f)) E(`${at} 的 flow \`${f}\` 不属于它声明的能力（${caps.join('、')}）`)
+    }
+    if (a.scheduler === true && !a.flows.length) E(`${at} \`scheduler=true\` 但 \`flows\` 为空 —— 没有流程就没有定时器`)
+    if (a.scheduler === false && a.flows.length) E(`${at} \`scheduler=false\` 但声明了 ${a.flows.length} 条 flow —— 二者自相矛盾`)
+    if (typeof a.scheduler !== 'boolean') E(`${at} 缺 \`scheduler\`（布尔：该智能体是否要定时流程）`)
+    // 与**能力声明的宿主资产**逐条对齐（判据源 = `capabilities.<c>.pack.hostAssets.scheduler.required`）：
+    // 两处不一致 ⇒ 智能体说"有定时器"而能力说"不需要"（或反过来）⇒ 安装器会打印/漏打印命令。
+    {
+      const need = caps.some((c) => {
+        const ha = (ctx.capabilities[c] || {}).hostAssets
+        return !!(ha && ha.scheduler && ha.scheduler.required === true)
+      })
+      if (typeof a.scheduler === 'boolean' && a.scheduler !== need) {
+        E(`${at} 的 \`scheduler=${a.scheduler}\` 与能力声明的宿主资产不一致（能力侧 scheduler.required=${need}）`)
+      }
+    }
+    const capFlows = caps.reduce((n, c) => n + (ctx.capabilities[c].flows || []).length, 0)
+    if (capFlows > 0 && a.flows.length === 0) E(`${at} 声明的能力有 ${capFlows} 条流程，但 \`flows\` 为空 —— 那等于"装了不跑"`)
+
+    // ③ roles：必须含恒装入口；每个角色必须归属本智能体；flow 的 role 必须在内（opts.flowRole 给了才查）
+    if (!isArr(a.roles) || !a.roles.length) E(`${at} 缺 \`roles\` 数组（至少含 \`${ALWAYS_ROLE}\`）`)
+    else {
+      const roles = a.roles.map(String)
+      if (!roles.includes(ALWAYS_ROLE)) E(`${at} 的 \`roles\` 缺恒装入口 \`${ALWAYS_ROLE}\``)
+      if (new Set(roles).size !== roles.length) E(`${at} 的 \`roles\` 有重复项`)
+      const flowRoles = new Set((a.flows || []).map((f) => (opts.flowRole || {})[f]).filter(Boolean))
+      for (const r of roles) {
+        if (!presetIds.includes(r)) { E(`${at} 未知角色 \`${r}\`（在册 preset：${presetIds.join('、') || '（无）'}）`); continue }
+        const meta = ctx.presets[r] || {}
+        if (r === ALWAYS_ROLE) continue
+        const byCap = isStr(meta.capability) && caps.includes(String(meta.capability))
+        const byList = isArr(meta.capabilities) && meta.capabilities.map(String).some((c) => caps.includes(c))
+        const byRolesFor = isArr(meta.rolesFor) && meta.rolesFor.map(String).includes(String(a.id))
+        const byFlow = flowRoles.has(r)
+        if (!(byCap || byList || byRolesFor || byFlow)) {
+          E(`${at} 的角色 \`${r}\` 归属不上（preset 声明 capability=${meta.capability || '（无）'}；也不在 rolesFor/[flow.role] 里）`)
+        }
+        if (isStr(meta.visibility) && meta.visibility === 'internal' && !byRolesFor) {
+          W(`${at} 引用了内部角色 \`${r}\`（默认不落客户机；要装需 \`--internal-roles\`）`)
+        }
+      }
+      // 反向：每条已声明 flow 的角色必须在 roles 里
+      for (const f of a.flows || []) {
+        const fr = (opts.flowRole || {})[f]
+        if (fr && !roles.includes(fr)) E(`${at} 声明了 flow \`${f}\`（角色 ${fr}）却没把 \`${fr}\` 放进 \`roles\``)
+      }
+      // 反向：同能力里**别的** flow 的角色不得混进来（本批的核心诉求：发票两条 flow 分属两个智能体）
+      if (capFlows > 1 && (a.flows || []).length < capFlows) {
+        const excluded = caps.flatMap((c) => (ctx.capabilities[c].flows || [])).filter((f) => !(a.flows || []).includes(f))
+        for (const f of excluded) {
+          const fr = (opts.flowRole || {})[f]
+          if (fr && roles.includes(fr)) E(`${at} 未声明 flow \`${f}\`，却把它的角色 \`${fr}\` 放进了 \`roles\` —— 子集过滤会让它落不了地`)
+        }
+      }
+    }
+
+    // ④ plugins：至少含共享壳；未知插件 ⇒ 红
+    if (!isArr(a.plugins) || !a.plugins.length) E(`${at} 缺 \`plugins\` 数组（至少含 ${SHARED_SHELL_PLUGINS.join(' + ')}）`)
+    else {
+      const ps = a.plugins.map(String)
+      for (const p of SHARED_SHELL_PLUGINS) if (!ps.includes(p)) E(`${at} 的 \`plugins\` 缺共享壳 \`${p}\``)
+      for (const p of ps) {
+        if (!(ctx.plugins || []).includes(p)) E(`${at} 未知插件 \`${p}\`（仓库 plugins/ 下没有它）`)
+        else if (!(p in declPlugins)) W(`${at} 的插件 \`${p}\` 未在目录文档的 \`plugins\` 说明表里登记`)
+      }
+    }
+
+    // ⑤ skills：必须真实存在 ∧ ∈ 已声明能力包的技能集
+    if (!isArr(a.skills)) E(`${at} 缺 \`skills\` 数组（不需要就给 \`[]\`）`)
+    else {
+      const packSkills = new Set(caps.flatMap((c) => ctx.capabilities[c].packSkills || []))
+      for (const s of a.skills.map(String)) {
+        if (!(ctx.skills || []).includes(s)) E(`${at} 未知技能 \`${s}\`（skills/ 下没有含 SKILL.md 的该目录）`)
+        else if (!packSkills.has(s)) E(`${at} 的技能 \`${s}\` 不在已声明能力包的技能集里（${[...packSkills].join('、') || '（空）'}）⇒ 装了也拿不到它`)
+      }
+      const flowSkills = new Set((a.flows || []).map((f) => (ctx.flows[f] || {}).skill).filter(Boolean))
+      for (const s of flowSkills) if (!a.skills.map(String).includes(s)) W(`${at} 的 flow 声明了技能 \`${s}\`，但 \`skills\` 没列它`)
+    }
+
+    // ⑥ integrations：必须在目录文档的集成说明表里登记
+    if (!isArr(a.integrations)) E(`${at} 缺 \`integrations\` 数组（不需要就给 \`[]\`）`)
+    else for (const g of a.integrations.map(String)) {
+      if (!(g in declIntegrations)) E(`${at} 未知系统集成 \`${g}\`（在册：${Object.keys(declIntegrations).join('、') || '（无）'}）`)
+    }
+
+    // ⑦ credentials：只写槽位/落点/用途，⛔ 不含值
+    if (!isArr(a.credentials)) E(`${at} 缺 \`credentials\` 数组（不需要就给 \`[]\`）`)
+    else a.credentials.forEach((c, j) => {
+      const ct = `${at}.credentials[${j}]`
+      if (!c || typeof c !== 'object' || Array.isArray(c)) { E(`${ct} 不是对象`); return }
+      for (const k of Object.keys(c)) {
+        if (FORBIDDEN_CRED_KEYS.includes(k)) E(`${ct} 出现禁止键 \`${k}\` —— 凭据槽**只写槽位名与落点**，⛔ 绝不写值`)
+        else if (!CREDENTIAL_KEYS.includes(k)) E(`${ct} 未知键 \`${k}\`（允许：${CREDENTIAL_KEYS.join('、')}）`)
+      }
+      for (const k of CREDENTIAL_KEYS) if (!isStr(c[k])) E(`${ct} 缺 \`${k}\``)
+      if (isStr(c.slot) && !/^[A-Za-z][A-Za-z0-9_.-]*$/.test(c.slot)) E(`${ct} 的 \`slot\` 不像凭据槽名：${c.slot}`)
+      // 落点白名单（**只认既有约定的两处**）：`config.json`（~/.dsh/argent/config.json 的槽位）
+      // 或 `**/env/*.env`（业务线 env 文件，`scope: vertical` 的既有落点）。
+      if (isStr(c.target) && c.target !== 'config.json' && !/(^|\/)env\/[^/]+\.env$/.test(c.target)) {
+        E(`${ct} 的 \`target\` 不是约定的凭据落点：${c.target}（只认 \`config.json\` 或 \`<…>/env/<名>.env\`）`)
+      }
+      for (const v of Object.values(c)) {
+        if (typeof v !== 'string') continue
+        for (const re of SECRET_SHAPED) if (re.test(v)) E(`${ct} 的字段出现**密钥形态**串（${re}）—— 凭据槽里不许有值`)
+      }
+    })
+
+    // ⑧ minPlan：合法 ∧ 不低于已声明能力包的档位下限
+    if (!isStr(a.minPlan) || !plans.includes(a.minPlan)) E(`${at} 未知档位 \`${a.minPlan}\`（在册：${plans.join('、')}）`)
+    else for (const c of caps) {
+      const need = ctx.capabilities[c].minPlan
+      if (need && PLAN_RANK[a.minPlan] < PLAN_RANK[need]) {
+        E(`${at} 档位 ${a.minPlan} 低于能力 \`${c}\` 的下限 ${need}`)
+      }
+    }
+  })
+
+  // 每个能力都应至少被一个智能体覆盖（否则货架上买不到它）
+  const covered = new Set(doc.agents.flatMap((a) => (isArr(a.capabilities) ? a.capabilities : (isStr(a.capability) ? [a.capability] : []))))
+  for (const c of capIds) if (!covered.has(c)) W(`能力 \`${c}\` 没有任何智能体覆盖 —— 货架上买不到它`)
+  return { errors, warnings }
+}
+
+// ── 纯函数：清单构造 ──────────────────────────────────────────────────
+
+/** 按 id 取智能体（找不到 ⇒ null）。 */
+export function findAgent(doc, id) {
+  return (doc && Array.isArray(doc.agents) ? doc.agents : []).find((a) => a && String(a.id) === String(id)) || null
+}
+
+/**
+ * 把若干智能体投影成**安装清单**（"装什么"），并算出"**刻意没装什么**"（universe − 装）。
+ *
+ * @param {object} doc 目录文档
+ * @param {string[]} ids 点名的智能体 id
+ * @param {object} ctx buildContext() 输出
+ * @returns {{ok: boolean, unknown: string[], capabilities: string[], flows: string[], roles: string[],
+ *   plugins: string[], skills: string[], integrations: string[], credentials: object[], scheduler: boolean,
+ *   minPlan: string, notInstalled: object}}
+ */
+export function planForAgents(doc, ids, ctx) {
+  const want = [...new Set((ids || []).map(String))]
+  const agents = want.map((id) => findAgent(doc, id))
+  const unknown = want.filter((_, i) => !agents[i])
+  const found = agents.filter(Boolean)
+  const capabilities = [...new Set(found.flatMap((a) => (isArr(a.capabilities) ? a.capabilities : [a.capability]).map(String)))]
+  const declaredFlows = [...new Set(found.flatMap((a) => (a.flows || []).map(String)))]
+  // flow 子集过滤：只保留**已声明能力**名下的 flow（能力包会带全部流程的资产 ⇒ 落盘侧再按此收窄）
+  const ownFlows = new Set(capabilities.flatMap((c) => (ctx.capabilities[c] || {}).flows || []))
+  const flows = declaredFlows.filter((f) => ownFlows.has(f))
+  const roles = [...new Set(found.flatMap((a) => (a.roles || []).map(String)))]
+  const plugins = [...new Set(found.flatMap((a) => (a.plugins || []).map(String)))]
+  const shellPlugins = plugins.filter((p) => SHARED_SHELL_PLUGINS.includes(p))
+  // 「声明的额外插件」= 网关/流程控制台这类**不是**共享壳的。⚠️ 它们**不在本安装器的落盘面内**
+  // （安装器的壳插件名单是固定两个：`allowedPlugins`；profile 装配面由整装/设置页负责）⇒
+  // 回执里必须把"恒装"与"声明需要"分开讲，⛔ 不许把它们混成一句"装了"。
+  const extraPlugins = plugins.filter((p) => !SHARED_SHELL_PLUGINS.includes(p))
+  const skills = [...new Set(found.flatMap((a) => (a.skills || []).map(String)))]
+  const integrations = [...new Set(found.flatMap((a) => (a.integrations || []).map(String)))]
+  // 凭据槽按 slot 去重（同一槽被多个智能体需要 ⇒ 只列一次；why 取第一条）
+  const credMap = new Map()
+  for (const a of found) for (const c of a.credentials || []) if (!credMap.has(c.slot)) credMap.set(c.slot, { ...c, agents: [a.id] })
+    else credMap.get(c.slot).agents.push(a.id)
+  const credentials = [...credMap.values()]
+  const scheduler = found.some((a) => a.scheduler === true)
+  const minPlan = found.reduce((acc, a) => (PLAN_RANK[a.minPlan] > PLAN_RANK[acc] ? a.minPlan : acc), 'free')
+
+  const allCaps = Object.keys(ctx.capabilities || {})
+  const allFlows = Object.keys(ctx.flows || {})
+  const allRoles = Object.keys(ctx.presets || {})
+  // 货架上"别的插件"：排除共享壳、排除**角色承载**（`argent-presets` 是所有角色的挂载面，不是某个智能体的插件，
+  // 把它列进"刻意没装"是误导 —— 它恰恰是这次要落的那一个）。
+  // ⚠️ W3（0.6.0）追加两条**同类**排除（同一条理由：它们不是"可以另外装的插件"）：
+  //   · `argent-shell`（W2 的壳 bundle）—— 基座，不是可选项；列进"刻意没装"是口径错（W2 遗留的假条目）；
+  //   · `argent-agent-<id>`（W3 的智能体 bundle）—— **它们就是智能体本身**（货架上的另一件商品），
+  //     不是"插件"；⛔ 更不能让 `--agent hr` 的回执把另外 5 个智能体列成"故意不装的插件"。
+  const allPlugins = (ctx.plugins || []).filter((p) => p.startsWith('argent-') && !SHARED_SHELL_PLUGINS.includes(p)
+    && p !== 'argent-presets' && p !== 'argent-shell' && !p.startsWith('argent-agent-'))
+  const allSkills = Object.keys(ctx.capabilities || {}).flatMap((c) => (ctx.capabilities[c].packSkills || []))
+    .concat(((doc && doc.agents) || []).flatMap((a) => a.skills || []))
+  const notInstalled = {
+    capabilities: allCaps.filter((c) => !capabilities.includes(c)),
+    flows: allFlows.filter((f) => !flows.includes(f)),
+    roles: allRoles.filter((r) => !roles.includes(r)),
+    plugins: [...new Set(allPlugins)].filter((p) => !extraPlugins.includes(p)),
+    skills: [...new Set(allSkills)].filter((s) => !skills.includes(s)),
+  }
+  return { ok: unknown.length === 0, unknown, capabilities, flows, roles, plugins, shellPlugins, extraPlugins, skills, integrations, credentials, scheduler, minPlan, notInstalled }
+}
+
+/**
+ * **preset 落盘集合**（唯一实现；安装器与升级器共用）。
+ *
+ * 口径（A 批，2026-10-10）：
+ *   · `internal` 为真 ⇒ **全部**（显式 `--internal-roles`；本机开发/内部角色用）；
+ *   · `agentScoped` 为真（`--agent`）⇒ `恒装（always）` ∪ `智能体点名的角色` ∪ `previous`
+ *     —— 这才是"选一个智能体 ⇒ **只落它的角色**"（**同能力的兄弟角色不落**：
+ *        共享能力包里有两条流程时，各自的角色只随各自那一个智能体走）；
+ *   · 否则（默认整装）⇒ `客户可见集（visibility=customer）` ∪ `previous`
+ *     —— **内部角色默认不落客户机**；
+ *   · `previous`（本机**已经装过**的角色）三档都并入。
+ *
+ * ⚠️ 为什么每档都要并上 `previous`：默认集从"全部"收紧成"客户可见/本智能体"后，若不做并集，
+ * **重跑安装器/升级会把本机既有角色一起抹掉**（本机 7 个内部角色正在被内部会话使用；HR 的
+ * `argent-hr-office` 墓碑也靠这条留在老机器上）。收紧的目标是"**全新机器**不许默认拿到不该拿的"，
+ * 不是"把已有机器改坏"。全新机器 `previous` 为空 ⇒ 落盘集合**精确等于**上面那一档。
+ *
+ * @param {{presets: object, agents?: object[], internal?: boolean, agentScoped?: boolean, previous?: Iterable<string>}} o
+ * @returns {string[]} 允许落盘的 preset id（保序 = 货架顺序）
+ */
+export function presetSelectionForAgents({ presets, agents = [], internal = false, agentScoped = false, previous = [] }) {
+  const all = Object.keys(presets || {})
+  if (internal) return all
+  const keep = new Set(previous || [])
+  if (agentScoped && (agents || []).length) {
+    for (const id of all) if ((presets[id] || {}).always === true) keep.add(id)
+  } else {
+    for (const id of all) {
+      const meta = presets[id] || {}
+      const vis = isStr(meta.visibility) ? meta.visibility : 'customer'
+      if (vis === 'customer' || meta.always === true) keep.add(id)
+    }
+  }
+  for (const a of agents || []) for (const r of (a && a.roles) || []) keep.add(String(r))
+  return all.filter((id) => keep.has(id))
+}
+
+/** 「装了什么 / 刻意没装什么」的可复核回执（纯文本行；⛔ 不含凭据值）。 */
+export function composeReceipt(plan, ctx, doc, { dshHome = '', internal = false } = {}) {
+  const L = []
+  const list = (xs) => (xs.length ? xs.join('、') : '（无）')
+  L.push(`  装了什么：`)
+  L.push(`    能力包：${list(plan.capabilities)}`)
+  L.push(`    流程：${list(plan.flows)}${plan.scheduler ? '' : '（本智能体无定时流程）'}`)
+  L.push(`    角色：${list(plan.roles)}${internal ? '（含内部角色）' : ''}`)
+  L.push(`    插件（共享壳，恒装）：${list(plan.shellPlugins || plan.plugins.filter((p) => SHARED_SHELL_PLUGINS.includes(p)))}`)
+  if ((plan.extraPlugins || []).length) {
+    L.push(`    插件（**声明需要**，不在本安装器的落盘面内）：${plan.extraPlugins.join('、')}`)
+    L.push(`      ℹ 网关/流程控制台属 profile 装配面（整装 + 设置页），本命令只做"智能体面"：能力包 + 角色 + 技能`)
+  }
+  L.push(`    技能：${list(plan.skills)}`)
+  L.push(`    系统集成：${list(plan.integrations)}`)
+  L.push(`    宿主资产（判据 = 能力声明的 hostAssets）：定时器 ${plan.scheduler ? '需要' : '**不需要**'}`
+    + `${plan.scheduler ? '（安装器只**打印**命令，⛔ 不自动装）' : '（无 flow ⇒ 没有任何可定时的东西）'}`
+    + `　｜登录自启：默认不建　｜桌面项：无`)
+  if (plan.credentials.length) {
+    L.push(`    凭据**槽位**（⛔ 安装器不写任何值；值只由你/设置页填）：`)
+    for (const c of plan.credentials) L.push(`      · ${c.slot}  →  ${c.target}  —— ${c.why}`)
+  } else {
+    L.push(`    凭据槽位：（无 —— 本智能体不需要外部凭据）`)
+  }
+  L.push(`    档位：${plan.minPlan}${dshHome ? `　装机 home：${dshHome}` : ''}`)
+  L.push(`  刻意没装什么：`)
+  L.push(`    能力包：${list(plan.notInstalled.capabilities)}`)
+  L.push(`    流程：${list(plan.notInstalled.flows)}`)
+  L.push(`    角色：${list(plan.notInstalled.roles)}`)
+  L.push(`    其它插件：${list(plan.notInstalled.plugins)}`)
+  if (!internal) {
+    const internalRoles = Object.keys((ctx && ctx.presets) || {}).filter((r) => (((ctx.presets || {})[r] || {}).visibility === 'internal'))
+    if (internalRoles.length) L.push(`    内部角色（需 --internal-roles 才装）：${internalRoles.join('、')}`)
+  }
+  L.push(`  ⛔ 共享壳 ${SHARED_SHELL_PLUGINS.join(' / ')} 恒装、且移除时永不删（其它智能体还要用）`)
+  return L
+}