# 激活层硬化 Phase 1（止血）Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** 消灭激活层弱点 W1/W2/W3——给盲区场景加唤醒词、把埋藏的 UX 卡 schema 提为一等模板、把"改完图自动自检+同步"做成 done 硬约束——全部纯文档/协议改动，立刻减少返工。

**Architecture:** 改 3 份真源（`mockup-conventions.md` jump 表与 M23 段、`design-process.md` 已部分完成、`tvu-design-mockup` SKILL）+ 新建 1 份受维护 cheat-sheet（`docs/WAKE-WORDS.md`）。无代码、无新依赖。验证靠 grep 存在性 + 现有 `pnpm audit:rule-load-map` 不回归。

**Tech Stack:** Markdown 文档；现有 Node 审计脚本 `scripts/audit-rule-load-map.mjs`；pnpm。

## Global Constraints

- 真源唯一：mockup 业务规则改 `docs/internal/mockup-conventions.md`；流程规则改 `docs/internal/design-process.md`；skill 只做 trigger + 指路，不写规则正文（AGENTS.md）。
- 颜色/结构等已落规则不得回改：流程线起点白填充 `#FFFFFF` + 蓝边 `#33A4FD`（commit d7db0173）、M23.6 两端锚定（6b52403f）、PRD jump 行（已落）。
- Commit 默认含 push 到 origin（本项目约定）；commit message 英文，结尾 `Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>`。
- 文档双语：UX 交付相关结构段落保留中英（M23 既有惯例）。
- 改 `.md` 规则后若改动起手协议，需同步对应 skill 的 trigger 段（AGENTS.md §规则改动权）。
- 每次提交前 pre-commit 会自动跑 vitest + `audit-rule-load-map`，必须全绿。

---

### Task 1: 新建受维护 cheat-sheet `docs/WAKE-WORDS.md`

**Files:**
- Create: `docs/WAKE-WORDS.md`

**Interfaces:**
- Produces: `docs/WAKE-WORDS.md`，含三块 H2：`## A) 用户唤醒词表`、`## B) 任务内场景路由表`、`## C) 盲区清单`。Plan 3 的路由覆盖 audit 将断言此文件每个 skill/制品有行。

- [ ] **Step 1: 创建文件，写入三块内容**

写入以下内容（基于本 session 实证扒取版；表格可后续增补，但三块 H2 标题固定）：

