# Codex Prompt: T1a Fix Patch — 4 件事一刀

> T1a 第一版已跑出 4 个文件（脚本 + 报告 + JSON + prompt 归档），整体骨架对。但有 4 个具体缺陷需修补。**不是重写，是打补丁**。
>
> **不修 src/ / 不 commit / 不 push**。

---

## 上下文（必读）

1. **`docs/internal/_prompts/t1a-audit-component-token-fidelity.prompt.md`** — T1a 主 prompt，所有"为什么这么做"的理由在这里。本 fix patch 不替代它。
2. **`figma-sync/audit-component-token-fidelity.mjs`** — 你上轮已写的脚本（829 行），本次基于此修补。
3. **`docs/internal/component-token-fidelity-report.md`** — 上轮产出报告（2711 行）。
4. **`figma-data/normalized/component-token-fidelity.audit.json`** — 上轮产出机读 JSON。
5. **`/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system/CLAUDE.md`** — `## Audit / Data-Output Prompt 写作规则` 段说明 evidenceLevel schema 的来由。

---

## 主 Session 审计后发现的 4 个缺陷

| # | 缺陷 | 证据 |
|---|---|---|
| **P0** | **全局 axis 别名标准化未实现**（主 prompt 4 处明确要求被忽略） | 脚本 grep `darkTheme/alias/normaliz` 0 命中相关逻辑；Tooltip 段 axes 仍写 `darkTheme [off|on]`；推荐处置无"T1b 头号"行 |
| **P2** | **axis-diff-check 字符串拼接 bug** | Slider 段出现 `Mpx` / `Spx` / `lightpx` 这种无意义拼接，全判 figma-no-real-axis-diff |
| **P3** | **同 canonical 名多 figma component set 没合并** | Button 报告里出现 8 段（`### Component: Button` x 8）、Select x2、Input x2，推荐处置 8 行 Button 重复 |
| **NEW** | **缺 evidenceLevel / evidenceSource 溯源字段** | 报告把"figma 真源 vs code 静态 CSS"和"算法推断"混标，下游没法机械分流可信度 |

P1（dimension 假阳性）**不修 verdict**——通过 NEW 任务的 evidenceLevel 自然分流（dimension 字段标 heuristic）。

---

## 任务 1：补 P0 全局 axis 别名标准化

在脚本里加全局常量：

```js
// 项目级真源约定（用户 2026-04-29 confirmed）：
// 站点 ThemeProvider 切换时，所有 darkTheme=on/off 组件跟随站点 theme 渲染对应主题
// darkTheme 跟 theme 是同一个轴的两套命名
// TODO(T1b): 移到 src/design-system/translation/prop-aliases.md 后从文件读
const GLOBAL_AXIS_ALIASES = {
  axisName: { 'dark theme': 'theme', darkTheme: 'theme' },
  axisValue: {
    theme: { on: 'dark', off: 'light' },
  },
}
```

应用位置：在 `variant.name` 解析成 axis tuple **之后**立即标准化：
- axis 名先按 `axisName` 表替换（注意 figma 真源里写法可能是 `dark theme`、`darkTheme`、`Dark Theme` 等，做 normalize 后再查表）
- axis 值再按 `axisValue` 表替换

**后续所有步骤（fills 收集、code selector 定位、verdict 判定、报告输出）都使用标准化后的 axis tuple**——即 Tooltip 报告 axes 应显示 `theme [dark|light]`，不再是 `darkTheme [off|on]`。

推荐处置段加一行（放在最前面）：

```markdown
**T1b 头号任务（先于其它）**：把硬编码在脚本的全局别名 `darkTheme=on/off ↔ theme=dark/light` 登记到 `src/design-system/translation/prop-aliases.md`，并改脚本从该文件读，删除硬编码 + 删除 `// TODO(T1b)` 注释。这是项目级真源约定，覆盖所有 Class B 5 组件 + Tooltip。
```

---

## 任务 2：修 P2 axis-diff-check 字符串拼接 bug

Slider 报告里看到的 `Mpx` / `Spx` / `lightpx` 是错误拼接产物。请：

1. 在脚本里找产生 `axis-diff-check` finding 的代码段
2. 诊断为什么 figma 字段会拼成 `Mpx`（应该是 axis 值 `M` 跟 `px` 单位被错误连接）
3. 修复——`axis-diff-check` 的 figma 列应该是**该 axis 在不同值之间的 fills 比较结果**，不是单值字符串
4. 如果原算法逻辑就有缺陷，**简化它**：只保留"figma 该 axis 跨值 fills 完全相同 + code 实现了该 axis 分支 → ⚠️ figma-no-real-axis-diff"这一条核心判断；finding 的 figma 字段写人话（如 `"dark==light fills identical (#cccccc)"`），不要拼接

---

## 任务 3：修 P3 同 canonical 名 component set 合并

当前报告 Button 出现 8 次，因为 figma 上 Button 是 8 个 component set（dark_l / dark_m / dark_s / dark_xs / light_l / light_m / light_s / light_xs）。

**合并规则**：

- 同 canonical 名（如 `Button` / `Select` / `Input`）下所有 component set 合并到**一个** `### Component:` 段
- 标题写法：`### Component: Button (8 component sets: 1545:51854, 1545:51964, ...)`
- axes 段合并所有 set 的 axis 维度（去重）：例如 Button 8 个 set 各有 size/theme，合并后写 `axes: theme [dark|light] × size [L|M|S|XS] × ...`
- finding 表合并所有 set 的 variants（按 axis tuple 去重——同 tuple 不同 set 的 finding 选其一或保留全部并标 set 来源，由你决定）
- 推荐处置段每 canonical 名只一行

