@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/check-sample-redaction.mjs

@@ -0,0 +1,320 @@
+#!/usr/bin/env node
+/**
+ * check-sample-redaction.mjs —— 官网样例**脱敏自证门禁**（只读）
+ *
+ * 为什么有它：`docs/samples/ml-daily-report-sample.{json,md}` 是给官网展示页用的
+ * **真实日报样例**。一旦有人"顺手更新样例"时把真实店铺名 / 商品标题 / SKU / 单号 /
+ * 原始金额粘回来，肉眼极难发现 —— 脱敏这种事**必须机器判**，不能靠 review 记得。
+ *
+ * ## 两件事，一次跑完
+ * | 检查 | 判据 |
+ * |---|---|
+ * | **A 禁用串扫描** | 两份交付物里出现**任何**能定位到具体客户 / 店铺 / 商品 / 订单 / 账号的串，或**原始金额·销量数字** ⇒ 命中（详见 {@link BANNED} 与 {@link HASHED_TOKENS}） |
+ * | **B 键名一致性** | 样例 JSON 的 `schema` / `note` / 每个 `section.id` / 每个 `metrics[].name`，必须与**真源指标清单**（`docs/` 下的「数据指标清单.json」）**逐条对齐**（防样例与指标清单各写一份而悄悄漂移） |
+ *
+ * ## 禁用串清单的分档理由
+ * - **形状规则**（{@link BANNED}，9 条明文）：商品 ID 形态（`ML[A-Z]+<6+位数字>`）/ SKU 形态
+ *   （`XX-XX-<数字>`）/ 账号 ID 形态（10 位以上连续数字）/ 飞书与 Base ID 形态 /
+ *   带标签的单号 / 邮箱 / 禁用字样。这类只描述"长相"，**不含任何客户原文**。
+ * - **单向摘要**（{@link HASHED_TOKENS}，43 条 `sha256` 前 16 位）：取材日报里出现过的
+ *   **原始金额与销量/件数**、店铺账号 ID、SKU 品牌缩写、客户·群·人名。
+ *   ⛔ **刻意不写明文** —— 禁用串清单若把原始值原样列出来，等于**把原始客户数据又落进仓库一次**，
+ *   正是本门禁要防的事；摘要单向、不可还原，比对时明文只出现在交付物那一侧。
+ *   维护法见 {@link HASHED_TOKENS} 的注释与 `--hash`。
+ * - **短数字刻意不入清单**：四位以下的量（客单价、订单数这类）满页都是，禁了就是恒红陷阱
+ *   （假阳性比漏报更伤：会骗人去"修"一个没坏的东西）。
+ * - **无量纲量（率 / 占比 / 可售天数 / 最久等待时长）刻意不禁**：它们对缩放不变，
+ *   且单独任何一个都不构成定位信息（`0.41%` 纠纷率 + `5_green` 等级定位不到任何一家店）。
+ *   本清单只钉"可搜索原文"与"能反推规模"的两类。
+ *
+ * ## 用法
+ *   node scripts/check-sample-redaction.mjs            # 只报告，**恒 exit 0**
+ *   node scripts/check-sample-redaction.mjs --strict   # 有命中才 exit 1（CI 判据用）
+ *   node scripts/check-sample-redaction.mjs --json     # 机器可读
+ *   node scripts/check-sample-redaction.mjs --list-rules
+ *   node scripts/check-sample-redaction.mjs --root <dir>   # 换根目录（自测夹具用；仍然只读）
+ *   node scripts/check-sample-redaction.mjs --hash <原文>  # 维护用：打印摘要（明文不入库）
+ *
+ * ## 纪律
+ * 只读：不改文件、不写台账/数据目录、不读凭据、不联网。判据面只有 `docs/` 下的三个文件
+ * （两份样例 + 一份真源指标清单）。
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const DEFAULT_ROOT = resolve(here, '..')
+
+const SAMPLE_JSON = 'docs/samples/ml-daily-report-sample.json'
+const SAMPLE_MD = 'docs/samples/ml-daily-report-sample.md'
+
+/**
+ * 真源指标清单的**发现式**定位 —— L1 引擎里刻意**不写业务线名**
+ * （`scripts/` 不得出现业务词，见 `scripts/vertical-lint.mjs` 的 engine-words 规则与
+ * `verticals/_engine-words.json`）。判据 = 文件名以「数据指标清单.json」结尾
+ * **且** `schema` 命中 {@link INVENTORY_SCHEMA}（不靠路径硬编码，清单改名也不会静默放过）。
+ */
+const INVENTORY_SCHEMA = 'argent-ml-daily-metrics/1'
+const INVENTORY_SUFFIX = '数据指标清单.json'
+
+/** 在 `<root>/docs/` 下发现真源指标清单；返回相对路径或 `null`。只读。 */
+export function findInventoryFile(root = DEFAULT_ROOT) {
+  const dir = join(root, 'docs')
+  if (!existsSync(dir)) return null
+  for (const name of readdirSync(dir).sort()) {
+    if (!name.endsWith(INVENTORY_SUFFIX)) continue
+    try {
+      if (JSON.parse(readFileSync(join(dir, name), 'utf8')).schema === INVENTORY_SCHEMA) return `docs/${name}`
+    } catch { /* 同名但解析失败 ⇒ 不是它，继续找 */ }
+  }
+  return null
+}
+
+/** 样例 JSON 的固定头（与官网消费方约定的契约）。 */
+export const SAMPLE_SCHEMA = 'argent-ml-daily-sample/1'
+export const SAMPLE_NOTE = '示例数据（已脱敏，非真实客户数据）'
+
+/**
+ * **形状**规则（不含任何客户原文）—— 描述"什么长相的串不该出现"，
+ * 命中时报告里点名的是**规则**（如 `sku-shape`），不是某个具体客户值。
+ */
+export const BANNED = [
+  { id: 'account-id', why: '店铺 / 卖家账号 ID 形态（10 位以上连续数字）', re: /\b\d{10,}\b/g },
+  { id: 'item-id', why: '电商平台商品 ID 形态（ML + 字母站点码 + 6 位以上数字）', re: /\bML[A-Z]\d{6,}\b/g },
+  { id: 'sku-shape', why: 'SKU 形态（<前缀>-MX-<数字>，真实 SKU 即此形）', re: /\b[A-Za-z]{2,4}-MX-[A-Za-z0-9-]*\d[A-Za-z0-9-]*/g },
+  { id: 'sku-generic', why: '通用 SKU 形态（<2-4 字母>-<2 大写字母>-<数字>）', re: /\b[A-Za-z]{2,4}-[A-Z]{2}-\d[A-Za-z0-9-]*/g },
+  { id: 'feishu-id', why: '飞书 / Base / 表 ID 形态（chat_id、open_id、base token、table id）', re: /\b(?:oc_|ou_|om_|cli_|tbl|bas|fld)[A-Za-z0-9_]{8,}/g },
+  { id: 'record-id', why: 'Base 记录号形态', re: /\brec[A-Za-z0-9]{8,}\b/g },
+  { id: 'labelled-number', why: '带标签的原始单号 / 卖家 ID（订单号 / 货件号 / 包裹号 / 卖家 ID + 4 位以上数字）', re: /(?:订单号|货件号|包裹号|卖家\s*ID)\s*[:：]?\s*\d{4,}/g },
+  { id: 'email-shape', why: '邮箱形态（客户 / 联系人标识）', re: /@[A-Za-z0-9.-]+\.(?:com|cn|net)/g },
+  { id: 'banned-phrase', why: '交付物里不得出现"某客户真实数据"这类字样', re: /某客户真实数据/g },
+]
+
+/**
+ * **具体客户原文的单向摘要**清单（`sha256(token)` 的前 16 位十六进制）。
+ *
+ * ### 为什么是摘要而不是明文
+ * 禁用串清单天然要写"禁什么"，但**把取材日报的原始金额 / 销量、店铺账号 ID、品牌缩写、
+ * 客户与群名原样写进这个脚本，等于把原始客户数据又落进仓库一次** —— 那正是本门禁要防的事。
+ * 摘要单向、不可还原，比对时**明文只出现在交付物那一侧**（命中报告里点名的是交付物里的
+ * 那一段，本来就已经在交付物里，不构成新增泄露）。
+ *
+ * ### 覆盖范围（43 条）
+ * · 取材日报的原始**金额**（GMV / 佣金 / 优惠券 / 商品 7 日销售额）；
+ * · 原始**销量 / 件数**（订单数、件数、累计已售、访问量、访客 Top5、SKU 数）；
+ * · 店铺 / 卖家**账号 ID**（同时被 `account-id` 形状规则兜住，摘要提供"点名到具体值"的能力）；
+ * · 真实 SKU 的**品牌缩写**前缀；
+ * · **客户 / 群 / 人**名。
+ *
+ * ### 怎么补新条目（维护动作）
+ * 拿到新一批取材数据后，对每个原始值跑一次
+ * `node scripts/check-sample-redaction.mjs --hash <原文>`，把打印出的摘要追加到下面即可 ——
+ * **明文只在你的终端里出现一次，不进仓库、不进提交、不进 CI 日志**。
+ */
+export const HASHED_TOKENS = new Set([
+  '5d207cf244a249e8', '7cf1c96f66f8e87b', 'f8de3df2c078baa7', '89d295d75a9717e8',
+  'cb0b20f98ee49533', 'f4dd96228b9a0d6e', 'c3c8204aec16162a', '0304631267d2f0e1',
+  'a0337a650ec85c55', '4f9f73b34c5b8987', '876c9b16254e157d', 'a037a7dfaf26abe1',
+  '55fdec963805de59', '890fd025edbcc524', '47b25095a0fe135a', '0944d4d0aabb9305',
+  '9c978dcb04837772', 'e36deec09aa73922', 'e3be6803d0ccd399', 'b97d4904938f12a0',
+  '0dc89b2fb404b4d7', '3ee78724cb832ac7', '0dc5713ce820f082', '262b06d105e1c865',
+  '3f9eb849d10083d5', 'cb209f169ae04866', 'dc50a94325365105', '614f5408eab24ce6',
+  '43908979b8b2d28d', 'db6479551754db9b', 'e06f88267f246de6', 'b700bd6ebf3dadab',
+  '6317984746f70826', '5a4a0c923c9a9f9e', '0b689c5667de7f17', '2bb1c90302bea604',
+  '69898c7bb333c6ad', '01ba9d7ab5112ec9', '91660cd41bd4fe15', '9889a3fb03c5db96',
+  '1882b4902a76e8c8', 'a46569295c2eb8af', 'f413de3a975813cb',
+])
+
+/** `sha256(token)` 的前 16 位十六进制 —— 与 {@link HASHED_TOKENS} 同口径。 */
+export const tokenDigest = (token) => createHash('sha256').update(String(token), 'utf8').digest('hex').slice(0, 16)
+
+/**
+ * 从交付物里抽出候选 token（**只读交付物那一侧**）：
+ * · 数字 —— 去掉千分位后 3 位以上（故 `1234` 与 `1,234` 会归一到同一个摘要）；
+ * · ASCII 词 —— 转小写（故 `HW` / `hw` 同一个摘要）；
+ * · CJK —— 连续汉字段的全部 2–4 元组（人名 / 群名不靠分词也能被摘要命中）。
+ */
+export function candidateTokens(text) {
+  const out = new Set()
+  for (const m of String(text).matchAll(/\d[\d,]*/g)) {
+    const t = m[0].replace(/,/g, '')
+    if (/^\d{3,}$/.test(t)) out.add(t)
+  }
+  for (const m of String(text).matchAll(/[A-Za-z][A-Za-z0-9_-]*/g)) out.add(m[0].toLowerCase())
+  for (const m of String(text).matchAll(/[\u4e00-\u9fff]{2,}/g)) {
+    const run = m[0]
+    for (let n = 2; n <= 4; n++) for (let i = 0; i + n <= run.length; i++) out.add(run.slice(i, i + n))
+  }
+  return out
+}
+
+/** 摘要比对：命中 ⇒ 报告里点名**交付物本身**的原文片段（不引入任何新明文）。 */
+export function scanHashedTokens(file, text, digests = HASHED_TOKENS) {
+  const out = []
+  const lines = String(text).split('\n')
+  for (const tok of candidateTokens(text)) {
+    const h = tokenDigest(tok)
+    if (!digests.has(h)) continue
+    const idx = lines.findIndex((l) => l.includes(tok))
+    out.push({
+      file, line: idx >= 0 ? idx + 1 : 0, id: `banned-token:${h}`,
+      why: '命中取材日报的原始金额 / 销量 / 客户标识（明文不入库，按单向摘要比对）',
+      text: idx >= 0 ? lines[idx].trim().slice(0, 120) : tok,
+    })
+  }
+  return out
+}
+
+/** 逐行扫一个禁用串清单。返回命中数组（含 `file` / `line` / `id` / `why` / `text`）。 */
+export function scanText(file, text, rules = BANNED) {
+  const out = []
+  const lines = text.split('\n')
+  for (const rule of rules) {
+    for (let i = 0; i < lines.length; i++) {
+      rule.re.lastIndex = 0
+      if (rule.re.test(lines[i])) {
+        out.push({ file, line: i + 1, id: rule.id, why: rule.why, text: lines[i].trim().slice(0, 120) })
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * 键名一致性：样例 JSON ↔ 指标清单。
+ * 判据：`schema` / `note` 逐字一致；每个 `section.id` 命中清单的 `sections[].id`；
+ * 每个 `metrics[].name` 命中**同一分区**的 `metrics[].name`。
+ */
+export function checkKeyAlignment(sample, inventory) {
+  const problems = []
+  if (sample.schema !== SAMPLE_SCHEMA) problems.push({ id: 'schema', why: `schema 必须是 ${SAMPLE_SCHEMA}`, got: String(sample.schema) })
+  if (sample.note !== SAMPLE_NOTE) problems.push({ id: 'note', why: `note 必须是「${SAMPLE_NOTE}」`, got: String(sample.note) })
+  if (!Array.isArray(sample.sections) || !sample.sections.length) {
+    problems.push({ id: 'sections', why: 'sections 必须是非空数组', got: String(sample.sections && sample.sections.length) })
+    return problems
+  }
+  const inv = new Map((inventory.sections || []).map((s) => [s.id, new Set((s.metrics || []).map((m) => m.name))]))
+  const seen = new Set()
+  for (const sec of sample.sections) {
+    if (!sec || typeof sec.id !== 'string') { problems.push({ id: 'section.id', why: 'section 缺 id', got: JSON.stringify(sec).slice(0, 80) }); continue }
+    if (seen.has(sec.id)) problems.push({ id: `dup-section:${sec.id}`, why: '分区 id 重复', got: sec.id })
+    seen.add(sec.id)
+    if (!inv.has(sec.id)) { problems.push({ id: `unknown-section:${sec.id}`, why: '分区 id 不在指标清单里（键名漂移）', got: sec.id }); continue }
+    if (typeof sec.title !== 'string' || !sec.title) problems.push({ id: `no-title:${sec.id}`, why: '分区缺 title', got: sec.id })
+    if (typeof sec.summary !== 'string' || !sec.summary) problems.push({ id: `no-summary:${sec.id}`, why: '分区缺 summary', got: sec.id })
+    if (!Array.isArray(sec.metrics) || !sec.metrics.length) { problems.push({ id: `no-metrics:${sec.id}`, why: '分区缺 metrics', got: sec.id }); continue }
+    const names = inv.get(sec.id)
+    for (const m of sec.metrics) {
+      if (!m || typeof m.name !== 'string') { problems.push({ id: `metric.name:${sec.id}`, why: '指标缺 name', got: JSON.stringify(m).slice(0, 80) }); continue }
+      if (typeof m.unit !== 'string') problems.push({ id: `metric.unit:${sec.id}`, why: '指标缺 unit（复合值写空串）', got: m.name })
+      if (m.value === undefined || m.value === null || m.value === '') problems.push({ id: `metric.value:${sec.id}`, why: '指标缺 value', got: m.name })
+      if (!names.has(m.name)) problems.push({ id: `metric-name-drift:${sec.id}`, why: '指标名不在指标清单的同名分区里（键名漂移）', got: m.name })
+    }
+  }
+  return problems
+}
+
+/** 主检查：返回 `{ hits, problems, stats }`（纯函数，不打印、不退出）。 */
+export function runCheck(root = DEFAULT_ROOT) {
+  const hits = []
+  const problems = []
+  const read = (rel) => (existsSync(join(root, rel)) ? readFileSync(join(root, rel), 'utf8') : null)
+
+  const jsonText = read(SAMPLE_JSON)
+  const mdText = read(SAMPLE_MD)
+  const invRel = findInventoryFile(root)
+  const invText = invRel ? read(invRel) : null
+
+  for (const [rel, text] of [[SAMPLE_JSON, jsonText], [SAMPLE_MD, mdText]]) {
+    if (text == null) problems.push({ id: 'missing-file', why: '交付物不存在', got: rel })
+    else {
+      hits.push(...scanText(rel, text))
+      hits.push(...scanHashedTokens(rel, text))
+    }
+  }
+
+  let stats = { sections: 0, metrics: 0 }
+  if (jsonText != null) {
+    let sample = null
+    try { sample = JSON.parse(jsonText) } catch (e) { problems.push({ id: 'json-parse', why: '样例 JSON 解析失败', got: String(e.message) }) }
+    if (sample) {
+      if (invText == null) problems.push({ id: 'missing-inventory', why: '真源指标清单未发现（文件名以「数据指标清单.json」结尾且 schema 命中），无法校验键名一致性', got: `docs/**/${INVENTORY_SUFFIX}` })
+      else {
+        let inv = null
+        try { inv = JSON.parse(invText) } catch (e) { problems.push({ id: 'inventory-parse', why: '指标清单 JSON 解析失败', got: String(e.message) }) }
+        if (inv) problems.push(...checkKeyAlignment(sample, inv))
+      }
+      stats = {
+        sections: (sample.sections || []).length,
+        metrics: (sample.sections || []).reduce((a, s) => a + ((s.metrics || []).length), 0),
+      }
+    }
+  }
+
+  // MD 必须能让官网页照抄：每个分区标题都要在 MD 里出现
+  if (jsonText && mdText) {
+    try {
+      for (const sec of JSON.parse(jsonText).sections || []) {
+        if (typeof sec.title === 'string' && sec.title && !mdText.includes(sec.title)) {
+          problems.push({ id: `md-missing-section:${sec.id}`, why: '人读版缺少该分区标题', got: sec.title })
+        }
+      }
+    } catch { /* 解析失败已在上面报过 */ }
+  }
+
+  hits.sort((a, b) => (a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1))
+  return { hits, problems, stats }
+}
+
+// ── CLI ────────────────────────────────────────────────────────────────────
+function main(argv) {
+  // 维护工具：把一个原文转成摘要（明文只在终端出现一次，不进仓库 / 提交 / CI 日志）
+  const hashIdx = argv.indexOf('--hash')
+  if (hashIdx >= 0) {
+    const tok = argv[hashIdx + 1]
+    if (!tok) { console.error('用法：node scripts/check-sample-redaction.mjs --hash <原文>'); return 2 }
+    console.log(tokenDigest(tok))
+    return 0
+  }
+  if (argv.includes('--list-rules')) {
+    console.log(`禁用串清单 = ${BANNED.length} 条**形状**规则 + ${HASHED_TOKENS.size} 条**单向摘要**（具体客户原文一律不入库）`)
+    for (const r of BANNED) console.log(`  · ${r.id.padEnd(20)} ${r.why}`)
+    console.log(`  · ${'banned-token:*'.padEnd(20)} 取材日报的原始金额 / 销量 / 客户标识（按 sha256 前 16 位比对）`)
+    return 0
+  }
+  const rootIdx = argv.indexOf('--root')
+  const root = rootIdx >= 0 ? resolve(argv[rootIdx + 1]) : DEFAULT_ROOT
+  const strict = argv.includes('--strict')
+  const asJson = argv.includes('--json')
+
+  const { hits, problems, stats } = runCheck(root)
+
+  if (asJson) {
+    console.log(JSON.stringify({ ok: hits.length === 0 && problems.length === 0, root, stats, hits, problems }, null, 2))
+    return strict && (hits.length || problems.length) ? 1 : 0
+  }
+
+  console.log(`[sample-redaction] 根目录 ${root}`)
+  console.log(`[sample-redaction] 样例规模：${stats.sections} 个分区 / ${stats.metrics} 条指标`)
+  console.log(`[sample-redaction] 禁用串清单：${BANNED.length} 条形状规则 + ${HASHED_TOKENS.size} 条单向摘要（${SAMPLE_JSON} + ${SAMPLE_MD}）`)
+  if (hits.length) {
+    console.log(`\n❌ 禁用串命中 ${hits.length} 处：`)
+    for (const h of hits) console.log(`   ${h.file}:${h.line}  [${h.id}] ${h.why}\n      ${h.text}`)
+  } else {
+    console.log('✅ 禁用串命中 0 处')
+  }
+  if (problems.length) {
+    console.log(`\n❌ 结构与键名问题 ${problems.length} 处：`)
+    for (const p of problems) console.log(`   [${p.id}] ${p.why} —— ${p.got}`)
+  } else {
+    console.log('✅ 结构与键名一致（schema / note / 分区 id / 指标名与指标清单逐条对齐）')
+  }
+  const bad = hits.length + problems.length
+  console.log(`\n结论：${bad === 0 ? '✅ 通过' : `❌ 不通过（${bad} 处）`}${strict ? '' : '　（默认只报告；加 --strict 才非零退出）'}`)
+  return strict && bad ? 1 : 0
+}
+
+if (isDirectRun(import.meta.url)) process.exit(main(process.argv.slice(2)))

package/engine/scripts/check-skill-classification.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * check-skill-classification.mjs —— **技能归类**门禁（P3，§6.1 D5；2026-10-03）
+ *
+ * ## 它防的是什么（R3：SKILL 外发泄露内部角色）
+ * `skills/` 是**混装**目录：客户可用的流程技能与我方内部角色技能住在一起，而升级器是**全量同步**
+ * （`scripts/argent-upgrade.mjs` 对每个子目录 `rmSync` + `cpSync`，**无角色过滤**）⇒
+ * **往 `skills/` 里丢一个新目录，等于默认把它发给每个客户**。这个门禁把"默认放行"改成
+ * "**必须做一次决定**"：新技能要么在业务线声明里（外发），要么在内部清单里（不外发），
+ * **两边都没有 ⇒ 红**（与 kernel-purity 的"未归类即红"、D5 的判据同精神）。
+ *
+ * ## 判据（全部来自仓库里的**声明文件**，门禁不另写第二份名单）
+ * | # | 判据 | 违反 |
+ * |---|---|---|
+ * | G1 | `skills/internal.json` 必须存在且可解析（内部半边**必须是清单文件**，不许把规则写死在安装脚本里） | ❌ |
+ * | G2 | `skills/` 下的每个技能目录（含 `SKILL.md`）∈ 外发集 ∪ 内部集 | ❌ `未归类` |
+ * | G3 | **外发集 = 所有 `verticals/<id>/manifest.json#skills` 的并集**（唯一真源；照抄 manifest 即漂移，故不另立名单） | — |
+ * | G4 | 外发集里的每个技能目录必须存在（声明了却没有 ⇒ 装机时静默少一个） | ❌ |
+ * | G5 | 内部集里的每个技能目录必须存在（过期条目 = 名单在腐烂） | ❌ |
+ * | G6 | 内部集每条必须带**非空理由**（没有理由的"内部"半年后没人敢删） | ❌ |
+ * | G7 | 外发集 ∩ 内部集 = ∅（同一个技能不能既外发又不外发） | ❌ |
+ * | G8 | `skills/` 下的非技能目录（没有 `SKILL.md`）只**提示**，不判红（可能是 references/模板/在建件） | ⚠️ |
+ *
+ * ## 用法与退出码
+ * ```
+ * node scripts/check-skill-classification.mjs                 # 只报告
+ * node scripts/check-skill-classification.mjs --json
+ * node scripts/check-skill-classification.mjs --root <dir>    # 换根（夹具自证用）
+ * node scripts/check-skill-classification.mjs --strict-warn   # 把"未带 SKILL.md 的目录"也判红
+ * ```
+ *   · exit `0` 全部合规；`1` 有 ❌；`2` 用法错误（未知参数 / 根不存在）。
+ *
+ * ## 纪律
+ *   · **只读**：不写任何文件、不动 `~/.dsh`、不联网；
+ *   · `classify()` 是**唯一实现**：`scripts/skill-install.mjs` 复用同一个函数（安装器不得自己再判一遍
+ *     —— 那正是"判据两份"的老事故形态）。
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { isDirectRun } from './lib/is-direct-run.mjs'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const SELF_ROOT = resolve(HERE, '..')
+
+/** 内部清单的相对路径（**只此一处**；改名要同时改门禁、安装器、文档）。 */
+export const INTERNAL_MANIFEST = 'skills/internal.json'
+/** 技能目录下必须存在的入口文件（`dsh-skill-filesystem#parseSkillFile` 的硬约束之一）。 */
+export const SKILL_FILE = 'SKILL.md'
+
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')) } catch { return null } }
+
+/**
+ * 归类（**唯一实现**；纯函数式：只读传入的 root）。
+ * @param {{root?:string}} [opts]
+ * @returns {{ok:boolean, external:string[], internal:string[], unclassified:string[],
+ *            nonSkillDirs:string[], errors:Array<{rule:string,message:string}>, warnings:Array<{rule:string,message:string}>,
+ *            manifest:object|null, sources:Array<{vertical:string,skills:string[]}>}}
+ */
+export function classify({ root = SELF_ROOT } = {}) {
+  const errors = []
+  const warnings = []
+  const skillsRoot = join(root, 'skills')
+
+  // ── G3：外发集 = 所有 verticals/*/manifest.json#skills 的并集 ────────────────
+  const verticalsRoot = join(root, 'verticals')
+  const sources = []
+  const external = []
+  let verticalDirs = []
+  try {
+    verticalDirs = readdirSync(verticalsRoot, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && existsSync(join(verticalsRoot, e.name, 'manifest.json')))
+      .map((e) => e.name).sort()
+  } catch { verticalDirs = [] }
+  if (!verticalDirs.length) {
+    errors.push({ rule: 'G3', message: `读不到任何 verticals/*/manifest.json（外发集无从得出）：${verticalsRoot}` })
+  }
+  for (const v of verticalDirs) {
+    const man = readJson(join(verticalsRoot, v, 'manifest.json'))
+    if (!man) { errors.push({ rule: 'G3', message: `verticals/${v}/manifest.json 不可解析` }); continue }
+    const skills = Array.isArray(man.skills) ? man.skills.map(String) : []
+    if (!skills.length) warnings.push({ rule: 'G3', message: `verticals/${v}/manifest.json#skills 为空（该业务线不声明任何流程技能？）` })
+    sources.push({ vertical: v, skills })
+    for (const s of skills) if (!external.includes(s)) external.push(s)
+  }
+  external.sort()
+
+  // ── G1：内部清单必须存在且可解析 ──────────────────────────────────────────
+  const manPath = join(root, INTERNAL_MANIFEST)
+  const manifest = existsSync(manPath) ? readJson(manPath) : null
+  const internalMap = manifest && manifest.internal && typeof manifest.internal === 'object' ? manifest.internal : null
+  if (!existsSync(manPath)) {
+    errors.push({ rule: 'G1', message: `缺内部清单 ${INTERNAL_MANIFEST} —— 内部半边**必须**是清单文件（不许把规则写死在安装脚本里）` })
+  } else if (!manifest) {
+    errors.push({ rule: 'G1', message: `${INTERNAL_MANIFEST} 不是合法 JSON` })
+  } else if (!internalMap) {
+    errors.push({ rule: 'G1', message: `${INTERNAL_MANIFEST} 缺 \`internal\` 对象（形状见该文件 _doc）` })
+  }
+  const internal = internalMap ? Object.keys(internalMap).sort() : []
+
+  // ── skills/ 下的真实目录 ─────────────────────────────────────────────────
+  let entries = []
+  try { entries = readdirSync(skillsRoot, { withFileTypes: true }) } catch {
+    errors.push({ rule: 'G2', message: `读不到技能目录：${skillsRoot}` })
+  }
+  const skillDirs = []
+  const nonSkillDirs = []
+  for (const e of entries) {
+    if (!e.isDirectory() || e.name.startsWith('.')) continue
+    if (existsSync(join(skillsRoot, e.name, SKILL_FILE))) skillDirs.push(e.name)
+    else nonSkillDirs.push(e.name)
+  }
+  skillDirs.sort(); nonSkillDirs.sort()
+
+  // ── G2：未归类即红 ───────────────────────────────────────────────────────
+  const unclassified = skillDirs.filter((d) => !external.includes(d) && !internal.includes(d))
+  for (const d of unclassified) {
+    errors.push({
+      rule: 'G2',
+      message: `未归类：skills/${d}/ 既不在任何 verticals/*/manifest.json#skills（外发），也不在 ${INTERNAL_MANIFEST}（内部）`
+        + ' —— 往 skills/ 丢目录 = 默认发给每个客户（升级器无角色过滤）⇒ 必须做一次决定',
+    })
+  }
+  for (const d of nonSkillDirs) {
+    warnings.push({ rule: 'G8', message: `skills/${d}/ 没有 ${SKILL_FILE} ⇒ 不算技能（不判红；若是废弃技能请删目录）` })
+  }
+
+  // ── G4/G5/G6/G7 ─────────────────────────────────────────────────────────
+  for (const s of external) {
+    if (!existsSync(join(skillsRoot, s, SKILL_FILE))) {
+      errors.push({ rule: 'G4', message: `业务线声明了技能 \`${s}\`，但 skills/${s}/${SKILL_FILE} 不存在（装机时会静默少一个）` })
+    }
+  }
+  for (const s of internal) {
+    if (!existsSync(join(skillsRoot, s, SKILL_FILE))) {
+      errors.push({ rule: 'G5', message: `${INTERNAL_MANIFEST} 列了 \`${s}\`，但 skills/${s}/${SKILL_FILE} 不存在（过期条目）` })
+    }
+    const reason = internalMap[s] && (internalMap[s].reason || internalMap[s]._reason)
+    if (!reason || !String(reason).trim()) {
+      errors.push({ rule: 'G6', message: `${INTERNAL_MANIFEST} 的 \`${s}\` 缺 reason（没有理由的"内部"半年后没人敢删）` })
+    }
+    if (external.includes(s)) {
+      errors.push({ rule: 'G7', message: `\`${s}\` 同时出现在外发集（业务线声明）与内部清单里 ⇒ 归类矛盾` })
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    root, external, internal, unclassified, nonSkillDirs,
+    errors, warnings, manifest, sources,
+    counts: { external: external.length, internal: internal.length, skillDirs: skillDirs.length, unclassified: unclassified.length },
+  }
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────────────
+function main(argv) {
+  let root = SELF_ROOT
+  let asJson = false
+  let strictWarn = false
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--json') { asJson = true; continue }
+    if (a === '--strict-warn') { strictWarn = true; continue }
+    if (a === '--root') { const v = argv[i + 1]; if (!v || v.startsWith('--')) return { code: 2, out: '❌ --root 缺值' }; root = resolve(v); i++; continue }
+    if (a === '-h' || a === '--help') return { code: 0, out: readFileSync(fileURLToPath(import.meta.url), 'utf8').split('*/')[0].replace(/^\/\*\*?/, '').trim() }
+    return { code: 2, out: `❌ 未知参数：${a}（用法：node scripts/check-skill-classification.mjs [--root <dir>] [--strict-warn] [--json]）` }
+  }
+  if (!existsSync(root)) return { code: 2, out: `❌ 根不存在：${root}` }
+  const r = classify({ root })
+  const bad = r.errors.length + (strictWarn ? r.warnings.length : 0)
+  if (asJson) return { code: bad ? 1 : 0, out: JSON.stringify({ ...r, strictWarn, code: bad ? 1 : 0 }, null, 2) }
+  const lines = ['', '【技能归类门禁（P3 / §6.1 D5）】']
+  lines.push(`  外发 ${r.counts.external} 个（真源：${r.sources.map((s) => `verticals/${s.vertical}/manifest.json#skills`).join('、') || '（无）'}）`)
+  for (const s of r.sources) lines.push(`     · ${s.vertical}: ${s.skills.join('、') || '（空）'}`)
+  lines.push(`  内部 ${r.counts.internal} 个（${INTERNAL_MANIFEST}）`)
+  for (const s of r.internal) lines.push(`     · ${s} —— ${r.manifest.internal[s].reason || '（缺理由）'}`)
+  for (const e of r.errors) lines.push(`  ❌ [${e.rule}] ${e.message}`)
+  for (const w of r.warnings) lines.push(`  ⚠️  [${w.rule}] ${w.message}`)
+  lines.push(`  结论：${r.ok ? '✅ 通过' : '❌ 不通过'}（外发 ${r.counts.external} / 内部 ${r.counts.internal} / 未归类 ${r.counts.unclassified}）`
+    + `${strictWarn ? `（--strict-warn：${r.warnings.length} 条提示也计入）` : ''}`)
+  return { code: bad ? 1 : 0, out: lines.join('\n') }
+}
+
+if (isDirectRun(import.meta.url)) {
+  const { code, out } = main(process.argv.slice(2))
+  console.log(out)
+  process.exit(code)
+}