From dd1e306c86160bd19fb5587f3d6e322d0647dc5f Mon Sep 17 00:00:00 2001 From: aurora-admin Date: Fri, 11 Sep 2026 22:47:51 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20AGENTS.md=20=E6=89=A7=E8=A1=8C=E7=BA=A6?= =?UTF-8?q?=E5=AE=9A=20+=20=E8=A1=A5=E5=85=A8=20ROADMAP=20=E7=9A=84?= =?UTF-8?q?=E7=BB=93=E6=9E=84=E6=80=A7=E7=BC=BA=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 补三处规划漏洞（自查发现，非用户指出） 1) 缺「执行模型自动能读到的约束」 - 新建 AGENTS.md（216 行）：其他模型不会主动翻 ROADMAP，但大多会自动读 AGENTS.md。把它做成硬约束入口 - 含六条铁律（零依赖/ASCII-only/改模板/改内嵌层/data.json 是承诺/八次回归） - 含禁止事项表（6 条）、交付说明模板、失败升级路径、关键文件地图、 已知陷阱速查（7 条）、当前状态 - 验证过文档里承诺的命令真能跑：铁律 1 的验收命令在 package.json 不存在时 输出 "n/a" 而非报错（原写法会失败） 2) 缺「显式不做」清单 - 新增第四章：8 项不做什么及理由（不引打包器/不做全量像素回归/不做 SSR/ 不做主题商店/不重写 app.js/不改 frameworks 视觉/不做 Storybook/不做单测） - 没有这份清单，执行模型会以为"漏了"，或在不当时机自作主张 3) 缺「未解问题」 - 新增第五章：6 个我无法单方面决策的问题（是否发布 npm/目标用户/设计团队 协作/RTL 必要性/性能预算底线/暗色 iframe 策略），每项附影响面与建议 修正验收命令的 3 处踩坑（自查发现） - P2 的 npm pack 校验：原写法 `npm pack | grep -q site/ && echo FAIL || echo OK` 在 npm 不可用时 grep 也失败 → 误报 OK。改为显式判断 exit code - P4 的 sources 文件计数：目录不存在时错误信息不友好 → 加提示与 exit 1 - 铁律 1 的依赖检查：package.json 不存在时报错 → 改为可容错 章节编号顺延（原「五、验收总纲」→「七」，因新增两章） 回归：100%（961 断言 / 0 失败 / 79 页全通过） --- AGENTS.md | 216 +++++++++++++++++++++++++++++++++++++++++++++++++++++ ROADMAP.md | 128 ++++++++++++++++++++++++++++--- 2 files changed, 335 insertions(+), 9 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..ceec0ff --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,216 @@ +# 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` + +### 3. 改结构要改模板 + +`tests/.html` × 79 是**生成物**。改它们没用 —— 下次重跑会被覆盖。 + +| 想改 | 改哪里 | +|---|---| +| 测试页结构 | `tests/_template.html` → 重跑 `run-tests.ps1` | +| 测试总览页 | `tests/_index_template.html` | +| 测试断言逻辑 | `tests/_runtime.js`（跨帧断言引擎） | +| 文档站 | `site/app.js` | + +### 4. 改样式要改内嵌层 + +**演示页的内嵌 `