**机读 JSON 也合并**：`components[]` 数组里同 canonical 名只一个 entry，含字段 `componentSetIds: [...]`。

---

## 任务 4（NEW）：加 evidenceLevel / evidenceSource 溯源字段

按 [CLAUDE.md `## Audit / Data-Output Prompt 写作规则`](/Users/nancy/Documents/AICoding/VS_Code/tvu-design-system/CLAUDE.md) 要求，每条 finding 加两个字段：

```json
{
  "kind": "...",
  "figma": {...},
  "code": {...},
  "verdict": "⚠️ token-mismatch",
  "evidenceLevel": "direct" | "heuristic" | "semantic-inference",
  "evidenceSource": ["figma-tokenized-json", "vue-static-css", "axis-diff-algorithm", ...]
}
```

### Verdict → evidenceLevel 映射（严格按此实现）

| verdict | evidenceLevel | evidenceSource |
|---|---|---|
| ✅ token-match (颜色) | direct | `["figma-tokenized-json", "vue-static-css"]` |
| ⚠️ token-mismatch (颜色) | direct | `["figma-tokenized-json", "vue-static-css"]` |
| ⚠️ literal-but-equal | direct | `["figma-tokenized-json", "vue-static-css"]` |
| ⚠️ visual-drift (颜色 hex literal 真不等) | direct | `["figma-tokenized-json", "vue-static-css"]` |
| ⚠️ visual-drift (dimension：figma 裸数字 + code var()) | **heuristic** | `["figma-tokenized-json", "vue-static-css", "dimension-untokenized-on-figma-side"]` |
| ⚠️ axis-branch-missing | heuristic | `["vue-static-css", "selector-search"]` |
| ⚠️ figma-no-real-axis-diff | semantic-inference | `["figma-tokenized-json", "axis-diff-algorithm"]` |
| ❌ figma-data-missing (JSON 真空) | direct | `["figma-tokenized-json"]` |
| ❌ figma-data-missing (code 有 figma 没 — 推断型) | heuristic | `["figma-tokenized-json", "vue-static-css", "code-presence-implies-figma-gap"]` |
| ❌ token-broken | direct | `["figma-tokenized-json", "variables-css"]` |

### 报告 Markdown 表加一列 `来源级别`

例：

```
| variant | finding kind | figma | code | 标记 | 来源级别 |
|---|---|---|---|---|---|
| ... | ... | ... | ... | ⚠️ token-mismatch | direct |
| ... | ... | ... | ... | ⚠️ visual-drift | heuristic |
```

### Summary 表加一段 evidence 分布

```
| 来源级别 | 数量 |
|---|---:|
| direct | N |
| heuristic | N |
| semantic-inference | N |
```

---

## 任务 5：重跑 + 自验

```bash
# 跑两次确认幂等
node figma-sync/audit-component-token-fidelity.mjs
node figma-sync/audit-component-token-fidelity.mjs

# 第二次跑后 git diff 应只有时间戳差
git diff docs/internal/component-token-fidelity-report.md | head -20
```

**Sanity check（必须通过）**：

| 检查项 | 期望 |
|---|---|
| `grep -c '^### Component: Button' report.md` | **1**（不是 8） |
| `grep -c '^### Component: Select' report.md` | **1**（不是 2） |
| `grep -c '^### Component: Input' report.md` | **1**（不是 2） |
| `grep -m1 '^axes:' Tooltip 段` | 显示 `theme [dark\|light]`，**不出现** `darkTheme [off\|on]` |
| `grep 'T1b 头号' report.md` | 至少 1 命中 |
| `grep -E 'Mpx\|Spx\|lightpx' report.md` | **0 命中**（P2 修干净） |
| `grep -c 'evidenceLevel' audit.json` | 远 > 0 |
| `grep -c '来源级别' report.md` | 远 > 0 |
| 报告总行数 | 应小于上轮（合并 + 简化后） |
| Finding 总数 | 应 < 上轮 38701（合并去重 + axis-diff bug 修后） |

如果某项不通过，**先报告**为什么不通过，不要硬调。

---

## 任务 6：⚠️ 不要 commit

按 v2 plan 工作纪律 1：

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

本轮 4 个产物全部留 dirty 工作区：
- `figma-sync/audit-component-token-fidelity.mjs`（修改）
- `docs/internal/component-token-fidelity-report.md`（重写）
- `figma-data/normalized/component-token-fidelity.audit.json`（重写）
- `docs/internal/_prompts/t1a-fix-patch.prompt.md`（本 prompt，已存在不要动）

---

## 总禁止清单

- ❌ 不修 `src/**`
- ❌ 不修 `prop-aliases.md` / `divergences.md` / `runtime-additions.md`（推荐处置里写"T1b 头号"建议即可）
- ❌ 不修其它 `figma-sync/*.mjs`
- ❌ 不删除上轮产出再重写——要 patch 不是 rewrite，保留上轮算法骨架
- ❌ 不 commit / push

---

## 完成后 STOP

跑完输出给主 Session：

```
P0 全局别名：✅ 实现 / ❌ 未实现
P2 axis-diff bug：✅ 修复 / ❌ 残留
P3 component 合并：Button=N段, Select=N段, Input=N段（应都 1）
evidenceLevel：✅ schema 已加 / ❌ 未加

新 finding 总数：N（vs 上轮 38701）
direct：N
heuristic：N
semantic-inference：N

工作区状态：4 modified, 0 commits
```

**STOP。不要进 T1b。**