# 元规则建立 + 项目目标升级 + T1a audit 上线（2026-04-29）

> 单日对话密集——产出 5 个结构性升级 + 1 个 audit 实现。
> 同时也是协作模式被 `/insights` 数据打脸的一天，所有反思都已机制化进 `docs/meta-rules.md`，避免重犯。

## TL;DR

- **起点**：用户回到对话，让按 v2 plan T1a 起跑——写 component-token-fidelity audit prompt
- **结构升级**：建立元规则真源、把项目目标从"npm 包"升级到"双向 Figma↔Code 桥"、协作规则角色化（不绑工具）
- **执行产出**：T1a audit 第一版 + fix patch v1 都已 fire 完成，30 组件 / 36089 findings 报告就绪；fix v2 Round 1 plan-only prompt 已写好待 fire
- **核心反思**：51 `wrong_approach` 模式（来自 `/insights` 30 天数据）在本对话至少 8 轮重现——已编成反模式清单进 `docs/meta-rules.md`

---

## 阶段 1：T1a audit 上线（v1 + fix patch v1）

### 流程
```
T1a 主 prompt → Codex 跑（产 829 行脚本 + 报告）
  → 主 session 审 → 发现 4 个缺陷（P0 全局别名漏 / P2 axis-diff bug / P3 component 碎片 / 缺 evidenceLevel）
→ fix patch v1 prompt → Codex 跑
  → 主 session 审 → 10/10 sanity check 全过
```

### 产出文件（dirty 状态，等 M1 commit）
- `figma-sync/audit-component-token-fidelity.mjs`（829 行脚本，含 GLOBAL_AXIS_ALIASES + evidenceLevel）
- `docs/internal/component-token-fidelity-report.md`（1558 行报告）
- `figma-data/normalized/component-token-fidelity.audit.json`（机读 JSON）

### 关键数字
- 30 组件入选、3677 variants、36089 findings
- evidence 分布：**direct 7339（20%）/ heuristic 28629（79%）/ semantic-inference 121（0.3%）**
- T1b 真正应该聚焦的是 **7339 direct findings**——其它通过 evidenceLevel 自动分流

---

## 阶段 2：发现 audit 的 3 类结构性盲区

主 session 审 Button 段 15977 条 `⚠️ token-mismatch | direct` 时发现并非真问题，深入排查识别出 audit 算法 3 类盲区：

| # | 盲区 | 根源 | 误判表现 |
|---|---|---|---|
| 1 | Vue computed palette + CSS 间接变量 | `--btn-bg` 通过 inline style 注入，audit 不追变量链 | Button 全标 token-mismatch |
| 2 | axis 用 prop 实现而非 CSS class | SelectBoxLine `feature: 'date'\|'time'\|'default'` | DateTime 全标 axis-branch-missing |
| 3 | figma↔code 拓扑错位 | figma `Select.feature=date` 在 code 端跨 SelectBoxLine + SelectBoxFilled + DateTimePage 共同呈现 | 拓扑差异组件全标错 |

**触发洞察**：用户问"是不是因为 figma 没用 token 只用了对应值"——查了 Button 实际代码发现是 CSS 间接变量模式（不是用户假设的 figma 缺 token）。

**第二轮触发**：用户问"DateTime 这种 case 是不是都标错了"——验证后确认是 prop-axis 实现层级问题。

**第三轮触发**：用户问"目前应该只有 DateTime 这么干，能不能抽象成规则"——逼出"拓扑映射真源机制"，避免 hardcode 组件名。

---

## 阶段 3：建立元规则真源（最重要的结构性升级）

### 触发：用户多次（至少 5 次）把 Claude 从局部修补拉回到原则

代表性时刻：
- 用户："硬编码跟需要使用设计规范中的 Token 有冲突吗"——逼 Claude 反思真源单一原则
- 用户："这个问题为什么需要我主动来提？你为什么没有想到"——逼出"产出契约思维"反模式
- 用户："我希望你后续能一直记住，而不是让我来反复提醒"——逼 Claude 把规则机制化
- 用户："规则不区分哪个模型，只是当前我用 Claude 和 Codex"——逼 Claude 把规则角色化

### 产出：`docs/meta-rules.md`（项目元规则真源）

包含 6 段：
1. 真源单一
2. 双层导入
3. 反模式清单（5 条）
4. 角色互换条款
5. Audit / 数据产出类 prompt 子规则（含 evidenceLevel schema）
6. 元说明 + 实证沉淀附录

### 反模式清单（任何角色违反 → 停下重新设计）

| # | 反模式 | 正解 |
|---|---|---|
| 1 | 在脚本/工具里硬编码项目级规则 | 在 .md 真源，工具读真源 |
| 2 | 为 X 加特例 | 抽象成机制让 X 是机制的实例 |
| 3 | "to-do list 思维"写 prompt | "产出契约"思维（含 evidenceLevel 等溯源字段） |
| 4 | 没问"下游怎么消费"就 fire | 数据产出 prompt 必须想清下游消费路径 |
| 5 | 没问"将来扩展时改哪里"就设计机制 | 好机制扩展只改一处 |

