# Codex Prompt: T1a Fix v2 — Round 2 Implementation（实施已批准的 plan）

> **本 prompt 在新 Session 中执行**——你（executor）没有之前对话的上下文。所有需要的输入都在仓库文件里，按下面"必读前置"读完。
>
> **任务性质**：纯执行——按已批准的 plan + 真源实现 audit v2。**没有任何抽象设计任务**——所有 schema / 算法接口 / verdict 类型 / 实例都已 plan owner 写完。你只做"按已定 X 实现 Y / 按已定算法写代码 / 按已定预期验证"。

---

## 必读前置（按顺序，不能跳）

新 Session 必须先把以下文件读全，否则会破坏边界：

1. **`AGENTS.md`** — 项目级 AI 协作入口（特别看"工作流"段的 executor 角色行为约束）
2. **`docs/meta-rules.md`** — 元规则真源（特别看反模式清单 + 触发器 G + 触发器 H + 实证沉淀附录）
3. **`docs/internal/_plans/t1a-fix-v2-plan.md`** — Plan v2（589 行，已批准；本 Round 2 任务全部按它实施）
4. **`src/design-system/translation/axis-implementation-map.md`** — Axis 实现层级真源（313 行，含 16 个实例 + schema + enum + audit 消费契约）
5. **`figma-sync/audit-component-token-fidelity.mjs`** — 现有 audit 脚本（v1.5，含 GLOBAL_AXIS_ALIASES + evidenceLevel；本轮基于此大改）
6. **`docs/internal/component-token-fidelity-report.md`** — v1.5 报告（1558 行，用于 sanity check 对比）
7. **`figma-data/normalized/component-token-fidelity.audit.json`** — v1.5 机读 JSON
8. **`docs/internal/_prompts/t1a-fix-v2-round1-plan-only.prompt.md`** + **`t1a-fix-v2-round1-plan-supplement.prompt.md`** — Round 1 prompt（参考上下文）

读完前不要写任何代码。

---

## 你的角色边界（meta-rules 触发器 G）

| 已定（不要改 / 不要重新设计） | 你要做（执行） |
|---|---|
| Schema 字段定义（axis-implementation-map.md §3） | 解析真源、按 schema 提取实例 |
| 实现层级 enum（axis-implementation-map.md §2） | 按 enum 5 个值 switch 调用对应 verify*() |
| Audit 消费契约（axis-implementation-map.md §5） | 按契约实现 auditAxisValue() 主算法 |
| 16 个实例（axis-implementation-map.md §4） | 解析它们作为算法输入 |
| 新 verdict 类型 + evidenceLevel 映射（plan §3） | 按映射表填 verdict / evidenceLevel / evidenceSource |
| Vue AST 解析方案（plan §4） | 实现 extractPalette / extractDefineProps / extractCssCustomProperties |
| Palette 求值算法（plan §5） | 实现 resolvePaletteVar |
| 双端 hex 比对算法（plan §6） | 实现 resolveCssVarToHex |
| audit 主算法伪代码（plan §6.5） | 翻译成可执行 JS |
| 边界 case 列表（plan §7） | 在实现里覆盖这些 case |
| sanity check 数字预期（plan §8） | 跑完对照数字 |

**严禁做的事**：

