@whyshu/argent-engine 0.0.0-stage → 0.6.1

package/engine/scripts/capability_pack.py

@@ -0,0 +1,1242 @@
+#!/usr/bin/env python3
+"""能力包版本化（迭代 3-⑨）：把一条 capability 打成**可版本化、可装配、装配后能自检**的包。
+
+## 问题
+现状是"整仓 `git pull`"：想只领"发票能力"做不到；能力与仓库版本绑死；装完也没法在客户机上
+证明"这一包是自洽的"（缺脚本/缺 preset/缺适配器都要等真跑那天才发现）。
+
+## 口径
+- **包 = capability**（不是 flow，也不是整仓）：`capabilities.<c>` 下的共同声明 + 该能力的
+  flow/preset/提示词/技能/集成适配器/脚本。
+- **版本**在注册表里声明：`capabilities.<c>.pack.version`（语义化版本）；装配产物里写 `PACK.json`
+  （含每个文件的 sha256 + 源提交），因此"客户机上跑的是哪一版"可核对。
+- **装配后必须能自检**：`--build` 结束前，在**产物目录里**真跑
+  `flow_config.py --flow <id> --registry <产物>/scripts/flow-requirements.json --lax`
+  与 `integration_contract.py --validate`；任一失败 ⇒ 非零退出（把"装完才知道缺东西"提前到装配时）。
+
+## 派生 vs 声明（避免第二份真相）
+- **派生**：flow/prompt/preset/适配器/runners/模板/技能引用（扫描提示词里的 `skills/<名>`）。
+- **声明**：`capabilities.<c>.pack.{version,scripts,skills}`（该能力**额外**要带的脚本、要装的技能）
+  与顶层 `pack.engine`（共用引擎文件 —— 它是**分发清单**，不是运行时真相）。
+- 派生与声明**都要存在性校验**：声明了却不存在 ⇒ 报错，不许静默少装。
+
+用法：
+    python3 scripts/capability_pack.py --list [--json]
+    python3 scripts/capability_pack.py --describe invoice [--json]
+    python3 scripts/capability_pack.py --validate [--json]
+    python3 scripts/capability_pack.py --stamp [--allow-downgrade]
+    python3 scripts/capability_pack.py --check-stamp [--json]      # 只读：锁内摘要 == 当前内容重算摘要
+    python3 scripts/capability_pack.py --build invoice --out-dir /tmp/pack-invoice [--force]
+    python3 scripts/capability_pack.py --emit-server-manifest --out <whyshu-svr>/src/config/capability-packs.json
+        · 默认 **merge**：只刷新注册表认识的能力，清单里它不认识的条目**原样保留**（键序也不动）；
+        · 要删除不认识的条目须显式 `--prune`（会把将删项打印出来）；
+        · `--dry-run` 只打印 diff、不写文件（发布前复核用；发布工具已保证不误删，这一步是双保险）。
+
+⚠️ 2026-10-06 修（脚枪）：`--emit-server-manifest` 旧实现是**整表替换** —— 跑一次就会把
+    "清单里有、注册表里没有"的条目（如 `daily-report-lite`）抹掉，还会顺手重写本批不动的条目。
+    现在默认 merge，删除必须显式 `--prune`。
+
+⚠️ 2026-10-11 修（两条真缺陷，都在盖章期才拦得住）：
+    ① **降版不拦**：并发批在自己的旧文件上继续改 ⇒ diff 一度把三个包**降版**（实测）。
+       现在 `--stamp` 见到"新版本 < 锁里的版本"即判红并点名（能力/旧版本/新版本/重建姿势）；
+       确实要刻意回滚须显式 `--allow-downgrade`（放行但**显著告警**）。
+    ② **"内容变但版本没变"只在发布期被 `--check-dl` 抓到**：`scripts/flow-requirements.json`
+       变了（新增 `failureClasses.capacityFull`）⇒ **每个包的 tgz 都带一份注册表投影** ⇒
+       `hr` 的包字节随之改变，而没人提 `hr` 版本 ⇒ 只能等 `--check-dl` 报
+       「版本相同但内容摘要不同」。现在锁里给**每个能力**记一个 `digest`
+       （口径与 `--emit-server-manifest#sha256` / `--digest-tgz` **逐字一致**，见 `pack_digest()`），
+       `--stamp` 时"摘要不同 ∧ 版本未变"即判红；`--check-stamp` 供**批次收口前**离线自检。
+
+退出码：0 正常；1 有问题（校验失败 / 装配自检失败 / 拒绝盖章 / 摘要漂移）；2 用法或读取失败。
+"""
+from __future__ import annotations
+
+import argparse
+import gzip
+import hashlib
+import json
+import os
+import pathlib
+import re
+import shutil
+import tarfile
+import subprocess
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+REPO = HERE.parent
+sys.path.insert(0, str(HERE / "lib"))
+# ⛔ 本进程不种 `.pyc`（2026-10-11 补，**必须在下面 import flow_registry 之前**）：
+# `--check-stamp` / `--describe` / `--validate` 都对外声称"只读"，而 CPython 默认会在
+# `scripts/__pycache__/` 写下 `flow_registry.*.pyc` ⇒ **只读子命令往被检查的树里写字节**。
+# 与 `_run()` / `_registry_probe()` / `_adapter_files()` 里已有的 `PYTHONDONTWRITEBYTECODE=1`
+# 同一条纪律（"别在产物/被检查的树里种 __pycache__"），这里覆盖**本进程自己**那一路。
+# 判据：回归 ⑦ 对整棵夹具树做字节级前后比对（零写入）。
+sys.dont_write_bytecode = True
+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"))
+
+LOCK = pathlib.Path(os.environ.get("ARGENT_PACK_LOCK") or (HERE / "capability-packs.lock.json"))
+PROMPTS = HERE / "flow-prompts"
+PRESETS = REPO / "presets"
+SKILLS = REPO / "skills"
+INTEGRATIONS = HERE / "integrations"
+
+SEMVER = r"^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$"
+
+
+def semver_key(v) -> tuple | None:
+    """语义化版本 ⇒ **可比较**的元组；不是语义化版本 ⇒ `None`（⛔ 不猜、不硬比）。
+
+    为什么需要它（2026-10-11 实测缺陷）：`stamp_check()` 此前只判"版本**相等**与否" ——
+    相等才查内容，不等就当成"合规提版"直接放行 ⇒ **降版（新 < 旧）与提版走同一条路**，
+    并发批次在自己的旧文件上继续改就能把三个包**降版**而全程无红灯。
+
+    口径：`(major, minor, patch, 是否正式版, 预发布串)`；预发布版按 semver §11 **小于**同号正式版
+    （`0.1.7-rc.2 < 0.1.7`），两个预发布之间按字符串比较（本仓只有 `rc.N` 这一种，够用且**可解释**）。
+    """
+    m = re.match(r"^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$", str(v or ""))
+    if not m:
+        return None
+    pre = m.group(4)
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3)), 0 if pre else 1, pre or "")
+
+
+def is_downgrade(new: str, old: str) -> bool:
+    """`new` 是不是**降版**（严格小于 `old`）。任一侧不是语义化版本 ⇒ `False`（不据此判红）。"""
+    a, b = semver_key(new), semver_key(old)
+    return bool(a and b and a < b)
+
+
+def load() -> dict:
+    return _registry_doc()
+
+
+def engine_files(doc: dict) -> list:
+    return [str(p) for p in ((doc.get("pack") or {}).get("engine") or [])]
+
+
+def _posix(rel) -> str:
+    """包内相对路径的**唯一归一入口**：一律 POSIX 形态（正斜杠）。
+
+    为什么必须有它（2026-10-08，Windows 装机验证）：包内路径的**全部**下游用法都假定正斜杠 ——
+      · 锁文件（`capability-packs.lock.json`）与 `PACK.json#files` 的键是正斜杠；
+      · "从路径取业务线 id"（`verticals/<id>/manifest.json`）；
+      · tgz 成员名（`tarfile` 的 arcname）与 Node 侧 `join(packDir, rel)`。
+    而 `str(Path.relative_to(...))` 在 Windows 上给的是**反斜杠** ⇒ 两种故障：
+      ① 解析当场 IndexError（旧实现按正斜杠切分后取第二段）；
+      ② 反斜杠键与正斜杠键**永不相等** ⇒ 与锁/基线的逐文件比对被**静默绕过**（比崩溃更危险，
+         2026-10-08 实测 hr 的 sha 清单就是反斜杠键，因而"没发生比对"）。
+    ⇒ 归一是这一层唯一正确的做法；`PurePosixPath` 顺带压掉 `./`、重复斜杠与尾斜杠。
+    ⛔ 不要自己拼字符串（先 `os.sep` 替换再 split 会漏掉 `a//b`、`./a` 这类形态）。
+    （与 Node 侧 `scripts/argent-capabilities.mjs#normalizePackPath()` **逐字同口径**：
+      同一张 sha 表会被两侧分别比对，任一侧口径不同都会变成"永远不比"。）
+    """
+    s = str(rel or "")
+    if not s:
+        return ""          # `PurePosixPath("")` 是 `.`：空串必须原样返回空串（与 Node 侧同口径）
+    return pathlib.PurePosixPath(s.replace("\\", "/")).as_posix()
+
+
+def _posix_map(files) -> dict:
+    """`{相对路径: sha}` ⇒ 键统一成 POSIX 形态（**历史产物**可能是反斜杠：Windows 上盖过章的锁）。"""
+    if not isinstance(files, dict):
+        return {}
+    return {_posix(k): v for k, v in files.items()}
+
+
+def digest_tarball(path) -> dict:
+    """算一个**已下载的**能力包 tgz 的整包内容摘要（`--digest-tgz` 的唯一实现）。
+
+    为什么要它（2026-10-09）：发布体检要回答的是"**HTTP 下发的那一个包**，内容是不是清单里写的
+    那一个"。只比 md5（传输没坏）不够 —— 包内容与清单 sha256 对不对得上才是判据。为此需要一条
+    "从 tgz 重算摘要"的通道。
+
+    ⛔ 为什么不做成"自己 import 本模块再算"：`importlib` 加载时 `scripts/` 不在 `sys.path` ⇒
+    `import flow_registry` 失败并**静默降级**成未合并的 base 注册表 ⇒ 带流程的能力（full/invoice/
+    daily-report）摘要**算错**（2026-10-08 实测）。做成 CLI 子命令 ⇒ 谁调都是同一条、同一份 sys.path。
+
+    成对返回两个排序口径的摘要：客户端 `packContentDigest()` 排的是**拼好的 `路径:sha` 行**，而
+    `pack_digest()` 排的是**元组**；二者只在"某路径是另一路径的前缀且下一字符 < ':'"这类边角上
+    分歧（`a/b` vs `a/b-c`）。主值取**客户端口径**（装机时真正被比的就是它），分歧时单独报出来。
+    """
+    p = pathlib.Path(path)
+    if not p.exists():
+        raise ValueError(f"文件不存在：{p}")
+    try:
+        with tarfile.open(p, "r:gz") as tf:
+            try:
+                member = tf.getmember("PACK.json")
+            except KeyError:
+                raise ValueError(f"{p} 里没有 PACK.json —— 这不是能力包 tgz")
+            pack_json = json.loads(tf.extractfile(member).read().decode("utf-8"))
+    except tarfile.TarError as exc:
+        raise ValueError(f"{p} 不是合法的 gzip/tar：{exc}")
+    files = _posix_map(pack_json.get("files") or {})
+    client = hashlib.sha256("\n".join(sorted(f"{r}:{s}" for r, s in files.items())).encode("utf-8")).hexdigest()
+    tuple_order = hashlib.sha256("\n".join(f"{r}:{s}" for r, s in sorted(files.items())).encode("utf-8")).hexdigest()
+    return {"capability": str(pack_json.get("capability") or ""), "version": str(pack_json.get("version") or ""),
+            "fileCount": len(files), "sha256": client, "sha256TupleOrder": tuple_order,
+            "orderingDivergence": client != tuple_order}
+
+
+def _vertical_id(rel: str) -> str:
+    """`verticals/<id>/manifest.json` ⇒ `<id>`（用 `PurePosixPath.parts`，⛔ 不 split 字符串）。"""
+    parts = pathlib.PurePosixPath(_posix(rel)).parts
+    return parts[1] if len(parts) > 2 and parts[0] == "verticals" else ""
+
+
+def _expand_files(rel: str) -> list:
+    """把清单里的条目展开成**真实文件**列表（目录 ⇒ 其下所有文件）。
+
+    为什么必须展开（2026-09-21 实测）：`files` 里可以有目录（`presets/argent-hr-office`、`skills/ml-invoice`），
+    而 `integrity` 原先只对"恰好是文件"的条目算 sha ⇒ HR 这类只带 preset 的能力**整包没有一条 sha**，
+    医生只能 WARN、安装器也没法校验"包内容有没有被改过"。展开后 PACK.json 的 sha 清单才是完整的。
+    """
+    p = REPO / rel
+    if p.is_dir():
+        out = []
+        for f in sorted(p.rglob("*")):
+            if not f.is_file():
+                continue
+            relf = _rel(f)
+            parts = pathlib.PurePosixPath(relf).parts
+            if "__pycache__" in parts or f.suffix == ".pyc" or f.name == ".DS_Store":
+                continue
+            out.append(relf)
+        return out
+    return [_rel(REPO / rel)] if p.exists() else []
+
+
+def _rel(p: pathlib.Path) -> str:
+    """仓库相对路径 ⇒ **POSIX 形态**（包内路径的唯一形态，见 `_posix()`）。"""
+    try:
+        return _posix(p.relative_to(REPO))
+    except ValueError:
+        return _posix(p)
+
+
+def manifest(cap: str, doc: dict | None = None) -> dict:
+    """派生 + 声明的能力包清单（**不落盘**）。缺文件记进 `missing`，由 --validate 判死。"""
+    d = doc or load()
+    caps = {k: v for k, v in (d.get("capabilities") or {}).items() if not k.startswith("_")}
+    if cap not in caps:
+        raise KeyError(cap)
+    c = caps[cap] or {}
+    pack = c.get("pack") or {}
+    flows = sorted(fid for fid, f in (d.get("flows") or {}).items() if (f or {}).get("capability") == cap)
+
+    roles, presets_f, prompts, skills, integrations, scripts = [], [], [], set(), set(), set()
+    for fid in flows:
+        f = d["flows"][fid] or {}
+        role = str(f.get("role") or "")
+        if role:
+            roles.append(role)
+            presets_f.append(f"presets/argent-{role}")
+        for p in _prompt_paths(fid, f):
+            if True:
+                prompts.append(_rel(p))
+                # 提示词里引用的技能 = 该能力的技能依赖（派生，不靠人记）
+                for ln in p.read_text(encoding="utf-8").splitlines():
+                    for tok in _skill_refs(ln):
+                        skills.add(tok)
+        integ = f.get("integration")
+        if integ:
+            integrations.add(str(integ))
+    # 集成适配器带来的脚本/模板（runners/template 由契约声明，避免第二份清单）
+    integrations_resolved = []
+    for name in sorted(integrations):
+        adir = INTEGRATIONS / name
+        integrations_resolved.append(_rel(adir / "adapter.py") if (adir / "adapter.py").exists()
+                                   else f"scripts/integrations/{name}/adapter.py")
+        for fn in _adapter_files(name):
+            scripts.add(fn)
+
+    for s in (pack.get("scripts") or []):
+        scripts.add(str(s))
+    for s in (pack.get("skills") or []):
+        skills.add(str(s))
+    # 无 flow 的能力（HR 办公）靠 **preset** 提供入口 ⇒ 显式声明（2026-09-21 批 C1）。
+    # 有 flow 的能力不需要声明：preset 由 `flows.<id>.role` 派生（`presets/argent-<role>`）。
+    for p in (pack.get("presets") or []):
+        presets_f.append(str(p))
+    if pack.get("prompts"):
+        prompts.extend(str(p) for p in pack["prompts"])
+
+    # 业务线清单（**技能归类的真源**）：`scripts/check-skill-classification.mjs#classify()` 读
+    # `verticals/*/manifest.json#skills` 得出"外发集"，而技能同步**只发外发集** ⇒ 包不带它，
+    # 装出来的机器上外发集为空（G3 红）⇒ 技能同步段无从执行（2026-10-05 演练实测）。
+    # 逐字复制（**不**按能力过滤）：同一批包里的这份文件 sha 相同，不引入跨包不一致。
+    #
+    # P2a（2026-10-09，P0 修复）：**`flows.json` 必须与 `manifest.json` 同批带上** ——
+    # `flow_registry.merge()` 的 `load_vertical()` 见到 `verticals/<id>/manifest.json` 就要求同目录
+    # 有 `flows.json`（缺 ⇒ `Conflict: 缺 flows.json` ⇒ `--json` exit 2）。旧包只带 manifest ⇒
+    # **纯包装机**（无源码树）装完引擎读不了注册表。两文件都**不按能力过滤**（逐字复制）：
+    # ① `merge()` 会核对 `manifest.flows == flows.json` 的规范 id 集合 ⇒ 过滤任一份都是冲突；
+    # ② 同一批包里的这两份文件 sha 相同 ⇒ 多包同装不会撞"引擎文件版本不一致"。
+    vertical_manifests = []
+    for vf in sorted((REPO / "verticals").glob("*/manifest.json")):
+        try:
+            vd = json.loads(vf.read_text(encoding="utf-8"))
+        except Exception:  # noqa: BLE001 —— 坏 manifest 由 --validate 报，不在这里吞
+            continue
+        ids = {str(x.get("id")) for x in (vd.get("capabilities") or []) if isinstance(x, dict)}
+        if cap in ids:
+            vertical_manifests.append(_rel(vf))
+            # 没有 flows.json 的业务线是**坏树**（加载器必拒）⇒ 交给 --validate 报，不在这里静默补
+            vfl = vf.with_name("flows.json")
+            if vfl.exists():
+                vertical_manifests.append(_rel(vfl))
+            # 业务线**配置目录**（`verticals/<id>/config.json`，契约 §7）：它是该线可配项的声明面，
+            # 运行期由 `core/lib/config-catalog.mjs` 读取。不带它 ⇒ 纯包装机上该线的可配项**整体消失**
+            # （引擎级 configs/ 还在，于是"缺一半"且无报错 —— 比缺件更难发现）。与 manifest/flows 同理
+            # **不按能力过滤**：同一批包里 sha 相同，多包同装不会撞版本。
+            vcf = vf.with_name("config.json")
+            if vcf.exists():
+                vertical_manifests.append(_rel(vcf))
+
+    # 共用引擎只跟"有 flow"的能力走：工作台原生能力（无 flow）不需要流程引擎，
+    # 带上一整套会把"轻量"变成"整仓"（与 ⑩ 的初衷相反）。
+    files = (list(engine_files(d)) if flows else []) + sorted(scripts) + sorted(prompts) \
+        + sorted(presets_f) + [f"skills/{s}" for s in sorted(skills)] + sorted(set(integrations_resolved)) \
+        + vertical_manifests
+    seen, uniq = set(), []
+    for f in files:
+        if f not in seen:
+            seen.add(f)
+            uniq.append(f)
+    files = uniq
+    missing = sorted({f for f in files if not (REPO / f).exists()})
+
+    entrypoints = [str(e) for e in (pack.get("entrypoints") or [])]
+    return {
+        "capability": cap,
+        "version": str(pack.get("version") or ""),
+        "minPlan": str(c.get("minPlan") or ""),
+        "entrypoints": entrypoints,
+        # 显式声明的 preset（无 flow 的能力用；有 flow 的能力靠 roles 派生）
+        "presets": [str(p) for p in (pack.get("presets") or [])],
+        "flows": flows,
+        "roles": sorted(set(roles)),
+        "files": files,
+        "missing": missing,
+        # sha 清单：把目录展开成其下文件（否则带 preset/skills 的能力整包没有 sha 可核）
+        "integrity": {f: _sha(REPO / f)
+                      for f in dict.fromkeys(x for rel in files for x in _expand_files(rel))},
+        # 业务线 id（去重：`vertical_manifests` 现在每条业务线有 **两个** 条目 —— manifest + flows）
+        "verticals": sorted({v for v in (_vertical_id(x) for x in vertical_manifests) if v}),
+        "unitCount": sum(1 for f in files if not (REPO / f).is_dir()),
+        "dirCount": sum(1 for f in files if (REPO / f).is_dir()),
+    }
+
+
+def _sha256_full(p: pathlib.Path) -> str:
+    return hashlib.sha256(p.read_bytes()).hexdigest()
+
+
+def pack_digest(cap: str, doc: dict | None = None) -> str:
+    """能力包的**整包摘要**（64 位 sha256）：对 `路径:文件sha256` 排序后逐行求摘要。
+
+    为什么不是"每文件一个 sha"：服务端的清单字段只有一个 `sha256`（安装器做整包比对），
+    而单文件明细在 `PACK.json`（--build 产物）里本来就有 ⇒ 这里给一个稳定的整包指纹。
+    """
+    # 口径必须与客户端 `packContentDigest()` **逐字一致**：对 `文件:sha16` 排序后求 sha256。
+    # 早期版本遍历 `m["files"]` 并对**目录**跳过 ⇒ HR 这类只带 preset 的能力算出来是"空串摘要"
+    # （e3b0c442…），而客户端用 PACK.json 里展开后的 3 个文件算 ⇒ 两边对不上，实测被 live 安装当场抓到。
+    m = manifest(cap, doc)
+    reg = json.dumps(packed_registry(cap, doc, m), ensure_ascii=False, indent=2) + "\n"
+    files = {**(m.get("integrity") or {}),
+             "scripts/flow-requirements.json": hashlib.sha256(reg.encode("utf-8")).hexdigest()[:16]}
+    lines = [f"{rel}:{sha}" for rel, sha in sorted(files.items())]
+    return hashlib.sha256("\n".join(lines).encode("utf-8")).hexdigest()
+
+
+GEN_NOTE = ("能力包清单（能力 → minPlan/版本/整包 sha256/下载地址）。"
+            "由 argent-dsh `scripts/capability_pack.py --emit-server-manifest` 生成，勿手改；"
+            "发布新包后重新生成并覆盖本文件。")
+
+
+def reg_capabilities(doc: dict | None = None, dl_base: str = "") -> dict:
+    """注册表里**认识**的能力 ⇒ 清单条目（纯派生：版本 / 档位 / 整包摘要 / 下载地址）。"""
+    d = doc or load()
+    base = (dl_base or os.environ.get("ARGENT_PACK_DL_BASE") or "https://whyshu.com/dl").rstrip("/")
+    caps = {}
+    for cap in sorted(k for k in (d.get("capabilities") or {}) if not k.startswith("_")):
+        m = manifest(cap, d)
+        ver = m["version"]
+        caps[cap] = {
+            "minPlan": m["minPlan"],
+            "version": ver,
+            "sha256": pack_digest(cap, d),
+            "url": f"{base}/packs/{cap}-{ver}.tgz",
+        }
+    return caps
+
+
+def read_manifest_file(path) -> dict:
+    """读一份**已存在**的服务端清单（merge 的来源）。读不了/结构非法 ⇒ 抛 ValueError。
+
+    ⛔ 不静默降级成"没有旧清单"：那等于把清单里本工具不认识的条目**当成不存在**而抹掉，
+    正是本函数要防的那类损失。宁可报错让操作者决定。
+    """
+    p = pathlib.Path(path)
+    try:
+        doc = json.loads(p.read_text(encoding="utf-8"))
+    except Exception as exc:  # noqa: BLE001
+        raise ValueError(f"读取失败：{exc}") from exc
+    if not isinstance(doc, dict) or not isinstance(doc.get("capabilities"), dict):
+        raise ValueError("结构非法：缺少 capabilities 对象")
+    return doc
+
+
+def server_manifest(doc: dict | None = None, dl_base: str = "",
+                    existing: dict | None = None, prune: bool = False) -> dict:
+    """生成 **whyshu-svr** 消费的能力清单（`src/config/capability-packs.json`）。
+
+    闭环：`--build` 出包 → 上传到 `DL_BASE/packs/<cap>-<ver>.tgz` → 本命令生成清单 →
+    覆盖到 whyshu-svr（`ARGENT_CAPABILITY_PACKS` 可覆盖路径）⇒ 安装票据就能返回
+    "这个套餐有哪些能力、各是哪版、sha 是多少、从哪下"。
+
+    ## 默认 **merge**，不是整表替换（2026-10-06 修，脚枪）
+    传了 `existing`（现网清单）时：
+      · 注册表**认识**的能力 ⇒ 用本次重新派生的值覆盖（这就是本命令的意义）；
+      · 注册表**不认识**的条目（如历史上线的 `daily-report-lite`）⇒ **原样保留**；
+      · 键序沿用旧清单，新能力追加在末尾 ⇒ 没动到的条目**连顺序都不变**（diff 最小）。
+    要删掉不认识的条目必须显式 `prune=True`（CLI `--prune`），且调用方应把将删项打印出来。
+
+    ## 为什么曾出事故
+    旧实现是整表输出：只输出注册表里的能力 ⇒ 跑一次就把"表里有、注册表没有"的条目**抹掉**，
+    还会顺手重写本批不打算动的条目（失去"恰好变更文件"的可审计性）。
+    """
+    existing = existing if isinstance(existing, dict) else None
+    fresh = reg_capabilities(doc, dl_base)
+    if existing is None:
+        return {"_note": GEN_NOTE, "capabilities": fresh}
+    old_caps = existing.get("capabilities") or {}
+    merged = {}
+    for k, v in old_caps.items():
+        if k in fresh:
+            merged[k] = fresh[k]           # 认识 ⇒ 刷新
+        elif not prune:
+            merged[k] = v                  # 不认识 ⇒ 默认原样保留
+    for k, v in fresh.items():
+        if k not in merged:
+            merged[k] = v                  # 新能力 ⇒ 追加在末尾
+    out = dict(existing)                   # 顶层其它键（_note / version / …）原样保留
+    out["capabilities"] = merged
+    return out
+
+
+def manifest_merge_report(existing: dict | None, merged: dict, known: list | None = None,
+                          prune: bool = False) -> dict:
+    """把"这次合并做了什么"算成可打印的结构（保留/新增/更新/删除），供 CLI 汇报与 --dry-run 用。
+
+    `known` = **注册表认识**的能力 id 列表（= 本次重新派生的键集合）。判定"保留"看的是
+    "不在 known 里"（而不是"不在输出里"）—— 保留的条目**本来就在输出里**（原样未动）。
+    """
+    old = ((existing or {}).get("capabilities") or {})
+    new = merged.get("capabilities") or {}
+    known_set = set(known or [])
+    preserved = [k for k in old if k not in known_set] if not prune else []
+    removed = sorted(k for k in old if k not in known_set) if prune else []
+    added = sorted(k for k in new if k not in old)
+    refreshed = sorted(k for k in new if k in old and k in known_set)
+    updated = []
+    for k in new:
+        if k in old and old[k] != new[k]:
+            old_e, new_e = old[k] or {}, new[k] or {}
+            for f in sorted(set(old_e) | set(new_e)):
+                if old_e.get(f) != new_e.get(f):
+                    updated.append((k, f, old_e.get(f), new_e.get(f)))
+    return {"preserved": sorted(preserved), "removed": removed,
+            "added": added, "updated": updated, "refreshed": refreshed}
+
+def packed_registry(cap: str, doc: dict | None = None, m: dict | None = None) -> dict:
+    """**包内注册表**（纯函数）：只留本能力 + 它引用的流程 + 共同声明。
+
+    被 `build()`（写文件）与 `pack_digest()`（算摘要）**共用** ⇒ 两边看到同一份字节；
+    这条是 2026-09-22 修的：此前摘要只覆盖源文件，而包内注册表是 build 时生成的 ⇒
+    改了它（候选判据/闸门/计费/租约口径全在里面）摘要与校验都发现不了。
+
+    ## P2a（2026-10-09 修，P0）：投影**只并引擎级段**，flow 声明不进来
+    这份投影的落点就是 `scripts/flow-requirements.json` —— P2a 契约里的**引擎级 base**
+    （引擎契约/错误词表/lease/billing/pack.engine）。按拆分约定，**flow 声明属业务线**：
+    `verticals/<id>/flows.json`（由 `manifest()` 同批带进包）。
+
+    旧实现把 `m["flows"]`（规范 id）写进投影 ⇒ 两种机器两种崩法（2026-10-09 真机复核，P0）：
+      · 源码树装带 flow 的包 ⇒ base 与 `verticals/<id>/flows.json` **重复定义** ⇒ `--json` exit 2；
+      · 纯包装机 ⇒ 包带了 manifest 却没带 flows.json ⇒ exit 2。
+    所以这里 `flows`/`aliases` **恒为空**（保留键形只是稳定消费者与摘要口径：无 flow 的能力
+    hr 的投影字节**不变**，不用跟着提版本）。⛔ 不要为"包自足"再把 flow 抄一份进来 ——
+    真正让包自足的是同批带上的 `verticals/<id>/flows.json`（`build()` 的自检会证明它能加载）。
+    装配自检也因此**必须走合并路径**（`ARGENT_REGISTRY_ROOT=<产物>`），见 `build()`。
+    """
+    d = doc or load()
+    m = m or manifest(cap, d)
+    caps = {k: v for k, v in (d.get("capabilities") or {}).items() if k == cap or k.startswith("_")}
+    return {
+        # 空段（不是缺失）：base 不该有 flow 声明，但键形保留 ⇒ 消费者 `doc.flows` 恒是对象
+        "aliases": {},
+        "_doc": f"[能力包 {cap} v{m['version']}] 由 scripts/capability_pack.py --build 生成；"
+                f"只含该能力的**引擎级**声明（flow 声明在 verticals/<id>/flows.json，随包同批带上）。"
+                f"改能力请改源仓库后重新打包。",
+        "flows": {},
+        "capabilities": caps,
+        "failureClasses": d.get("failureClasses") or {},
+        "pack": d.get("pack") or {},
+        "entitlements": d.get("entitlements") or {},
+        "billing": d.get("billing") or {},
+        "lease": d.get("lease") or {},
+        "_requiredRoles": d.get("_requiredRoles") or {},
+        "_pauseSwitchRule": d.get("_pauseSwitchRule") or {},
+        "_integrationNote": d.get("_integrationNote") or {},
+    }
+
+
+
+def _prompt_paths(fid: str, spec: dict) -> list:
+    """该流程的主提示词、失败提示词，以及**宿主排程的静态轮次指令**（P1-A，2026-10-12）。
+
+    注册表 `trigger.promptTemplate` 是**唯一出处**；业务线落位后提示词在
+    `verticals/<id>/prompts/`，不再在 `scripts/flow-prompts/`。历史目录仅作兜底
+    （base 流程仍可能在那里）。
+
+    `trigger.schedule.promptFile`（宿主原生排程用；相对业务线目录）同样**随包走** ——
+    判据与 `trigger.promptTemplate` 同一条：**注册表引用谁，包就带谁**。不带它的话纯包装机上
+    那个文件不存在 ⇒ "注册表说有、机器上却没有"这种半缺件最难查（运行期只会响亮警告，
+    而人会先怀疑注册表）。
+    """
+    out: list[pathlib.Path] = []
+    tpl = str(((spec.get("trigger") or {}).get("promptTemplate")) or "")
+    if tpl:
+        main = HERE.parent / tpl
+        out += [main, main.with_name(main.name[:-3] + ".failure.md")]
+    sched = str((((spec.get("trigger") or {}).get("schedule") or {}).get("promptFile")) or "")
+    if sched:
+        out.append(schedule_prompt_path(fid, sched))
+    out += [PROMPTS / f"{fid}.md", PROMPTS / f"{fid}.failure.md"]
+    seen, uniq = set(), []
+    for p in out:
+        if p.exists() and p not in seen:
+            seen.add(p); uniq.append(p)
+    return uniq
+
+
+def schedule_prompt_path(fid: str, rel: str) -> pathlib.Path:
+    """`trigger.schedule.promptFile` 的路径解析（与 `scripts/flow_config.py` **同一套**）。
+
+    两种写法都认：`verticals/<id>/…`（仓库根相对）与 `prompts/<x>.md`（**业务线内**相对）。
+    ⛔ 两份实现不许漂移 —— 回归 `scripts/tests/schedule-declaration.test.mjs` 对同一份声明
+    断言"运行期读取器与打包器解析到**同一个文件**"。
+    """
+    p = pathlib.Path(str(rel))
+    if p.is_absolute():
+        return p
+    if str(rel).startswith("verticals/"):
+        return HERE.parent / p
+    vid = str(fid).split(".", 1)[0] if "." in str(fid) else ""
+    if vid:
+        return HERE.parent / "verticals" / vid / p
+    return HERE.parent / p
+
+
+def _skill_refs(line: str) -> list:
+    """提示词里的技能引用：`skills/<名>` 或 `~/.dsh/skills/<名>`。"""
+    out = []
+    for marker in ("skills/",):
+        idx = 0
+        while True:
+            i = line.find(marker, idx)
+            if i < 0:
+                break
+            j = i + len(marker)
+            k = j
+            while k < len(line) and (line[k].isalnum() or line[k] in "-_"):
+                k += 1
+            name = line[j:k].strip("/-_ ")
+            if name and (SKILLS / name).is_dir():
+                out.append(name)
+            idx = max(k, i + 1)
+    return out
+
+
+def _adapter_files(name: str) -> list:
+    """从适配器契约里读它与它引用的脚本/模板（**不复制契约的实现**，只读声明）。"""
+    code = (
+        "import sys, json, pathlib\n"
+        f"sys.path.insert(0, {str(HERE)!r})\n"
+        "import integration_contract as C\n"
+        f"m = C.load({name!r})\n"
+        "out = list((m.RUNNERS or {}).values()) + ([m.TEMPLATE] if m.TEMPLATE else [])\n"
+        "print(json.dumps(out))\n"
+    )
+    try:
+        # `PYTHONDONTWRITEBYTECODE=1`（2026-10-11 补）：探针子进程会 `import integration_contract`
+        # ⇒ 默认会在 `scripts/` 下种 `__pycache__/*.pyc` —— 而本模块的 `--check-stamp` 与
+        # `--describe` 都对外声称"只读"。「只读子命令往仓库里写字节」正是要防的那类隐性副作用，
+        # 故在这里掐掉（判据见回归 ⑦ 的字节级断言）。
+        r = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True, timeout=30,
+                           env=dict(os.environ, PYTHONDONTWRITEBYTECODE="1"))
+        names = json.loads(r.stdout or "[]")
+    except Exception:  # noqa: BLE001
+        return []
+    out = []
+    for n in names:
+        if not n:
+            continue
+        p = HERE / str(n)
+        if p.exists():
+            out.append(_rel(p))
+        else:
+            out.append(f"scripts/{n}")   # 交给 missing 报错，不静默吞
+    return out
+
+
+def _sha(p: pathlib.Path) -> str:
+    return hashlib.sha256(p.read_bytes()).hexdigest()[:16]
+
+
+def _display(p: pathlib.Path) -> str:
+    """打印用路径：能相对仓库就相对，否则原样（`ARGENT_PACK_LOCK` 允许把锁指到仓库外 —— 夹具就这么用）。"""
+    try:
+        return str(pathlib.Path(p).relative_to(REPO))
+    except ValueError:
+        return str(p)
+
+
+def read_lock() -> dict:
+    """读版本锁。**文件映射的键一律归一成 POSIX 形态**后再比对（见 `_posix_map()`）。
+
+    Windows 上盖过章的锁（旧版本 `_rel()` 给的是反斜杠）若原样与正斜杠清单比 ⇒ 每个文件都"不符"
+    ⇒ `--validate` 恒红、`--stamp` 拒绝盖章（自锁死）。归一是让比对**真正发生**的那一步：
+    反斜杠与正斜杠指向同一文件 ⇒ 必须同判，而不是"绕过"或"全判不符"。
+    """
+    if not LOCK.exists():
+        return {}
+    try:
+        doc = json.loads(LOCK.read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001
+        return {}
+    caps = doc.get("capabilities") if isinstance(doc, dict) else None
+    if isinstance(caps, dict):
+        for entry in caps.values():
+            if isinstance(entry, dict) and isinstance(entry.get("files"), dict):
+                entry["files"] = _posix_map(entry["files"])
+    return doc
+
+
+def downgrade_check(doc: dict | None = None) -> list:
+    """只列**降版**项（锁里的旧版本 → 当前注册表的版本），供 `--allow-downgrade` 时显著告警。
+
+    2026-10-11 补（实测缺陷）：两批并发时，某批在自己的**旧文件**上继续改 ⇒ diff 一度把三个包
+    **降版**（发现后以 `git show HEAD:<file>` 重建）。`--stamp` 此前对"版本不等"一律放行
+    ⇒ 降版与提版走同一条路、全程无红灯。现在降版默认判红；确实要刻意回滚须显式
+    `--allow-downgrade`，那时**放行但把这一项显著打出来**（回滚是有意行为，不是静默事故）。
+    """
+    d = doc or load()
+    lock = (read_lock() or {}).get("capabilities") or {}
+    out = []
+    for cap in sorted(k for k in (d.get("capabilities") or {}) if not k.startswith("_")):
+        try:
+            m = manifest(cap, d)
+        except KeyError:
+            continue
+        lk = lock.get(cap)
+        if not lk:
+            continue
+        old_v, new_v = str(lk.get("version") or ""), str(m["version"] or "")
+        if is_downgrade(new_v, old_v):
+            out.append(f"能力 {cap} **降版**：锁里 {old_v} → 当前注册表 {new_v}")
+    return out
+
+
+def stamp_check(doc: dict | None = None, allow_downgrade: bool = False) -> list:
+    """盖章前的**纪律检查**：内容变了但版本没动 ⇒ 报问题（2026-09-21 补；2026-10-11 扩两条）。
+
+    ## ① 「内容变了但版本没动」（2026-09-21）
+    子代理指出并实测过 —— C4 改了共用引擎（engine 18 → 20 项）却只 `--stamp` 没提版本，
+    "内容变了必须提版本"这条纪律被绕过（锁里记录了新 sha，版本号却原地不动 ⇒ 客户机无法靠版本号
+    判断"这台机器跑的代码变没变"）。
+
+    ## ② 「降版」（2026-10-11 实测）
+    旧实现只判"版本**相等**与否" ⇒ 不等即当成合规提版放行 ⇒ **降版与提版同路**。并发批在自己的
+    旧文件上继续改就会把包降版而**没有红灯**。现在降版默认判红并点名；`allow_downgrade=True`
+    （CLI `--allow-downgrade`）时放行，由调用方把 `downgrade_check()` 的结果**显著告警**。
+
+    ## ③ 「摘要变了但版本没动」（2026-10-11 实测，本函数此前**看不见**的那一层）
+    今天的实例：`scripts/flow-requirements.json` 变了（新增 `failureClasses.capacityFull`），
+    `hr` 包字节随之改变 —— **每个包的 tgz 都带一份注册表投影** —— 但没人提 `hr` 版本。
+    旧实现只比 `files`（各能力**自身**的源文件 sha）⇒ `hr` 的 6 个 preset 一个没变 ⇒ **放行**，
+    直到发布期才被 `release-argent.sh --check-dl` 报
+    「✗ hr: 版本相同（0.1.51）但内容摘要不同」。现在锁里给每个能力记 `digest`
+    （= `pack_digest()`，与 `--emit-server-manifest#sha256` / `--digest-tgz` **逐字同口径**）：
+    摘要不同 ∧ 版本未变 ⇒ 判红（**摘要相同 ⇒ 不变**，幂等）。
+    旧锁没有 `digest` 字段 ⇒ **不报错**（首次 `--stamp` 补上，向后兼容）。
+    """
+    d = doc or load()
+    lock = (read_lock() or {}).get("capabilities") or {}
+    problems = []
+    for cap in sorted(k for k in (d.get("capabilities") or {}) if not k.startswith("_")):
+        try:
+            m = manifest(cap, d)
+        except KeyError:
+            continue
+        lk = lock.get(cap)
+        if not lk:
+            continue                       # 新能力：首次盖章，无所谓
+        old_v, new_v = str(lk.get("version") or ""), str(m["version"] or "")
+        if is_downgrade(new_v, old_v):
+            if not allow_downgrade:
+                problems.append(
+                    f"能力 {cap} **降版**：锁里 {old_v} → 现在 {new_v}"
+                    f"（疑似用旧文件覆盖了别人的提版；请先 `git log -- <file>` / "
+                    f"`git show HEAD:<file>` 以 HEAD 为基准重建，⛔ 不要在自己的旧副本上改）"
+                    f" ⇒ 确认要回滚请显式加 --allow-downgrade（会显著告警）")
+            continue                       # 版本确实动了：不再按"版本没动"重复报
+        if old_v != new_v:
+            continue                       # 提版 = 合规路径（③ 的摘要检查只在"版本未变"下成立）
+        old_files, new_files = lk.get("files") or {}, m["integrity"]
+        if old_files != new_files:
+            changed = sorted(set(new_files) ^ set(old_files)) or \
+                sorted(f for f in new_files if old_files.get(f) != new_files[f])
+            problems.append(f"能力 {cap} v{m['version']} 内容变了但版本没动"
+                            f"（{len(changed)} 个文件；例：{changed[:3]}）⇒ 请提版本后再盖章")
+        locked_digest = str(lk.get("digest") or "")
+        if locked_digest and old_files == new_files:
+            cur_digest = pack_digest(cap, d)     # 只算一次：两次算可能读到不同字节（并发批次正在改）
+            if locked_digest != cur_digest:
+                # 只有包**字节**变了（源文件表一字未动）⇒ 命中的正是"改共用注册表/引擎投影"那一类改动
+                problems.append(
+                    f"能力 {cap} v{m['version']} 的**内容摘要变了但版本没动**"
+                    f"（锁 {locked_digest[:16]}… → 现 {cur_digest[:16]}…）"
+                    f" ⇒ 内容变 ⇒ 版本必变（含无 flow 的包）；本包含注册表投影"
+                    f"（scripts/flow-requirements.json）⇒ 请提版本后再盖章")
+    return problems
+
+
+def check_stamp(doc: dict | None = None) -> list:
+    """**只读**自检（`--check-stamp`）：锁里记的**内容摘要** == 当前内容重算的摘要。
+
+    给**批次收口前**用（⛔ 不联网、⛔ 不写盘）：`--check-dl` 负责服务端那一侧，这一条在本地
+    就能回答"我这一版盖章之后，包内容有没有再被动过" —— 包括**无 flow 的包**因注册表投影变化
+    而漂移、而 `files` 表看不出来的那一层（见 `stamp_check()` ③）。
+
+    与 `stamp_check()` 的分工：那个是**盖章闸门**（回答"能不能盖"），这个是**收口体检**
+    （回答"盖过的章还准不准"）。判据同源（都走 `pack_digest()`）。
+    """
+    d = doc or load()
+    lock = (read_lock() or {}).get("capabilities") or {}
+    problems = []
+    for cap in sorted(k for k in (d.get("capabilities") or {}) if not k.startswith("_")):
+        try:
+            m = manifest(cap, d)
+        except KeyError:
+            continue
+        lk = lock.get(cap)
+        if not lk:
+            problems.append(f"能力 {cap} 没登记进版本锁 ⇒ 先跑 --stamp")
+            continue
+        locked = str(lk.get("digest") or "")
+        cur = pack_digest(cap, d)
+        if not locked:
+            problems.append(f"能力 {cap} v{m['version']} 的锁里**没有内容摘要**（旧锁的形态）"
+                            f" ⇒ 跑一次 --stamp 补上（首次补写不报错、不改版本）")
+            continue
+        if locked != cur:
+            problems.append(
+                f"能力 {cap} 的锁内摘要与当前内容不符：锁 {locked[:16]}… vs 现 {cur[:16]}…"
+                f"（锁登记 v{lk.get('version')}，当前 v{m['version']}）"
+                f" ⇒ 说明盖章之后包内容又变了 ⇒ 提版本并重跑 --stamp")
+    return problems
+
+
+def stamp(doc: dict | None = None) -> dict:
+    """把当前能力包内容（版本 + 每个文件的 sha + **整包内容摘要**）登记进锁文件。改了内容必须重盖章。
+
+    `digest`（2026-10-11 补）：与 `--emit-server-manifest#sha256` / `--digest-tgz` / 客户端
+    `packContentDigest()` **同一条口径**（都走 `pack_digest()`）⇒ 本地盖章期就能判"包字节变没变"，
+    不必等到发布期 `--check-dl`。旧锁（无该字段）首次 `--stamp` 会被补上，**不报错、不改版本**。
+    """
+    d = doc or load()
+    caps = {k: v for k, v in (d.get("capabilities") or {}).items() if not k.startswith("_")}
+    out = {"_doc": "能力包版本锁（迭代3-⑨）：由 scripts/capability_pack.py --stamp 生成。"
+                   "内容变了（sha 或 digest 变）而版本没变 ⇒ --stamp 直接拒绝（stamp_check）且 --validate 报错；"
+                   "版本**降**了同样拒绝（--allow-downgrade 才放行，且显著告警）；提了版本再盖章。"
+                   "digest = 整包内容摘要，与 --emit-server-manifest#sha256 / --digest-tgz 同口径；"
+                   "批次收口前用只读的 --check-stamp 自检。",
+           "capabilities": {}}
+    for cap in sorted(caps):
+        try:
+            m = manifest(cap, d)
+        except KeyError:
+            continue
+        out["capabilities"][cap] = {"version": m["version"], "flows": m["flows"],
+                                    "files": m["integrity"], "digest": pack_digest(cap, d)}
+    return out
+
+
+def validate(doc: dict | None = None) -> list:
+    d = doc or load()
+    caps = {k: v for k, v in (d.get("capabilities") or {}).items() if not k.startswith("_")}
+    problems = []
+    if not (d.get("pack") or {}).get("engine"):
+        problems.append("注册表缺顶层 pack.engine（共用引擎分发清单）⇒ 打出来的包跑不起来")
+    flows_no_cap = [fid for fid, f in (d.get("flows") or {}).items() if not (f or {}).get("capability")]
+    if flows_no_cap:
+        problems.append(f"这些流程没声明 capability ⇒ 无法归属任何能力包：{flows_no_cap}")
+    for cap in sorted(caps):
+        try:
+            m = manifest(cap, d)
+        except KeyError:
+            continue
+        if not m["version"]:
+            problems.append(f"能力 {cap} 缺 pack.version（能力包必须可版本化）")
+        elif not re.match(SEMVER, m["version"]):
+            problems.append(f"能力 {cap} 的 pack.version={m['version']!r} 不是语义化版本")
+        if m["missing"]:
+            problems.append(f"能力 {cap} 缺 {len(m['missing'])} 个文件：{m['missing']}")
+        # P2a（2026-10-09，P0）：带 flow 的能力必须把业务线的 `flows.json` 一起打进包 ——
+        # `flow_registry.load_vertical()` 见到 `manifest.json` 就要求同目录有 `flows.json`
+        # （缺 ⇒ `Conflict: 缺 flows.json` ⇒ `--json` exit 2）⇒ 漏带它 = **纯包装机**装完引擎读不了注册表。
+        # 这一条把该形态从"装完才发现"提前到打包前判红。
+        for vid in m.get("verticals") or []:
+            if (REPO / "verticals" / vid / "manifest.json").exists() \
+                    and not (REPO / "verticals" / vid / "flows.json").exists():
+                problems.append(f"能力 {cap} 带业务线 {vid} 的 manifest.json 却没有 verticals/{vid}/flows.json "
+                                f"⇒ 装完 flow_registry.py 必 exit 2（缺 flows.json）")
+        if not m["flows"] and not m.get("entrypoints") and not (m.get("presets") or []):
+            problems.append(f"能力 {cap} 既没有 flow、也没有 pack.entrypoints / pack.presets ⇒ 空包"
+                            f"（工作台原生能力允许无 flow，但必须声明入口：工作台入口或角色 preset）")
+        for fid in m["flows"]:
+            # P2a：提示词路径以注册表声明为准（业务线落位后在 verticals/<id>/prompts/）
+            _spec = (d.get("flows") or {}).get(fid) or {}
+            if not _prompt_paths(fid, _spec):
+                problems.append(f"能力 {cap} 的流程 {fid} 缺主提示词（注册表 trigger.promptTemplate 指向的文件不存在）")
+            role = str((d["flows"][fid] or {}).get("role") or "")
+            if role and not (PRESETS / f"argent-{role}").is_dir():
+                problems.append(f"能力 {cap} 的流程 {fid} 角色 {role} 缺 preset presets/argent-{role}")
+
+    # 版本锁：内容变了必须提版本（否则"客户机上跑的是哪一版"是假的）
+    lock = (read_lock() or {}).get("capabilities") or {}
+    for cap in sorted(caps):
+        m = manifest(cap, d)
+        lk = lock.get(cap)
+        if not lk:
+            problems.append(f"能力 {cap} 未登记进版本锁（跑 --stamp）；缺锁 ⇒ 内容改了也不会被拦")
+            continue
+        if lk.get("version") != m["version"]:
+            problems.append(f"能力 {cap} 版本不一致：注册表 {m['version']} vs 锁 {lk.get('version')}"
+                            f"（提了版本请重跑 --stamp）")
+        old, new = lk.get("files") or {}, m["integrity"]
+        changed = sorted(f for f in set(old) & set(new) if old[f] != new[f])
+        added = sorted(set(new) - set(old))
+        gone = sorted(set(old) - set(new))
+        if changed or added or gone:
+            detail = []
+            if changed:
+                detail.append(f"内容变了 {changed}")
+            if added:
+                detail.append(f"新增 {added}")
+            if gone:
+                detail.append(f"移除 {gone}")
+            problems.append(f"能力 {cap} v{m['version']} 的包内容与锁不符（{'; '.join(detail)}）"
+                            f"⇒ 要么回退改动，要么**提版本**后重跑 --stamp（版本绑死就是靠这条守住的）")
+        # 整包内容摘要（2026-10-11 补）：`files` 只看该能力**自身**的源文件，看不见**包内的注册表投影**
+        # —— 而每个包的 tgz 都带一份（含 `failureClasses`/`pack.engine`）⇒ 改了共用注册表时，无 flow 的
+        # `hr` 也会变字节，而上面那条逐文件比对**一声不响**。只在"版本没变"下设判（提版就是合规路径）；
+        # 旧锁没有 `digest` ⇒ 跳过（首次 --stamp 补上，⛔ 不因缺字段判红）。
+        locked_digest = str(lk.get("digest") or "")
+        if locked_digest and lk.get("version") == m["version"]:
+            cur_digest = pack_digest(cap, d)     # 只算一次（同上：避免两次读之间被并发批次改动）
+            if locked_digest != cur_digest:
+                problems.append(f"能力 {cap} v{m['version']} 的**内容摘要**与锁不符"
+                                f"（锁 {locked_digest[:16]}… vs 现 {cur_digest[:16]}…）"
+                                f"⇒ 内容变 ⇒ 版本必变（含无 flow 的包）；本包含注册表投影"
+                                f"（scripts/flow-requirements.json）⇒ 提版本后重跑 --stamp")
+    return problems
+
+
+def pack_tarball(cap: str, pack_dir: pathlib.Path, doc: dict | None = None) -> pathlib.Path:
+    """把装配目录打成 `<cap>-<version>.tgz`（文件名与服务端清单的 url 约定一致）。
+
+    确定性：按相对路径排序写入、成员 mtime 固定为 0、uid/gid 归零，**且 gzip 容器头不给 mtime**
+    ⇒ **同样内容出同样字节**，这样"发布出去的包"与"本地校验的包"可以逐字节对上（sha256 才有意义）。
+    ⚠️ 2026-10-09 补：容器头的 mtime 此前漏了（`w:gz` 默认填**当前时间**）⇒ 同内容两次打包出**不同字节**
+    （实测 hr 0.1.41 两次 `--publish-packs`：tgz sha256 `0c0193f3…` vs `39ead5d2…`，而内容摘要
+    `09e1fef9…` 两次相同）—— 「同样内容出同样字节」当时是假的。⛔ 该字段不进 `PACK.json`，
+    **内容摘要（清单 sha256，客户端真正校验的那个）不受影响**。
+    """
+    d = doc or load()
+    ver = str(manifest(cap, d)["version"])
+    tgz = pack_dir.parent / f"{cap}-{ver}.tgz"
+    if tgz.exists():
+        tgz.unlink()
+    # ⚠️ gzip 头里有一个 **mtime 字段**：`tarfile.open(..., "w:gz")` 会把它填成**当前时间**
+    # ⇒ 同一份内容两次打包得到**不同字节**（2026-10-09 实测：hr 0.1.41 两次 `--publish-packs`
+    # 打出 `0c0193f3…` 与 `39ead5d2…` 两个 tgz sha256，而**内容摘要** `09e1fef9…` 两次相同）。
+    # 后果：同一个 URL 下的**字节**会变（内容没变），"发布出去的包"与"本地校验的包"无法逐字节对上，
+    # 本函数头声称的「同样内容出同样字节」是假的。这里显式给 `mtime=0`，把它变成真的。
+    # ⛔ 只影响容器头：包内成员 mtime 早已固定为 0，**内容摘要（清单 sha256）不受影响**。
+    # ⛔ 别写成 `tarfile.open(..., "w:gz", fileobj=GzipFile(...))`：那会**再套一层 gzip**
+    #    （`w:gz` 自己就会包 GzipFile）⇒ 产出不是合法 gzip，`--digest-tgz` 当场报 invalid header（实测）。
+    #    正确形态 = 外层自己建 GzipFile、tarfile 用**不压缩**的 `"w"` 写进去。
+    with gzip.GzipFile(str(tgz), "wb", mtime=0) as gz:
+        with tarfile.open(fileobj=gz, mode="w") as tf:
+            # 成员名走 `_posix()`：tgz 的 arcname 是**包内路径**，Windows 上 `str(relative_to(...))`
+            # 会给反斜杠 ⇒ 包在 Linux/macOS 上解出来是一个「名字里带反斜杠的单文件」（实测类缺陷同 ⑧）。
+            for rel in sorted(_posix(p.relative_to(pack_dir)) for p in pack_dir.rglob("*")):
+                if rel.endswith(".pyc") or "__pycache__" in rel or rel.endswith(".DS_Store"):
+                    continue
+                src = pack_dir / rel
+                info = tf.gettarinfo(str(src), arcname=rel)
+                info.mtime = 0
+                info.uid = info.gid = 0
+                info.uname = info.gname = ""
+                if src.is_dir():
+                    tf.addfile(info)
+                else:
+                    with open(src, "rb") as fh:
+                        tf.addfile(info, fh)
+    return tgz
+
+
+def build(cap: str, out_dir: pathlib.Path, doc: dict | None = None, force: bool = False) -> dict:
+    d = doc or load()
+    m = manifest(cap, d)
+    if m["missing"]:
+        raise RuntimeError(f"能力 {cap} 缺文件，拒绝装配：{m['missing']}")
+    out_dir = out_dir.resolve()
+    if out_dir == REPO or REPO in out_dir.parents:
+        raise RuntimeError(f"拒绝把包装配进仓库（{out_dir}）——包是分发产物，不是源码")
+    if out_dir.exists():
+        if not force:
+            raise RuntimeError(f"目标已存在：{out_dir}（要覆盖加 --force）")
+        shutil.rmtree(out_dir)
+    out_dir.mkdir(parents=True)
+
+    for rel in m["files"]:
+        src, dst = REPO / rel, out_dir / rel
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        if src.is_dir():
+            shutil.copytree(src, dst, dirs_exist_ok=True,
+                            ignore=shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store"))
+        else:
+            shutil.copy2(src, dst)
+
+    # 过滤注册表：只留本能力（+ 它引用的流程与共同声明），装到客户机上不会"顺手带上别家能力"
+    sub = packed_registry(cap, d, m)
+    (out_dir / "scripts").mkdir(parents=True, exist_ok=True)
+    reg_text = json.dumps(sub, ensure_ascii=False, indent=2) + "\n"
+    (out_dir / "scripts" / "flow-requirements.json").write_text(reg_text, encoding="utf-8")
+    (out_dir / "PACK.json").write_text(json.dumps({
+        "capability": cap, "version": m["version"], "minPlan": m["minPlan"],
+        "flows": m["flows"], "entrypoints": m.get("entrypoints") or [],
+        "roles": m["roles"],
+          # 2026-09-22 修：生成出来的 `scripts/flow-requirements.json`（过滤后的注册表）**也必须进 sha 清单** ——
+          # 它决定客户机按什么口径跑（候选判据/闸门/计费/租约），此前不在清单里 ⇒ 被改过也没人发现。
+          "files": {**m["integrity"], "scripts/flow-requirements.json":
+                    hashlib.sha256(reg_text.encode("utf-8")).hexdigest()[:16]},
+        "sourceRegistry": "scripts/flow-requirements.json",
+    }, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+
+    # 装配后自检：在**产物目录里**真跑（不是回头跑源仓库）。P2a（2026-10-09）起**必须走合并路径**
+    # （`ARGENT_REGISTRY_ROOT=<产物>`），不再用 `--registry` 的 legacy 单文件模式 —— 因为 flow 声明
+    # 不在投影里，而在随包带上的 `verticals/<id>/flows.json`。这一条同时就是**「装完即加载注册表」**
+    # 的装配期判据：产物自己必须是一棵能加载的注册表根（`flow_registry.py --json` exit 0 + 本能力
+    # 的流程一条不少）。⛔ 别退回去用 `--registry <投影>`：那正是 2026-10-09 P0 的形态。
+    checks = []
+    reg_env = {"ARGENT_REGISTRY_ROOT": str(out_dir), "ARGENT_REGISTRY_MODE": "merged"}
+    if m["flows"]:
+        probe = _registry_probe(out_dir, reg_env)
+        checks.append(probe["check"])
+        if probe["code"] == 0:
+            missing = [f for f in m["flows"] if f not in probe["flows"]]
+            if missing:
+                checks.append({"cmd": "flow_registry.py --json（本能力的流程都在？）", "code": 1,
+                               "out": f"合并后共 {len(probe['flows'])} 条 flow",
+                               "err": f"缺本能力的流程 {missing} —— 投影不含 flow，必须由 "
+                                      f"verticals/<id>/flows.json 提供（包有没有带上它？）"})
+    for fid in m["flows"]:
+        checks.append(_run([sys.executable, str(out_dir / "scripts" / "flow_config.py"),
+                            "--flow", fid, "--lax"], cwd=out_dir, env_over=reg_env))
+    if m["integrity"] and any(r.startswith("scripts/integrations/") for r in m["files"]):
+        checks.append(_run([sys.executable, str(out_dir / "scripts" / "integration_contract.py"), "--validate"],
+                           cwd=out_dir))
+    bad = [c for c in checks if c["code"] != 0]
+    return {"manifest": m, "outDir": str(out_dir), "checks": checks, "ok": not bad,
+            "registryFlows": list(m["flows"])}
+
+
+def _registry_probe(out_dir: pathlib.Path, env_over: dict) -> dict:
+    """在产物目录里跑 `flow_registry.py --json` ⇒ `{code, flows, check}`（装配期"装完即加载注册表"判据）。"""
+    argv = [sys.executable, str(out_dir / "scripts" / "flow_registry.py"), "--json"]
+    env = dict(os.environ, PYTHONDONTWRITEBYTECODE="1", **env_over)
+    check = {"cmd": "flow_registry.py --json", "code": 2, "out": "", "err": ""}
+    try:
+        r = subprocess.run(argv, capture_output=True, text=True, cwd=str(out_dir), timeout=120, env=env)
+    except Exception as exc:  # noqa: BLE001 —— 起不来也算自检失败（不静默跳过）
+        check["err"] = f"跑不起来：{exc}"
+        return {"code": 2, "flows": [], "check": check}
+    if r.returncode != 0:
+        check.update(code=r.returncode, out=(r.stdout or "")[-300:], err=(r.stderr or "")[-300:])
+        return {"code": r.returncode, "flows": [], "check": check}
+    try:
+        flows = sorted((json.loads(r.stdout or "{}").get("flows") or {}).keys())
+    except Exception as exc:  # noqa: BLE001
+        check["err"] = f"输出不是 JSON：{exc}"
+        return {"code": 2, "flows": [], "check": check}
+    check.update(code=0, out=f"flow {len(flows)} 条：{', '.join(flows)}")
+    return {"code": 0, "flows": flows, "check": check}
+
+
+def _run(argv: list, cwd: pathlib.Path, env_over: dict | None = None) -> dict:
+    import os
+    env = dict(os.environ, PYTHONDONTWRITEBYTECODE="1")   # 自检别在产物里种 __pycache__
+    env.update(env_over or {})
+    r = subprocess.run(argv, capture_output=True, text=True, cwd=str(cwd), timeout=120, env=env)
+    base = pathlib.Path(argv[1]).name if len(argv) > 1 else ""
+    args = [str(a) for a in argv[2:]]
+    # 命令回显保留脚本名（只报最后几个参数会看不出跑的是谁）
+    return {"cmd": " ".join([base] + args[:3] + (["…"] if len(args) > 3 else [])),
+            "code": r.returncode,
+            "out": (r.stdout or "")[-600:], "err": (r.stderr or "")[-600:]}
+
+
+def main(argv=None) -> int:
+    use_utf8_stdio()   # 唯一出口编码判据：见 scripts/lib/stdio_utf8.py 的事故说明
+    ap = argparse.ArgumentParser(description="能力包版本化（清单 / 校验 / 装配自检）")
+    ap.add_argument("--list", action="store_true")
+    ap.add_argument("--describe")
+    ap.add_argument("--validate", action="store_true")
+    ap.add_argument("--stamp", action="store_true")
+    ap.add_argument("--allow-downgrade", action="store_true",
+                    help="--stamp：放行**降版**（刻意回滚用）。默认降版判红；放行时仍会显著告警")
+    ap.add_argument("--check-stamp", action="store_true",
+                    help="**只读**自检：锁里记的内容摘要 == 当前内容重算摘要（批次收口前跑；"
+                         "⛔ 不联网、⛔ 不写盘；服务端那一侧仍由 release-argent.sh --check-dl 负责）")
+    ap.add_argument("--build")
+    ap.add_argument("--out-dir")
+    ap.add_argument("--force", action="store_true")
+    ap.add_argument("--tar", action="store_true",
+                    help="--build 时额外产出 <cap>-<version>.tgz（确定性打包；服务端清单的 url 指向它）")
+    ap.add_argument("--emit-server-manifest", action="store_true",
+                    help="打印 whyshu-svr 消费的能力清单（能力→minPlan/版本/整包 sha256/下载地址）。"
+                         "默认 **merge**：给了 --out/--merge-from 且文件已存在时，注册表不认识的条目原样保留")
+    ap.add_argument("--dl-base", help="包下载根（默认 $ARGENT_PACK_DL_BASE 或 https://whyshu.com/dl）")
+    ap.add_argument("--out", help="--emit-server-manifest 的输出文件（省略则打到 stdout）")
+    ap.add_argument("--merge-from", help="--emit-server-manifest 的合并来源清单（默认 = --out）")
+    ap.add_argument("--prune", action="store_true",
+                    help="--emit-server-manifest：**显式**删除合并来源里注册表不认识的条目（默认保留；会把将删项打印出来）")
+    ap.add_argument("--dry-run", action="store_true",
+                    help="--emit-server-manifest：只打印清单 diff，**不写文件**（仍建议发布前跑一次复核）")
+    ap.add_argument("--json", action="store_true")
+    ap.add_argument("--digest-tgz",
+                    help="算一个**已下载的**能力包 tgz 的整包内容摘要（与客户端 packContentDigest 同口径；"
+                         "发布体检用：HTTP 取回的包 vs 清单 sha256）")
+    a = ap.parse_args(argv)
+    if a.digest_tgz:
+        # ⛔ 放在 `load()` **之前**：这一步只读一个 tgz，不该被"注册表读不出来"牵连
+        #    （发布体检可能在别的工作目录/裁剪树上跑）。
+        try:
+            info = digest_tarball(a.digest_tgz)
+        except Exception as exc:  # noqa: BLE001
+            print(f"  ❌ 摘要计算失败：{exc}", file=sys.stderr)
+            return 2
+        if a.json:
+            print(json.dumps(info, ensure_ascii=False, indent=2))
+        else:
+            print(info["sha256"])
+            if info["orderingDivergence"]:
+                print(f"  ⚠️ 路径排序口径分歧：按元组排序 = {info['sha256TupleOrder']}"
+                      f"（与客户端口径不同 ⇒ 这类路径名会让清单摘要与实际装机比对永远对不上）", file=sys.stderr)
+        return 0
+    if a.dry_run and not a.emit_server_manifest:
+        print("--dry-run 目前只用于 --emit-server-manifest（打印清单 diff、不写文件）", file=sys.stderr)
+        return 2
+    try:
+        doc = load()
+    except Exception as exc:  # noqa: BLE001
+        print(f"❌ 读取注册表失败：{exc}", file=sys.stderr)
+        return 2
+
+    if a.stamp:
+        # `--allow-downgrade` 只关掉**降版**这一条闸门（明知故犯的回滚），⛔ 不顺带关掉"内容变但版本没动"。
+        gate = [] if a.force else stamp_check(doc, allow_downgrade=a.allow_downgrade)
+        if gate:
+            print("  ❌ 拒绝盖章（版本纪律）：", file=sys.stderr)
+            for g in gate:
+                print(f"     {g}", file=sys.stderr)
+            print("     ⇒ 先改 capabilities.<id>.pack.version（引擎文件改动会让**所有**能力包内容变化，"
+                  "四个包都要提），再重跑 --stamp；确实要跳过着装纪律请用 --force", file=sys.stderr)
+            return 1
+        # 降版是**有意行为**：放行了也要显著打出来（否则回滚会静默发生，与"降版事故"无从区分）
+        drops = downgrade_check(doc)
+        data = stamp(doc)
+        LOCK.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        if drops:
+            # ⛔ 走 stderr：`--stamp --json` 的 stdout 必须是**纯 JSON**（既有调用方按此解析）
+            print("  ⚠️⚠️ 已按 --allow-downgrade 放行**降版**（刻意回滚才应出现这一行）⚠️⚠️", file=sys.stderr)
+            for x in drops:
+                print(f"     ⚠️ {x}", file=sys.stderr)
+            print("     ⇒ 客户机按**版本号**判更新 ⇒ 降版后存量装机不会自动退回；"
+                  "要回滚请连同发布/投递一起规划（本命令只改锁）", file=sys.stderr)
+        if a.json:
+            print(json.dumps(data, ensure_ascii=False, indent=2))
+        else:
+            print(f"  🔖 版本锁已更新：{_display(LOCK)}"
+                  + "".join(f"\n     {c} v{v['version']}（{len(v['files'])} 文件 / 摘要 {str(v.get('digest') or '')[:16]}…）"
+                            for c, v in sorted(data["capabilities"].items())))
+        return 0
+
+    if a.check_stamp:
+        # ⛔ 只读：不写锁、不写注册表、不种 __pycache__（_adapter_files 已带 PYTHONDONTWRITEBYTECODE）
+        problems = check_stamp(doc)
+        if a.json:
+            print(json.dumps({"problems": problems}, ensure_ascii=False, indent=2))
+        elif problems:
+            print("  ❌ 盖章自检不通过（锁内摘要 ≠ 当前内容重算摘要）：\n"
+                  + "\n".join(f"     {p}" for p in problems))
+        else:
+            caps = sorted(k for k in (doc.get("capabilities") or {}) if not k.startswith("_"))
+            print(f"  ✅ 盖章自检通过：{len(caps)} 个能力的锁内摘要 == 当前内容重算摘要"
+                  f"（{'、'.join(caps)}）")
+        return 1 if problems else 0
+
+    if a.emit_server_manifest:
+        src = a.merge_from or a.out
+        existing = None
+        if src and pathlib.Path(src).exists():
+            try:
+                existing = read_manifest_file(src)
+            except ValueError as exc:
+                print(f"  ❌ 合并来源清单 {src} {exc}", file=sys.stderr)
+                print("     ⇒ 拒绝在「读不懂旧清单」的情况下写盘（那会把它独有的条目抹掉）；"
+                      "确认要整表重建请显式换一个不存在的 --out，或先修好该文件", file=sys.stderr)
+                return 2
+        sm = server_manifest(doc, a.dl_base or "", existing, a.prune)
+        known = sorted(k for k in (doc.get("capabilities") or {}) if not k.startswith("_"))
+        rep = manifest_merge_report(existing, sm, known, a.prune)
+        text = json.dumps(sm, ensure_ascii=False, indent=2) + "\n"
+        if a.dry_run:
+            print(f"  ── dry-run：清单 diff（⛔ 未写盘）──")
+            print(f"     来源：{src or '（无 —— 未给 --out/--merge-from，按全新清单计算）'}")
+            print(f"     刷新（注册表认识）：{', '.join(rep['refreshed']) or '—'}")
+            if rep["updated"]:
+                for cap, field, old, new in rep["updated"]:
+                    print(f"       ~ {cap}.{field}: {json.dumps(old, ensure_ascii=False)} → "
+                          f"{json.dumps(new, ensure_ascii=False)}")
+            else:
+                print("       ~ （无字段值变化）")
+            print(f"     ➕ 新增：{', '.join(rep['added']) or '—'}")
+            print(f"     ➖ 删除（--prune）：{', '.join(rep['removed']) or '—'}"
+                  + ("" if a.prune else "（未加 --prune ⇒ 不认识的条目一律保留）"))
+            print(f"     🛡 保留（注册表不认识，原样未动）：{', '.join(rep['preserved']) or '—'}")
+            print("     ⇒ 复核无误后去掉 --dry-run 再跑一次才会落盘")
+            return 0
+        if a.out:
+            pathlib.Path(a.out).write_text(text, encoding="utf-8")
+            print(f"  ✅ 已写出服务端能力清单：{a.out}（{len(sm['capabilities'])} 个能力）")
+            if existing is not None:
+                print(f"     刷新 {len(rep['refreshed'])} 条：{', '.join(rep['refreshed']) or '—'}")
+                if rep["added"]:
+                    print(f"     新增：{', '.join(rep['added'])}")
+                if rep["preserved"]:
+                    print(f"     🛡 保留（注册表不认识，原样未动）：{', '.join(rep['preserved'])}")
+                if rep["removed"]:
+                    print(f"     ➖ 已按 --prune 删除：{', '.join(rep['removed'])}")
+        else:
+            print(text, end="")
+        return 0
+    if a.validate:
+        problems = validate(doc)
+        if a.json:
+            print(json.dumps({"problems": problems}, ensure_ascii=False, indent=2))
+        elif problems:
+            print("  ❌ 能力包校验不通过：\n" + "\n".join(f"     {p}" for p in problems))
+        else:
+            print("  ✅ 每个能力包都自洽（版本 / 文件 / 流程 / preset / 提示词）")
+        return 1 if problems else 0
+
+    if a.build:
+        if not a.out_dir:
+            print("--build 需要 --out-dir（包是分发产物，不落仓库）", file=sys.stderr)
+            return 2
+        try:
+            res = build(a.build, pathlib.Path(a.out_dir), doc, a.force)
+        except Exception as exc:  # noqa: BLE001
+            print(f"  ❌ 装配失败：{exc}", file=sys.stderr)
+            return 1
+        tgz = None
+        if a.tar:
+            try:
+                tgz = pack_tarball(a.build, pathlib.Path(res["outDir"]), doc)
+                res["tarball"] = str(tgz)
+                res["tarballSha256"] = hashlib.sha256(tgz.read_bytes()).hexdigest()
+            except Exception as exc:                             # noqa: BLE001
+                print(f"  ❌ 打包失败：{exc}", file=sys.stderr)
+                return 1
+        if a.json:
+            print(json.dumps(res, ensure_ascii=False, indent=2))
+        else:
+            m = res["manifest"]
+            print(f"  📦 {a.build} v{m['version']} → {res['outDir']}"
+                  f"（{m['unitCount']} 文件 / {m['dirCount']} 目录；流程 {', '.join(m['flows'])}）")
+            if tgz:
+                print(f"     🗜 {tgz.name}（sha256 {res['tarballSha256'][:16]}…）")
+            for c in res["checks"]:
+                print(f"     {'✅' if c['code'] == 0 else '❌'} 装配后自检 {c['cmd']}"
+                      + ("" if c["code"] == 0 else f" → exit {c['code']}：{(c['err'] or c['out']).strip()[:200]}"))
+        return 0 if res["ok"] else 1
+
+    if a.describe:
+        try:
+            m = manifest(a.describe, doc)
+        except KeyError:
+            print(f"❌ 没有这个能力：{a.describe}", file=sys.stderr)
+            return 1
+        if a.json:
+            print(json.dumps(m, ensure_ascii=False, indent=2))
+        else:
+            print(f"  {m['capability']} v{m['version']}（档位 {m['minPlan']}）")
+            print(f"   流程：{', '.join(m['flows']) or '（无 —— 工作台原生能力）'}")
+            if m.get("entrypoints"):
+                print(f"   入口：{', '.join(m['entrypoints'])}")
+            print(f"   角色/preset：{', '.join(m['roles'])}")
+            for f in m["files"]:
+                kind = "目录" if (REPO / f).is_dir() else "文件"
+                print(f"     [{kind}] {f}")
+            if m["missing"]:
+                print(f"   ❌ 缺：{m['missing']}")
+        return 0
+
+    caps = {k: v for k, v in (doc.get("capabilities") or {}).items() if not k.startswith("_")}
+    rows = []
+    for cap in sorted(caps):
+        m = manifest(cap, doc)
+        rows.append({"capability": cap, "version": m["version"], "minPlan": m["minPlan"],
+                     "flows": m["flows"], "entrypoints": m.get("entrypoints") or [],
+                     "files": m["unitCount"] + m["dirCount"],
+                     "missing": len(m["missing"])})
+    if a.json or a.list:
+        if a.json:
+            print(json.dumps(rows, ensure_ascii=False, indent=2))
+        else:
+            for r in rows:
+                what = f"流程={len(r['flows'])}" if r["flows"] else \
+                    f"入口={len(r.get('entrypoints') or [])}"
+                print(f"  {r['capability']:18} v{r['version']:10} 档位={r['minPlan']:11}"
+                      f" {what} 条目={r['files']}"
+                      + (f"  缺 {r['missing']} 个文件" if r["missing"] else ""))
+        return 0
+    ap.print_help()
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())