---
"@ux-team/tvu-design-system": minor
---

Mockup conformance 从「10 个子进程」合并成**单进程引擎 + 10 个规则模块**，并给闸的 stdout 定了一份可机械收割的输出契约。

**对 consumer 可见的变化**

- `scripts/audit-mockup-conformance.mjs` 现在是引擎：一次取数、一次解析、共享 payload。整文件模式的 `api.figma.com` 请求数 **12 → 3**（大 payload **8 → 1**），子进程 **10 → 1**；同一个产品文件上的整文件耗时实测 **140s → 27s**。
- 新增 `--rule <id[,id]>` 只跑其中几条规则，`--list-rules` 列当前规则清单（清单真源 = 引擎自己，⛔ 别抄文档里的条数）。未知 rule id ⇒ `exit 2`，不会静默跑全量。
- 规则条数 **9 → 10**：并入 `geometry-consistency`（G1 同组件同宽 / G2 跨状态帧同名同宽 / G3 动作按钮右边缘对齐）。它此前既不在总闸清单里、也没有任何执行点。
- 引擎**逐规则自报 scope**。`--node` 只约束 8/10 条：`library-binding`（只读离线缓存 = 整文件快照）与 `connector`（live REST 但计数全文件）是**全文件口径**，⛔ 不要把 `--node` 读成「范围已缩到这个节点」。
- 每条规则都自报 `checkedUnits`（分母）。`findings: 0` 且 `checkedUnits: 0` 会被显式标成「分母是空的，这条绿不可解读」——**「闸绿」不再等于「校验结论」**。
- 新增 workflow 模板 `templates/audit-mockup-workflow.yml`：consumer CI 里跑 mockup conformance（真的读 `secrets.FIGMA_TOKEN`）。`postinstall` 提示已改为分别指向代码面与 mockup 面两份模板。

**修掉的两个既有缺陷**

- `audit:consumer-mockup` 这条别名**结构上跑不通**（三条命令串联时 `pnpm run <别名> --file K` 只把参数追加到最后一条，第一条在任何 fetch 之前就 `exit 2` 并短路 `&&`）。现改为一条命令 + `--rule integrity,colors,typography-icon`，语义不变。
- 逗号形态的 `--node "a,b"` 两条路径口径矛盾（落 report 时按逗号拆、透传给子闸时精确键查找 ⇒ not found）。现在解析只有一处：只取第一个 id 做取数范围，其余 id **显式报「未覆盖」**，不再产出一份看起来覆盖了 N 个节点的报告。

**兼容性**

- `--report` 落盘的 JSON schema **未变**（`{fileKey, nodeIds, subAudits[].exitCode, nodeFindings, timestamp, figmaLastModified, nonBlocking, ok}`），handoff gate 照旧可校验。
- 退出码语义未变：`0` 全过（或 `--non-blocking`）· `1` 至少一条有 findings 或跑不起来 · `2` 用法错。缺 `--file` 仍是 `exit 2`。
- ⚠️ **人读输出的逐条措辞变了**（散文现由引擎统一生成，不再是各子进程各自打印）。若你在解析它的**文本**，改读 `--report` 的 JSON 或 stdout 末尾那块契约 JSON。