# 设计系统「激活层」硬化 — Design Spec

> 状态：Draft（待用户复审 → writing-plans）
> 日期：2026-06-18
> 作者：Nancy Zeng × Claude Opus 4.8
> 触发背景：用户反映"一直让 AI 自查/优化设计系统，但同类返工一次比一次频繁"，并连续暴露 5 个同病根实例（组件未复用 / 流程线不合规 / PRD 漏模板 / UX 卡写错结构 / 改完图不自检）。

---

## 1. 问题与诊断

### 1.1 两层模型

这套设计系统分两层：

| 层 | 内容 | 现状 |
|---|---|---|
| **规则内容层** | 60+ 条 M-rule、PRD 6 段模板、UX 卡 6 段 schema、C4 颜色、M-INTEGRITY I1-I6… | 极丰富，基本不缺 |
| **激活层** | 决定"对的规则在对的时机被点亮"：jump 表 + 任务分类 + scoped-load + 用户措辞 | 薄弱，且未随规则数增长而加强 |

**所有近期返工的失败点 100% 在激活层，规则内容层都已存在。**

### 1.2 为什么"越加越频繁"（核心机制）

每新增一条规则，激活层就多承担一个"必须在对的时刻被对的信号点亮"的负担；但激活强度（钩子的可靠性）没变。规则数单调上升、激活强度持平 → "某条该亮没亮"的概率单调上升。**持续"加规则自查"是在加重真正的瓶颈 → 负 ROI。** 这就是"一次比一次频繁"的机制性解释。

### 1.3 激活层的具体弱点（均有实证）

- **W1 — 触发挂在"粗粒度任务分类"，不挂用户真说的关键词/制品。**
  PRD / UX 交付说明 / 同步交付物**都没有独立唤醒词**，全寄生在"被判定为完整 mockup 任务（含 Jira ID）"内。用户说"更新一下 PRD" → 不像完整任务 → 整条链静默绕过。
- **W2 — canonical 模板/结构埋在纪律规则里，非一等公民、未被路由。**
  PRD 6 段在 `design-process.md` Pre-Phase 0 Step B；UX 卡 6 段 schema 埋在 `mockup-conventions.md` §M23.11（一条 scope 纪律的"允许内容"小节，L1216-1227）。jump 表 L29 只把"起草 UX 交付卡"路由到 M23.10/M23.11（语言 + scope 纪律），**正向结构模板无关键词路由** → AI 看不到 schema → 自创 What/Menu/Navigation。
- **W3 — 没有"状态转移"触发。**
  "改完 mockup（confirmed）→ 同步 UX 卡 / 连线 / state-label + 跑 I1-I6 完整性自检" 不是独立 trigger。M-INTEGRITY 挂在「完成自检 / section.resize 后 / place 前」这些"需自我识别处于该阶段"的钩子上（jump 表 L27）；done-definition（§M-DISCIPLINE L2342）只在**任务起手**按类型预填 TodoWrite，而局部改图（US-3 增量，L2325）的预填子集**明确不含 UX 卡 / 完整性同步**。没有任何钩子挂在"刚发生一次编辑"这个动作上。
- **W4 — 跨文件路由盲区 + 路由覆盖审计不完整。**
  `audit-rule-load-map.mjs` 只校验 `mockup-conventions.md` / `code-conventions.md` **文件内** M-rule heading 是否进 jump 表；跨文件（design-process Step B）+ "每个制品是否有唤醒词" 不覆盖 → PRD 缺口能静默存在至今。
- **W5 — 自检被"目测"顶替，未跑确定性脚本。**
  即便触发了"去检查"，AI 常以"目测/看起来 OK"代替跑 `audit-mockup-integrity.mjs` 等确定性脚本 → 漏过本可被机器抓到的违例（2026-06-18 实证：提醒检查后仍漏 I3 overflow）。本质是"结果 OK ≠ 真查过"。修法：自检只认脚本机器输出，目测不构成通过（见 WS3 硬约束 + WS4 守门只认证据块）。

### 1.4 五个实证实例（全同病根）

