aurora-admin
16f365a045
执行 ROADMAP 的 S1-P4，按规划的三阶段走，本次完成 A 与 B。 阶段 A · 预计算 scenarios（验证「构建期预计算 + 运行时回退」链路） - tools/precompute.mjs：与 app.js 的 extractScenarios 逻辑完全一致， 构建期算出结果写进 data.components[].scenarios - app.js 加快速路径：优先读 c.scenarios，缺失时回退运行时解析 - 浏览器实测：预计算值与运行时提取值**完全一致**（逐字节比对） - 实测收益有限：仅 4 个组件有 ≥2 场景（场景卡片本就少见）， 但链路验证通过，为阶段 C 的 API 预计算铺路 阶段 B · css 源码分离（零风险，css 不参与任何解析） - css 从 data.js 移到 site/sources/<slug>/css.txt（79 个文件） - data.js 里改为 sourcesRef.css 引用，data.json 保持完整（For Agents 承诺） - data.js: 1058 KB → 942 KB（−116 KB） - app.js 新增 srcOf(c, kind) / hasSrc(c, kind)： · srcOf 同步返回已有源码，缺失时触发后台 fetch 并缓存 · __aaSrcReady 回调在加载完成后填充代码区 - 修正回调时机 bug：原实现捕获构建时的 current（初始 tab）， 导致用户后续切换的 tab 收不到通知。改为回调内实时比对当前 tab 关于 P4 的实测修正（已登记 ROADMAP 规划修正记录） - 规划估计「拆 sources → ~110KB」。实测 css 仅占 119KB/888KB， 且 html/vue2/vue3/jsx 共 765KB 被**渲染期同步消费** （extractComponentAPI 读 vue3/vue2/jsx，extractScenarios 读 html） - 故需分阶段：A+B 先减 116KB，阶段 C 需先预计算 API 表才能分离其余 4 端 新增构建链（两步，不可省第二步） - npm run build:site = build-site.ps1 + precompute.mjs - build-site.ps1 会把 data.js 重写回全量，precompute 才做瘦身 - 已写入 AGENTS.md 的铁律章节（含「只跑第一步会怎样」的后果说明） 验证 - 回归 100%：1003/1003，79 页全通过，N/A 35 - 浏览器实测：展开代码区 → CSS tab → 2121 字符正常显示， Network 出现 sources/button/css.txt 请求 - 预计算 vs 运行时场景提取结果逐字节一致
231 lines
9.5 KiB
Markdown
231 lines
9.5 KiB
Markdown
# AGENTS.md · Aurora Admin 执行约定
|
||
|
||
> **给在此仓库工作的 AI 模型**：这个文件是硬约束，不是建议。开始任何任务前先读完。
|
||
> 人类贡献者请看 [CONTRIBUTING.md](./CONTRIBUTING.md)；任务清单看 [ROADMAP.md](./ROADMAP.md)。
|
||
|
||
---
|
||
|
||
## 一 · 这个仓库是什么
|
||
|
||
**Aurora Admin Design System** —— B 端中后台设计系统，**79 组件 × 5 端实现**（H5 / React / Vue 2 / Vue 3 / CSS），含完整文档站、设计契约、回归体系。
|
||
|
||
| 项 | 值 |
|
||
|---|---|
|
||
| 组件 | 79 |
|
||
| 端实现文件 | 395（`frameworks/`，79 × 5） |
|
||
| 契约 JSON | 79（`.design_library/aurora-admin/components/`） |
|
||
| 设计令牌 | 75（`colors_and_type.css`） |
|
||
| i18n 字典 | 330 条（`site/i18n.js`） |
|
||
| 测试断言 | 961（`tests/`，12.2/页） |
|
||
| 回归通过率 | **100%**（八次连跑一致） |
|
||
|
||
---
|
||
|
||
## 二 · 六条铁律（违反即返工）
|
||
|
||
### 1. 零运行时依赖
|
||
|
||
不引入 npm **运行时**依赖。
|
||
|
||
```bash
|
||
# 验收：这条必须在所有改动后通过
|
||
# 注意：P2 之前 package.json 不存在，此时应输出 "n/a (no package.json yet)" 而非报错
|
||
node -e "
|
||
const fs=require('fs');
|
||
if(!fs.existsSync('package.json')) { console.log('n/a (no package.json yet)'); process.exit(0) }
|
||
const p=require('./package.json');
|
||
const deps=Object.keys(p.dependencies||{});
|
||
if(deps.length) { console.error('FAIL: 运行时依赖 ' + deps.join(', ')); process.exit(1) }
|
||
console.log('zero-dep OK');
|
||
"
|
||
```
|
||
|
||
`devDependencies` 可用（构建/测试工具），但要在 README 注明"CI 专用"。
|
||
|
||
### 2. `build-site.ps1` 必须 ASCII-only
|
||
|
||
PowerShell 5.1 按 ANSI 读无 BOM 文件 —— 脚本里出现非 ASCII 字面量会被**静默损坏**。
|
||
|
||
- 中文文案放 UTF-8 模板（`tests/_template.html` 等）
|
||
- 输出用 `[System.IO.File]::WriteAllText($path, $content, [System.Text.UTF8Encoding]::new($false))` 写无 BOM
|
||
- `build-site.ps1` 只能在 Windows 跑；CI 需要构建时改用 `runs-on: windows-latest`
|
||
|
||
#### 构建链是两步，必须按序执行
|
||
|
||
```bash
|
||
npm run build:site # 等价于下面两步
|
||
# 1) powershell -NoProfile -ExecutionPolicy Bypass -File build-site.ps1
|
||
# 2) node tools/precompute.mjs
|
||
```
|
||
|
||
**第 2 步不能省** —— `build-site.ps1` 会把 `data.js` 重写回全量（1058 KB），
|
||
`tools/precompute.mjs` 才做瘦身（→ 942 KB，把 css 源码移到 `site/sources/<slug>/css.txt`）。
|
||
只跑第 1 步会导致：`data.js` 变大、且 `sourcesRef` 字段消失 → 详情页代码区缺 CSS tab。
|
||
|
||
单独重跑只需 `npm run precompute`。
|
||
|
||
### 3. 改结构要改模板
|
||
|
||
`tests/<slug>.html` × 79 是**生成物**。改它们没用 —— 下次重跑会被覆盖。
|
||
|
||
| 想改 | 改哪里 |
|
||
|---|---|
|
||
| 测试页结构 | `tests/_template.html` → 重跑 `run-tests.ps1` |
|
||
| 测试总览页 | `tests/_index_template.html` |
|
||
| 测试断言逻辑 | `tests/_runtime.js`（跨帧断言引擎） |
|
||
| 文档站 | `site/app.js` |
|
||
|
||
### 4. 改样式要改内嵌层
|
||
|
||
**演示页的内嵌 `<style>` 才是实际生效的样式。**
|
||
|
||
v1.4.0 的教训：花了几小时令牌化 `frameworks/*.css`（915 处），结果发现演示页不一定 link 它 —— 真正生效的是内嵌的 `<style>` 块（另 287 处）。
|
||
|
||
```bash
|
||
# 诊断：这个页面的样式从哪来
|
||
grep -o 'href="[^"]*\.css"' frameworks/Button.html
|
||
# 若无 frameworks/Button.css，说明样式在内嵌 <style> 里
|
||
```
|
||
|
||
### 5. `data.json` 是对外承诺
|
||
|
||
`site/data.json` 是 For Agents 页承诺的「一次请求拿到全部」。可以拆 `data.js`（性能优化），但 **`data.json` 必须保持完整**。
|
||
|
||
破坏它是 breaking change。
|
||
|
||
### 6. 单次改动后必须跑回归
|
||
|
||
```bash
|
||
node site/dev-server.js & # 起服务（端口 3311）
|
||
# 浏览器打开 http://127.0.0.1:3311/tests/_collect.html
|
||
# 或：node tools/run-regression.mjs（需 playwright）
|
||
```
|
||
|
||
**验收标准**：`100% / 0 失败 / 0 超时`，且**连跑八次一致**。
|
||
|
||
> 为什么是八次：偶发问题（并发超时）在单次运行中可能不出现。项目的超时兜底逻辑已改为「重试一次 + 超时单列」，但连跑仍是最可靠的验证。
|
||
|
||
---
|
||
|
||
## 三 · 禁止事项
|
||
|
||
| 禁止 | 原因 | 正确做法 |
|
||
|---|---|---|
|
||
| 手工改 `frameworks/` 里的样式让它"更好看" | 那是规范原文的忠实实现 | 改令牌，或走 ROADMAP 任务包 |
|
||
| `git reset --hard` / `git checkout .` 清理 | 会丢用户改动 | `git stash` 或定向还原 |
|
||
| 改写 `CHANGELOG.md` 的历史条目 | 变更事实记录 | 只追加 `[Unreleased]` 或新版本段 |
|
||
| 改 `tests/report.json` 的数值 | 等于伪造证据 | 修实际问题后重跑生成 |
|
||
| 为通过验收而放宽断言判据 | v1.3.1 出现过这个诱惑 | 判据修正必须附**理由 + 反例** |
|
||
| 在任务范围外顺手重构 | 范围蔓延让验收失焦 | 写成新任务包追加到 ROADMAP |
|
||
|
||
---
|
||
|
||
## 四 · 交付形态
|
||
|
||
每个任务完成时提交**交付说明**：
|
||
|
||
```markdown
|
||
## <任务 ID> 完成说明
|
||
|
||
**验收输出**（原样粘贴命令输出，不要转述）：
|
||
（命令 + 输出）
|
||
|
||
**改动文件**：
|
||
- <路径> — <做了什么>
|
||
|
||
**规划偏差**（若有）：
|
||
- ROADMAP 写的 <X> → 实际的 <Y>，原因：<...>
|
||
|
||
**发现的新问题**（若有）：
|
||
- <描述> → 已追加为 ROADMAP 任务包 <ID>
|
||
|
||
**回归**：100%（<通过>/<总数>）/ 八次连跑一致 / 0 超时
|
||
```
|
||
|
||
**不要写「已完成」而不给证据。** 这个项目的历史上有 6 次"文档声称完成但代码缺失"，全部是靠实测发现的。
|
||
|
||
---
|
||
|
||
## 五 · 失败升级路径
|
||
|
||
按顺序处理，**不要停下来等**：
|
||
|
||
| 情况 | 处理 |
|
||
|---|---|
|
||
| 验收命令本身有错 | 修正它使其真实反映目标，在交付说明写明修了什么、为什么 |
|
||
| 目标不可达（依赖的服务/网络不可用） | 交付最强替代物 + 写明缺什么 |
|
||
| 发现 ROADMAP 有事实错误 | **以实测为准**，修正规划并标注「⚠️ 规划修正」 |
|
||
| 发现规划未覆盖的新缺口 | 写成新任务包追加到 ROADMAP，**不在原任务里顺手修** |
|
||
| 同一路径连续两次失败 | 换策略而非重试，记录两次失败的原因 |
|
||
|
||
---
|
||
|
||
## 六 · 关键文件地图
|
||
|
||
```
|
||
组件规范第一套/
|
||
├─ AGENTS.md ← 本文件（硬约束）
|
||
├─ ROADMAP.md ← 任务清单（13 个任务包 + 验收命令）
|
||
├─ CHANGELOG.md ← 变更记录（build 时注入文档站）
|
||
├─ CONTRIBUTING.md ← 人类贡献指南
|
||
├─ TESTING.md ← 测试矩阵说明
|
||
├─ LICENSE ← MIT
|
||
│
|
||
├─ build-site.ps1 ← 构建（ASCII-only！生成 data.js/data.json/薄壳/sitemap/令牌导出）
|
||
├─ run-tests.ps1 ← 重生成 79 个测试页
|
||
│
|
||
├─ frameworks/ ← 395 个实现文件（79 × 5 端）—— 只读，除非规格变更
|
||
│
|
||
├─ .design_library/aurora-admin/
|
||
│ ├─ colors_and_type.css ← 75 个设计令牌（改色的唯一入口）
|
||
│ ├─ components.css ← 6 核心组件样式聚合
|
||
│ ├─ css.json ← 结构化令牌（For Agents 消费）
|
||
│ ├─ components/*.json ← 79 份契约（含 unknowns/doNotInvent）
|
||
│ └─ specs/组件1~10.txt ← 规范原文（CRLF！读时用 split(/\r?\n/)）
|
||
│
|
||
├─ site/
|
||
│ ├─ app.js ← 文档站全部逻辑（2064 行，hash 路由 SPA）
|
||
│ ├─ i18n.js ← 330 条中英字典（中文源串作键）
|
||
│ ├─ data.js / data.json ← 构建产物（勿手改）
|
||
│ ├─ tokens/ ← 令牌导出（CSS / W3C DTCG / Figma）
|
||
│ └─ components/*.html ← 79 个静态薄壳（SEO 入口）
|
||
│
|
||
└─ tests/
|
||
├─ _template.html ← 测试页模板（改结构改这里）
|
||
├─ _runtime.js ← 跨帧断言引擎（iframe 载真实演示页）
|
||
├─ _collect.html ← 零依赖批量回归收集器
|
||
├─ report.json ← 回归报告（生成物）
|
||
└─ <slug>.html × 79 ← 生成物
|
||
```
|
||
|
||
---
|
||
|
||
## 七 · 已知陷阱速查
|
||
|
||
| 陷阱 | 现象 | 解法 |
|
||
|---|---|---|
|
||
| 规范文件是 CRLF | 正则 `/^#{3}/` 匹配不到行尾，标题解析全失败 | `split(/\r?\n/)` 先归一化 |
|
||
| PS5.1 写文件带 BOM | 严格 JSON 解析器（node require）直接失败 | `WriteAllText` + `UTF8Encoding($false)` |
|
||
| 演示页 DOM 由内联脚本生成 | 静态抽快照得到空 DOM | 用 iframe 载真实页面跨帧断言 |
|
||
| 并发 iframe 抢主线程 | 偶发超时被误记为失败 | 已修：超时重试 + 超时单列（见 `_collect.html`） |
|
||
| 改令牌组件不变 | 改的是没被加载的文件 | 改内嵌 `<style>`（铁律 4） |
|
||
| `$themes` / `$schema` 在 PS 里 | 被当变量展开成 null，报"Null 键" | 用引号包裹键名 `'$themes'` |
|
||
| `Write-Output "...{}..." -f $n` | `{}` 被当格式占位符 | 改写措辞或转义 |
|
||
|
||
---
|
||
|
||
## 八 · 当前状态
|
||
|
||
**版本**：v1.4.1 ｜ **回归**：100%（961 断言 / 0 失败 / N/A 36）｜ **下一阶段**：ROADMAP 的 S1 可交付
|
||
|
||
**已完成的里程碑**：
|
||
- v1.3.0 验收链路修复（测试页从空 DOM 误报改为 iframe 真实渲染）
|
||
- v1.3.1 无障碍与令牌合规（回归 85.1% → 100%）
|
||
- v1.3.2 契约全量 79/79 + 令牌导出三格式
|
||
- v1.3.3 中英双语 i18n
|
||
- v1.4.0 组件层全面令牌化（1202 处）
|
||
- v1.4.1 四轮审计 + 回归偶发根治
|
||
|
||
**当前缺口（详见 ROADMAP 的 G1-G8）**：
|
||
无 LICENSE（已补）、无分发机制、CI 无测试、暗色模式是假的、跨端一致性无验证、`data.js` 1MB、RTL 未支持、断言偏结构。
|