```markdown
# TVU 项目唤醒词 / 触发词 Cheat-Sheet

> 真源：本文件 + 各 skill frontmatter + `mockup-conventions.md` jump 表。
> 维护：新增 skill / canonical 制品时必须在此登记（Plan 3 路由覆盖 audit 会校验）。
> 用途：日常查"什么场景 → 说什么 → 点亮什么"，减少漏触发返工。

## A) 用户唤醒词表（你主动说 → 触发 skill / 命令）

| 你想做 | 说这个（真实触发短语）| 点亮什么 | 来源 |
|---|---|---|---|
| 画 / 改 Figma mockup | `@TVU mockup`（或 Figma 链接 + 加/改/画/同步）| tvu-design-mockup 全套起手协议 | skills/tvu-design-mockup |
| 写消费产品代码 | `@TVU code` | code-conventions 全套 | skills/tvu-design-code |
| 走完整设计流程 | `@TVU 设计全流程` | 7 阶段编排 | skills/tvu-design-pipeline |
| 起草 / 更新 PRD | `@TVU PRD` / 起草 PRD / 更新 PRD | design-process Step B（6 段结构）| design-process.md Step B |
| 写 / 更新 UX 交付说明 | `@TVU UX说明` / 写 UX 交付说明 / 更新 UX 交付说明 | M23 + M23.6 + UX 卡 canonical schema | mockup-conventions §M23 |
| 改完 mockup 后同步交付物 | `同步交付物` | UX 卡 / 连线 / state-label + PRD card / handoff 同步 checklist | mockup-conventions §M-DISCIPLINE |
| 设计走查 | `design walkthrough` / 走查这个设计 | F1 6-section 走查 | skills/design-walkthrough |
| 改完后 QA + 自动修 | `design done` / qa loop | F1 + auto-fix + F2 + handoff gate | skills/design-qa-loop |
| 接入 TVU 设计系统 | 初始化 TVU 消费产品 / 把这个项目接入 TVU | scaffold | skills/setup-tvu-consumer |
| 同步 Figma 库 | 同步 Figma 库 | `pnpm sync:figma-library --with-extract` | AGENTS.md |
| 更新 Claude Design 文件包 | 更新 Claude Design 文件包 | `pnpm build && pnpm export:claude-design-bundle` | docs/CLAUDE_DESIGN_SETUP.md |
| consumer 收尾 | 收尾 / wrap up / 复盘 | 写复盘 + commit + push gitea | skills/consumer-product-conventions |

## B) 任务内场景路由表（AI 起手/过程中，场景 → 该读哪段）

> 这是 AI 自动路由（非用户唤醒词），真源 = `mockup-conventions.md` 顶部 jump 表（L11-50）。此处只镜像高频项，改动以 jump 表为准。

| 场景 | 该读的段 |
|---|---|
| 任务起手（所有 mockup） | §0-§5 + §M48 + §M49 + §M0 Phase 0 + §M-DISCIPLINE |
| 画 UX 交付注释 / 流程连线 | §M23 + §M23.6 + §M33 |
| 起草 / 更新 UX 交付卡（结构模板）| §M23 〈canonical UX 卡结构〉 |
| 起草 UX 卡的语言 / scope | §M23.10 + §M23.11 |
| 起草 / 更新 PRD | design-process Pre-Phase 0 Step B（6 段）|
| 改完图自检（section/位置/间距/重叠）| §M-INTEGRITY I1-I6（跑脚本，非目测）|
| 绑视觉属性 token | §M49.1 + §C5 |

## C) 盲区清单（历史漏触发高发区 → 已补/待补）

| 场景 | 状态 |
|---|---|
| 写 / 更新 PRD | ✅ 已补 jump 行 + 唤醒词 `@TVU PRD` |
| 写 / 更新 UX 交付说明 | ✅ 唤醒词 `@TVU UX说明` + canonical schema 提级（本 Plan Task 3）|
| 改完 mockup 后同步交付物 | ✅ 唤醒词 `同步交付物` + 状态转移触发（本 Plan Task 4）|
| 改完图未跑确定性自检 | ✅ 状态转移触发：自检=脚本输出（本 Plan Task 4）|
```

- [ ] **Step 2: 验证文件存在且三块齐全**

Run: `grep -c "^## [ABC])" docs/WAKE-WORDS.md`
Expected: `3`

- [ ] **Step 3: Commit**

```bash
git add docs/WAKE-WORDS.md
git commit -m "docs(wake-words): add maintained trigger cheat-sheet (WS1)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
```

---

### Task 2: UX 卡 canonical 结构模板提为一等公民（WS2）

**Files:**
- Modify: `docs/internal/mockup-conventions.md`（M23 主规则段新增 canonical 卡结构子段；§M23.11 改为 link 引用该子段）

**Interfaces:**
- Consumes: 现有 §M23.11 L1216-1227 的 6 卡枚举（Why/Changes/Data Contract/Interaction/Acceptance + Section Header）。
- Produces: 新子段标题 `#### M23 — UX 交付卡 Canonical 结构（正向模板）`，供 Task 5 的 jump 表行与 skill 指向。

- [ ] **Step 1: 在 M23 主规则段末尾（流程图 5 层结构之后、§M23.6 之前的合适位置）新增 canonical 卡结构子段**

先 Read `docs/internal/mockup-conventions.md` 定位 M23 主规则段结束处（约 L520-525，§M23.6 之前）。在该处插入：

