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/<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 未支持、断言偏结构。
diff --git a/ROADMAP.md b/ROADMAP.md
index b719901..506bb1f 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -9,13 +9,77 @@
 
 ## 〇 · 交接约定（执行模型必读）
 
-1. **零依赖约束不可破**：不引入 npm 运行时依赖。构建/测试脚本用 Node 内置能力或 PowerShell。
+### 0.1 铁律（违反即返工）
+
+1. **零运行时依赖不可破**：不引入 npm 运行时依赖。构建/测试脚本用 Node 内置能力或 PowerShell。`package.json` 的 `dependencies` 必须为空（`devDependencies` 可用）。
 2. **`build-site.ps1` 必须 ASCII-only**：PS5.1 按 ANSI 读无 BOM 文件，脚本里出现非 ASCII 字面量会被损坏。中文文案放 UTF-8 模板。
-3. **改结构要改模板**：`tests/<slug>.html` 是生成物，改它没用 —— 改 `tests/_template.html` 后重跑 `run-tests.ps1`。
-4. **改样式要改内嵌层**：演示页的**内嵌 `<style>`** 才是实际生效的样式（见 v1.4.0 教训）。只改 `frameworks/*.css` 可能不生效。
-5. **验收以实测为准**：跑本文件给出的命令，把输出贴进交付说明。不要写"已完成"而不给证据。
+3. **改结构要改模板**：`tests/<slug>.html` 是生成物 —— 改它没用。改 `tests/_template.html` / `tests/_index_template.html` 后重跑 `run-tests.ps1`。
+4. **改样式要改内嵌层**：演示页的**内嵌 `<style>`** 才是实际生效的样式（v1.4.0 教训：只改 `frameworks/*.css` 可能不生效，因为演示页不一定 link 它）。
+5. **`data.json` 是 For Agents 的对外承诺**：可以拆 `data.js`，但 `data.json` 必须保持完整（一次请求拿到全部）。破坏它是 breaking change。
 6. **单次改动后必须跑回归**：`tests/_collect.html` 八次连跑，`100% / 0 失败 / 0 超时` 才算过。
 