| 实例 | 规则在哪（存在） | 激活层为何失败 |
|---|---|---|
| 消费产品未复用 DS 组件/图标 | code-conventions R1/R15 + mockup M32 | 复用只活在 trigger-skill，无 always-on（已补 consumer Rule 6，commit a640bbc9）|
| UX 流程线不合规 | M23 / M23.6 / C4 | 无 runnable verifier，全靠 AI 走查记得跑 |
| PRD 漏固定格式 | design-process Step B（6 段）| W1+W2：无唤醒词 + 未进 jump 表（已补 jump 行）|
| UX 卡写成临时结构 | schema 埋在 M23.11 | W2：结构非一等、未路由 |
| 改完图不做 section/位置/间距/重叠自检 | M-INTEGRITY I1-I6 + `audit-mockup-integrity.mjs` | W3：触发挂"阶段识别"不挂"编辑动作"，gate 手动跑 |
| 内容未完整包在 Section 内（I3 overflow）；**提醒检查后仍漏** | M-INTEGRITY §I3 + `audit-mockup-integrity.mjs` | W3 + **W5（新）：自检被"目测"顶替，未跑确定性脚本** —— 2026-06-18 实证 |

---

## 2. 设计原则

1. **修激活层，不再加内容规则**（除非补的是"缺失的一等模板"或"缺失的触发"）。
2. **触发钩子下沉到用户措辞 / 制品关键词 / 状态转移**，不再依赖 AI 对"任务分类"的模糊判断。
3. **每个 canonical 制品都必须三件齐全**：① 一等定义；② jump 表关键词路由；③ 用户唤醒词。缺一即视为激活缺口。
4. **激活层本身要被机器审计**（路由覆盖 audit），新盲区一出现即 pre-commit 报。
5. **能做成 runnable gate 的，不留在"靠自觉"**；Figma 在 repo 外 → 走"skill 强制跑 + repo 守门查证据"双保险。
6. **YAGNI**：组件"手搓伪装"检测只做启发式 warn（结构性无法确定性检测，不强求）。

---

## 3. 工作流（5 个 workstream）

### WS1 — 盲区场景补独立唤醒词 + 受维护的 cheat-sheet

**目标**：消灭 W1。给 B 区三个高频盲区各加一句话唤醒词，把激活从"AI 猜任务分类"降到"用户一句话"。

- 新增唤醒词（写进 mockup-conventions jump 表 + 对应 skill frontmatter trigger）：
  - `@TVU PRD` / "起草 PRD" / "更新 PRD" → `design-process.md` Pre-Phase 0 Step B（6 段结构）
  - `@TVU UX说明` / "写 UX 交付说明" / "更新 UX 交付说明" → M23 + M23.6 + UX 卡 schema（见 WS2）
  - `同步交付物` → 改完 mockup 后的交付物同步 checklist（PRD card / Jira 评论 / handoff，与"同步 Figma 库"区分）
- 产出 `docs/WAKE-WORDS.md`（受维护 cheat-sheet）：A) 用户唤醒词表 B) 任务内场景路由表 C) 盲区清单。内容以本 session 扒出的实证版为基线。
- cheat-sheet 被 WS5 的路由覆盖 audit 校验（每个 skill/制品都要在表里有行）。

### WS2 — 埋藏的 canonical 模板提为一等公民 + 路由

**目标**：消灭 W2。

- 把 UX 卡 6 段 schema（Why / Changes / Data Contract / Interaction / Acceptance + Section Header）从 §M23.11 的"允许内容"小节**抽成 M23 主规则下的一等 canonical 模板段**（正向结构 + 每段说明 + 示例），M23.11 改为只管 scope 纪律并 link 到该模板。
- jump 表新增/改写行：`UX 交付卡结构模板 → §M23 〈canonical 卡结构〉`（关键词：起草/更新 UX 交付卡、卡 section 模板）。
- PRD 同构项已完成（commit：PRD jump 表行）。本 WS 复用同一手法。

### WS3 — "状态转移"触发：编辑 confirmed → 自动自检 + 交付物同步

**目标**：消灭 W3。这是用户最痛的一条（每次要催）。

- 新增规则（落 §M-DISCIPLINE 或 §M-INTEGRITY 顶部）：
  > **任何 mockup 编辑动作完成并 confirmed 后，自动执行**（属 done 定义，不依赖阶段识别 / 用户提醒）：
  > (a) 跑 I1-I6 完整性自检（section 归属 / 位置 / 间距 / 重叠）；
  > (b) 同步受影响的 UX 卡 + M23.6 连线 + M23.7 state-label；
  > (c) handoff 反映同步结果。