- ❌ 改 `axis-implementation-map.md` 的 §1 / §2 / §3 / §5 / §6（plan owner 真源）
- ❌ 加新 verdict 类型（plan §3 已定）
- ❌ 改 plan v2 任何内容（已批准）
- ❌ 改 src/* 任何代码（包括 .vue / .ts / .css）
- ❌ 改 figma-data/raw/* / figma-data/published/*（始终只读）
- ❌ 自创算法 / 偏离 plan §4-6.5 的接口契约
- ❌ git add / git commit / git push（v2 plan no-commit until milestone）

---

## 任务 1：实现 audit v2 核心算法

修改 `figma-sync/audit-component-token-fidelity.mjs`（保留现有 v1.5 骨架——`GLOBAL_AXIS_ALIASES` / `evidenceLevel` schema / 报告生成 / 机读 JSON 生成都保留）。

### 1.1 新增模块：解析 axis-implementation-map.md 真源

实现 `parseAxisImplementationMap()`：

- 输入：文件路径 `src/design-system/translation/axis-implementation-map.md`
- 输出：`instances[]`，每条对象含 schema 9 字段（`figmaComponent` / `figmaComponentSetIds` / `figmaAxis` / `figmaValue` / `codeImplementationLayer` / `codeFile` / `codeAnchor` / `verifyHint` / `notes`）
- 解析方式：扫每个 `### Instance N: ...` 段，按 markdown list 格式（`- **fieldName**: value`）正则提取
- 跳过 `<!-- TODO -->` 段和 schema/enum/消费契约段

**严格按真源 §3 schema 字段命名**——不要重命名字段。

### 1.2 实现 Vue AST 解析（plan §4）

按 plan §4 接口契约实现 3 个函数：

- `extractPalette(vueFilePath)` → `{ paletteName: <ObjectExpression AST>, ... }`
- `extractDefineProps(vueFilePath)` → `{ propName: { type, enum, default }, ... }`
- `extractCssCustomProperties(vueFilePath)` → `{ selector: { '--var': value, ... }, ... }`

用 `@vue/compiler-sfc` 的 `parse` + `compileScript`。先 `pnpm list @vue/compiler-sfc` 确认依赖；不在则 `pnpm install -D @vue/compiler-sfc`。

降级策略（按 plan §4 给的）：palette 不是 `computed` 而是 `ref` / `reactive` / 直接 const → 各自有降级处理；都失败时返回 null，下游标 `❌ palette-resolution-failed`。

### 1.3 实现 palette 求值（plan §5）

`resolvePaletteVar(indirectVarName, axisTuple, paletteAst)`：

- 按 axis tuple 在 palette ObjectExpression 分支里查最终 cssVar
- **精确匹配**（按当前 variant 的 axis 值走分支），不穷举
- 工具能力边界：palette 内含动态 JS 表达式（如 `getColor(props)`）→ 返回 `{ failed: true }`，下游标 `❌ palette-resolution-failed`

### 1.4 实现双端 hex 比对（plan §6）

`resolveCssVarToHex(cssVarName)`：

- 优先查 `figma-data/normalized/variables.json`（已有解析）
- 兜底解析 `src/styles/variables.css`
- 返回 `#XXXXXX`（小写）或 null

### 1.5 实现 5 个 verify\*() 函数（plan §6.5 + 真源 §5）

按 plan §6.5 给的接口契约：

- `verifyCssClass(instance, axisTuple)` → `{ verdict, code, evidenceLevel, evidenceSource }`
- `verifyVueProp(instance, axisTuple)` → 同上
- `verifyComputedPalette(instance, axisTuple)` → 同上
- `verifyCssCustomPropertyChain(instance, axisTuple)` → 同上
- `verifyCrossComponentTopology(instance, axisTuple)` → 同上（递归遍历 `codeAnchor` 的多文件，任一通过即标 ✅）

每个函数：
- 成功 → 标对应 `✅ token-match-via-<layer>`，evidenceLevel = `direct`
- 失败 → 标 `⚠️ implementation-mismatch`，evidenceLevel 视情况

### 1.6 实现主算法 `auditAxisValue()`

严格按真源 §5 消费契约 + plan §6.5 伪代码实现：

```
function auditAxisValue(figmaComponent, figmaAxis, figmaValue, axisTuple) {
  const instances = parseAxisImplementationMap()
  const match = instances.find(i =>
    i.figmaComponent === figmaComponent &&
    i.figmaAxis === figmaAxis &&
    (i.figmaValue === figmaValue || i.figmaValue === '*')
  )
  if (match) {
    switch (match.codeImplementationLayer) {
      case 'css-class':                  return verifyCssClass(match, axisTuple)
      case 'vue-prop':                   return verifyVueProp(match, axisTuple)
      case 'vue-computed-palette':       return verifyComputedPalette(match, axisTuple)
      case 'css-custom-property-chain':  return verifyCssCustomPropertyChain(match, axisTuple)
      case 'cross-component-topology':   return verifyCrossComponentTopology(match, axisTuple)
    }
  }
  // 兜底：v1 默认行为（CSS class scan）
  const fallback = verifyCssClass(/* default behavior */)
  if (fallback.success) return fallback
  return { verdict: '⚠️ unmapped-axis-value', evidenceLevel: 'heuristic', evidenceSource: ['figma-tokenized-json', 'axis-implementation-map.md'] }
}
```

### 1.7 集成到现有脚本

- 现有 v1.5 算法在判定 token-mismatch / axis-branch-missing 等的位置改为调用 `auditAxisValue()`
- 保留 v1.5 的：`GLOBAL_AXIS_ALIASES` 标准化（步骤 2）/ `evidenceLevel` schema / 同名 component set 合并 / 报告 + JSON 生成
- 新增 verdict（按 plan §3 完整列表）：
  - `✅ token-match-via-css-class`
  - `✅ token-match-via-prop`
  - `✅ token-match-via-indirection`
  - `✅ token-match-via-custom-property-chain`
  - `✅ token-match-via-topology`
  - `⚠️ hex-equal-different-token`
  - `⚠️ true-token-mismatch`
  - `⚠️ true-visual-drift`
  - `⚠️ implementation-mismatch`
  - `⚠️ unmapped-axis-value`
  - `❌ palette-resolution-failed`
  - 保留 v1.5：`✅ token-match` / `⚠️ axis-branch-missing` / `⚠️ figma-no-real-axis-diff` / `❌ figma-data-missing` / `❌ token-broken` / `⚠️ visual-drift`（dimension）/ `⚠️ literal-but-equal`

如果脚本变得过长（> 1500 行），可以拆分到 `figma-sync/lib/*.mjs`（如 `figma-sync/lib/vue-ast.mjs` / `figma-sync/lib/palette-resolver.mjs` / `figma-sync/lib/topology-verifier.mjs`）。**只新增**，不改其它已有 figma-sync/* 脚本。

---

## 任务 2：重跑 audit + 产新报告

```bash
node figma-sync/audit-component-token-fidelity.mjs
```

报告路径不变：`docs/internal/component-token-fidelity-report.md` + `figma-data/normalized/component-token-fidelity.audit.json`（覆写 v1.5 版本）。

**保留 v1.5 报告结构**：Summary / 按 component × variant 明细 / 推荐处置——只是 verdict 类型扩展。

---

## 任务 3：Sanity check（按 plan §8 已定预期）

跑完后**机械验证**：

| # | 检查项 | 预期 |
|---|---|---|
| 1 | 脚本可重跑（幂等） | 跑两次后 git diff 报告只有时间戳差 |
| 2 | Button `✅ token-match-via-indirection` 数 | **> 2500**（v1.5 大量 token-mismatch direct 应被升级） |
| 3 | Badge `✅ token-match-via-indirection` 数 | **>= 10**（`--badge-bg` / `--badge-border` 应解析） |
| 4 | DateTime / SelectBoxLine.feature axis | 应出现 `✅ token-match-via-prop` 或 `✅ token-match-via-topology`，**不出现** `axis-branch-missing` |
| 5 | Tooltip text-fill | 应升级到 `✅ token-match-via-custom-property-chain` 或 `⚠️ hex-equal-different-token`，不再 `⚠️ token-mismatch direct` |
| 6 | 总 finding 数 | 跟 v1.5 36089 大致同量级（不期望大幅减；只是 verdict 重新分布） |
| 7 | direct 类 finding 数 | 应**比 v1.5 7339 多**（更多 finding 可被 direct 验证） |
| 8 | `❌ palette-resolution-failed` 数 | **应较少**（< 100）；如果很多说明 palette 解析能力有 bug |
| 9 | `⚠️ unmapped-axis-value` 数 | 应**很少**（真源 16 实例覆盖大部分）；如果大量出现，提示真源需要扩展 |
| 10 | HEAD 不动 | `git log --oneline -1` 应仍 `c9032ad` |

**如果某项预期没达到** → 不要硬调算法去对上数字。先报告原因（"算法 X 处实现了 Y，导致 Z 不达预期"），让 plan owner 复审。

---

## 任务 4：⚠️ 不要 commit

```
❌ git add
❌ git commit
❌ git push
❌ git stash
```

允许新增 / 修改：

- ✅ `figma-sync/audit-component-token-fidelity.mjs`（大改）
- ✅ `figma-sync/lib/*.mjs`（如果拆分需要，新增）
- ✅ `docs/internal/component-token-fidelity-report.md`（覆写）
- ✅ `figma-data/normalized/component-token-fidelity.audit.json`（覆写）

允许装依赖（如果 `@vue/compiler-sfc` 不在）：

- ✅ `pnpm install -D @vue/compiler-sfc`（会改 `package.json` + `pnpm-lock.yaml`，**这两个文件留 dirty 不 commit**）

**禁止**：

- ❌ 改 `axis-implementation-map.md` 任何内容（plan owner 真源）
- ❌ 改 `docs/internal/_plans/t1a-fix-v2-plan.md`（已批准）
- ❌ 改 `src/**` 任何文件
- ❌ 改 `figma-data/raw/**` / `figma-data/published/**`
- ❌ 改其它 `figma-sync/*.mjs`（除 `audit-component-token-fidelity.mjs` 和新增 `lib/`）
- ❌ 改 AGENTS.md / meta-rules.md / PROJECT_GOAL.md / PROJECT_MAP.md

---

## 任务 5：完成后 STOP + 报告关键数字

```
任务 1 实施状态：
  parseAxisImplementationMap：✅ / ❌
  Vue AST 3 函数：✅ / ❌
  resolvePaletteVar：✅ / ❌
  resolveCssVarToHex：✅ / ❌
  5 个 verify*()：✅ / ❌
  auditAxisValue 主算法：✅ / ❌
  集成到 audit 脚本：✅ / ❌

任务 2 报告产出：
  报告路径：docs/internal/component-token-fidelity-report.md（行数：N）
  JSON 路径：figma-data/normalized/component-token-fidelity.audit.json（行数：N）

任务 3 Sanity check 10 项：
  通过：N / 10
  未通过项：[列出来 + 原因]

新版 finding 分布：
  ✅ token-match: N
  ✅ token-match-via-css-class: N
  ✅ token-match-via-prop: N
  ✅ token-match-via-indirection: N
  ✅ token-match-via-custom-property-chain: N
  ✅ token-match-via-topology: N
  ⚠️ hex-equal-different-token: N
  ⚠️ true-token-mismatch: N
  ⚠️ true-visual-drift: N
  ⚠️ implementation-mismatch: N
  ⚠️ unmapped-axis-value: N
  ❌ palette-resolution-failed: N
  其它（v1.5 保留的）: N
  total: N（vs v1.5 36089）

evidence 分布：
  direct: N（vs v1.5 7339）
  heuristic: N（vs v1.5 28629）
  semantic-inference: N（vs v1.5 121）

工作区状态：
  modified: N（其中 audit 脚本 + package.json + pnpm-lock.yaml + lib/* 可能新增）
  untracked: N
  HEAD: c9032ad（应不变）
```

**STOP。不要进 T1b。不要 commit。**

---

## 完成标准（机械可验证）

满足全部条件 → 任务完成：

1. 任务 1.1-1.7 全部 ✅
2. 任务 2 报告 + JSON 文件存在
3. 任务 3 Sanity check 通过 ≥ 8 / 10（未通过项已报告原因）
4. HEAD 仍 `c9032ad`
5. 没有改禁止文件（`axis-implementation-map.md` schema 段 / plan / src/* / 其它 figma-sync/*）

任一不满足 → 在报告里说明，让 plan owner 决定是否修正。

---

## 给 executor 的元提醒

如果你在新 Session 中读到本 prompt：

- 你**没有**之前对话的记忆——所有上下文已在仓库文件里
- 你的角色是 **executor**——按已定 plan / 真源实施，不重新设计任何东西
- meta-rules 触发器 G 严格适用：发现 prompt 让你"设计 / 决定 / 选定"什么 → 这是 plan owner 漏写了真源，**报告给 plan owner**，不要自己设计
- 严格遵守 STOP——任务结束就停，不自动进 T1b 或继续探索

完成后 STOP。