```markdown
#### M23 — UX 交付卡 Canonical 结构（正向模板，⚠️ 起草/更新 UX 卡必照此结构，禁自创 What/Menu/Navigation 等临时段）

UX 交付卡 = 一组 **navy chip 卡**（背景 `#2B2D42`，title fill cyan `#33A4FD`），固定 ≤ 6 张、固定顺序、固定语义。**这是唯一合法卡结构**：

| # | 卡 | 内容 | 必填 |
|---|---|---|---|
| 1 | **Section Header** | `UX · [Feature] — [States/Rules]` | 必 |
| 2 | **Why** | 1-3 句驱动力：为什么做这个改动（中英）| 必 |
| 3 | **Changes** | 本期改动 list（只列本次，不堆历史/roadmap）| 必 |
| 4 | **Data Contract** | 字段 / 数据契约（来源、类型、空态、边界）| 数据相关时必 |
| 5 | **Interaction** | 交互细节（触发、状态转移、反馈）| 有交互时必 |
| 6 | **Acceptance** | 验收 checkbox（可勾选、可测）| 必 |

**硬约束**：
- 段名、顺序、语义照上表，**不得自创**（如 What / Menu / Navigation / Notes 等临时段 = 违例）。
- 语言纪律见 §M23.10（禁 regex/pseudocode，白话决策树）；scope 纪律见 §M23.11（只放本期、不堆 Persona/out-of-scope/roadmap）。**本段管结构，.10 管语言，.11 管取舍——三者配套。**
- 卡视觉 = M23 navy chip（§配色表 + §M23.6 同色系 cyan accent）。