- 触发钩子改写：把 jump 表 L27 / done-definition 的触发条件从"完成自检阶段 / 任务起手分类"**补上"编辑动作 confirmed"这一维**；US-3 增量预填子集补入 I1-I6 + UX 卡同步。
- 机器侧：把 `audit-mockup-integrity.mjs`（已覆盖 I1-I4）接入 WS4 的总闸。注意"自动"指**协议层强制**（skill wrap-up 必跑步骤 + WS4 repo 守门查证据），**不是后台监听 Figma**——Figma 在 repo 外，无法 daemon watch（见 §5/§7）。"状态转移触发"是把"编辑 confirmed"列为 AI 必须跑总闸的触发条件，由双保险兜住"忘跑"。
- **「自检」= 脚本机器输出，目测不算数（硬约束）**：I1-I6 自检**只能由 `audit-mockup-integrity.mjs` 的逐条机器输出满足**（如 `I3=overflow-count 0`），贴进 handoff。AI"目测/看起来 OK/应该没问题"一律**不构成自检通过**，repo 守门（4d）只认脚本证据块、不认自然语言断言。
  > **实证 2026-06-18**：改完后内容未完整包在 Section 内（I3 overflow），用户手动调整；**即便被提醒"去检查"，AI 仍漏过**——因为它目测而非跑 I3 脚本。这条把"提醒后的检查"也钉死成"必须跑脚本"。

### WS4 — Mockup conformance verifier 升级（流程线 + 绑定率 + 手搓组件）

**目标**：把"流程线 / token / 组件"走查从"AI 自觉"做成 gate。全部扩展现有 `audit-mockup-conformance.mjs` 总闸（live Figma + `FIGMA_PERSONAL_ACCESS_TOKEN` + `--non-blocking` 场景感知），零新框架。

- **单元 4a `audit-mockup-connector.mjs`（新，确定性 gate，blocking）**
  读 `?plugin_data=ux_annotation` 的 reconnect_map，逐 arrow 查：
  - 正交折线（M23.6 C）：parse `vectorPaths[0].data` 按 `L` 分段，任一段 `Δx>4 && Δy>4` → ❌
  - 两端锚定（M23.6 A）：`fromCanvas` 在触发元素 bbox ±8、`tipCanvas` 在 target bbox ±8（抓"卡边到卡边"）
  - 颜色 + 圆点形态（C4）：起点 ELLIPSE = 白填充 `#FFFFFF` + 蓝边 `#33A4FD`；线/箭头 VECTOR = 蓝；GROUP 内出现绿 `#33ab4f` → ❌
  - reconnect_map 缺/不全 → exit 1（"连线不可验证"，逼 AI 补——M23.6 本就强制）
- **单元 4b `audit-mockup-library-binding.mjs` 扩名集（强约束）**
  把 `checkM30NonInstanceIcon` 范式从 icon 名扩到 canonical 组件名（button/checkbox/input/radio/select/badge/tab/modal/notification/tooltip/pill…）：非 INSTANCE 但命名像组件 → 报。补 H 盲区（手搓 frame 当按钮）。
- **单元 4c `audit-mockup-binding-fidelity.mjs` 加 B-COVERAGE 档（核心，场景感知 gate）**
  复用现有 `loadScaleSets()` + node walk + `bv[prop]` bound 检测：itemSpacing/padding/容器·文字 fill·stroke **未绑任何变量/style 即报**（不管裸值是否恰好 = token）。区别现有 B-SCALE（只报 off-scale）。
  - 逃生口：节点名含 `[[raw-ok]]` 或 page sharedPluginData allowlist → 跳过。
  - 场景感知：greenfield（场景3）阻断 / 存量增量（场景2）`--non-blocking` warn（沿用总闸现有 scenario 模式）。
- **总闸接线**：`AUDITS` 数组加 connector（blocking）+ integrity（WS3，blocking）；binding-coverage 作为 binding-fidelity 的档；引入 `blocking` 字段，summary 区分 ❌FINDINGS（阻断）/ ⚠️WARN（启发式 4b·场景2）。
- **单元 4d `audit-mockup-handoff-evidence.mjs`（新）+ pre-commit（repo 守门）**
  staged `.md` 含 `Rule checklist:` 标记（= 它是 mockup handoff）→ 必须同时含 conformance summary（connector=PASS + 两端审计表 + Integrity audit 行），缺则阻断 commit。这是"AI 忘跑"的仓库层硬拦。

### WS5 — 路由覆盖 audit 升级 + trigger-drift 复盘机制

