aurora-admin/AGENTS.md

AGENTS.md · Aurora Admin 执行约定

给在此仓库工作的 AI 模型：这个文件是硬约束，不是建议。开始任何任务前先读完。 人类贡献者请看 CONTRIBUTING.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 运行时依赖。

# 验收：这条必须在所有改动后通过
# 注意：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

构建链是两步，必须按序执行

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 处）。

# 诊断：这个页面的样式从哪来
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. 单次改动后必须跑回归

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

---

四 · 交付形态

每个任务完成时提交交付说明：

## <任务 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	{} 被当格式占位符	改写措辞或转义
.dockerignore 的 *.md / *.png 等 glob	只匹配构建上下文根目录，嵌套路径照样进镜像（实测：sub/nested.md 仍被 COPY）	嵌套一律写 **/*.md；排除目录写完整相对路径
手工拷贝部署目录	修复被下一次拷贝覆盖（absolute_redirect off 就是这样丢的），且 .dockerignore 不随行导致规范原文入镜像	走 §九 的 tools/pack-deploy.mjs，不要手工拷贝
部署后浏览器仍跑旧 JS	静态资源无 Cache-Control 时浏览器会启发式缓存（实测：页面内 fetch 能取到新 app.js，<script src> 却用缓存）	nginx 已加 Cache-Control: no-cache（带 ETag 复验 304）；升级前遗留的旧缓存需强刷一次
AA_PORT 默认 13311 与文档里的隧道端口撞车	tools/verify-dev-server.mjs 报 EADDRINUSE 并失败	隧道开着时用 AA_PORT=13511 node tools/verify-dev-server.mjs

---

八 · 当前状态

版本：v1.4.1 ｜ 回归：100%（1017 通过 / 0 失败 / N/A 34，共 1051 条断言，2026-09-19 连跑 10 次一致）｜ 下一阶段：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 未支持、断言偏结构。

---

九 · 部署（192.168.5.7）

当前形态：Compose 项目 aurora-admin，容器 aurora-admin-showcase，端口 127.0.0.1:3311 -> 80。 只监听回环——局域网直连 192.168.5.7:3311 会超时，这是有意的；服务器上没有任何 frp / 反代 / 域名指向它，所以除了 SSH 隧道没有别的访问路径。不要靠改绑定或挂反代来解决"打不开"。

本机访问（Windows，已实测可用）：

ssh -o ExitOnForwardFailure=yes -N -L 13311:127.0.0.1:3311 root@192.168.5.7
# 然后浏览器打开 http://127.0.0.1:13311/site/

本地用 13311 而不是 3311，是为了不和 node site/dev-server.js（本地也占 3311）抢端口。 想要局域网/其它设备直接访问：那是一次显式的暴露变更（改 compose 绑定为 0.0.0.0:3311），并且 Docker 发布端口会绕过 ufw 规则 —— 需要明确许可后再做。

部署目录：/opt/aurora-admin（= docker build 上下文，必须含 Dockerfile / nginx.conf / .dockerignore / docker-compose.yml / sitemap.xml + 4 个内容目录）。

标准流程（不要在服务器上手工拼文件）：

# 1) 本地打包（.dockerignore 是排除规则的唯一真源，含硬断言）
node tools/pack-deploy.mjs --tar          # -> dist-deploy/aurora-admin-deploy.tar.gz

# 2) 上传 + 备份现状
#    scp 到 /tmp/aurora-admin-deploy.tar.gz
#    ssh: tar czf /root/aurora-admin-backup-$(date +%Y%m%d-%H%M).tgz -C /opt aurora-admin

# 3) 解到暂存目录、核对、替换、重建
cd /opt && mkdir -p aurora-admin.staged \
  && tar xzf /tmp/aurora-admin-deploy.tar.gz -C aurora-admin.staged --strip-components=1
ls -a aurora-admin.staged            # 必须无 specs/ agent-reports/ preview/ ui_kits/
mv aurora-admin aurora-admin.pre-<日期> && mv aurora-admin.staged aurora-admin
cd /opt/aurora-admin && docker compose build && docker compose up -d

# 4) 验收（四条必须全中）
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3311/.design_library/aurora-admin/specs/组件1.txt  # 404
curl -sI http://127.0.0.1:3311/ | grep -i '^Location'                                                         # /site/
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3311/sitemap.xml                                    # 200
curl -sI http://127.0.0.1:3311/healthz | grep -ci '^content-type'                                             # 1

铁律：任何"只改服务器、不回写仓库"的修复都会在下次部署时丢失——nginx.conf 的 absolute_redirect off 已经因此丢过一次。先改仓库，再走打包流程。