# AI Agents 必读（跨 AI 工具通用）

> 本文件适用于：Codex / Claude Code / Cursor / Cline / GitHub Copilot / 任何在本仓库工作的 AI 工具。

---

## ⛔ Onboarding Gate（第一个项目相关回答前 mandatory）

**任何 AI 在第一个项目相关任务 / 推荐 / 回答前，必须先完成 [`docs/STATUS.md` 起手必读链路](./docs/STATUS.md#起手必读链路) 5-step onboarding（~30min）**：

1. `docs/STATUS.md`（项目状态 SoT）
2. `docs/PROJECT_GOAL.md`（项目目标）
3. `docs/internal/retrospection/design-spec-canonical-alignment-tracker.md`（排期 SoT）+ `docs/internal/_plans/next-session-pickup-*.md` 最新一份（sprint 操作手册）
4. `AGENTS.md`（本文件）必读链路 §1-10（Mockup 任务额外 §7-10）
5. 当前 sprint task 对应 `docs/internal/backlog.md` entry

**机械执行**：用 TodoWrite / TaskList / 等价机制建 5 个 todo，逐个 Read 完才能开始回答。**基于 partial onboarding 给推荐 = 协议违反**。

**违反信号**（命中任一 → 停下重读）：
- "我已经知道大概了" / "状态简单跳一步" → 错
- "grep 替代完整 Read" → 错（grep 只在已 onboard 后的具体查找场景用）
- "memory 兜底替代 SoT" → 错（memory 是 AI 缓存，项目契约真源在仓库）

**历史实证**：2026-05-13 session 10 跳过 PROJECT_GOAL + AGENTS → 首轮推荐缺 4 项硬约束（canonical SoT / plan owner 边界 / working-principles / meta-rules）→ 用户返工纠偏。

---

## 项目一句话

把 **Figma 已发布 Library**（组件 / Token / 图标 / Styles）做成 **AI 与开发可消费的双向 Figma↔Code 桥**：

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

详细目标 + 各能力的前置约束（T3/T4 schema 设计要点）：[`docs/PROJECT_GOAL.md`](./docs/PROJECT_GOAL.md)

---

## 必读链路（按顺序）

1. **[`docs/PROJECT_GOAL.md`](./docs/PROJECT_GOAL.md)** — 项目目标 / 受众 / 路线图 / Quick Reference
2. **[`docs/PROJECT_MAP.md`](./docs/PROJECT_MAP.md)** — 数据来源 / 组成 / 生成链 / 跨 AI 分工 / 清理规则
3. **[`docs/working-principles.md`](./docs/working-principles.md)** — 7 条工作原则（边界翻译层 / API 形态判定 / 命名优先级 / 图标 alias / 颜色 token / 审计粒度 / 决策默认值）+ 决策 Log
4. **[`src/design-system/translation/`](./src/design-system/translation/)** — 翻译层 SoT，4 个文件：
   - `prop-aliases.md` — 已登记的命名 alias（如 `closable ↔ showCloseIcon`）
   - `divergences.md` — 显式不映射 / 组件级映射 / 双形态映射 / Button 双 API 决策
   - `icon-aliases.ts` — 图标 alias 表（如 `status/warning ↔ icon/Message/Error 4`）
   - `token-aliases.ts` — token 映射
5. **[`docs/internal/retrospection/`](./docs/internal/retrospection/)** — 阶段复盘（看最新日期）
6. **[`docs/internal/backlog.md`](./docs/internal/backlog.md)** — 项目级 backlog（已知 bug / 延后任务 / 技术债清单 + 触发查看条件）

### Mockup 任务额外必读

> 任何 AI 工具收到"在 TVU 产品 Figma 文件画 UX mockup / 改 mockup / 抽组件入库"类任务时，**除上面 1-6 还必须读**：

7. **[`docs/internal/design-process.md`](./docs/internal/design-process.md)** — 通用 process 规则（M22 / Pre-Phase 0 / Stage 0.5 / M11 / M14 / M15 / M16 / M21 / M6 / Lazy Reference Loading）
8. **[`docs/internal/domain-tvu.md`](./docs/internal/domain-tvu.md)** — TVU 业务规则（M3 / M4 / M5 / M7 / M8 / M9）
9. **[`docs/internal/mockup-conventions.md`](./docs/internal/mockup-conventions.md)** — Path A 专属（Figma 真源 / 组件取数优先级 / 库归属验证 / M0 / M1 / M10）
   + **[`docs/internal/figma-technical-reference.md`](./docs/internal/figma-technical-reference.md)**（Figma API quirks，实现时查）
10. **[`docs/internal/figma-component-catalog.md`](./docs/internal/figma-component-catalog.md)** — TVU 已发布库组件目录快速查（mockup 任务起手第一查，避免凭印象造组件）

---

## 硬规则（不可违背）

| # | 规则 | 违反后果 |
|---|---|---|
| 1 | **不修改 Figma**——Figma 是设计师真源 | 任何 Figma 写操作都是 bug |
| 2 | **不让 AI 按"行业惯例"自由发挥** | 必须读 translation/ 已登记决策；新决策必须先得到用户确认 |
| 3 | **不创建未登记的 prop / variant / 状态** | 例：Notification 历史上自创的 `success` status 已被识别为 bug，正在删除 |
| 4 | **颜色硬编码 = bug** | 必须用 token；token 缺失就新建，不能写 hex |
| 5 | **任何 Figma↔Code 不一致必须先在 translation/ 登记** | 不登记的不一致 = 漂移 |
| 6 | **AI 工具从 Figma URL 生成代码必须用 `src/canonical/*` 作为 SoT，不用 `src/components/*`** | `src/components/*` 是实现/base 层，`src/canonical/*` 是 Figma-aligned 桥层（npm 经 `src/index.ts` 导出 canonical）。落 base/legacy → 输出 API 错位。详见 [`src/design-system/translation/divergences.md`](./src/design-system/translation/divergences.md) "Code 端双源" 段 |

---

## 元规则：真源单一 + 双层导入（不绑工具 / 不绑模型）

> 本元规则适用于**任何 AI 工具**（Claude Code / Codex / Cursor / Cline / Copilot / 其它）、**任何角色**（plan owner / executor / reviewer）。
> 角色与工具的绑定可变化——当前 Claude Code = plan owner、Codex = executor，但可互换或被替代——**本规则不变**。

详细规则、反模式清单、角色互换条款、Audit/数据产出类 prompt 子规则，统一登记在：

→ **[`docs/meta-rules.md`](./docs/meta-rules.md)**（元规则真源）

任何角色在写 prompt / 设计机制 / 推荐方案前，**必须先过 meta-rules.md 的反模式清单**。命中任一条 → 停下重新设计。

---

## 工作流（约定）

> **角色驱动，工具可换。** 本段使用角色名（`plan owner` / `executor`）而非工具名。
> **当前默认绑定**：`plan owner = Claude Code`、`executor = Codex`。
> **切换方式**：用户在对话里说"把 `<角色>` 换成 `<AI 工具>`"，新工具读 `AGENTS.md` + `docs/meta-rules.md` 即可承担该角色。
> **切换不需要改本文件 / `meta-rules.md` / 任何 prompt 模板**——它们都是角色无关的。如果发现哪条规则绑了具体工具名，应该改成角色名（违反 meta-rules 反模式 #1）。

### 角色定义

| 角色 | 职责 |
|---|---|
| **plan owner** | 写 plan / 设计 prompt / 审 executor 的 diff / 复审是否进入下一阶段 |
| **executor** | 按 plan owner 写的 prompt 严格执行任务 / 跑脚本 / 报告改动与未解决项 |
| **reviewer** | 用户最终拍板（部分情况下 plan owner 兼任审计） |

### 标准闭环（必须按顺序）

1. plan owner 读项目规则 + audit
2. plan owner 生成 `docs/internal/_prompts/<name>.prompt.md`
3. 用户把 prompt 交给 executor
4. executor 按 prompt 改代码 / 产出文件
5. executor STOP，列出改动和未验证项
6. plan owner 复审 executor diff
7. 用户决定是否进入下一阶段

### 单一决策源模式（当前默认）

为避免 plan owner 与 executor 在对话中互相"补充框架"、反复扩展路线，后续协作默认采用以下边界：

- **plan owner 负责产出一版路线图 / prompt**，并把结构性决策固化到仓库文档
- **executor 不做"加料式评论"**：不在 plan owner 路线图基础上继续发明新轨道、新阶段或新框架
- **executor 只做三件事**：
  1. 检查 prompt 是否有明显 blocker（会误删 / 误 commit / 改 Figma / 范围不可验证 / 与仓库规则冲突）
  2. 执行 prompt 指定任务
  3. 报告改动、验证结果、未解决项
- 如果 executor 不同意 prompt，只指出**会导致失败的 blocker**，不扩展替代路线
- 一旦 `docs/internal/long-term-plan-v2-*.md` 或同等路线图落仓库并经用户确认，本阶段以该文档为准；不要在对话里反复发明新框架

### executor 角色行为约束

- 用户通过 file-based prompt 触发任务：`请按 docs/internal/_prompts/<name>.prompt.md 执行`
- 每个 prompt 末尾会有 "完成后 STOP，等用户审"——**严格遵守 STOP**，不要自行进入下一步
- 关键参数（如 token 值、变体枚举）**先列出来给用户确认**，不要自行决定
- 在单一决策源模式下，执行前只做 blocker 检查；无 blocker 就执行，不再提出额外路线规划

### plan owner 角色行为约束

- 直接读项目文件审 executor 产出
- 设计 prompt 前**强制过 `docs/meta-rules.md` 反模式清单**——命中任一条 → 重新设计，不 fire
- 任何重大决策（破坏性 API 改造、跨阶段路径选择）必须 propose 给用户拍板
- 默认**不直接修改代码 / 脚本 / tokens / JSON 数据 / 组件文件**——涉及这些改动时，应先生成 executor prompt，除非用户明确授权
- 可以直接修改协作规则文档、prompt 文件、审计报告和复盘文档；完成后必须 STOP，等用户确认

### 共同规则

- 决策必须固化到文档（不能只在对话里口头提）
- 阶段完成后追加复盘到 `docs/internal/retrospection/{date}.md`
- 所有 prompt 版本化保存在 `docs/internal/_prompts/`

### 唤醒词："同步 Figma 库"

任何 AI session 收到这句话时，按下面顺序执行，**禁止跳步、禁止默认走破坏性路径**：

1. 跑 `pnpm sync:figma-library`（默认**安全模式**：cleanup 只 dry-run，不删任何 figma-data/）
2. 看 cleanup dry-run 报告：
   - 如果有候选删除项，**只输出报告**，绝不直接删除
   - 把候选清单列给用户，并明确说明"会删除 N 个文件，需要授权"
3. 等用户回 `--apply-cleanup` 或显式确认后，才能跑 `pnpm sync:figma-library --apply-cleanup` 真删
4. `audit:figma-conformance` / `audit:docs-site` / `audit:published-vs-code` 输出必须能解释；如有未通过项，STOP 并报告，不要继续后续阶段
5. 任何 `figma-data/` 写操作（删除、改 index、改 manifest）必须经过 dry-run + 用户授权
6. 任何 `audit:published-vs-code --auto-suggest-unmapped` 新写入 mapping JSON 的条目，状态必须是 `needs-review`，禁止自动 `approved`

### 默认安全 vs 显式破坏性

| 场景 | 命令 | 默认行为 |
|---|---|---|
| 同步 Figma 库（推荐入口） | `pnpm sync:figma-library` | 安全：cleanup dry-run，不删 figma-data |
| 真要删（用户已审过 dry-run 报告） | `pnpm sync:figma-library --apply-cleanup` | 破坏性：cleanup 实际删除 |
| 含 Figma extract | 加 `--with-extract` | 需要 .env 中的 `FIGMA_TOKEN` |

---

## 项目约束（影响所有 AI 工具的任务规划）

> 本段登记**跨工具有效**的项目级约束。任何 AI 工具（Claude Code / Codex / Cursor / Cline / Gemini / 其它）规划任务前必须读这段，按约束评估可行性，不要默认更宽松假设。

- **Figma plan = Professional**（不是 Organization / Enterprise）
  - `figma connect publish` 不可达（需 Org/Ent Developer seat；任何 Code Connect API 调用都会返回 401，已实证——不限工具/协议）
  - DevMode 显代码片段功能不可用（依赖 publish）
  - 当前 Bridge 价值通过以下机制实现：硬规则 #6 + canonical SoT + [`divergences.md`](./src/design-system/translation/divergences.md) "Code 端双源" 段 + 现有 `pnpm sync:figma-library` audit pipeline
  - **失效条件**：用户主动说"升 Org"或"升级 Figma plan"——在那之前所有 Pro 限制生效
  - 详见 [t4-spike-validated 复盘](./docs/internal/retrospection/2026-04-30-t4-spike-validated.md) 阶段 6

- **截图 / 视觉证据交付走脚本文本 + 文件路径，不走对话粘贴大图** — 详见 [`docs/internal/visual-evidence-conventions.md`](./docs/internal/visual-evidence-conventions.md)
  - V1：视觉验收 ground truth 是脚本文本输出（参考 `.f19-visual-audit.mjs`），截图仅在 diff>0 时兜底
  - V2：进会话的截图长边 ≤ 1800px（`sips -Z 1800 *.png`）
  - V3：大图落盘 + `Read`，不剪贴板粘贴
  - V4：撞 2000px 限制 → STOP + 落盘进度 + 新 session
  - 失效条件：所有主流 AI 工具都把图片限制升到 4000px+ 以后——在那之前严格执行

- **Docs site 支持 dark / light theme toggle**（2026-05-08 INFRA-F19 升级）
  - `playground/docs/DocsShell.vue` 提供 toggle 按钮，`provide('docsTheme', ...)` 把当前 theme 下发到所有后代组件
  - `<FigmaMembersGrid>` 默认 `inject('docsTheme')` 跟随全局 toggle —— 切 dark 只渲染 dark variants，切 light 只渲染 light variants（基于 figma 真源 variant.theme axis）
  - **theme 渲染降级链**（与 figma 真源约定一致）：
    - **L1** figma component 有 theme axis → grid 按当前 docsTheme filter 对应 variants
    - **L2** figma 无 theme axis 但 component 用 theme-aware Color Token → 渲染依赖 token 自动响应（CSS 变量随 `data-theme` 切）
    - **L3** figma 无 theme axis 且 token 也无 theme 区分 → 多主题下视觉等同（不视为 bug）
    - 实证 L3：2026-05-08 Rating figma 简化为 token-driven（删 theme axis），多主题下视觉等同
  - 默认主题：dark（`isDark = ref(true)` 初值）
  - 改造 docs page 范式：page 内不再分 "Dark Theme Members" / "Light Theme Members" 两 section，单 grid 跟随全局 toggle 即可；**禁止任何 dark/light 并排展示**（包括手写 demo block 的 dual-card 范式）
  - `<FigmaMembersGrid>` API 不接受任何 theme override prop —— theme 唯一来源是全局 inject('docsTheme')；audit gate 对 page 模板里出现的 `:site-theme=` 任何写法报 error
  - figma 数据 dark/light 不对称（如 notification dark=15 light=14）是 figma 真源决定，**不是 docs site bug**，无需补齐
  - 失效条件：用户主动撤回 toggle —— 在那之前 toggle-aware 严格执行
  - 实证：F19 修复前文档站 shell 有 toggle 但 18 个 page 写死 `:site-theme="'dark'"` 形成半成品 bug；2026-05-08 F19 修复

---

## 当前阶段定位

**最新更新：2026-04-28** — 详见 [retrospection 最新日期](./docs/internal/retrospection/)

```
✅ 0-3：架构（边界翻译层 / 工作原则 / 翻译层登记）
✅ 4-5：模式聚类 + 10 项 B 类决策
✅ 6.1：翻译层批量登记
[当前位置 ↓]
🔴 6.2-6.5：关键修复（视觉 token / 删除自创 / 新增运行时能力 / 微结构）
🆕 npm 包化
🟡 Phase 7：Element Plus 风格文档站（含多角色视图）
🟢 上线 v0.1
🔵 后续迭代：6.6/6.7/6.8（破坏性 API 改造）+ Phase 8（视觉脚本 + Code Connect）
```

---

## 受众

| 角色 | 关注点 |
|---|---|
| 开发（P0 主要使用者） | npm 安装、props/events/slots、可复制代码、TypeScript 类型 |
| 设计（P1 查看者） | 与 Figma 对应关系、变体网格、设计 spec |
| 产品（P1 查看者） | 业务场景示例、何时用哪个组件 |
| QA（P1 查看者） | 状态矩阵、可交互测试、边界条件 |

---

## Quick Reference

| 我想知道 | 看哪里 |
|---|---|
| 项目目标 | `docs/PROJECT_GOAL.md` |
| 项目地图 / 数据流 / 清理规则 | `docs/PROJECT_MAP.md` |
| 实现原则 | `docs/working-principles.md` |
| 当前进度 | `docs/internal/retrospection/`（最新日期） |
| 已做的决策 | `src/design-system/translation/` + working-principles 末尾"决策 Log" |
| 下一步 prompt | `docs/internal/_prompts/` |
| API diff 状态 | `docs/internal/api-diff.md` + `api-diff-patterns.md` |
| 资产清单 | `docs/internal/asset-inventory.md` |
| 组件级映射扫描 | `docs/internal/component-mapping-scan.md` |
| 待补运行时能力 | `docs/internal/runtime-additions.md` |
| Backlog / 已知 bug / 技术债 | `docs/internal/backlog.md` |
| Mockup 通用 process 规则（M22 / Pre-Phase 0 / M11 / M14 / M15 / M16 / M21 / M6）| `docs/internal/design-process.md` |
| TVU 业务规则（M3 / M4 / M5 / M7 / M8 / M9）| `docs/internal/domain-tvu.md` |
| Mockup Path A 专属（Figma 真源 / M0 / M1 / M10）| `docs/internal/mockup-conventions.md` |
| Figma API quirks | `docs/internal/figma-technical-reference.md` |
| TVU 库组件目录（mockup 任务起手查）| `docs/internal/figma-component-catalog.md` |
| 系统性 review 报告 | `docs/internal/_reports/systematic-review-<date>.md` |

---

## 元说明

- 本文件是**跨 AI 工具的入口**，应保持简短，详细内容指向 `docs/PROJECT_GOAL.md` 和 `docs/meta-rules.md`
- 各 AI 工具的入口文件（如 [`CLAUDE.md`](./CLAUDE.md)、未来的 `GEMINI.md` / `CURSOR.md` 等）应**仅登记该工具自己特有的工程细节**——规则、角色行为约束、元规则统一指向本文件 + `docs/meta-rules.md`
- 修改本文件需谨慎——所有 AI 工具的入口契约都在这
- **修改本文件时不要写工具具体名（"Claude" / "Codex" 等）作为规则主体**——应写"角色名"（plan owner / executor）。当前角色绑定在工作流段顶部明示