@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/check-role-mapping.mjs

@@ -0,0 +1,461 @@
+#!/usr/bin/env node
+/**
+ * 角色映射一致性门禁 + roles.json 生成器（2026-09-15）
+ *
+ * 背景：`PRESET_BY_ROLE` 曾在 gateway 与 drive **各存一份**，漏改一处 ⇒ 角色拿不到工具
+ *       （实测 KB-134：`unknown tool "bash"`）。本脚本把"漏配"从事后发现变成门禁拦截。
+ *
+ * 用法：
+ *   node scripts/check-role-mapping.mjs            # 门禁：gateway.json 角色 ↔ 两份 PRESET_BY_ROLE（**双向**）
+ *   node scripts/check-role-mapping.mjs --emit     # 额外把合并结果写到 stdout（供生成 roles.json）
+ *   node scripts/check-role-mapping.mjs --write    # 生成/刷新 roles.json（角色→preset 的唯一来源）
+ *   node scripts/check-role-mapping.mjs --fix-skills [--yes]   # 按真源修 gateway.json 里**无效**的技能声明（Q6）
+ * 退出码：0 = 一致；1 = 有缺口
+ *
+ * ## 第 ⑤ 项：**反向校验**（声明侧 → gateway 侧；2026-10-04）
+ * 老门禁只做单向：`gateway.json` 里的每个角色必须有映射。反过来「源码/注册表**声明了**某角色、
+ * 但运行期 `gateway.json` 里**根本没有这一行**」不检查 ⇒ 实测 `general` 与 `ml-invoice-xzh`
+ * 有声明无网关角色（**飞书 @ 唤不醒**），而门禁 exit 0（盘点文档 §3-④）。
+ * 现在这一向判红，并区分两类：
+ *   · **有意不接网关** —— 登记在仓库侧 `NO_GATEWAY_BY_DESIGN` 或站点侧
+ *     `$ARGENT_DATA_DIR/role-gateway-exemptions.json`（`{"exemptions":{"<role>":"<理由>"}}`），
+ *     **必须带理由**（缺理由/登记了不存在的角色都判红 —— 否则登记表会变成洗白工具）；
+ *   · **遗漏** —— 未登记 ⇒ ❌ 判红（缺口如实暴露，**不要**为了变绿而登记或擅自塞进 gateway.json）。
+ *
+ * ## 第 ⑥ 项：**技能声明必须真实存在**（Q6，2026-10-04）
+ * `roles[].skills` / `roles[].chats[*].skills` 曾被填成**角色名**（`ml-daily` / `ml-fulfillment`），
+ * 而 `~/.dsh/skills/` 下的真实目录是 `ml-store-daily-report` / `ml-fulfillment-sop` ⇒ 网关注入的
+ * 「【本群启用技能】」提示词**指向空目录**：不抛错、日志无异常、技能永不生效（**静默失效**）。
+ * 判据的**唯一实现**在 `plugins/argent-gateway/src/skill-declaration.js`（网关启动/热重载跑同一份，
+ * ⛔ 不另写"门禁版判据"）；本项把两个声明面都过一遍：
+ *   ① 运行期 `$ARGENT_DATA_DIR/gateway.json`；
+ *   ② 仓库侧客户模板 `deploy/customer/roles.spec.json`（由 `customer-config-migrate.mjs` 并入客户机
+ *      gateway.json ⇒ 模板里的错名会**批量复制**到每台客户机，必须先在这里拦住）。
+ * 空数组 = **没声明**（合法，不报）；缺字段同理。修法见下面的 `--fix-skills`。
+ *
+ * ## `--fix-skills`：按真源修（**只修错的，不猜**）
+ * 真源 = `verticals/<id>/flows.json` 的 `role`+`skill` 配对 + `skills/internal.json` 的键
+ * （见 `skill-declaration.js` 头注释 §二）—— 本脚本不维护第二份名单。
+ *   · 默认 **dry-run**：打印每条 `before → after`，不落盘；
+ *   · `--yes`：写前备份 `<数据目录>/backup/gateway.json.<ts>.skills-fix` ⇒ 同目录 `*.tmp` + `rename`
+ *     **原子写**（网关 watch 的是**目录**，原子写**能**触发热重载；旧的文件级 watch 会被 rename 打死）
+ *     ⇒ 写后**读回并重跑判据**（不靠"我以为写对了"）；
+ *   · `skills: []` / 缺字段 **不动**（那是"没声明"）；真源推导不出候选的 ⇒ 列进 `unresolved` 并 exit 1，
+ *     **绝不编一个名字**。
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+import { resolveDataDir } from './lib/argent-datadir.mjs'
+
+const REPO = new URL('..', import.meta.url).pathname
+// 数据目录：内核三级链（唯一判据）。注意 launchd/定时器里 `HOME` 可能未导出 ⇒ 内核用
+// `env.HOME || homedir()` 兜底，与旧注释（2026-09-28）同一口径。
+const DATA_DIR = resolveDataDir({ env: process.env }).dir
+const GATEWAY_JSON = join(DATA_DIR, 'gateway.json')
+
+/**
+ * 技能声明判据（唯一实现 = 网关那份）。加载失败 ⇒ 由第 ⑥ 项判红（不静默跳过）。
+ * 用动态 import：本脚本是 L2（判据面是宿主），允许引用 `plugins/`。
+ */
+const SD = await (async () => {
+  try { return await import('../plugins/argent-gateway/src/skill-declaration.js') } catch { return null }
+})()
+
+/** 声明面（gateway.json + 仓库客户模板），供第 ⑥ 项与 `--fix-skills` 共用。 */
+const SPEC_JSON = join(REPO, 'deploy/customer/roles.spec.json')
+const readJsonDoc = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return null } }
+/** dsh 家目录（`DSH_HOME` → `$HOME/.dsh`）——技能目录 `<home>/skills/` 在它下面。 */
+const DSH_HOME = process.env.DSH_HOME || join(process.env.HOME || homedir(), '.dsh')
+/** 技能查找根（宿主优先，其次仓库）——与网关启动校验同一份实现。 */
+const SKILL_ROOTS = SD ? SD.resolveSkillRoots({ dshHome: DSH_HOME, repoRoots: [REPO] }) : []
+
+// ══════════════════════════════════════════════════════════════════════════
+// `--fix-skills`：按真源修**无效**的技能声明（Q6）—— 默认 dry-run，`--yes` 才落盘
+//   子命令形态（命中即**短路**，不再跑 ①~⑥ 那套门禁）：它是"修复入口"，不是"体检报告"。
+// ══════════════════════════════════════════════════════════════════════════
+if (process.argv.includes('--fix-skills')) {
+  const APPLY = process.argv.includes('--yes')
+  if (!SD) { console.error('❌ 技能声明判据模块加载失败：plugins/argent-gateway/src/skill-declaration.js（同步插件后再跑）'); process.exit(2) }
+  const doc = readJsonDoc(GATEWAY_JSON)
+  if (!doc || !Array.isArray(doc.roles)) { console.error(`❌ 读不到 gateway.json 的 roles 数组：${GATEWAY_JSON}`); process.exit(2) }
+
+  const known = SD.listSkillNames(SKILL_ROOTS)
+  const { byRole, sources } = SD.deriveRoleSkills({ repoRoots: [REPO] })
+  const { changes, unresolved } = SD.planSkillFixes({
+    declarations: SD.declarationsFromRoles(doc.roles), knownSkills: known, derived: byRole,
+  })
+  console.log(`  文件：${GATEWAY_JSON}`)
+  console.log(`  技能目录：${SKILL_ROOTS.join(' ｜ ') || '（未找到）'}（${known.length} 个技能）`)
+  console.log(`  真源：${sources.join('、') || '（未找到声明文件）'}`)
+  for (const c of changes) {
+    console.log(`  ▸ ${c.where}（role=${c.role}）`)
+    console.log(`      ${JSON.stringify(c.from)}  →  ${JSON.stringify(c.to)}`)
+    console.log(`      无效条目：${c.bad.map((b) => JSON.stringify(b)).join(', ')}`)
+  }
+  for (const u of unresolved) {
+    console.log(`  ❌ 修不了（真源推导不出候选，**不猜**）：${u.where}（role=${u.role}）无效条目 ${u.bad.map((b) => JSON.stringify(b)).join(', ')}`)
+    console.log('     ⇒ 二选一：① 该角色没有对应流程 ⇒ 从 gateway.json 删掉这些声明；② 补一条 `role`+`skill` 声明（flows.json）或把它登记进 skills/internal.json。')
+  }
+  if (!changes.length && !unresolved.length) { console.log('  ✅ 无需修复：所有已声明的技能都真实存在'); process.exit(0) }
+  if (!APPLY) {
+    console.log(`  （dry-run：未落盘。加 --yes 应用这 ${changes.length} 条修改：写前备份 + 同目录 tmp+rename 原子写 + 写后读回验收）`)
+    process.exit(unresolved.length ? 1 : 0)
+  }
+
+  // ── 落盘：① 备份 ② 原子写 ③ 读回验收（三步都不省）──────────────────────────
+  const before = readFileSync(GATEWAY_JSON, 'utf8')
+  const pad = (n) => String(n).padStart(2, '0')
+  const d = new Date()
+  const ts = `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}-${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`
+  const backupDir = join(DATA_DIR, 'backup')
+  mkdirSync(backupDir, { recursive: true })
+  let backup = join(backupDir, `gateway.json.${ts}.skills-fix`)
+  for (let i = 2; existsSync(backup); i++) backup = join(backupDir, `gateway.json.${ts}-${i}.skills-fix`)
+  writeFileSync(backup, before)
+  console.log(`  ✅ 备份：${backup}（${Buffer.byteLength(before)} 字节）`)
+
+  const { applied, skipped } = SD.applySkillFixes(doc, changes)
+  const tmp = `${GATEWAY_JSON}.tmp`                                // 同目录 ⇒ rename 是原子的（跨盘才不原子）
+  const text = JSON.stringify(doc, null, 2) + (before.endsWith('\n') ? '\n' : '')
+  writeFileSync(tmp, text, { mode: statSync(GATEWAY_JSON).mode & 0o777 })
+  renameSync(tmp, GATEWAY_JSON)
+  console.log(`  ✅ 已原子写 ${GATEWAY_JSON}（${applied} 条；跳过 ${skipped.length} 条${skipped.length ? '：' + skipped.join('、') : ''}）`)
+
+  const after = readJsonDoc(GATEWAY_JSON)
+  const left = after ? SD.validateSkillDeclarations({
+    declarations: SD.declarationsFromRoles(after.roles), knownSkills: known, derived: byRole,
+  }) : [{ where: '（读回）', owner: '-', value: 'JSON 解析失败', reason: 'not-array', index: -1, derived: [] }]
+  if (left.length) {
+    console.log(`  ❌ 写后读回**仍有** ${left.length} 条无效声明 —— 备份在 ${backup}（可原样回滚）`)
+    for (const line of SD.formatSkillWarnings(left, { knownSkills: known })) console.log(`  ${line}`)
+    process.exit(1)
+  }
+  console.log(`  ✅ 写后读回验收：${changes.length} 条声明全部指向真实技能目录`)
+  process.exit(unresolved.length ? 1 : 0)
+}
+
+
+
+/** 抽出成对映射（角色 → preset id），用于生成 roles.json。 */
+function extractPairs(file, constName) {
+  const src = existsSync(file) ? readFileSync(file, 'utf8') : ''
+  const re = new RegExp(`const\\s+${constName}\\s*=\\s*Object\\.assign\\(Object\\.create\\(null\\),\\s*\\{`)
+  const m = re.exec(src)
+  if (!m) return {}
+  let i = src.indexOf('{', m.index + m[0].length - 1)
+  let depth = 0, end = -1
+  for (let k = i; k < src.length; k++) {
+    if (src[k] === '{') depth++
+    else if (src[k] === '}') { depth--; if (depth === 0) { end = k; break } }
+  }
+  const out = {}
+  for (const mm of src.slice(i + 1, end).matchAll(/'([a-zA-Z0-9_-]+)'\s*:\s*'([^']+)'/g)) out[mm[1]] = mm[2]
+  return out
+}
+
+/** 从插件源码里抽出 `const NAME = Object.assign(Object.create(null), { ... })` 的键。 */
+function extractKeys(file, constName) {
+  if (!existsSync(file)) return null
+  const src = readFileSync(file, 'utf8')
+  const re = new RegExp(`const\\s+${constName}\\s*=\\s*Object\\.assign\\(Object\\.create\\(null\\),\\s*\\{`)
+  const m = re.exec(src)
+  if (!m) return null
+  let i = src.indexOf('{', m.index + m[0].length - 1)
+  let depth = 0, end = -1
+  for (let k = i; k < src.length; k++) {
+    if (src[k] === '{') depth++
+    else if (src[k] === '}') { depth--; if (depth === 0) { end = k; break } }
+  }
+  const body = src.slice(i + 1, end)
+  const keys = []
+  for (const line of body.split('\n')) {
+    const km = /^\s*'([a-zA-Z0-9_-]+)'\s*:/.exec(line) || /^\s*([a-zA-Z0-9_-]+)\s*:/.exec(line)
+    if (km) keys.push(km[1])
+  }
+  return [...new Set(keys)]
+}
+
+const gw = join(REPO, 'plugins/argent-gateway/src/index.js')
+const dr = join(REPO, 'plugins/argent-drive/src/index.js')
+
+const gwMap = extractKeys(gw, 'PRESET_BY_ROLE')
+// 2026-09-15 P4-4c：argent-drive 已退场 ⇒ 其副本不再要求存在；存在则继续比对（过渡期保护）
+const drMap = extractKeys(dr, 'PRESET_BY_ROLE')
+if (!gwMap) { console.error('❌ 未能从 gateway 源码解析 PRESET_BY_ROLE（源码结构可能变了）'); process.exit(1) }
+if (!drMap) console.log('  · 提示：未找到 argent-drive 的 PRESET_BY_ROLE（已退场，跳过其比对）')
+
+let roles = []
+/** gateway.json 的**整份**解析结果（第 ⑥ 项要按 roles[].skills 逐项核，光有角色名不够）。 */
+let gwDoc = null
+if (existsSync(GATEWAY_JSON)) {
+  try {
+    gwDoc = JSON.parse(readFileSync(GATEWAY_JSON, 'utf8'))
+    const raw = gwDoc.roles
+    // gateway.json 的 roles 是**数组**（每项含 role 字段）；兼容对象写法
+    roles = Array.isArray(raw) ? raw.map((r) => r && r.role).filter(Boolean) : Object.keys(raw || {})
+  } catch (e) { console.error('❌ gateway.json 解析失败:', e.message); process.exit(1) }
+} else {
+  console.log('⚠️ 未找到 gateway.json，跳过角色对比，仅报告两份映射的差异')
+}
+
+// 代码注入的兜底角色：不需要 PRESET_BY_ROLE（用默认 preset）
+//   main = 主 Bot 兜底（gateway 源码 KB-046：config.feishuAppId 的通用助手，运行时注入内存数组）
+const INJECTED_ROLES = new Set(['main'])
+const need = (r) => !INJECTED_ROLES.has(r)
+
+// ── 第 ⑤ 项用：「有意不接网关」的**显式登记**（仓库侧）────────────────────────────
+// 语义：登记 = 声明「这个角色**不需要** gateway.json 的独立条目」，不是「我知道它缺着」。
+// ⛔ 不要为了变绿往这里塞角色（那就是把门禁变成橡皮图章）；每条必须带 reason。
+// 站点侧登记（客户机姿态不同、不该改仓库）用 $ARGENT_DATA_DIR/role-gateway-exemptions.json。
+const NO_GATEWAY_BY_DESIGN = Object.assign(Object.create(null), {
+  // `general`：@ 能力由**主 Bot 兜底**承载 —— gateway 源码 KB-046 的 main 行（agentId=gw-main，
+  // prefix=ROLE_PREFIX.general）+ 无 bot 命中路由（`plugins/argent-gateway/src/index.js:624`
+  // 的 `{ role: 'general', agentId: 'gw-general', prefix: ROLE_PREFIX.general }`）⇒ 无需独立条目。
+  // （客户机模板 `deploy/customer/roles.spec.json` 同样不含 general，与该设计一致。）
+  general: { reason: '主 Bot 兜底行（main）+ 无 bot 命中路由承载，源码 index.js:624 / KB-046 ⇒ 不需要独立条目', since: '2026-10-04' },
+  // `hr-office` / `ml-dev`：**2026-10-04 退役**（docs/Argent-角色合并与收敛-操作方案-2026-10-04.md §3.3）。
+  // 语义要点：这两条**不是**"知道它缺着"，而是"退役后**本就不该**有独立条目"——
+  //   · role 层已撤：`~/.dsh/argent/gateway.json` 里两行已删 ⇒ 飞书 @ 不再派单（这是退役的目的）；
+  //   · 但**墓碑仍在**：`presets/argent-{hr-office,ml-dev}/` 与两份 `PRESET_BY_ROLE` 映射**故意保留**，
+  //     因为 `preset id` 是 web 手选会话头 `agentPreset` 的**外键** —— 删了老会话就打不开
+  //     （`Unknown agent preset`）。⇒ 声明侧仍有这两个角色，必须在这里登记，否则本门禁会把
+  //     "按设计的墓碑"误报成"遗漏"。
+  //   · 收口：观察窗口 ≥2 周后删墓碑（preset 目录 + 行式产物 + 这两条登记），届时本登记一并删除。
+  'hr-office': { reason: '已退役（2026-10-04，方案 §3.3.1）：role 层已撤 ⇒ 不需要独立条目；preset 保留为墓碑（web 老会话的 agentPreset 外键）', since: '2026-10-04' },
+  'ml-dev': { reason: '已退役（2026-10-04，方案 §3.3.2）：role 层已撤 ⇒ 不需要独立条目；preset 保留为墓碑（web 老会话的 agentPreset 外键）', since: '2026-10-04' },
+})
+
+/** 站点侧豁免登记表路径（测试可覆盖；缺省落在数据目录，随站点走、不进仓库）。 */
+const EXEMPTIONS_FILE = process.env.ARGENT_ROLE_GATEWAY_EXEMPTIONS || join(DATA_DIR, 'role-gateway-exemptions.json')
+
+/**
+ * 读站点侧豁免登记表。格式：`{ "exemptions": { "<role>": "<理由>" } }`（也接受扁平 `{role: 理由}`）。
+ * 解析失败**返回 error**（由调用方判红）—— 坏登记表绝不能静默当成"没有豁免"。
+ */
+function loadSiteExemptions() {
+  if (!existsSync(EXEMPTIONS_FILE)) return { map: {}, file: EXEMPTIONS_FILE, present: false, error: null }
+  try {
+    const doc = JSON.parse(readFileSync(EXEMPTIONS_FILE, 'utf8'))
+    const src = (doc && typeof doc === 'object' && doc.exemptions && typeof doc.exemptions === 'object') ? doc.exemptions : (doc || {})
+    const map = Object.assign(Object.create(null), {})
+    for (const [k, v] of Object.entries(src)) {
+      if (['version', 'note', '_doc', '_note', 'exemptions'].includes(k)) continue
+      const reason = typeof v === 'string' ? v : ((v && (v.reason || v.why)) || '')
+      map[k] = { reason: String(reason), since: (v && typeof v === 'object' && v.since) || '', source: 'site' }
+    }
+    return { map, file: EXEMPTIONS_FILE, present: true, error: null }
+  } catch (e) {
+    return { map: {}, file: EXEMPTIONS_FILE, present: true, error: (e && e.message) || String(e) }
+  }
+}
+
+const onlyGw = drMap ? gwMap.filter((r) => !drMap.includes(r)) : []
+const onlyDr = drMap ? drMap.filter((r) => !gwMap.includes(r)) : []
+const missingGw = roles.filter((r) => need(r) && !gwMap.includes(r))
+const missingDr = drMap ? roles.filter((r) => need(r) && !drMap.includes(r)) : []
+
+console.log(`  gateway PRESET_BY_ROLE: ${gwMap.length} 个｜drive: ${drMap ? drMap.length : '—'} 个｜gateway.json 角色: ${roles.length} 个`)
+// 注意：后续检查（preset 目录、roles.json）也会置红，故必须是 let。
+// 2026-09-28 实测：写成 const 时，客户机的 roles.json 缺失分支一赋值就 TypeError ——
+// 门禁**自己崩掉**而不是报红，比漏检更糟（人看到的是栈，不是"缺 roles.json"）。
+let bad = onlyGw.length + onlyDr.length + missingGw.length + missingDr.length
+if (onlyGw.length) console.log(`  ❌ 仅 gateway 有（drive 缺）: ${onlyGw.join(', ')}`)
+if (onlyDr.length) console.log(`  ❌ 仅 drive 有（gateway 缺）: ${onlyDr.join(', ')}`)
+if (missingGw.length) console.log(`  ❌ gateway.json 有但 gateway 映射缺: ${missingGw.join(', ')}`)
+if (missingDr.length) console.log(`  ❌ gateway.json 有但 drive 映射缺: ${missingDr.join(', ')}`)
+if (!bad) console.log('  ✅ 三方一致：gateway.json 每个角色在两份 PRESET_BY_ROLE 里都有映射')
+
+// 2026-09-17 新增：**角色引用的 preset 目录必须存在**（否则角色起来会缺工具，静默失败）。
+// 来源两处：① 真实产物 ~/.dsh/argent/roles.json 的 presets 段；② gateway 源码里的映射对。
+// 注意：`roles` 这个变量是**角色名数组**（来自 gateway.json），不是 roles.json 的解析结果 —— 别读错。
+{
+  const referenced = new Set()
+  try {
+    // 用 homedir() 而不是 process.env.HOME：launchd/定时器环境里 HOME 可能未导出（2026-09-28）
+    const p = join(DATA_DIR, 'roles.json')
+    if (existsSync(p)) {
+      const doc = JSON.parse(readFileSync(p, 'utf8'))
+      for (const v of Object.values((doc && doc.presets) || {})) if (typeof v === 'string') referenced.add(v)
+    }
+  } catch (e) {
+    // 这里只负责"收集引用"，**不判红**；坏文件由下面第 ④ 项检查统一判红并给修法
+    console.error(`  ⚠️ roles.json 解析失败（第 ④ 项检查会判红）：${e && e.message}`)
+  }
+  for (const v of Object.values(extractPairs(gw, 'PRESET_BY_ROLE'))) if (typeof v === 'string') referenced.add(v)
+  if (!referenced.size) {
+    console.error('  ❌ 检查到 0 个 preset 引用 —— 说明来源路径/解析有问题（不允许假绿灯）')
+    process.exit(1)
+  }
+  const presetsDir = join(REPO, 'presets')
+  const missingPresets = [...referenced].filter((pid) =>
+    !existsSync(join(presetsDir, pid)) || !existsSync(join(presetsDir, pid, 'agent.cordis.yml')))
+  if (missingPresets.length) {
+    console.error(`  ❌ 引用了不存在的 preset：${missingPresets.join(', ')}`)
+    console.error('     ⇒ 角色起来会缺工具（静默）。修：改名/新建 preset 后跑 node scripts/check-role-mapping.mjs --write')
+    process.exit(1)
+  }
+  console.log(`  ✅ 引用的 ${referenced.size} 个 preset 目录都存在`)
+
+  // 2026-09-17 新增（客户机核对时发现）：**仓库里有 ≠ 运行时装着**。
+  // 角色真正唤起时 dsh 从 `$DSH_HOME/.agent-presets/<id>/` 挂载；只在仓库 presets/ 里存在
+  // ⇒ 角色会话建得起来但缺工具（实测：新建的 argent-ml-invoice-xzh 一直没装进运行时目录，
+  //    而旧门禁只查仓库目录 ⇒ 假绿灯）。这里补一条运行时检查：
+  //    · 运行时目录整个不存在 ⇒ 只提示（可能是隔离 home / 客户机尚未部署）
+  //    · 目录存在但缺某个被引用的 preset ⇒ 直接失败（一定会静默缺工具）
+  const runtimeDir = join(DSH_HOME, '.agent-presets')
+  if (!existsSync(runtimeDir)) {
+    console.log(`  ⚠️ 运行时 preset 目录不存在（跳过运行时检查）：${runtimeDir}`)
+  } else {
+    const notInstalled = [...referenced].filter((pid) => !existsSync(join(runtimeDir, pid, 'agent.cordis.yml')))
+    if (notInstalled.length) {
+      console.error(`  ❌ 运行时未安装的 preset：${notInstalled.join(', ')}（目录 ${runtimeDir}）`)
+      console.error('     ⇒ 角色会话能建起来但缺工具（静默失败）。修：bash scripts/sync-presets.sh <id>')
+      process.exit(1)
+    }
+    console.log(`  ✅ 运行时已安装全部 ${referenced.size} 个 preset（${runtimeDir}）`)
+  }
+}
+
+// ④ roles.json 是否与角色集一致（2026-09-28 P10 踩坑）：
+// 这份文件是**运行时**角色→preset 的唯一来源（flow_preflight 读它判"角色映射不一致"）。
+// 老版本门禁只比 gateway.json ↔ 源码常量 ⇒ 客户机上 roles.json **根本不存在**时这里仍然全绿，
+// 而流程触发器却因角色映射缺失被拦 ⇒ 两边说法不一致。故补这一项。
+{
+  const rolesJson = join(DATA_DIR, 'roles.json')
+  let doc = null
+  try { doc = JSON.parse(readFileSync(rolesJson, 'utf8')) } catch { doc = null }
+  const expect = Object.assign({}, extractPairs(dr, 'PRESET_BY_ROLE'), extractPairs(gw, 'PRESET_BY_ROLE'))
+  const need = [...roles].filter((r) => expect[r])          // 只要求 gateway 现有角色可用
+  if (!doc) {
+    bad = true
+    console.log(`  ❌ 缺 ${rolesJson}（运行时角色→preset 的唯一来源）⇒ flow_preflight 会判「角色映射不一致」并拦住触发器`)
+    console.log('     ⇒ 修：node scripts/check-role-mapping.mjs --write')
+  } else {
+    const got = doc.presets || {}
+    const missing = need.filter((r) => !got[r])
+    const wrong = need.filter((r) => got[r] && got[r] !== expect[r])
+    if (missing.length || wrong.length) {
+      bad = true
+      if (missing.length) console.log(`  ❌ roles.json 缺角色：${missing.join(', ')}（流程会挂错 preset 或挂不上）`)
+      if (wrong.length) console.log(`  ❌ roles.json 映射不符：${wrong.map((r) => `${r}: ${got[r]} ≠ ${expect[r]}`).join('；')}`)
+      console.log('     ⇒ 修：node scripts/check-role-mapping.mjs --write')
+    } else {
+      console.log(`  ✅ roles.json 与角色集一致（${need.length} 个角色）`)
+    }
+  }
+}
+
+// ⑤ **反向校验：声明侧有、gateway.json 没有**（2026-10-04，盘点 §3-④ 的缺口）
+// 为什么要它：老门禁只有 `missingGw`（gateway.json 的角色必须有映射）这**一个方向**；
+// 「源码/注册表声明了某角色、而运行期 gateway.json 里根本没有这一行」= 该角色**飞书 @ 唤不醒**，
+// 却一路绿灯（实测：`general` / `ml-invoice-xzh`）。这一项把该缺口从"没人知道"变成"门禁报红"。
+{
+  if (!existsSync(GATEWAY_JSON)) {
+    // 没有任何 gateway 配置 ⇒ 没有任何角色可被唤醒，属**未配置**状态（上面已提示"跳过角色对比"）；
+    // 这里**不**把 13 个声明全列成缺口（那是噪音，不是漂移）。⚠️ 该状态下反向校验不生效 —— 如实标注。
+    console.log('  ⚠️ 无 gateway.json ⇒ 第 ⑤ 项反向校验跳过（该状态下没有任何角色能被 @ 唤醒，属未配置而非映射漂移）')
+  } else {
+    const gwSet = new Set(roles)
+    // 声明侧 = 两份 PRESET_BY_ROLE（源码）+ roles.json#presets（运行期注册表；坏文件由第 ④ 项判红）
+    const declared = new Set([...gwMap, ...(drMap || [])])
+    try {
+      const doc = JSON.parse(readFileSync(join(DATA_DIR, 'roles.json'), 'utf8'))
+      for (const r of Object.keys((doc && doc.presets) || {})) declared.add(r)
+    } catch { /* 缺/坏 roles.json 由第 ④ 项判红；这里只是少一路声明来源 */ }
+    const notInGateway = [...declared].filter((r) => need(r) && !gwSet.has(r)).sort()
+    // 登记表 = 仓库侧（随代码评审）+ 站点侧（机器姿态）；同角色以仓库侧为准
+    const site = loadSiteExemptions()
+    const registered = new Map()
+    for (const [r, v] of Object.entries(NO_GATEWAY_BY_DESIGN)) registered.set(r, { ...v, source: 'repo' })
+    for (const [r, v] of Object.entries(site.map)) if (!registered.has(r)) registered.set(r, v)
+    // 登记表自身卫生：① 每条必须带理由；② 不许登记"不存在的角色"（错别字/腐烂 ⇒ 会掩盖真缺口）
+    const known = new Set([...declared, ...gwSet, ...INJECTED_ROLES])
+    const noReason = [...registered].filter(([, v]) => !String(v.reason || '').trim()).map(([r]) => r).sort()
+    const unknownReg = [...registered.keys()].filter((r) => !known.has(r)).sort()
+    const intentional = notInGateway.filter((r) => registered.has(r))
+    const gaps = notInGateway.filter((r) => !registered.has(r))
+    if (site.error) {
+      bad = true
+      console.log(`  ❌ 站点侧豁免登记表解析失败：${site.file}（${site.error}）⇒ 不能当成"没有豁免"（否则缺口被静默吞掉）`)
+    }
+    if (noReason.length) {
+      bad = true
+      console.log(`  ❌ 豁免登记缺理由：${noReason.join(', ')}（带理由才叫"有意"，无理由与"遗漏"无法区分）`)
+    }
+    if (unknownReg.length) {
+      bad = true
+      console.log(`  ❌ 豁免登记了不存在的角色：${unknownReg.join(', ')}（错别字/腐烂登记 ⇒ 会掩盖真正缺的角色）`)
+    }
+    bad += gaps.length
+    console.log(`  声明侧 ${declared.size} 个角色 → gateway.json ${gwSet.size} 个：不在网关的 ${notInGateway.length} 个（有意不接 ${intentional.length} / 遗漏 ${gaps.length}）`)
+    for (const r of intentional) {
+      const e = registered.get(r)
+      console.log(`  ✅ 有意不接网关（已登记理由，非"遗漏"）：${r} —— ${e.reason}（来源：${e.source === 'repo' ? 'NO_GATEWAY_BY_DESIGN' : site.file}）`)
+    }
+    if (gaps.length) {
+      console.log(`  ❌ 声明了但 gateway.json 没有（**飞书 @ 唤不醒**）：${gaps.join(', ')}`)
+      console.log('     ⇒ 二选一：① 在运行期 gateway.json 补该角色条目（机器配置 ⇒ 需用户点头 + 重启窗口）；')
+      console.log(`        ② 确属**有意**不接网关 ⇒ 带理由登记：站点侧 ${site.file}`)
+      console.log('           （{"exemptions":{"<role>":"<为什么不需要独立条目>"}}）或仓库侧本脚本的 NO_GATEWAY_BY_DESIGN。')
+      console.log('        ⛔ 不要为了变绿而登记，也不要为了变绿擅自把角色塞进 gateway.json。')
+    } else {
+      console.log('  ✅ 声明侧每个角色在 gateway.json 里都有条目（或已登记"有意不接"）')
+    }
+  }
+}
+
+// ⑥ 技能声明必须真实存在（Q6，2026-10-04）
+// 判据的唯一实现在 plugins/argent-gateway/src/skill-declaration.js（**网关启动/热重载跑同一份**）。
+// 两个声明面都过：① 运行期 gateway.json ② 仓库侧客户模板 deploy/customer/roles.spec.json
+// （模板会被 customer-config-migrate 并入每台客户机 ⇒ 这里的错名是**批量**故障）。
+{
+  if (!SD) {
+    bad = true
+    console.log('  ❌ 技能声明判据模块加载失败：plugins/argent-gateway/src/skill-declaration.js')
+    console.log('     ⇒ 该模块是网关启动校验与本节判据的**唯一实现**；缺它 ⇒ 技能声明无人校验（静默失效复发面）')
+  } else {
+    const known = SD.listSkillNames(SKILL_ROOTS)
+    const { byRole, sources } = SD.deriveRoleSkills({ repoRoots: [REPO] })
+    const surfaces = []
+    if (gwDoc && Array.isArray(gwDoc.roles)) surfaces.push({ file: GATEWAY_JSON, roles: gwDoc.roles })
+    else console.log('  ⚠️ 无 gateway.json（或 roles 非数组）⇒ 本节只查仓库侧客户模板')
+    const specDoc = readJsonDoc(SPEC_JSON)
+    if (specDoc && Array.isArray(specDoc.roles)) surfaces.push({ file: SPEC_JSON, roles: specDoc.roles })
+    else console.log(`  ⚠️ 读不到客户模板 ${SPEC_JSON} ⇒ 本节不查它（模板缺失本身不判红）`)
+
+    console.log(`  技能目录：${SKILL_ROOTS.join(' ｜ ') || '（未找到）'}（${known.length} 个技能）｜真源：${sources.length} 份声明文件`)
+    let bad6 = 0
+    for (const s of surfaces) {
+      const problems = SD.validateSkillDeclarations({
+        declarations: SD.declarationsFromRoles(s.roles), knownSkills: known, derived: byRole,
+      })
+      if (!problems.length) { console.log(`  ✅ ${s.file}：已声明的技能都真实存在（空数组 = 没声明，不算错）`); continue }
+      bad6 += problems.length
+      console.log(`  ❌ ${s.file}：${problems.length} 条技能声明指向**不存在**的技能目录（网关注入的「【本群启用技能】」会指向空目录，静默失效）`)
+      for (const line of SD.formatSkillWarnings(problems, { knownSkills: known })) console.log(`  ${line}`)
+    }
+    if (bad6) {
+      console.log('     ⇒ 修：node scripts/check-role-mapping.mjs --fix-skills --yes（按真源修错名；先备份 + 原子写 + 写后读回）')
+      console.log('       ⛔ 别手改第二份名单：角色→技能 的真源是 verticals/<id>/flows.json 的 role+skill 与 skills/internal.json。')
+      bad += bad6
+    }
+  }
+}
+
+if (process.argv.includes('--write')) {
+  const pairs = Object.assign({}, extractPairs(dr, 'PRESET_BY_ROLE'), extractPairs(gw, 'PRESET_BY_ROLE'))
+  const doc = { version: 1, generatedAt: new Date().toISOString(),
+    note: '角色 → preset 的**唯一来源**（Hub 化）。gateway/drive 读取本文件；源码内常量仅作缺失兜底。由 scripts/check-role-mapping.mjs --write 生成。',
+    presets: pairs }
+  const out = join(DATA_DIR, 'roles.json')
+  writeFileSync(out, JSON.stringify(doc, null, 2) + '\n', 'utf8')
+  console.log(`  ✅ 已写 ${out}（${Object.keys(pairs).length} 个角色）`)
+}
+
+if (process.argv.includes('--emit')) {
+  const merged = {}
+  for (const r of [...new Set([...gwMap, ...drMap, ...roles])].sort()) merged[r] = { preset: gwMap.includes(r) ? true : (drMap.includes(r) ? true : false) }
+  console.log(JSON.stringify({ generatedAt: new Date().toISOString(), roles: merged }, null, 2))
+}
+process.exit(bad ? 1 : 0)