# 长期计划：把 docs 站重组为 EP 模式（2026-04-28 起）

## 总目标

把 TVU 设计系统的 docs 站从"页面各自为政"重组为"按 [Element Plus 组件文档](https://element-plus.org/en-US/component/overview) 模式呈现的可消费产物"，让 AI / 开发同事 / 多项目消费方都能直接拿来用。

最终交付物：

1. 22 个组件页统一遵守 Breadcrumb 样板模式
2. 描述当前真实状态的 spec（非预设规则）
3. 机器化 audit 阻挡回归
4. Code Connect 文件（Figma → Code 官方绑定）
5. AI manifest（机器可读消费层）

## 工作原则（重要）

1. **Spec 跟着现实走**：每条规则必须有真实实现作为锚点。规则 / 实现 / audit 三件一起 ship，spec 不允许预设
2. **阶段性 commit**：不微 commit，按里程碑（M1 / M2 / ...）批量提交。每个里程碑是一组协调的 spec + 实现 + audit + 修复
   - **No-commit until milestone（2026-04-29 起补充）**：所有 Codex prompt 严禁自带 "自己 commit" 步骤——Codex 跑完只动文件，留 dirty 工作区。所有 D 系列 / E 系列改动累积到 dirty 状态，**主 Session（用户）确认后一刀统一 commit**。
   - 已发生的例外：`9fa1882`（D1 API 三表）—— 这是 D1 prompt 设计时还包含 "自己 commit"，已 commit 的事实保留；后续不再撤销。M1 commit 时这一刀已在历史里，不再重复包入。
   - 通用模板：每个 prompt 末尾用"任务 N：⚠️ 不要 commit，留 dirty 给主 Session"段替代旧的"任务 N：自己 commit"段。execution report 里仅作 commit message draft 备用，不真 commit。
3. **Claude vs Codex 分工**：
   - Claude（我）：写 spec / 写 prompt / 改文档 / 只读分析 / 审 Codex diff
   - Codex（你触发）：改 .mjs 脚本 / 改 .vue 组件 / 改测试 / 改 JSON 数据
4. **用户触发节奏**：Codex 必须由你（用户）显式触发；Claude 自主推进只读和文档类工作

## 阶段划分

### Phase A：现实评估（Claude 单独，无需 Codex）

**目标**：对 22 个组件页机器扫描+人脑判断，形成"当前每页相对 Breadcrumb 样板的差距"基线。

**产物**：`docs/internal/component-page-conformance-baseline-2026-04-28.md`

**评分维度**（5 项 × 20 分）：
- A1. 5 段固定结构存在？（Figma Coverage / Real Members / Capability / Development Usage / API）
- A2. 引入的是 canonical 组件而非 runtime？
- A3. API 段三表齐全（Attributes / Slots / Events，None 显式写）？
- A4. 至少一个 demo 真交互（v-model / 事件触发）？
- A5. 没有 `:deep()` 视觉补丁？

**完成条件**：22 页都有打分 + gap 列表，输出文件存在

**状态**：待 Claude 自主执行（本回合开始）

---

### Phase B：从用户 WIP 中提炼真实模式（Claude 单独）

**目标**：观察用户当前正在做的 5 个 in-review 页（特别是 Steps / FormItem 这类需要回组件层修复的）的真实 diff，提炼"事实证明可行"的修复模式。

**输入**：用户 commit 8 个当前 dirty WIP 文件后的 diff

**产物**：附加到 `docs/internal/component-page-conformance-baseline-2026-04-28.md` 的"已验证模式"节

**特别关注**：
- 修 docs 还是修组件本体？
- canonical 改了什么 vs runtime 改了什么？
- 测试如何配套修改？

**完成条件**：从用户实际 commit 中提炼 3-5 条可复用模式

**状态**：依赖用户先 commit WIP，本回合不动

---

### Phase C：spec 收敛到事实版本（Claude 单独）

**目标**：把当前 untracked 的 595 行 spec 砍掉一半多，只保留"现实就是这样"的部分；加入 Phase B 提炼的模式作为正例。

**操作**：
- 砍掉 §2 / §4 / §6 / §7 中预设但未验证的规则
- §1 改成"Breadcrumb 是当前唯一合规样板，其它 21 页对齐进度见 baseline"
- §0 失败列表保留（这部分是事实，不是预设）
- §5 修复层级判定保留并配 Phase B 的真实样板
- §8 / §9 / §10 保留（已是事实）
- 新增"渐进合规计划"节，指向本长期计划文档

**产物**：spec 重写版本（文件名沿用 `docs/docs-site-dx-parity-spec.md`），保持 untracked

**完成条件**：spec 每一行规则都能指向至少一个真实实现锚点

**状态**：依赖 Phase A + B，本回合不动

---

### Phase D：Codex prompt 批量设计（Claude 单独）

**目标**：把 Phase A 的 baseline 按"修复类型"分组，为每组写一个 Codex prompt。

**预期分组**（待 Phase A 数据确认）：
- D1: API 三表补齐组（缺 Slots / Events 表的页）
- D2: 5 段顺序重排组（demo 被旧 Figma section 盖过的页）
- D3: canonical 切换组（仍 import runtime 的页）
- D4: 真交互组（demo 用 prop 锁死状态摆拍的页）
- D5: `:deep()` 清除 + 组件本体修组（如 FormItem 类）

**产物**：`docs/internal/_prompts/conformance-batch-D{1,2,3,4,5}.prompt.md`