+### 0.2 禁止事项（做过即需回滚）
+
+| 禁止 | 原因 | 正确做法 |
+|---|---|---|
+| 在 `frameworks/` 里直接手工改出"更好看"的样式 | `frameworks/` 是规范原文的忠实实现，改动会破坏契约一致性 | 要改样式先改令牌，或走任务包流程 |
+| 用 `git reset --hard` / `git checkout .` 清理 | 会丢用户改动 | 用 `git stash` 或定向还原 |
+| 删除或改写 `CHANGELOG.md` 的历史条目 | 那是变更事实记录 | 只追加 `[Unreleased]` 或新版本段 |
+| 修改 `tests/report.json` 的数值来"通过"验收 | 报告是生成物，改它等于伪造证据 | 修实际问题后重跑生成 |
+| 为了通过验收而放宽断言判据 | v1.3.1 曾出现"调松断言刷分"的诱惑 | 断言判据的修正必须附**理由 + 反例** |
+| 在规划未涉及的领域顺手重构 | 范围蔓延会让验收失焦 | 写成新任务包追加到本文件 |
+
+### 0.3 环境与工具
+
+| 项 | 说明 |
+|---|---|
+| 操作系统 | Windows（开发）/ Linux（CI）。跨平台写法见下方「跨平台注意」 |
+| Shell | Git Bash（开发）/ bash（CI） |
+| Node | ≥ 18（用到 `node:sqlite` 的任务需 ≥ 22） |
+| 构建 | `powershell -NoProfile -ExecutionPolicy Bypass -File build-site.ps1`（**Windows 专用**） |
+| 回归 | 浏览器打开 `tests/_collect.html`，或 `node tools/run-regression.mjs`（需 playwright） |
+| 本地服务 | `node site/dev-server.js`（端口 3311） |
+
+**跨平台注意**：
+- 后台启动服务：Windows Git Bash 用 `node site/dev-server.js &`，CI 用 `node site/dev-server.js & sleep 3`。**不要用 `start` 或 `nohup`**。
+- 路径分隔符：脚本里统一用 POSIX 风格（`/`），Node 的 `path` 模块会处理。
+- PowerShell 脚本**只能在 Windows 跑**。若 CI 需要构建，改写为 Node 脚本或加 `runs-on: windows-latest`。
+
+### 0.4 失败升级路径
+
+执行中遇到阻塞时，按这个顺序处理，**不要停下来等**：
+
+| 情况 | 处理 |
+|---|---|
+| 验收命令本身有错（路径不对、语法不兼容） | 修正命令使其能真实反映目标，**在交付说明里写明修正了什么、为什么** |
+| 目标不可达（如依赖的服务/网络不可用） | 交付最强替代物 + 写明缺什么。例：无法 `npm pack` 则做本地 `npm pack --dry-run` 的等价检查 |
+| 发现规划有事实错误（如"某字段占 89%"实际不是） | **以实测为准**，修正规划并在本文件标注「⚠️ 规划修正」 |
+| 发现规划未覆盖的新缺口 | 写成新任务包追加到本文件，**不在原任务里顺手修** |
+| 连续两次尝试同一路径都失败 | 换策略而非重试。在交付说明里记录两次失败的原因 |
+
+### 0.5 交付说明模板（每个任务包完成时提交）
+
+```markdown
+## <任务 ID> 完成说明
+
+**验收输出**（原样粘贴命令输出，不要转述）：
+```
+<命令>
+<输出>
+```
+
+**改动文件**：
+- <路径> — <做了什么>
+
+**规划偏差**（若有）：
+- <规划里写的> → <实际的>，原因：<...>
+
+**发现的新问题**（若有）：
+- <描述> → 已追加为任务包 <ID>
+
+**回归**：100%（<总断言>/<通过>）/ 八次连跑一致 / 0 超时
+```
+
 ---
 
 ## 一 · 现状基线（全部为实测数据）
@@ -206,7 +270,15 @@ test $(ls dist/components/*.css | wc -l) -ge 80 && echo "79 components + index O
 node -e "const p=require('./package.json'); if(p.dependencies) { console.error('FAIL: 不允许 dependencies'); process.exit(1) } console.log('zero-dep OK')"
 
 # 3) 分发内容不含开发资产
-npm pack --dry-run 2>&1 | grep -q "site/" && echo "FAIL: 打包含 site/" || echo "pack contents OK"
+# 注意：不能用 `npm pack | grep -q site/ && echo FAIL || echo OK` —— npm 不可用时 grep 也失败，会误报 OK
+if npm pack --dry-run >/tmp/pack.txt 2>&1; then
+  if grep -qE "site/|tests/" /tmp/pack.txt; then
+    echo "FAIL: 打包含开发资产"; grep -E "site/|tests/" /tmp/pack.txt | head -3; exit 1
+  fi
+  echo "pack contents OK"
+else
+  echo "SKIP: npm 不可用（网络/未安装），此项需在有 npm 的环境补验"
+fi
 
 # 4) 产物可用（起本地服务，浏览器打开验证）
 node -e "const fs=require('fs');const c=fs.readFileSync('dist/components/index.css','utf8');if(!c.includes('--au-color-brand'))process.exit(1);console.log('css usable OK')"
@@ -353,9 +425,15 @@ console.log('budget OK');
 "
 
 # 2) 源码文件已分离（395 个）
+# 注意：目录未创建时 ls 会报错到 stderr，这里显式兜底，让输出可读
 n=$(ls site/sources/*/*.txt 2>/dev/null | wc -l)
-echo "sources files: $n"
-test "$n" -eq 395 && echo "split OK"
+echo "sources files: $n (期望 395)"
+if [ "$n" -ne 395 ]; then
+  echo "FAIL: 期望 395 个源码文件，实际 $n"
+  echo "  提示：若目录不存在，说明 build-site.ps1 的分离逻辑未执行"
+  exit 1
+fi
+echo "split OK"
 
 # 3) data.json 未缩水（For Agents 承诺不变 —— 硬约束）
 node -e "