**实证 2026-06-18**：AI 被要求"更新 UX 交付说明"时写成 What/Menu/Navigation 临时结构——根因是 6 卡 schema 此前埋在 §M23.11 scope 纪律里、无正向模板、无关键词路由。本子段即把结构提为一等公民（修 W2）。
```

- [ ] **Step 2: 改 §M23.11 的 6 卡枚举为 link 引用，避免双真源**

Read §M23.11（约 L1216-1227），把其中列举 6 卡的句子改为引用：在 "L1227 Acceptance「卡数量 ≤ 6…」" 附近补一行：

```markdown
> **卡结构正向模板见 [§M23 — UX 交付卡 Canonical 结构](#m23--ux-交付卡-canonical-结构正向模板)**；本 §M23.11 只管 scope 取舍，不再重复结构定义。
```

- [ ] **Step 3: 验证新子段存在且 jump 可锚**

Run: `grep -n "UX 交付卡 Canonical 结构" docs/internal/mockup-conventions.md`
Expected: 至少 2 行命中（新子段标题 + M23.11 的 link）

- [ ] **Step 4: 跑路由覆盖 audit 不回归**

Run: `pnpm audit:rule-load-map`
Expected: `audit-rule-load-map OK`（58+ rules 全覆盖，不报新漏）

- [ ] **Step 5: Commit**

```bash
git add docs/internal/mockup-conventions.md
git commit -m "docs(M23): hoist UX card 6-section schema to first-class canonical template (WS2)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
```

---

### Task 3: jump 表加 UX 卡结构路由行（WS2 路由侧）

**Files:**
- Modify: `docs/internal/mockup-conventions.md`（jump 表 L23-50，§M23.10/M23.11 行附近）

**Interfaces:**
- Consumes: Task 2 的新子段锚点。
- Produces: jump 表新增一行，把"起草/更新 UX 卡结构"路由到 Task 2 子段。

- [ ] **Step 1: 在 jump 表 §M23.10+M23.11 行之后插入结构路由行**

Read jump 表定位 `| §M23.10 + §M23.11 | 起草 UX 交付卡（…）时 |` 行（现 L29 附近），在其后插入：

```markdown
| §M23 〈canonical UX 卡结构〉（Why/Changes/Data Contract/Interaction/Acceptance + Section Header 正向模板）| **起草 / 更新 UX 交付卡结构**时（含"写/更新 UX 交付说明"措辞）—— 禁自创临时段 |
```

- [ ] **Step 2: 验证行已加**

Run: `grep -n "canonical UX 卡结构" docs/internal/mockup-conventions.md`
Expected: 命中 jump 表那一行

- [ ] **Step 3: 跑路由覆盖 audit**

Run: `pnpm audit:rule-load-map`
Expected: `audit-rule-load-map OK`

- [ ] **Step 4: Commit**

```bash
git add docs/internal/mockup-conventions.md
git commit -m "docs(jump-table): route 'UX card structure' keyword to M23 canonical template (WS2)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
```

---

### Task 4: 状态转移触发规则 — 编辑 confirmed → 自动自检(脚本)+ 交付物同步（WS3）

**Files:**
- Modify: `docs/internal/mockup-conventions.md`（§M-DISCIPLINE 段，约 L2303-2349）

**Interfaces:**
- Consumes: 现有 §M-INTEGRITY I1-I6 + `audit-mockup-integrity.mjs`；done-definition L2342。
- Produces: 新规则小节 `§M-DISCIPLINE.SYNC`，被 WAKE-WORDS C 区与 Plan 2 守门引用。

- [ ] **Step 1: 在 §M-DISCIPLINE 段内（done-definition L2342 附近）新增状态转移触发小节**

Read §M-DISCIPLINE 定位 done 反例段（L2342），在其后插入：

```markdown
#### M-DISCIPLINE.SYNC — 编辑 confirmed → 自动自检 + 交付物同步（状态转移触发，2026-06-18 新增，修 W3/W5）

**触发条件不是"任务起手分类"，而是"任何 mockup 编辑动作完成并 confirmed"这个动作本身。** 一旦改动 confirmed，以下属 done 定义，**无需用户提醒、不依赖 AI 自我识别处于哪个阶段**：

1. **跑 I1-I6 完整性自检** —— section 归属 / 位置 / 间距 / 重叠。
   - **「自检」= `audit-mockup-integrity.mjs` 的逐条机器输出**（如 `I3=overflow-count 0`），贴进 handoff。
   - ⚠️ **目测 / "看起来 OK" / "应该没问题" 一律不构成自检通过**（实证 2026-06-18：提醒检查后 AI 仍漏 I3 overflow，因目测代替跑脚本）。
2. **同步受影响的交付层** —— UX 卡（§M23 canonical 结构）+ M23.6 连线 + M23.7 state-label，使其反映本次改动。
3. **handoff 反映同步结果** —— Rule checklist 行 + Integrity audit 行（`I1=pass / I2=… / I3=overflow-count 0 / I4=orphan-count 0`）。

**唤醒词兜底**：用户说 `同步交付物` 时直接拉起本小节 checklist（与"同步 Figma 库"区分）。

**Acceptance**：改动 confirmed 后，handoff 能展示 (a) integrity 脚本机器输出，(b) 受影响 UX 卡/连线/state-label 已更新。缺脚本输出 = done 不成立（Plan 2 repo 守门将机器拦截）。
```

- [ ] **Step 2: 把 jump 表 §M-INTEGRITY 触发行补上"编辑 confirmed"维度**

Read jump 表 `| §M-INTEGRITY (…) | mockup 完成自检 / … 时 |`（现 L27），改为：

```markdown
| §M-INTEGRITY (§I1/§I2/§I3/§I4/§I5/§I6) | **任何编辑 confirmed 后（M-DISCIPLINE.SYNC）** / mockup 完成自检 / sibling 布局 / section 重叠 / children wrap / element parent 归属 / 替换既有节点前 diff(I5) / create·move·place 前 probe 目标位防叠加(I6) 时 |
```

- [ ] **Step 3: 验证规则与 jump 行存在**

Run: `grep -n "M-DISCIPLINE.SYNC\|编辑 confirmed 后" docs/internal/mockup-conventions.md`
Expected: ≥ 2 行命中（规则小节标题 + jump 行）

- [ ] **Step 4: 跑路由覆盖 audit**

Run: `pnpm audit:rule-load-map`
Expected: `audit-rule-load-map OK`

- [ ] **Step 5: Commit**

```bash
git add docs/internal/mockup-conventions.md
git commit -m "docs(M-DISCIPLINE): add edit-confirmed state-transition trigger; self-check = script output not eyeball (WS3/W5)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
```

---

### Task 5: tvu-design-mockup skill 协议同步（唤醒词 + wrap-up 必跑）

**Files:**
- Modify: `skills/tvu-design-mockup/SKILL.md`（frontmatter `description` trigger 段 + 正文 wrap-up 段）

**Interfaces:**
- Consumes: Task 1-4 的唤醒词与规则。
- Produces: skill 起手识别新唤醒词 + wrap-up 强制步骤。

- [ ] **Step 1: frontmatter description 补三个唤醒词**

Read `skills/tvu-design-mockup/SKILL.md` frontmatter。在其 trigger 短语列表里追加（保持原有不动）：`@TVU PRD`、`@TVU UX说明`、`同步交付物`，各注一句指向（PRD→design-process Step B；UX说明→§M23 canonical 结构；同步交付物→§M-DISCIPLINE.SYNC）。

- [ ] **Step 2: 正文 wrap-up 段加"必跑自检脚本 + 贴证据"步骤**

Read 正文 wrap-up / 收尾段，追加：

```markdown
**Wrap-up 必跑（M-DISCIPLINE.SYNC，不可跳过、不可目测代替）**：
1. `pnpm audit:mockup-conformance --file <fileKey>`（含 integrity I1-I6 + 后续 Plan 2 接入的 connector / binding-coverage）
2. 把机器输出的 `Integrity audit: I1=… / I2=… / I3=overflow-count 0 / I4=orphan-count 0` + conformance summary **贴进 handoff doc 的 `Rule checklist:` 块**
3. 同步受影响 UX 卡（§M23 canonical 结构）/ 连线 / state-label
> ⚠️ handoff 缺脚本证据块 = done 不成立（Plan 2 repo 守门机器拦截）。
```

- [ ] **Step 3: 验证 skill 已含新唤醒词与 wrap-up 步骤**

Run: `grep -n "@TVU PRD\|@TVU UX说明\|同步交付物\|audit:mockup-conformance" skills/tvu-design-mockup/SKILL.md`
Expected: 命中全部 4 个关键串

- [ ] **Step 4: Commit**

```bash
git add skills/tvu-design-mockup/SKILL.md
git commit -m "docs(mockup-skill): add PRD/UX说明/同步交付物 wake words + mandatory wrap-up audit step (WS1/WS3)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"
```

---

## Self-Review

**1. Spec coverage（对 spec §3 WS1-3）：**
- WS1 唤醒词 + cheat-sheet → Task 1（WAKE-WORDS.md）+ Task 5（skill frontmatter 唤醒词）✅
- WS2 UX 卡 schema 提级 + 路由 → Task 2（提级）+ Task 3（jump 路由）✅
- WS3 状态转移触发 + 自检=脚本（W5）→ Task 4 ✅；skill wrap-up 必跑 → Task 5 ✅
- WS4/WS5 → 不在本 Plan（Plan 2/3）✅

**2. Placeholder scan：** 无 TBD/TODO；每个 doc 插入步骤给了完整 markdown 内容；每步有可执行验证命令 + 期望输出。✅

**3. Type/锚点一致性：** Task 3/5 引用的子段标题 "UX 交付卡 Canonical 结构" 与 Task 2 创建的标题一致；"M-DISCIPLINE.SYNC" 在 Task 4 定义、Task 5 引用一致；"Integrity audit: … I3=overflow-count 0" 措辞 Task 4/5 一致。✅

**注意**：Task 2/3/4 都改同一文件 `mockup-conventions.md`，按顺序执行（行号会随插入漂移，每个 Task Step 1 都要求先 Read 重新定位，不依赖固定行号）。