@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/check-1.0-criteria.mjs

@@ -0,0 +1,355 @@
+#!/usr/bin/env node
+/**
+ * check-1.0-criteria.mjs —— 《Argent 1.0 退出判据与版本规则》§2 的**计数自洽**门禁（只读）
+ *
+ * ## 为什么有它（2026-10-05 实测到真漂移）
+ * §2.0「八面总览」是**手写的汇总**（每面条数 + 🔴/🟡/✅ 计数 + 卡点一句话），
+ * 而**唯一真源**是 §2.1–§2.8 的判据行。两处靠人抄 ⇒ 已经漂过两次：
+ *   · 运营面写「🔴 1 / 🟡 4 / ✅ 0 ｜ 无只读运营视图（只能 `mongosh`）」——
+ *     判据行实为 **🟡 5**（O2 的只读视图早已落地，服务端只读接口也已上线）；
+ *   · 文档与官网面写「官网仍是 0.9.9 口径」—— P2 行的那两条事实依据（落地页 0.9.9 /
+ *     售卖已退役角色）已被官网改版替换。
+ * ⇒ 本门禁把「抄」变成「算」：**只读解析文档**，逐面复算并比对。
+ *
+ * ## 判据（唯一真源 = §2.1–§2.8 的判据行；本脚本不改任何文件）
+ * | # | 判据 | 说明 |
+ * |---|---|---|
+ * | ① | 判据条数 == **40** | {@link EXPECTED_TOTAL}，与 §2.0 合计行、文末图例「1.0 = 40 条全 ✅」同源 |
+ * | ② | 每面：实得条数 == §2.0 声明条数 | 少一行/多一行当场点名 |
+ * | ③ | 每面：实得 🔴/🟡/✅ == §2.0 声明计数 | 本门禁的**主判据** |
+ * | ④ | 八面计数之和 == §2.0 合计行 | 合计行不是"另算一份"，是八面之和 |
+ * | ⑤ | 每面「主要卡点」非空 | 不许留白，也不许只写占位符 `—` |
+ * | ⑥ | 每行「现状」格的首个符号 ∈ {🔴,🟡,✅} | `—` 仅限**显式写明不适用**的行（单独报告、不计数） |
+ * | ⑦ | 判据行 ID = 面字母 + 从 1 起的连续编号 | 缺行 / 串面 / 重复号当场点名 |
+ *
+ * ## 用法
+ * ```bash
+ * node scripts/check-1.0-criteria.mjs            # 只报告（**默认恒 exit 0**）
+ * node scripts/check-1.0-criteria.mjs --strict   # 有问题 ⇒ exit 1（CI 判据 `1.0-criteria` 用这个）
+ * node scripts/check-1.0-criteria.mjs --json     # 机器可读（给别的脚本/记录用）
+ * node scripts/check-1.0-criteria.mjs --file <p> # 换文档（夹具/自测用；默认见 {@link DEFAULT_DOC}）
+ * ```
+ * 退出码：`0` 检查跑完（默认模式即便发现问题也是 0）｜`1` `--strict` 且有问题 ｜`2` 用法/环境错误（文档读不到）。
+ *
+ * ## 纪律
+ * · **只读**：不写文件、不读凭据、不联网、不碰数据目录（数据目录判据只有 `core/lib/argent-datadir.mjs` 一份，
+ *   本脚本根本不需要它 —— 它只读仓库里的一份 Markdown）；
+ * · **同一份判据进 CI**：`bash scripts/ci-run.sh --only 1.0-criteria`；清单见 `docs/CI-自建runner.md` §2。
+ */
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const REPO = resolve(HERE, '..')
+
+/** 1.0 的判据总条数（八面之和；改它必须同批改 §2.0 合计行与文末图例 —— 本门禁会一起核）。 */
+export const EXPECTED_TOTAL = 40
+
+/** 允许的状态符号（顺序 = 报告顺序）。 */
+export const STATUS = ['🔴', '🟡', '✅']
+
+/** 八面的字母顺序（§2.1 → §2.8）。 */
+export const FACE_ORDER = ['D', 'L', 'C', 'H', 'G', 'O', 'B', 'P']
+
+/** 默认文档（相对仓库根）。 */
+export const DEFAULT_DOC = 'docs/Argent-1.0-退出判据与版本规则.md'
+
+// ══════════════════════════════════════════════════════════════════════════
+// 一、解析（纯函数：吃文本、吐结构 —— 便于夹具自测与复用）
+// ══════════════════════════════════════════════════════════════════════════
+
+/** Markdown 表格行 → 单元格数组（去首尾竖线；**不**处理转义 —— 本表约定单元格内不写裸 `|`）。 */
+export function splitRow(line) {
+  let s = String(line).trim()
+  if (!s.startsWith('|')) return null
+  s = s.slice(1)
+  if (s.endsWith('|')) s = s.slice(0, -1)
+  return s.split('|').map((c) => c.trim())
+}
+
+/** 去掉单元格里的粗体标记，便于取首符号/判空。 */
+const plain = (s) => String(s == null ? '' : s).replace(/\*\*/g, '').trim()
+
+/** 取「现状」格的首个状态符号：返回 `{ kind: 'status'|'na'|'illegal'|'empty', symbol }`。 */
+export function leadingStatus(cell) {
+  const c = plain(cell)
+  if (c === '') return { kind: 'empty', symbol: '' }
+  const ch = Array.from(c)[0]
+  if (STATUS.includes(ch)) return { kind: 'status', symbol: ch }
+  if (ch === '—' || ch === '-') {
+    // 图例允许「显式写明 `—` 及其理由」的行 ⇒ 单独报告，不计数；但**必须**有理由文字。
+    const reason = c.replace(/^[—\-]\s*/, '').trim()
+    return { kind: 'na', symbol: ch, reason }
+  }
+  return { kind: 'illegal', symbol: ch }
+}
+
+/** 取「现状」格里的 `符号 + 数字` 对（缺的类别按 0 算，便于两种书写风格都能读）。 */
+export function countsOf(cell) {
+  const out = { '🔴': 0, '🟡': 0, '✅': 0 }
+  const re = /(🔴|🟡|✅)\s*\*{0,2}\s*(\d+)/gu
+  let m
+  while ((m = re.exec(String(cell))) !== null) out[m[1]] = Number(m[2])
+  return out
+}
+
+const sameCounts = (a, b) => STATUS.every((s) => (a[s] || 0) === (b[s] || 0))
+const fmtCounts = (c) => STATUS.map((s) => `${s} ${c[s] || 0}`).join(' / ')
+
+/**
+ * 解析整份文档。
+ * 返回 `{ faces, overview, legend }`：
+ *   · `faces[]`  = §2.1–§2.8 的判据行（**唯一真源**）+ 逐面实得计数；
+ *   · `overview` = §2.0 八面总览（声明条数/计数/卡点）+ 合计行；
+ *   · `legend`   = 文末图例里的「1.0 = N 条全 ✅」。
+ */
+export function parseDoc(text) {
+  const lines = String(text).split('\n')
+
+  // ── 定位八面的小节标题（`### 2.<n> <名>面（<字母>）`）────────────────────
+  const heads = []
+  lines.forEach((line, i) => {
+    const m = /^###\s+2\.(\d+)\s+(.+?)面（([A-Z])）\s*$/.exec(line.trim())
+    if (m) heads.push({ line: i, idx: Number(m[1]), name: m[2], letter: m[3] })
+  })
+
+  const faces = []
+  for (let h = 0; h < heads.length; h++) {
+    const head = heads[h]
+    // 小节范围 = 本标题之后、**下一个任意级标题**之前（§2.8 后面紧跟 `---` 与 `## 3.`；
+    // ⛔ 不能用"下一个判据小节标题"当边界 —— 那样最后一面会一路吃到 §6 决策表的 `Q*` 行）。
+    let end = lines.length
+    for (let i = head.line + 1; i < lines.length; i++) {
+      if (/^#{1,4}\s/.test(lines[i].trim())) { end = i; break }
+    }
+    const rows = []
+    for (let i = head.line + 1; i < end; i++) {
+      const t = lines[i].trim()
+      if (!t.startsWith('|')) continue
+      const c = splitRow(t)
+      if (!c || c.length < 5) continue
+      const m = /^([A-Z])(\d+)$/.exec(plain(c[0]))
+      if (!m) continue
+      // 判据行布局：`| ID | 判据 | 现状 | 缺口 | 验收 |` ⇒ 现状 = c[2]
+      rows.push({ lineNo: i + 1, id: `${m[1]}${m[2]}`, letter: m[1], num: Number(m[2]), cell: c[2] })
+    }
+    const tally = { '🔴': 0, '🟡': 0, '✅': 0 }
+    let na = 0
+    const statuses = []
+    for (const r of rows) {
+      const st = leadingStatus(r.cell)
+      r.status = st
+      if (st.kind === 'status') tally[st.symbol]++
+      else if (st.kind === 'na') na++
+      statuses.push(st)
+    }
+    faces.push({ ...head, rows, tally, na, statuses, count: rows.length })
+  }
+
+  // ── 定位 §2.0 八面总览 + 合计行 ─────────────────────────────────────────
+  const oStart = lines.findIndex((l) => /^###\s+2\.0\s/.test(l.trim()))
+  let oEnd = lines.length
+  for (let i = Math.max(oStart, 0) + 1; i < lines.length; i++) {
+    if (/^#{2,3}\s/.test(lines[i].trim())) { oEnd = i; break }
+  }
+  const overview = { rows: [], total: null }
+  if (oStart >= 0) {
+    for (let i = oStart + 1; i < oEnd; i++) {
+      const t = lines[i].trim()
+      if (!t.startsWith('|')) continue
+      const c = splitRow(t)
+      if (!c || c.length < 5) continue
+      if (/^\**合计\**$/.test(plain(c[1]))) {
+        overview.total = { lineNo: i + 1, declaredTotal: Number(plain(c[2]).replace(/[^0-9]/g, '')), counts: countsOf(c[3]), blockers: plain(c[4]) }
+        continue
+      }
+      if (!/^\d+$/.test(plain(c[0]))) continue
+      overview.rows.push({
+        lineNo: i + 1,
+        index: Number(plain(c[0])),
+        name: plain(c[1]),
+        declaredCount: Number(plain(c[2]).replace(/[^0-9]/g, '')),
+        counts: countsOf(c[3]),
+        blockers: plain(c[4]),
+      })
+    }
+  }
+
+  // ── 文末图例：「1.0 = N 条全 ✅」────────────────────────────────────────
+  const lg = /1\.0\s*=\s*(\d+)\s*条全\s*✅/.exec(String(text))
+  const legend = lg ? { lineNo: lines.findIndex((l) => l.includes(lg[0])) + 1, total: Number(lg[1]) } : null
+
+  return { faces, overview, legend }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 二、判据（吃解析结果、吐问题清单）
+// ══════════════════════════════════════════════════════════════════════════
+
+/** 逐条跑 ①–⑦，返回 `{ problems, notes }`（problems 为空 = 自洽）。 */
+export function checkDoc(parsed, { expectedTotal = EXPECTED_TOTAL } = {}) {
+  const problems = []
+  const notes = []
+  const add = (rule, where, msg) => problems.push({ rule, where, msg })
+  const { faces, overview, legend } = parsed
+
+  // 结构面：八个小节都在、顺序对
+  if (faces.length !== FACE_ORDER.length) {
+    add('结构', '§2.1–§2.8', `判据小节数 ${faces.length} ≠ ${FACE_ORDER.length}（八面各一节）`)
+  }
+  faces.forEach((f, i) => {
+    const want = FACE_ORDER[i]
+    if (want && f.letter !== want) add('结构', `§2.${f.idx}`, `第 ${i + 1} 面的字母是 ${f.letter}，期望 ${want}（八面顺序 = ${FACE_ORDER.join('/')}）`)
+  })
+
+  // ① 条数 40
+  const actualTotal = faces.reduce((a, f) => a + f.count, 0)
+  if (actualTotal !== expectedTotal) add('①条数', '§2.1–§2.8', `判据行实得 ${actualTotal} 条 ≠ 期望 ${expectedTotal} 条`)
+
+  // 图例（同源常量）
+  if (legend && legend.total !== expectedTotal) {
+    add('①条数', `第 ${legend.lineNo} 行（图例）`, `图例写「${legend.total} 条全 ✅」≠ ${expectedTotal}`)
+  }
+
+  // ②/③/⑤/⑥/⑦ 逐面
+  overview.rows.forEach((o, i) => {
+    const f = faces[i]
+    const label = `${o.index} ${o.name}`
+    if (!f) { add('结构', `§2.0 第 ${o.lineNo} 行`, `${label}：没有对应的判据小节`); return }
+    if (f.name !== o.name.replace(/（.*?）$/, '')) {
+      notes.push(`§2.0「${o.name}」↔ §2.${f.idx}「${f.name}面」名字不同（按顺序配对，仅供人工确认）`)
+    }
+    if (f.count !== o.declaredCount) {
+      add('②条数', `§2.0 第 ${o.lineNo} 行`, `${label}：声明 ${o.declaredCount} 条，判据行实得 ${f.count} 条`)
+    }
+    if (!sameCounts(f.tally, o.counts)) {
+      add('③计数', `§2.0 第 ${o.lineNo} 行`, `${label}：声明 ${fmtCounts(o.counts)}，判据行实得 ${fmtCounts(f.tally)}`)
+    }
+    if (o.blockers === '' || /^[—\-]+$/.test(o.blockers)) {
+      add('⑤卡点', `§2.0 第 ${o.lineNo} 行`, `${label}：主要卡点为空（不许留白/占位 —）`)
+    }
+    if (f.na > 0) notes.push(`${label}：有 ${f.na} 行显式标「—」（不计入 🔴/🟡/✅，按图例须写明理由）`)
+  })
+
+  // ④ 合计行 = 八面之和
+  const sum = { '🔴': 0, '🟡': 0, '✅': 0 }
+  faces.forEach((f) => STATUS.forEach((s) => { sum[s] += f.tally[s] }))
+  if (!overview.total) {
+    add('④合计', '§2.0', '找不到「合计」行')
+  } else {
+    const t = overview.total
+    if (t.declaredTotal !== actualTotal) add('④合计', `§2.0 第 ${t.lineNo} 行`, `合计行声明 ${t.declaredTotal} 条 ≠ 八面实得 ${actualTotal} 条`)
+    if (!sameCounts(sum, t.counts)) add('④合计', `§2.0 第 ${t.lineNo} 行`, `合计行声明 ${fmtCounts(t.counts)}，八面之和 ${fmtCounts(sum)}`)
+  }
+
+  // ⑥ 状态符号合法 + ⑦ ID 连续
+  faces.forEach((f) => {
+    const seen = new Set()
+    f.rows.forEach((r, i) => {
+      if (r.status.kind === 'illegal') add('⑥符号', `第 ${r.lineNo} 行（${r.id}）`, `「现状」格首符号「${r.status.symbol}」不在允许集 ${STATUS.join('/')} 内`)
+      if (r.status.kind === 'empty') add('⑥符号', `第 ${r.lineNo} 行（${r.id}）`, '「现状」格为空')
+      if (r.status.kind === 'na' && !r.status.reason) add('⑥符号', `第 ${r.lineNo} 行（${r.id}）`, '标了「—」但没写不适用理由')
+      if (r.letter !== f.letter) add('⑦编号', `第 ${r.lineNo} 行（${r.id}）`, `行 ID 字母 ${r.letter} ≠ 本节面字母 ${f.letter}`)
+      if (r.num !== i + 1) add('⑦编号', `第 ${r.lineNo} 行（${r.id}）`, `本节第 ${i + 1} 行的编号是 ${r.num}（应为 ${i + 1}，缺行或串号）`)
+      if (seen.has(r.id)) add('⑦编号', `第 ${r.lineNo} 行（${r.id}）`, '行 ID 重复')
+      seen.add(r.id)
+    })
+  })
+
+  return { problems, notes, actualTotal, sum }
+}
+
+// ══════════════════════════════════════════════════════════════════════════
+// 三、CLI
+// ══════════════════════════════════════════════════════════════════════════
+
+function main(argv) {
+  const has = (f) => argv.includes(f)
+  const val = (f) => { const i = argv.indexOf(f); return i >= 0 ? argv[i + 1] : null }
+  if (has('-h') || has('--help')) {
+    console.log('用法：node scripts/check-1.0-criteria.mjs [--strict] [--json] [--file <文档>]')
+    console.log('判据：① 条数 40 ② 每面条数 ③ 每面 🔴/🟡/✅ ④ 合计 = 八面之和 ⑤ 卡点非空 ⑥ 状态符号合法 ⑦ ID 连续')
+    console.log('退出码：0 跑完（默认只报告）｜1 --strict 且有问题｜2 用法/环境错误')
+    return 0
+  }
+  const unknown = argv.filter((a, i) => a.startsWith('-') && !['--strict', '--json', '--file', '-h', '--help'].includes(a)
+    && !(i > 0 && ['--file'].includes(argv[i - 1])))
+  if (unknown.length) { console.error(`✗ 未知参数：${unknown.join(' ')}`); return 2 }
+
+  const docArg = val('--file')
+  const docRel = docArg || DEFAULT_DOC
+  const docAbs = resolve(REPO, docRel)
+  let text
+  try {
+    text = readFileSync(docAbs, 'utf8')
+  } catch (e) {
+    console.error(`✗ 读不到文档：${docAbs}（${(e && e.message) || e}）`)
+    console.error('  ⇒ 用法错误/环境错误 exit 2（本门禁读的是仓库里的判据文档，⛔ 不猜路径、不跳过后报绿）')
+    return 2
+  }
+
+  const parsed = parseDoc(text)
+  const { problems, notes, actualTotal, sum } = checkDoc(parsed)
+  const strict = has('--strict')
+
+  if (has('--json')) {
+    console.log(JSON.stringify({
+      schema: 'argent-1.0-criteria/1',
+      doc: docRel,
+      expectedTotal: EXPECTED_TOTAL,
+      actualTotal,
+      ok: problems.length === 0,
+      faces: parsed.faces.map((f, i) => ({
+        letter: f.letter, name: f.name, section: `2.${f.idx}`,
+        count: f.count, tally: f.tally, na: f.na,
+        declared: parsed.overview.rows[i] ? { count: parsed.overview.rows[i].declaredCount, tally: parsed.overview.rows[i].counts } : null,
+      })),
+      declaredTotal: parsed.overview.total ? parsed.overview.total.declaredTotal : null,
+      sum,
+      problems, notes,
+    }, null, 2))
+    return problems.length === 0 ? 0 : (strict ? 1 : 0)
+  }
+
+  console.log(`1.0 判据文档一致性检查 —— ${docRel}`)
+  console.log('  唯一真源 = §2.1–§2.8 的判据行；本检查只读、不改文件')
+  console.log('')
+  console.log(`  §2.0 复算（逐面：声明 vs 判据行实得）`)
+  parsed.faces.forEach((f, i) => {
+    const o = parsed.overview.rows[i]
+    const declared = o ? `${o.declaredCount} 条 ｜ ${fmtCounts(o.counts)}` : '（§2.0 缺这一行）'
+    const actual = `${f.count} 条 ｜ ${fmtCounts(f.tally)}${f.na ? ` ｜ — ${f.na}` : ''}`
+    const okRow = o && o.declaredCount === f.count && sameCounts(o.counts, f.tally)
+    console.log(`    ${okRow ? '✅' : '❌'} ${String(i + 1).padStart(2)} ${f.name}（${f.letter}）  声明 ${declared}   →   实得 ${actual}`)
+  })
+  const t = parsed.overview.total
+  console.log(`    ${t ? (t.declaredTotal === actualTotal && sameCounts(t.counts, sum) ? '✅' : '❌') : '❌'} 合计  声明 ${t ? `${t.declaredTotal} 条 ｜ ${fmtCounts(t.counts)}` : '（缺合计行）'}   →   实得 ${actualTotal} 条 ｜ ${fmtCounts(sum)}`)
+  console.log('')
+  console.log(`  判据条数：${actualTotal} 条（期望 ${EXPECTED_TOTAL}）`)
+  console.log(`  合计：${fmtCounts(sum)}`)
+
+  if (notes.length) {
+    console.log('')
+    console.log('  ℹ️ 提示（不判红）：')
+    for (const n of notes) console.log(`    · ${n}`)
+  }
+  if (problems.length) {
+    console.log('')
+    console.log(`  ❌ 发现 ${problems.length} 个不一致（唯一真源 = 判据行 ⇒ 改 §2.0，或改判据行并说明为什么）：`)
+    for (const p of problems) console.log(`    · [${p.rule}] ${p.where}：${p.msg}`)
+    console.log('')
+    console.log(strict
+      ? `  结论：❌ 不一致（${problems.length} 个问题）⇒ --strict 退出码 1`
+      : `  结论：❌ 不一致（${problems.length} 个问题）⇒ 默认只报告、退出码 0；加 --strict 才非零`)
+    return strict ? 1 : 0
+  }
+  console.log('')
+  console.log('  结论：✅ 一致（① 40 条 ② 逐面条数 ③ 逐面计数 ④ 合计 = 八面之和 ⑤ 卡点非空 ⑥ 符号合法 ⑦ ID 连续）')
+  return 0
+}
+
+const invoked = process.argv[1] ? resolve(process.argv[1]) : ''
+if (invoked === resolve(fileURLToPath(import.meta.url))) {
+  process.exit(main(process.argv.slice(2)))
+}

package/engine/scripts/check-agent-catalog.mjs

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * check-agent-catalog.mjs —— **智能体目录**门禁（A 批，2026-10-10）。
+ *
+ * ## 它防的是什么
+ * `agents/catalog.json` 是**货架声明**（用户从智能体库选一个装）。声明错了不会当场报错，
+ * 而是在客户机上表现为"装了这个却少那个"（角色没落、技能拿不到、定时器没装、档位对不上）——
+ * 属于典型的**静默交付缺口**。本门禁把"声明 ↔ 现实"的每一条交叉引用都变成红/绿。
+ *
+ * ## 判据（每条都能被 lint 出来，见 `scripts/argent-agents.mjs#validateCatalog`）
+ * | # | 判据 | 违反 |
+ * |---|---|---|
+ * | C0 | 目录文档/条目**无未知字段**（schema 白名单） | ❌ |
+ * | C1 | `capability` 与 `capabilities` **二选一**；能力必须在册 | ❌ |
+ * | C2 | `flows` ⊆ 已声明能力名下的规范 id 子集；能力有流程而 flows 为空 ⇒ 红 | ❌ |
+ * | C3 | `roles` 含恒装入口 `argent-general`；每个角色归属得上（capability / rolesFor / flow.role）；**反向**：每条 flow 的角色必须在 roles 里、且**同能力其它 flow 的角色不得混入** | ❌ |
+ * | C4 | `plugins` 含共享壳 core+skin；未知插件 ⇒ 红 | ❌ |
+ * | C5 | `skills` 真实存在 ∧ ∈ 已声明能力包的技能集 | ❌ |
+ * | C6 | `integrations` 在目录文档的集成说明表里登记 | ❌ |
+ * | C7 | `credentials[]` 只有 `{slot,target,why}`；**禁止键 / 密钥形态串 ⇒ 红**（⛔ 凭据槽不带值） | ❌ |
+ * | C8 | `minPlan` 合法 ∧ 不低于各能力包档位下限 | ❌ |
+ * | C9 | `scheduler` 与 `flows` 一致（无流程 ⇒ 不许说要有定时器；有定时器 ⇒ 必须有流程） | ❌ |
+ * | C10 | **锁 ↔ 活注册表**：能力包锁里每条能力的 `flows` / 每个 flow 的 `role` 必须与 `flow_registry.py --json` **逐条一致**（锁过期 ⇒ 红，防"按过期锁做子集过滤"） | ❌ |
+ * | C11 | 每个在册能力都被至少一个智能体覆盖（否则货架上买不到） | ⚠️ |
+ * | C12 | 能力声明的**宿主资产**（`pack.hostAssets`）：枚举合法 + `required` 与 flow 数自洽 + 与目录的 `scheduler` 逐条一致 | ❌ |
+ *
+ * ## 用法与退出码
+ * ```
+ * node scripts/check-agent-catalog.mjs            # 门禁
+ * node scripts/check-agent-catalog.mjs --json     # 机器可读
+ * node scripts/check-agent-catalog.mjs --root <dir>
+ * ```
+ *   · exit `0` 全部合规（可带 ⚠️）；`1` 有 ❌；`2` 用法错误 / 目录或注册表读不到。
+ *
+ * ## 纪律
+ *   · **只读**：不写任何文件、不动 `~/.dsh`、不联网；
+ *   · `validateCatalog()` 是**唯一实现**（安装器 `--agent` 复用同一函数，⛔ 不另写一份判据）；
+ *   · `flow_registry.py --json` 是**流程/角色的唯一真源**（本脚本不自己合并 `verticals/<id>/flows.json`）。
+ */
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+import { loadRegistryDoc } from './lib/registry.mjs'
+import { CATALOG_REL, buildContext, loadCatalog, validateCatalog, validateHostAssets } from './argent-agents.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SELF_ROOT = resolve(HERE, '..')
+
+/**
+ * 跑全部判据。
+ * @param {{root?: string, registryDoc?: object}} [opts] `registryDoc` 可注入（测试夹具用；缺省真读注册表）。
+ * @returns {{errors: string[], warnings: string[], stats: object}}
+ */
+export function checkCatalog(opts = {}) {
+  const root = opts.root || SELF_ROOT
+  const errors = []
+  const warnings = []
+  const ctxWarn = (m) => errors.push(m)
+  const ctx = buildContext(root, ctxWarn)
+
+  if (!existsSync(join(root, CATALOG_REL))) {
+    return { errors: [`缺目录声明：${CATALOG_REL}`], warnings, stats: { agents: 0, capabilities: 0, flows: 0, presets: 0 } }
+  }
+  const doc = loadCatalog(root)
+  if (!doc) return { errors: [`${CATALOG_REL} 读不出/不是合法 JSON`], warnings, stats: { agents: 0, capabilities: 0, flows: 0, presets: 0 } }
+
+  // C10：锁 ↔ 活注册表（唯一真源 = flow_registry.py 的合并结果）
+  let reg = opts.registryDoc
+  if (!reg) {
+    try {
+      reg = loadRegistryDoc({ root })
+    } catch (e) {
+      errors.push(`读不到合并注册表（flow_registry.py --json）：${String(e.message).split('\n')[0]} —— C10（锁是否过期）无从判定`)
+      reg = null
+    }
+  }
+  const flowRole = {}
+  if (reg) {
+    const regFlows = reg.flows || {}
+    // `flows.json#role` 是**短角色名**（`ml-fulfillment`），preset id = `argent-<短名>`
+    // （唯一派生规则见 `scripts/capability_pack.py#manifest()`）⇒ 统一归一到 preset id 再比，
+    // 否则交叉校验拿短名去比 preset 清单（恒不命中 ⇒ 判据形同虚设）。
+    const presetIdOfRole = (r) => (String(r || '').startsWith('argent-') ? String(r) : `argent-${r}`)
+    for (const [fid, spec] of Object.entries(regFlows)) flowRole[fid] = presetIdOfRole((spec || {}).role)
+    for (const [cap, c] of Object.entries(ctx.capabilities)) {
+      const lockFlows = [...(c.flows || [])].sort()
+      const liveFlows = Object.keys(regFlows).filter((f) => String((regFlows[f] || {}).capability || '') === cap).sort()
+      if (lockFlows.join(',') !== liveFlows.join(',')) {
+        errors.push(`能力包锁里 \`${cap}\` 的 flows 与活注册表不一致（锁过期）——锁：[${lockFlows.join(', ')}]｜注册表：[${liveFlows.join(', ')}]`
+          + `\n      修法：node install-argent.mjs --stamp（或 python3 scripts/capability_pack.py --stamp）后重新提交`
+          + `\n      ⚠️ 别手改锁：它是 --stamp 的产物，手改会被下一次 --stamp 抹掉`)
+      }
+    }
+    for (const f of Object.keys(ctx.flows)) {
+      if (!(f in regFlows)) {
+        warnings.push(`flow \`${f}\` 出现在能力包锁/业务线文件里，但**合并注册表**里没有它（锁过期或业务线文件是坏树）`)
+        continue
+      }
+      const declared = (ctx.flows[f] || {}).role
+      const live = flowRole[f]
+      if (declared && live && declared !== live) {
+        errors.push(`flow \`${f}\` 的角色声明不一致：业务线文件写 \`${declared}\`，合并注册表写 \`${live}\``)
+      }
+    }
+  }
+
+  const res = validateCatalog(doc, ctx, reg ? { flowRole } : {})
+  errors.push(...res.errors)
+  warnings.push(...res.warnings)
+  // C12：能力声明的**宿主资产**字段自洽（枚举 / required 与 flow 数 / 与目录 scheduler 一致）
+  const ha = validateHostAssets(ctx)
+  errors.push(...ha.errors)
+  warnings.push(...ha.warnings)
+
+  const ids = (doc.agents || []).map((a) => a && a.id).filter(Boolean)
+  const stats = { agents: ids.length, capabilities: Object.keys(ctx.capabilities).length, flows: Object.keys(ctx.flows).length, presets: Object.keys(ctx.presets).length, ids }
+  return { errors, warnings, stats }
+}
+
+// ── CLI ───────────────────────────────────────────────────────────────
+if (isDirectRun(import.meta.url)) {
+  const argv = process.argv.slice(2)
+  if (argv.includes('-h') || argv.includes('--help')) {
+    console.log('用法: node scripts/check-agent-catalog.mjs [--json] [--root <dir>]')
+    process.exit(0)
+  }
+  const rootIdx = argv.indexOf('--root')
+  const root = rootIdx >= 0 ? argv[rootIdx + 1] : SELF_ROOT
+  if (!root || !existsSync(root)) { console.error(`✗ --root 指向的目录不存在：${root}`); process.exit(2) }
+  const { errors, warnings, stats } = checkCatalog({ root })
+  if (argv.includes('--json')) {
+    console.log(JSON.stringify({ ok: errors.length === 0, errors, warnings, stats }, null, 2))
+  } else {
+    console.log(`智能体目录门禁：${stats.agents} 个智能体 / ${stats.capabilities} 个能力 / ${stats.flows} 条 flow / ${stats.presets} 个角色（${CATALOG_REL}）`)
+    for (const e of errors) console.log(`  ❌ ${e}`)
+    for (const w of warnings) console.log(`  ⚠️  ${w}`)
+    console.log(`\n结果: ${errors.length ? `❌ FAIL ${errors.length} 项` : '✅ PASS'}${warnings.length ? `（另有 ${warnings.length} 项警告）` : ''}`)
+  }
+  process.exit(errors.length ? 1 : 0)
+}