**目标**：消灭 W4 + 阻止未来长出新盲区（治本 meta-process）。

- **`audit-rule-load-map.mjs` 升级为"路由覆盖 audit"**：
  - 跨文件：纳入 `design-process.md` 的 Step 制品 + 其它被 jump 表引用的外部段。
  - 断言每个 canonical 制品/模板三件齐全：① 一等定义存在；② jump 表有关键词路由行；③ `WAKE-WORDS.md` 有唤醒词行。缺任一 → 报。
  - 挂 pre-commit（沿用现有 rule-load-map gate 位）。
- **trigger-drift 复盘机制**（轻量协议，落 AGENTS.md 或新 skill）：
  每次返工/用户矫正后固定追问一句"**哪个触发没点亮？**" → 产出**只修激活层**的 fix（加唤醒词 / 加路由 / 加状态触发），**禁止以"加内容规则"收尾**。这是阻断"越加越频繁"的闭环。

---

## 4. 数据流与集成点

- **唯一总闸**：`pnpm audit:mockup-conformance --file <key>`（已存在）→ 编排 integrity（WS3）+ connector（4a）+ library-binding 扩展（4b）+ binding-fidelity/B-COVERAGE（4c）+ 原有子审计。
- **live Figma 读取**：REST + `FIGMA_PERSONAL_ACCESS_TOKEN`；connector 额外用 `?plugin_data=ux_annotation` 读 reconnect_map。
- **repo 守门**（4d）：pre-commit 扫 staged `.md` 的 `Rule checklist:` 证据块。
- **路由覆盖**（WS5）：pre-commit 扫 jump 表 + WAKE-WORDS.md + 跨文件制品定义。
- **skill 协议**：`tvu-design-mockup` wrap-up 增"必跑总闸 + handoff 贴 summary/审计表"；新唤醒词写入相关 skill frontmatter trigger。

---

## 5. 错误处理

- 无 `FIGMA_PERSONAL_ACCESS_TOKEN` → 子审计 exit 2（ERROR，could not run），与现有兄弟脚本一致。
- reconnect_map 缺/不全 → connector exit 1（FINDINGS，"连线不可验证"）。
- Figma API 错 → exit 2。
- binding-coverage 误报 → 逃生口（`[[raw-ok]]` / allowlist）；存量场景 `--non-blocking`。

## 6. 测试

全部用 fixture JSON（mock Figma 节点树 + reconnect_map）离线测，**不打 live API**，沿用现有 `tests/*.test.ts` fixture 范式：
- connector：斜线检测 / bbox-within（两端）/ 颜色·圆点断言 / reconnect_map 缺失
- 4b：canonical 组件名 matcher（含 ignore 逃生口）
- 4c B-COVERAGE：未绑即报（on-scale 裸值也报）/ 逃生口跳过 / 已绑跳过
- 4d 守门：handoff 缺证据块 fail、含 pass
- WS5 路由覆盖：制品缺路由/缺唤醒词 fail

## 7. 范围外（YAGNI）

- 不做"手搓裸 frame 语义识别"的确定性检测（结构不可能，只做 4b 命名启发式 warn）。
- 不把 Figma 走查做成真 git pre-commit（Figma 在 repo 外，靠双保险）。
- 不重构既有 60+ M-rule 内容（只补缺失的一等模板 + 触发）。
- 本轮不扫修存量 Figma 稿（用户已明确"只约定规则"）。

## 8. 已决策项（来自 brainstorming）

- 范围：流程线 + 组件两个 verifier 都做（组件启发式 warn）。
- 自动化：双保险（skill 强制跑 + repo 守门查证据）。
- 绑定率 gate：稳健"未绑即报 + 逃生口"，场景感知阻断/warn。
- 流程线起点：白填充 `#FFFFFF` + 蓝边 `#33A4FD` 圆点（已落 M23.6/C4，commit d7db0173）。
- M23.6：两端锚定（已落，commit 6b52403f）。
- PRD jump 表行：已落。

## 9. 实施顺序建议（交 writing-plans 细化）

1. **止血优先**：WS1 唤醒词 + WS2 UX 卡 schema 提级 + WS3 状态转移规则（纯 doc，低风险，立即减少返工）。
2. **gate 落地**：WS4 三个 verifier + 总闸接线 + 守门（代码 + 测试）。
3. **治本**：WS5 路由覆盖 audit 升级 + trigger-drift 机制。