**特点**：
- 每个 prompt 处理一组同类问题，覆盖多页
- 引用 spec §N + Breadcrumb 样板 + Phase A baseline
- 末尾禁令清单引用 spec §0 失败列表
- 要求 Codex 三段式自报告（已动手 / 仅诊断 / 未解决）

**完成条件**：每组 prompt 通过 self-review，等待用户触发

**状态**：依赖 Phase A，本回合不动

---

### Phase E：Codex 批量执行（用户触发，Claude 审 diff）

**目标**：依次触发 D1-D5，每组完成后 Claude 审 diff、跑 audit、更新 baseline。

**用户操作**：
1. 把 prompt 路径粘给 Codex
2. Codex 跑完，message Claude "done"
3. Claude 审 diff，告知是否通过
4. 重复

**Claude 审计要点**：
- 改动范围在 prompt 圈定内？
- 自报告三段式齐全？
- Phase A baseline 评分提升？
- 未引入新 :deep() 或新 runtime 依赖？

**完成条件**：5 组全跑完，22 页平均合规分 ≥ 80

**状态**：等用户触发，Claude 顺序响应

---

### Phase F：里程碑 M1 commit（Claude + 用户共同）

**目标**：把 Phase A-E 的累积产物一次 ship。

**单一 commit 包含**：
- spec（重写后版本）
- 一个新 audit 脚本（基于 Phase A 5 项评分维度）
- 22 页修复后的内容
- Phase A baseline + Phase B 模式提炼报告
- 长期计划文档（本文件）

**commit message 草案**：

```
docs(site): bring 22 component pages to EP-style conformance (M1)

- Spec reflects real state (no preset rules without anchors)
- New audit:docs-page-conformance enforces 5 dimensions
- Pages refactored to Breadcrumb pattern, average ≥ 80% conformance
- Baseline + execution log in docs/internal/
```

**前置条件**：Phase E 完成 + 用户人眼/浏览器目视通过

**状态**：等 Phase E 完成

---

### Phase G：单页微调（用户 + Codex 多轮）

**目标**：对 M1 后剩余 minor 问题（个别页面的细节）做精修。

**节奏**：
- 用户挑一页报问题
- Claude 写小 prompt
- Codex 修
- 几页攒一起后再 commit（M2 / M3 ...）

**完成条件**：所有 22 页用户满意

---

### Phase H：扩展能力（M2+ 之后）

**Code Connect 落地**（你提的"AI 直接 Figma → Code"）：
- 写 `<Component>.figma.ts` 文件，挂在每个 canonical 旁
- Cursor / Claude / Figma plugin 直接消费

**AI manifest 包**：
- npm 发布时附 `dist/ai-manifest.json`
- 合并 manifest + canonical-component-api.json + token data

**视觉回归 baseline**：
- Playwright / vitest browser mode
- 每个 demo 截图入 baseline

**多项目消费样板**：
- `examples/vue3-vite-basic/`
- `examples/with-theme/`
- `examples/icons-only/`

**状态**：M1 之后单独规划

---

## 当前状态快照（2026-04-28 18:00）

### 已 commit 到 master
- 6.3.5 反向 audit 报告（commit `8c38ffd`）
- BreadcrumbItem icon 修复（commit `9f9a898`）
- handoff baseline + 台账 [046]（commit `c0d6b55`）

### Untracked（未 commit 但已写）
- `docs/docs-site-dx-parity-spec.md`（595 行，将被 Phase C 重写）
- `docs/internal/_prompts/phase-6.3.5d-cleanup-table-striped.prompt.md`（待用，Table.striped 清理 prompt）

### Dirty WIP（用户进行中）
- `playground/docs/pages/FormItemPage.vue`
- `playground/docs/pages/StepsPage.vue`
- `src/canonical/StepItem.vue`
- `src/canonical/Steps.vue`
- `src/components/PromptMessage/PromptMessage.vue`
- `src/components/Steps/StepItem.vue`
- `src/components/Steps/Steps.vue`
- `tests/RemainingCanonicalPages.test.ts`

用户回来后建议：先决定这 8 个 WIP 文件如何 commit（可拆 1 个 / 多个 commit），然后启动 Phase E 第一组。

---

## 用户下班后 Claude 自主推进的范围

**可以做（只读 + 文档）**：
- ✅ Phase A inventory（读 22 页结构）
- ✅ Phase A baseline 评分输出
- ✅ Phase D prompt 草稿（基于 Phase A 数据）
- ✅ Code Connect 仓库现状调研（grep）
- ✅ 优化本计划文档

**不能做**：
- ❌ 触发 Codex（必须用户复制 prompt 到 Codex 工具）
- ❌ commit 任何东西（按用户原则等里程碑）
- ❌ 修改 src / tests / playground / figma-sync 任何代码
- ❌ 修改 manifest / token / icon 数据

**24 小时无人值守的现实**：Claude 会话由用户消息触发，没有用户消息我不会自动跑。所以"下班后继续工作"实际是：
- 我**这一回合**尽可能多做 Phase A + Phase D 草稿
- 你下次发消息（哪怕是"go"或"continue"）会激活我做下一批
- 真正的"过夜跑"需要你触发 Codex 来推进 Phase E

---

## 用户回来时优先看的三件事

1. **本计划文档** —— 校对方向是否还对
2. **Phase A baseline** —— 22 页当前真实差距，决定 Phase E 先攻哪组
3. **Claude 已准备好的 Phase D prompt 草稿** —— 直接复制触发 Codex

如果方向偏了，告诉 Claude 在哪改；如果对，直接启动 Phase E。