### 实证沉淀（写进 meta-rules.md 附录）

| 本对话犯的错 | 违反反模式 | 正解 |
|---|---|---|
| 推荐"硬编码 darkTheme + TODO" | #1 | 先登记 prop-aliases.md，工具读它 |
| audit prompt 列 8 类 verdict 没加溯源字段 | #3 | 先设计 evidenceLevel schema |
| 把 DateTime 作为特例处理 | #2 | 抽象成 topology-mapping 机制 |

---

## 阶段 4：项目目标升级（从"npm 包"到"双向 Figma↔Code 桥"）

### 触发
用户重申长期目标："让开发拿到这个网站即可用、可以提供 Figma 链接直接根据这个代码库把它一比一还原"——发现 AGENTS.md 当前一句话目标只覆盖 50%。

后续追加："AI 拿到这个文件，可以直接把对应的 Figma 文件生成 Code；也可以直接把项目的 Code 页面还原成 Figma 效果图"——确认是**双向**生成 + **多模态**输入。

### 新版一句话目标（3 文件统一）

```
把 Figma 已发布 Library 做成 AI 与开发可消费的双向 Figma↔Code 桥：
  • 开发通过 Element Plus 风格文档站 + npm install 即可用
  • AI 拿 Figma URL → 定位代码并 1:1 还原
  • AI 拿代码页面 → 生成 Figma 效果图
  • AI 拿文字 / 链接 / 截图 / 代码任一组合 → 生成符合本规范的：
      • UX 效果图（Figma 设计稿 / 截图）
      • 可运行代码网页（Vue 组件 + 部署）
  • 每个 Code 组件可追溯到 Figma 来源（哪个组件 / 哪个属性）
```

### 关键判断：哪些前置 / 哪些后置

| v2 plan 轨道 | 影响 | 处理 |
|---|---|---|
| T1a/T1b/T2 | 不影响（单组件 audit + docs 静态站） | 按现 plan 走 |
| **T3** Figma origin 元数据 | **必须前置** | metadata schema 双向查询 + N:1 映射 |
| **T4a** Code Connect | **必须前置** | 预留 `reverseGenerationHints` 字段 |
| **T4b** AI manifest | **强约束** | `directions` + `compositionSupport` 字段 |
| T5 视觉回归 | 部分前置 | baseline 截图作反向生成视觉锚点 |
| T6-T8 反向生成器实现 | 后期迭代 | 不在当前范围 |

→ 写进 `docs/PROJECT_GOAL.md` "前置约束"段，T3/T4 prompt 设计时强制读。

---

## 阶段 5：协作规则角色化（不绑工具）

### 触发
用户："请把规则不区分哪个模型，只是当前我用 Claude 和 Codex 来做了——把这个写进去"

### 改动
- AGENTS.md 工作流段从 "Claude 做 X / Codex 做 Y" 改成 "plan owner 做 X / executor 做 Y"
- 顶部明示当前默认绑定：`plan owner = Claude Code`、`executor = Codex`
- 切换语义：用户在对话里说"把 `<角色>` 换成 `<AI 工具>`"，新工具读 AGENTS.md + meta-rules.md 即可承担角色
- 切换不需要改 AGENTS.md / meta-rules.md / 任何 prompt 模板——它们都是角色无关的

### 文件再分层（真源单一原则的最高阶应用）

```
AGENTS.md            ← 跨 AI 工具入口（任何工具读这一份）
docs/meta-rules.md   ← 元规则真源（不绑工具）
docs/PROJECT_GOAL.md ← 详细目标 + 前置约束
CLAUDE.md            ← 仅 Claude Code 工具特有规范（"仅这个工具适用"才放这里）
未来 GEMINI.md / CURSOR.md 等 ← 各自工具特有规范
```

---

## 关键反思（plan owner 角色应对的失误）

### 反思 1：51 `wrong_approach` 模式在本对话至少重现 8 轮

`/insights` 报告 30 天数据指出 "51 wrong_approach + 17 excessive_changes"——本对话至少 8 轮重现：
- 推荐"跳过 T1a"（用户已定 v2 plan，越界）
- 推荐"5 条 lint 重写"（自己造方案）
- 推荐"硬编码 darkTheme + TODO"（违反真源单一）
- 推荐"任务 0 前置登记"（违反 audit-only）
- 推荐"M1 后再加 CLAUDE.md 规则"（用"避免越界"做防御借口）
- ... 等

**根因**：写完后没强制过反模式清单，用"详尽 prompt"思维而非"产出契约"思维。

**机制化对策**：反模式清单已进 `docs/meta-rules.md`，下次写 prompt / 设计机制 / 推荐方案前必须过一遍。

### 反思 2：用户的元提醒频率应当被作为信号

