@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/entitlements.py

@@ -0,0 +1,458 @@
+#!/usr/bin/env python3
+"""能力×档位矩阵（迭代 3-⑦）：**唯一出处 + 派生 + 校验**。
+
+## 问题（实测已漂移）
+"哪个角色需要哪一档"此前散在三处各判：
+  · 服务端 whyshu-svr 的 `ROLE_PLAN`；
+  · 网关 `plugins/argent-gateway/src/index.js` 的 `ROLE_PLAN`（注释写着"与服务端对齐"）；
+  · 客户端 `plugins/argent-skin/dist/client.js` 里写死 `ml-daily`/`ml-fulfillment` 与 `pro/enterprise`。
+实测漂移：网关把 `ml-daily` 写成 **pro**（文档口径是**企业级**），而两条发票角色
+（`ml-invoice-wy` / `ml-invoice-xzh`）**根本没登记** ⇒ `planOf()` 默认落回 **free**
+⇒ 免费版会把企业级角色显示成可用（用户以为自己能用）。
+
+## 口径（唯一出处 = 注册表）
+- 流程角色的档位 = 其 `capability` 的 `minPlan`（`flows.<id>.capability` → `capabilities.<c>.minPlan`）；
+- 不挂流程的角色在 `entitlements.roleMinPlan` 里显式声明；
+- 网关表由 `--emit-gateway-table` **机械派生**（不要手写）；
+- 客户端/安装器的档位判断由门禁校验（`scripts/tests/entitlements.test.mjs`）。
+
+用法：
+    python3 scripts/entitlements.py --matrix [--json]
+    python3 scripts/entitlements.py --role ml-invoice-wy
+    python3 scripts/entitlements.py --validate [--json]
+    python3 scripts/entitlements.py --emit-gateway-table        # 打印网关 ROLE_PLAN 片段
+退出码：0 一致；1 有问题；2 读取失败。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import re
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE / "lib"))
+from stdio_utf8 import use_utf8_stdio  # noqa: E402  出口编码钉 UTF-8（中文 Windows 的 GBK 管道下非 ASCII 会崩）
+REGISTRY = HERE / "flow-requirements.json"
+
+try:
+    from flow_registry import consumer_doc as _registry_doc
+except Exception:  # noqa: BLE001 —— 半坏机器上退回单文件（升级链路要能跑）
+    def _registry_doc(path=None):
+        return json.loads((pathlib.Path(path) if path else REGISTRY).read_text(encoding="utf-8"))
+
+GATEWAY = HERE.parent / "plugins" / "argent-gateway" / "src" / "index.js"
+GATEWAY_CLIENT = HERE.parent / "plugins" / "argent-gateway" / "dist" / "client.js"
+INSTALLER = HERE.parent / "install-argent.mjs"
+CLIENT = HERE.parent / "plugins" / "argent-skin" / "dist" / "client.js"
+
+
+def load() -> dict:
+    return _registry_doc()
+
+
+def matrix(doc: dict | None = None) -> dict:
+    """能力×档位矩阵：{capability: {minPlan, flows, roles}} + 角色反查。"""
+    d = doc or load()
+    ents = d.get("entitlements") or {}
+    tiers = list(ents.get("planTiers") or ["free", "pro", "enterprise"])
+    caps = {k: v for k, v in (d.get("capabilities") or {}).items() if not k.startswith("_")}
+    out = {}
+    role_plan: dict = {}
+    for cid, c in caps.items():
+        flows = [fid for fid, f in (d.get("flows") or {}).items() if f.get("capability") == cid]
+        roles = sorted({str((d["flows"][fid] or {}).get("role") or "") for fid in flows} - {""})
+        # ⛔ **不再**从 `pack.presets` 派生"能力 → 角色"（2026-10-06，P0-14/功能 bug）。
+        #   2026-09-21 批 C1 曾加过这条：无 flow 的能力（HR 办公）靠 preset 提供入口 ⇒ 想让网关
+        #   ROLE_PLAN 里有它的角色。但那个前提 2026-10-04 已失效 —— `hr-office` 角色**退役**，
+        #   preset 只剩**墓碑**（web 老会话的 agentPreset 外键）；而派生出来的角色名会被写进
+        #   客户端生成块的 `CAPABILITY_ROLES` ⇒ `capabilityAllowed("hr")` 要求角色表里出现
+        #   **已退役且 gateway.json 里根本没有**的 `hr-office` ⇒ **恒判"未装"**，付费客户用不了 HR。
+        #   口径改为：**能力按能力包判**（`CAPABILITY_MINPLAN[cap]` = 注册表 minPlan；＋可选
+        #   `installed` 能力清单），角色映射只保留"真挂流程的角色"（那些角色必然在 gateway.json 里）。
+        #   `hr` ⇒ roles=[] ⇒ 只看档位（与审计 §3-#14 的正解一致）。
+        #   退休角色的档位仍由 `entitlements.roleMinPlan` 负责（网关 ROLE_PLAN 的**唯一**出处）。
+        out[cid] = {"minPlan": str(c.get("minPlan") or ""), "flows": flows, "roles": roles}
+        for r in roles:
+            role_plan[r] = str(c.get("minPlan") or "")
+    for r, p in (ents.get("roleMinPlan") or {}).items():     # 不挂流程的角色
+        role_plan.setdefault(str(r), str(p))
+    out["_planTiers"] = tiers
+    out["_roles"] = role_plan
+    return out
+
+
+def rank(plan: str, tiers: list) -> int:
+    try:
+        return tiers.index(str(plan))
+    except ValueError:
+        return -1
+
+
+def norm(block: str) -> str:
+    """生成块比较用：忽略每行缩进（bundle 里会整体缩进），只比内容。"""
+    return "\n".join(ln.strip() for ln in str(block).splitlines() if ln.strip())
+
+
+def ents_role_min(doc: dict | None = None) -> dict:
+    """`entitlements.roleMinPlan`（不挂能力的角色档位；历史字段，保留兼容）。"""
+    d = doc or load()
+    return {str(k): str(v) for k, v in ((d.get("entitlements") or {}).get("roleMinPlan") or {}).items()}
+
+
+def free_tier(doc: dict | None = None) -> str:
+    """免费档名（`entitlements.freeTier`，默认 planTiers[0]）——"免费版零 B 端能力"的判据锚点。"""
+    d = doc or load()
+    ents = d.get("entitlements") or {}
+    tiers = list(ents.get("planTiers") or ["free", "pro", "enterprise"])
+    return str(ents.get("freeTier") or (tiers[0] if tiers else "free"))
+
+
+def plans_matrix(doc: dict | None = None) -> dict:
+    """套餐（SKU）→ 能力集合：{planId: {title, capabilities{cap:tier}, tier, capabilities[]}}。
+
+    `tier` = 该套餐授予的最高档（用于展示与排序，不参与授权判定 —— 授权判定仍按能力的 minPlan）。
+    """
+    d = doc or load()
+    ents = d.get("entitlements") or {}
+    tiers = list(ents.get("planTiers") or ["free", "pro", "enterprise"])
+    out: dict = {}
+    for pid, pl in (ents.get("plans") or {}).items():
+        if pid.startswith("_") or not isinstance(pl, dict):
+            continue
+        cap_map = {str(k): str(v) for k, v in (pl.get("capabilities") or {}).items()}
+        top = ""
+        for t in cap_map.values():
+            if rank(t, tiers) > rank(top, tiers):
+                top = t
+        out[pid] = {"title": str(pl.get("title") or pid), "capabilities": cap_map,
+                    "tier": top, "ids": sorted(cap_map)}
+    return out
+
+
+def validate(doc: dict | None = None) -> list:
+    """一致性校验 → 问题清单（空=通过）。"""
+    d = doc or load()
+    m = matrix(d)
+    tiers = m["_planTiers"]
+    role_plan = m["_roles"]
+    problems = []
+
+    for cid, c in m.items():
+        if cid.startswith("_"):
+            continue
+        if rank(c["minPlan"], tiers) < 0:
+            problems.append(f"能力 {cid} 的 minPlan={c['minPlan']!r} 不在 planTiers {tiers} 内")
+        pk = ((d.get("capabilities") or {}).get(cid) or {}).get("pack") or {}
+        # 「装了有入口」的三种形态（2026-09-21 批 C1 放宽）：flow（流程）/ entrypoints（工作台入口）/
+        # presets（角色会话 —— HR 这类纯本地能力就是这种：无 flow，入口是 preset）。
+        if not c["flows"] and not (pk.get("entrypoints") or []) and not (pk.get("presets") or []):
+            problems.append(f"能力 {cid} 既没有 flow、也没有 pack.entrypoints / pack.presets ⇒ 装了也没入口")
+        if rank(c["minPlan"], tiers) <= rank(free_tier(d), tiers) and c["flows"]:
+            problems.append(f"能力 {cid} 是免费档却挂了 {len(c['flows'])} 条流程"
+                            f"（{c['flows']}）⇒ C 端必须零 flow（免费档不得拥有任何 B 端流程）")
+    for r, p in role_plan.items():
+        if rank(p, tiers) < 0:
+            problems.append(f"角色 {r} 的档位 {p!r} 不在 planTiers 内")
+
+    # ── 套餐（SKU = 能力集合，2026-09-21 批 C1）────────────────────────────
+    # 为什么要有这一节：此前只有线性三档 ⇒ "只买 HR" / "只要美客多不要 HR" 都表达不了。
+    # 门禁守住三件事：① 套餐里的能力与档位都真实存在；② **每个能力至少被一个套餐授予**
+    # （否则客户买不到、装不上）；③ `capabilities.<c>.minPlan` = 授予它的**最低档**
+    # （派生一致 ⇒ 网关/客户端/服务端既有的档位判定一行不用改，也不会与套餐悄悄漂移）。
+    plans = (d.get("entitlements") or {}).get("plans") or {}
+    granted: dict = {}
+    for pid, pl in plans.items():
+        if pid.startswith("_"):
+            continue
+        if not isinstance(pl, dict):
+            problems.append(f"套餐 {pid} 定义不是对象")
+            continue
+        for cid, tier in (pl.get("capabilities") or {}).items():
+            if cid not in m:
+                problems.append(f"套餐 {pid} 授予了不存在的能力 {cid!r}")
+                continue
+            if rank(str(tier), tiers) < 0:
+                problems.append(f"套餐 {pid} 给能力 {cid} 的档位 {tier!r} 不在 planTiers {tiers} 内")
+                continue
+            granted.setdefault(cid, []).append(str(tier))
+    if not plans:
+        problems.append("entitlements 缺 plans（套餐=能力集合）⇒ 无法按套餐授权/安装")
+    for cid, c in m.items():
+        if cid.startswith("_"):
+            continue
+        if cid not in granted:
+            problems.append(f"能力 {cid} 没有被任何套餐授予 ⇒ 客户买不到、装不上")
+            continue
+        derived = min(granted[cid], key=lambda t: rank(t, tiers))
+        if derived != c["minPlan"]:
+            problems.append(f"能力 {cid} 的 minPlan={c['minPlan']!r} 与套餐派生的最低档 {derived!r} 不一致"
+                            f"（套餐授予档位：{sorted(set(granted[cid]))}）")
+    # roleMinPlan 若同时存在，必须与套餐派生结果一致（避免两处口径）
+    for r, p in (ents_role_min(d) or {}).items():
+        if r in role_plan and role_plan[r] != str(p):
+            problems.append(f"角色 {r}：roleMinPlan={p!r} 与能力/套餐派生的档位 {role_plan[r]!r} 不一致")
+
+    # 网关的 ROLE_PLAN 必须与矩阵一致（且覆盖全部流程角色）
+    if GATEWAY.exists():
+        src = GATEWAY.read_text(encoding="utf-8")
+        blk = re.search(r"const ROLE_PLAN = Object\.assign\(Object\.create\(null\), \{(.*?)\}\)", src, re.S)
+        if not blk:
+            problems.append("网关里找不到 ROLE_PLAN 表（改过结构？请同步本校验）")
+        else:
+            got = dict(re.findall(r"'([^']+)':\s*'([^']+)'", blk.group(1)))
+            for r in sorted(role_plan):
+                if r in got and got[r] != role_plan[r]:
+                    problems.append(f"网关 ROLE_PLAN[{r}]={got[r]!r} 与矩阵 {role_plan[r]!r} 不一致")
+            flow_roles = {r for cid, c in m.items() if not cid.startswith("_") for r in c["roles"]}
+            missing = sorted(flow_roles - set(got))
+            if missing:
+                problems.append(f"网关 ROLE_PLAN 漏登记流程角色 {missing}"
+                                f"（planOf 会默认 free ⇒ 免费版显示成可用）")
+            extra = sorted(set(got) - set(role_plan))
+            if extra:
+                problems.append(f"网关 ROLE_PLAN 多出未知角色 {extra}（矩阵里没有声明）")
+
+    # 网关客户端 bundle：档位分组必须**读载荷 minPlan**，不许再手写"某角色=某档"
+    if GATEWAY_CLIENT.exists():
+        gsrc = GATEWAY_CLIENT.read_text(encoding="utf-8")
+        hard = re.findall(r"'(ml-[a-z-]+|hr-office|pet-dev)':\s*'(free|pro|enterprise)'", gsrc)
+        if hard:
+            problems.append(f"网关客户端 bundle 里手写了角色→档位 {sorted(set(hard))}"
+                            f"（应由 roles 载荷的 minPlan 派生，档位文案也别点角色名）")
+        pt = re.search(r"var PLAN_TITLES = \{([^}]*)\}", gsrc)
+        if pt:
+            keys = re.findall(r"([A-Za-z_][\w]*)\s*:", pt.group(1))
+            bad = [k for k in keys if k not in tiers]
+            if bad:
+                problems.append(f"网关客户端 PLAN_TITLES 的档位名 {bad} 不在 planTiers {tiers} 内")
+        if "minPlan" not in gsrc:
+            problems.append("网关客户端 bundle 不再读载荷 minPlan ⇒ 档位分组失去唯一出处")
+
+    # preset 描述里的档位词必须与矩阵一致 —— 2026-09-20 实测：官网"美客多日报（Pro）"
+    # 就是从 `presets/argent-ml-daily/preset.yml` 的"（订阅 Pro）"抄来的，而矩阵是企业版。
+    # 这类"人读文案里的档位"没人守就会一直漂（还会被抄到官网/销售材料），所以让它进门禁。
+    # 中文词直接子串匹配；ASCII 档位词用词边界（否则 "provider"/"prompt"/"profile" 里的 pro 会误报）
+    tier_hits = [(r"免费", free_tier(d)), (r"\bfree\b", free_tier(d)),
+                 (r"\bpro\b", "pro"), (r"专业版", "pro"),
+                 (r"\benterprise\b", "enterprise"), (r"企业版", "enterprise")]
+    for role, plan in sorted(role_plan.items()):
+        py_file = HERE.parent / "presets" / f"argent-{role}" / "preset.yml"
+        if not py_file.exists():
+            continue
+        desc = ""
+        for line in py_file.read_text(encoding="utf-8").splitlines():
+            if line.startswith("description:"):
+                desc = line
+                break
+        wrong = sorted({t for pat, t in tier_hits if re.search(pat, desc, re.I)} - {plan})
+        if wrong:
+            problems.append(f"preset `presets/argent-{role}/preset.yml` 描述里的档位 {wrong} "
+                            f"与矩阵（{plan}）不一致 —— 官网/用户看到的档位就是从这里抄走的")
+
+    # 安装器的免费角色里不得出现任何流程角色（C 端零 flow 的第二道口子）
+    if INSTALLER.exists():
+        src = INSTALLER.read_text(encoding="utf-8")
+        fr = re.search(r"FREE_ROLES = \[(.*?)\]", src, re.S)
+        if not fr:
+            problems.append("install-argent.mjs 里找不到 FREE_ROLES（改过结构？请同步本校验）")
+        else:
+            free = re.findall(r"'([^']+)'", fr.group(1))
+            bad = sorted(set(free) & set(role_plan))
+            if bad:
+                problems.append(f"install-argent.mjs 的 FREE_ROLES 含流程角色 {bad} ⇒ B 端能力会被免费安装")
+
+    # 客户端的档位判断：必须是**生成块**且与注册表派生的块逐字节一致（无第二份手写判据）
+    if CLIENT.exists():
+        src = CLIENT.read_text(encoding="utf-8")
+        want = emit_client_block(d)
+        got = re.search(r"/\* \[entitlements:begin\].*?\[entitlements:end\] \*/", src, re.S)
+        if not got:
+            problems.append("客户端 bundle 里没有 [entitlements:begin/end] 生成块"
+                            "⇒ 档位判断还是手写的（跑 --emit-client-block 并整块覆盖）")
+        elif norm(got.group(0)) != norm(want):
+            problems.append("客户端 bundle 的 [entitlements] 生成块与注册表派生结果不一致"
+                            "⇒ 改过注册表没重生成（跑 --emit-client-block 整块覆盖）")
+        else:
+            # 生成块在，但不许再出现绕过它的手写判据
+            rest = src.replace(got.group(0), "")
+            for m2 in re.finditer(r'\.plan === "([^"]+)"', rest):
+                if m2.group(1) not in tiers:
+                    problems.append(f"客户端判断的档位名 {m2.group(1)!r} 不在 planTiers {tiers} 内")
+            for m2 in re.finditer(r'r\.role === "([^"]+)"', rest):
+                if m2.group(1) not in role_plan:
+                    problems.append(f"客户端按角色名硬编码门禁，但矩阵里没有 {m2.group(1)!r}")
+            caps_known = set(m)
+            for m2 in re.finditer(r'capabilityAllowed\("([^"]+)"', rest):
+                if m2.group(1) not in caps_known:
+                    problems.append(f"客户端引用了矩阵里没有的能力 {m2.group(1)!r}"
+                                    f"（改名/删能力必须同步客户端，否则该入口永远不显示）")
+    return problems
+
+
+def emit_gateway_table(doc: dict | None = None) -> str:
+    """机械派生网关 ROLE_PLAN 片段（手写必然漂移）。"""
+    m = matrix(doc)
+    rp = m["_roles"]
+    lines = ["const ROLE_PLAN = Object.assign(Object.create(null), {"]
+    for r in sorted(rp):
+        lines.append(f"  '{r}': '{rp[r]}',")
+    lines.append("})")
+    return "\n".join(lines)
+
+
+def emit_client_block(doc: dict | None = None) -> str:
+    """机械派生客户端档位判断块（client.js 里手写必然漂移）。"""
+    m = matrix(doc)
+    tiers = m["_planTiers"]
+    free = free_tier(doc)
+    cap_roles = {cid: c["roles"] for cid, c in m.items() if not cid.startswith("_")}
+    cap_minplan = {cid: c["minPlan"] for cid, c in m.items() if not cid.startswith("_")}
+    gated = sorted({r for roles in cap_roles.values() for r in roles})
+    body = [
+        "/* [entitlements:begin] 由 scripts/entitlements.py --emit-client-block 生成，请勿手改。",
+        "   唯一出处：scripts/flow-requirements.json（capabilities.*.minPlan / entitlements.*）。",
+        "   改注册表后重跑该命令并整块覆盖；scripts/tests/entitlements.test.mjs 断言本块无漂移。 */",
+        "var PLAN_TIERS = " + json.dumps(tiers, ensure_ascii=False) + ";",
+        "var FREE_TIER = " + json.dumps(free, ensure_ascii=False) + ";",
+        "// 能力 → 角色（角色的档位由网关按注册表 minPlan 下发；这里只留能力边界）",
+        "var CAPABILITY_ROLES = " + json.dumps(cap_roles, ensure_ascii=False, sort_keys=True) + ";",
+        "// 能力 → 所需档位（**注册表口径**）：无角色的运行现状原生能力只靠这一条判定",
+        "var CAPABILITY_MINPLAN = " + json.dumps(cap_minplan, ensure_ascii=False, sort_keys=True) + ";",
+        "var GATED_ROLES = " + json.dumps(gated, ensure_ascii=False) + ";",
+        "var planRank = function (p) {",
+        "  var i = PLAN_TIERS.indexOf(String(p == null ? '' : p));",
+        "  return i < 0 ? 0 : i; // 未知/缺失档位一律按最低档（保守默认：宁可少给，不可让用户以为能用）",
+        "};",
+        "var isPaidPlan = function (p) { return planRank(p) > planRank(FREE_TIER); };",
+        "var capabilityRoleAllowed = function (r, cap, account) {",
+        "  // 网关没下发 minPlan 时回落到**注册表口径**（r.minPlan 本来就是注册表下发的一份拷贝）",
+        "  var need = (r && r.minPlan) || CAPABILITY_MINPLAN[cap];",
+        "  return planRank(account && account.plan) >= planRank(need);",
+        "};",
+        "// 某能力是否可用：① 账号档位够该能力的 minPlan（注册表口径）",
+        "//               ② 挑了能力包（第 4 参 `installedCaps` = **已装的能力包 id 清单**）⇒ 该能力必须在里面",
+        "//                  —— 「装了才给」的口径落在**能力**上，不再靠角色名映射（角色名会退役，能力不会）",
+        "//               ③ 没挑能力包（第 4 参缺省，既有调用点）⇒ 有角色时按角色是否已装配判（保持原行为）",
+        "//               ④ 无角色的能力（如 HR 办公，入口 = 通用助手）⇒ 只看 ①（＋② 若挑了能力包）",
+        "var capabilityAllowed = function (cap, roles, account, installedCaps) {",
+        "  var need = CAPABILITY_MINPLAN[cap];",
+        "  if (!need) return false; // 未登记的能力 ⇒ 保守拒绝",
+        "  if (planRank(account && account.plan) < planRank(need)) return false;",
+        "  if (installedCaps) return (installedCaps || []).indexOf(cap) >= 0;",
+        "  var want = CAPABILITY_ROLES[cap] || [];",
+        "  if (!want.length) return true;",
+        "  var list = (roles || []).filter(function (r) { return r && want.indexOf(r.role) >= 0; });",
+        "  if (!list.length) return false; // 有角色但一个都没装配 ⇒ 未装好，不给",
+        "  return list.every(function (r) { return capabilityRoleAllowed(r, cap, account); });",
+        "};",
+        "// 某档位及以上的能力（派生自注册表：客户端**不写死**\"哪些能力是企业级\"）",
+        "var capabilitiesAtOrAbove = function (plan, roles, account, installedCaps) {",
+        "  var out = [];",
+        "  Object.keys(CAPABILITY_MINPLAN).forEach(function (c) {",
+        "    if (planRank(CAPABILITY_MINPLAN[c]) >= planRank(plan) && capabilityAllowed(c, roles, account, installedCaps)) out.push(c);",
+        "  });",
+        "  return out;",
+        "};",
+        "var anyCapabilityRegistered = function (roles) {",
+        "  return (roles || []).some(function (r) { return r && GATED_ROLES.indexOf(r.role) >= 0; });",
+        "};",
+        "var anyCapabilityAllowed = function (roles, account, installedCaps) {",
+        "  // 口径 = **有角色的能力**（与既有调用点兼容；`hr` 这类无角色能力不参与「总门控」）：",
+        "  // 若遍历全部能力，只装了**有角色那几条能力**的 Pro 账号会因为「HR 无角色、只看档位」而凭空通过",
+        "  // （实测：pro 档 false → true）⇒ 那是放大权限，不是修复。第 4 参照常透传。",
+        "  var caps = Object.keys(CAPABILITY_ROLES).filter(function (c) { return (CAPABILITY_ROLES[c] || []).length > 0; });",
+        "  for (var i = 0; i < caps.length; i++) {",
+        "    if (capabilityAllowed(caps[i], roles, account, installedCaps)) return true;",
+        "  }",
+        "  return false;",
+        "};",
+        "/* [entitlements:end] */",
+    ]
+    return "\n".join(body)
+
+
+def main(argv=None) -> int:
+    use_utf8_stdio()   # 唯一出口编码判据：见 scripts/lib/stdio_utf8.py 的事故说明
+    ap = argparse.ArgumentParser(description="能力×档位矩阵（唯一出处 + 校验 + 派生）")
+    ap.add_argument("--matrix", action="store_true")
+    ap.add_argument("--role")
+    ap.add_argument("--validate", action="store_true")
+    ap.add_argument("--emit-gateway-table", action="store_true")
+    ap.add_argument("--emit-client-block", action="store_true")
+    ap.add_argument("--write-client-block", metavar="FILE",
+                    help="把 [entitlements] 生成块原地写回该文件（默认 plugins/argent-skin/dist/client.js）")
+    ap.add_argument("--plans", action="store_true", help="打印套餐（SKU=能力集合）矩阵")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args(argv)
+    try:
+        doc = load()
+    except Exception as exc:  # noqa: BLE001
+        print(f"❌ 读取注册表失败：{exc}", file=sys.stderr)
+        return 2
+
+    if a.plans:
+        pm = plans_matrix(doc)
+        if a.json:
+            print(json.dumps(pm, ensure_ascii=False, indent=2))
+        else:
+            print(f"  套餐（{len(pm)} 个，档位 = 该套餐授予的最高档）：")
+            for pid, p in pm.items():
+                caps = "、".join(f"{c}:{t}" for c, t in sorted(p["capabilities"].items()))
+                print(f"    {pid:18} {p['title']:22} 档位={p['tier']:11} 能力={caps}")
+        return 0
+    if a.write_client_block:
+        target = pathlib.Path(a.write_client_block)
+        if not target.exists():
+            print(f"❌ 目标文件不存在：{target}", file=sys.stderr)
+            return 2
+        src = target.read_text(encoding="utf-8")
+        block = emit_client_block(doc)
+        # 与 validate() 用**同一个**匹配式（块首是说明性多行注释，不是 `begin] */`）
+        new = re.sub(r"/\* \[entitlements:begin\].*?\[entitlements:end\] \*/", lambda _m: block, src, flags=re.S)
+        if new == src:
+            print("  ℹ️ 生成块已是最新（未改动）")
+            return 0
+        target.write_text(new, encoding="utf-8")
+        print(f"  ✅ 已写回 [entitlements] 生成块 → {target}")
+        return 0
+    if a.emit_gateway_table:
+        print(emit_gateway_table(doc))
+        return 0
+    if a.emit_client_block:
+        print(emit_client_block(doc))
+        return 0
+    if a.role:
+        m = matrix(doc)
+        plan = m["_roles"].get(a.role)
+        if plan is None:
+            print(f"❌ 角色 {a.role} 不在矩阵里（流程角色由 capability 派生；其它角色请写进 entitlements.roleMinPlan）",
+                  file=sys.stderr)
+            return 1
+        print(json.dumps({"role": a.role, "minPlan": plan}, ensure_ascii=False) if a.json
+              else f"  {a.role} → {plan}")
+        return 0
+    if a.validate:
+        problems = validate(doc)
+        if a.json:
+            print(json.dumps({"problems": problems}, ensure_ascii=False, indent=2))
+        else:
+            print("  ✅ 能力×档位矩阵三处一致" if not problems else "  ❌ 不一致：\n" + "\n".join(f"     {p}" for p in problems))
+        return 1 if problems else 0
+    # 默认打矩阵
+    m = matrix(doc)
+    if a.json:
+        print(json.dumps(m, ensure_ascii=False, indent=2))
+    else:
+        print(f"  档位序列：{' < '.join(m['_planTiers'])}")
+        for cid, c in m.items():
+            if cid.startswith("_"):
+                continue
+            print(f"  {cid:14} minPlan={c['minPlan']:11} 流程={c['flows']}")
+        print("  角色 → 档位：" + "、".join(f"{r}={p}" for r, p in sorted(m["_roles"].items())))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())