@@ -780,7 +858,39 @@ figma export OK
 
 ---
 
-## 四 · 风险登记
+## 四 · 显式不做（及理由）
+
+> 这份清单同样重要 —— 没有它，执行模型会以为"漏了"，或者在错误的时机自作主张。
+
+| 不做 | 理由 | 什么条件下应该做 |
+|---|---|---|
+| **不引入打包器**（Vite / Rollup / esbuild） | 破除零依赖约束的代价远大于收益；本项目的卖点就是"打开 HTML 就能用" | 若未来要发布 ESM/CJS 模块化包，先评估是否需要独立仓库 |
+| **不做像素级视觉回归**（全量） | 79 组件 × 5 端 = 395 张基准图，维护成本极高且易误报（抗锯齿/字体渲染差异） | P6 已包含「6 个核心组件抽样像素比对」，够用 |
+| **不做 SSR / SSG** | 文档站是纯静态 SPA，爬虫需求已由 `site/components/*.html` 薄壳 + sitemap 解决 | 若 SEO 成为核心指标，再评估 |
+| **不做多主题商店**（Ant Design 式） | 已有 6 套预设 + 令牌导出，改色能力已足够；主题商店是运营功能非工程功能 | 产品化阶段（S4 之后） |
+| **不重写 `app.js`** | 2064 行单文件虽不理想，但功能正确、回归 100%。重构风险 > 收益 | 若某任务包因它受阻（如 P4 代码拆分），**局部**改造而非重写 |
+| **不改 `frameworks/` 的视觉** | 那是规范原文的忠实实现，改了会破坏契约一致性 | 只有规格原文变更时才同步 |
+| **不做 Storybook 集成** | 与零依赖冲突，且 Playground（v1.2.0）已覆盖在线试玩需求 | 不考虑 |
+| **不做 React/Vue 单元测试**（Jest/Vitest） | 与零依赖冲突；跨端一致性靠 P6 的静态比对 + 抽样渲染 | 若组件逻辑复杂化到静态分析无法覆盖 |
+
+---
+
+## 五 · 未解问题（需用户或后续规划决策）
+
+> 这些问题我作为规划师**无法单方面决定**，列出供决策。
+
+| # | 问题 | 影响面 | 我的建议 |
+|---|---|---|---|
+| Q1 | **是否发布到 npm？** 涉及包名占用、发布权、后续维护承诺 | S1-P2 | 建议发。当前无分发渠道是最大阻塞，且 npm 上同名包大概率未被占用 |
+| Q2 | **目标用户是谁？** 内部团队 / 开源社区 / 商业化产品，三者的优先级与验收标准不同 | 全局 | 建议先按「内部团队 + 开源复用」定位（对应 S1-S2 的优先级） |
+| Q3 | **是否有设计团队协作？** 若没有，S4-P10 的 Figma 产出无人使用 | S4-P10 | 建议推迟到有设计资源时再做，或降级为「Figma Variables JSON 导出」只做工程侧 |
+| Q4 | **是否需要 RTL？** 取决于是否有中东/希伯来语市场 | S3-P8 | 若无明确市场，降级为 P2 或推迟。迁移成本高（22 个文件） |
+| Q5 | **性能预算的底线是多少？** 我定的 300KB 是经验值 | S1-P4b | 建议以「3G 网络首屏可交互 < 3s」反推预算 |
+| Q6 | **暗色模式下演示 iframe 是否反色？** 两种都有道理 | S2-P5 | 建议反色（用户开暗色就是要整体变暗），但需人工验收视觉 |
+
+---
+
+## 六 · 风险登记
 
 | 风险 | 影响 | 缓解 |
 |---|---|---|
@@ -793,7 +903,7 @@ figma export OK
 
 ---
 
-## 五 · 验收总纲
+## 七 · 验收总纲
 
 任一任务包完成，必须同时满足：