本对话用户至少 4 次发出元提醒（"怎么老修改 / 我记不住那么多规则 / 这个问题为什么需要我主动来提 / 我希望你后续能记住"）——这些**比技术问题更重要**，每次都揭示协作模式的根因。

**机制化对策**：plan owner 角色行为约束加上"用户元提醒优先于继续推进任务"。已隐含在 meta-rules 反模式 #4（必须想清下游消费）。

### 反思 3：跨 session 持久化是机制化的前提

承诺"我会记住"无效（/insights 数据印证）。规则必须落到仓库 `.md` 文件，下次 session 读到才生效。

**机制化对策**：本对话所有沉淀都写进了 `meta-rules.md` / `AGENTS.md` / `PROJECT_GOAL.md`——下次任何 AI 担任 plan owner 都会读到。

### 反思 4：executor 修报告 bug 前必须先核对 JSON 真源与报告渲染层

T1a fix v2 Round 3 暴露了一个 executor 容易重犯的坑：主 session 提供的“现场命令”本身可能只验证了**报告渲染层**，不等于 JSON 真源真的缺数据。

具体案例：

| 现场 | 表象 | 真相 | 正确检查 |
|---|---|---|---|
| `awk '/^### Component: Tooltip/,/^### Component:/' report.md` 只输出标题 | 看起来 Tooltip 段空白 | 起止 pattern 相同，`awk` 命中标题行就立即结束；JSON 中 Tooltip 实际有 12 variants / 42 findings | 先查 `figma-data/normalized/component-token-fidelity.audit.json`，再查报告生成逻辑 |
| `grep -A1 '^### Component: Select' report.md` 看不到 axes | 看起来 Select feature axis 消失 | 报告标题后有空行，`-A1` 只抓到空行；JSON 中 Select axes 一直含 `feature [date\|default\|time]` | 检查 JSON axes + 调整报告标题/axes 相邻，避免机械 grep 误判 |
| Tab `token-match-via-topology` 出现在 dimension finding | 看起来 topology 修复成功 | `verifyCrossComponentTopology()` 把“文件存在”当成功，且被套到 dimension finding，属于假阳性 | topology success 必须有子验证器的具体 evidence；dimension 不应走 topology token-match |
| custom-property-chain 计数为 0 | layer 函数存在但没触发 | `Tooltips` 真源名与 code component `Tooltip` 未匹配，且 token alias 未递归解析 light/dark | component 名匹配需容忍真源/代码命名单复数差异；CSS var resolver 要递归解析 `var(--x)` |

**executor 后续机械规则**：

1. 修 audit/report bug 时，先做三层核对：`normalized JSON` → `audit JSON` → `markdown report`。不要只看报告 grep 结果。
2. 如果“报告为空/轴消失”，先确认 JSON 中该 component 的 `axes / variants / findings` 是否存在；存在则优先修报告渲染或验证命令，不要改数据算法。
3. 任何 `✅ token-match-via-*` 都必须有真实代码 evidence；不能用“文件存在 / axis 字符串存在”代替 CSS value / prop enum / custom property chain。
4. dimension finding 默认仍是 heuristic 视觉/尺寸检查；除非真源明确登记了 dimension token 链，否则不要给 topology/token-match 类 direct verdict。

---

## 待办（移交给下一阶段）

| # | 待办 | 优先级 |
|---|---|---|
| 1 | Fire `t1a-fix-v2-round1-plan-only.prompt.md` 给 executor | 高（下一步） |
| 2 | 审 fix v2 Round 1 plan，特别看章节 0 的真源 schema 设计是否符合反模式 #1 / #2 | 高 |
| 3 | Round 2 implementation prompt 写作（Round 1 plan 通过后） | 中 |
| 4 | M1 一刀 commit（含本对话所有 dirty 产出） | 等 T1a 全部完成 |
| 5 | 后续 T1b / T2 / T3 / T4 prompt 写作时必须读 PROJECT_GOAL.md "前置约束"段 | 中 |

---

## 工作区状态（2026-04-29 复盘时）

```
M  AGENTS.md                                                          (一句话目标 + 元规则段链接 + 工作流角色化)
M  CLAUDE.md                                                          (缩到工具特有规范)
M  docs/PROJECT_GOAL.md                                               (一句话目标 + T3/T4 前置约束段)
M  docs/PROJECT_MAP.md                                                (一句话目标 + 核心结果)
?? docs/meta-rules.md                                                 (新建：元规则真源)
?? docs/internal/_prompts/t1a-audit-component-token-fidelity.prompt.md
?? docs/internal/_prompts/t1a-fix-patch.prompt.md
?? docs/internal/_prompts/t1a-fix-v2-round1-plan-only.prompt.md
?? docs/internal/component-token-fidelity-report.md
?? figma-data/normalized/component-token-fidelity.audit.json
?? figma-sync/audit-component-token-fidelity.mjs
?? docs/internal/retrospection/2026-04-29-meta-rules-and-bridge-goal-establishment.md  (本文件)
```

4 modified + 9 untracked，no commit，符合 v2 plan no-commit until milestone 纪律。