From d88cdf23243fe3f0b55c97f7361df45e706881b4 Mon Sep 17 00:00:00 2001
From: aurora-admin <aurora-admin@users.noreply.github.com>
Date: Fri, 11 Sep 2026 22:40:10 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E9=95=BF=E6=9C=9F=E8=B7=AF=E7=BA=BF?=
 =?UTF-8?q?=E5=9B=BE=EF=BC=88ROADMAP.md=EF=BC=8C12=20=E4=B8=AA=E5=8F=AF?=
 =?UTF-8?q?=E6=89=A7=E8=A1=8C=E4=BB=BB=E5=8A=A1=E5=8C=85=EF=BC=89+=20?=
 =?UTF-8?q?=E6=89=A7=E8=A1=8C=20P1=20LICENSE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

规划师角色切换后的首份交付：把规划做成可交接工件，而非聊天里的建议。

ROADMAP.md 的形态
- 每个任务包含：目标 / 依据 / 依赖 / 精确路径 / 步骤 / 验收命令 / 预期输出 /
  失败判据。执行模型照做即可，不需要再问
- 附「交接约定」6 条（零依赖不可破、build-site.ps1 必须 ASCII-only、改结构要改
  模板、改样式要改内嵌层、验收以实测为准、单次改动跑八次回归）
- 附「验收总纲」5 条（给完整输出、跑八次回归、CHANGELOG 条目、ROADMAP 标记、
  新问题写成新任务包不顺手修）

基线全部实测（非估计）
- 资产：79 组件 / 395 端文件 / 79 契约 / 358 usageHints / 139 unknowns /
  101 doNotInvent / 75 令牌 / 330 字典 / 961 断言
- 回归 100%（八次连跑一致）/ 契约保真 93.9% / 令牌语义 0 错配 / i18n 0 残留
- 性能：文档站 1247KB，其中 data.js 1058KB（85%）
- 八项缺口（G1-G8）每项附实测证据

关键诊断（在规划里就完成，避免执行模型走弯路）
- data.json 体积实测拆解：sources 字段 888KB = 89.6%。拆出后 data.js
  991KB → ~110KB（−89%）。规划里的推测值已被实测替换

阶段划分与决策依据
- S1 可交付（LICENSE/npm/CI/data.js）→ S2 可信（暗色/跨端/行为断言）→
  S3 完整（RTL/FAQ）→ S4 生态（Figma/模板/发布）
- 顺序依据：S1 是「能不能用」，S2 是「能不能信」，S3 是「够不够全」，
  S4 是「好不好用」。颠倒会做出没人敢用的产品

顺带执行 P1（验证规划可落地）
- LICENSE：MIT 全文，README 新增许可证段与路线图链接，版本号校正为 v1.4.1
- 验收输出：LICENSE OK / README OK
- ROADMAP 对应任务包下追加完成标记（验证闭环机制可用）

回归：100%（961 断言 / 0 失败 / 79 页全通过）
---
 LICENSE    |  21 ++
 README.md  |  12 +-
 ROADMAP.md | 825 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 857 insertions(+), 1 deletion(-)
 create mode 100644 LICENSE
 create mode 100644 ROADMAP.md

diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..80f8db7
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aurora Admin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
index d5e860f..7c28efa 100644
--- a/README.md
+++ b/README.md
@@ -60,4 +60,14 @@ node tools/run-regression.mjs      # headless 回归（需 npm i playwright）
 
 ## 版本
 
-见 [CHANGELOG.md](./CHANGELOG.md)。当前 v1.2.0。
+见 [CHANGELOG.md](./CHANGELOG.md)。当前 v1.4.1。
+
+## 路线图
+
+后续规划（可交付性、可信度、完整度、生态四阶段，含逐任务验收标准）见 [ROADMAP.md](./ROADMAP.md)。
+
+## 许可证
+
+[MIT](./LICENSE) © 2026 Aurora Admin
+
+可自由用于商业项目、修改、再分发，仅需保留版权声明。如需变更许可证（例如 Apache-2.0 或 MPL-2.0），请参考 [ROADMAP.md](./ROADMAP.md) 的 S1-P1 任务包。
diff --git a/ROADMAP.md b/ROADMAP.md
new file mode 100644
index 0000000..b719901
--- /dev/null
+++ b/ROADMAP.md
@@ -0,0 +1,825 @@
+# Aurora Admin · 长期路线图与任务包
+
+> **文档性质**：交给执行模型的工程规划。每个任务包自带验收命令与失败判据，拿到即可开工，不需要再问。
+> **基线版本**：v1.4.1（2026-09-11）
+> **规划人**：海鸥（规划师角色）
+> **更新约定**：任务完成时在本文件对应任务包下追加 `✅ 完成于 <commit>`，不要删原计划。
+
+---
+
+## 〇 · 交接约定（执行模型必读）
+
+1. **零依赖约束不可破**：不引入 npm 运行时依赖。构建/测试脚本用 Node 内置能力或 PowerShell。
+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. **验收以实测为准**：跑本文件给出的命令，把输出贴进交付说明。不要写"已完成"而不给证据。
+6. **单次改动后必须跑回归**：`tests/_collect.html` 八次连跑，`100% / 0 失败 / 0 超时` 才算过。
+
+---
+
+## 一 · 现状基线（全部为实测数据）
+
+### 1.1 资产规模
+
+| 项 | 数量 | 测量方式 |
+|---|---|---|
+| 组件 | 79 | `components/index.json` |
+| 5 端实现文件 | 395 | `ls frameworks/*.{html,css,jsx,vue2.vue,vue3.vue}` 各 79 |
+| 契约 JSON | 79（全量） | `ls .design_library/aurora-admin/components/*.json` |
+| 契约 usageHints | 358 条 | 遍历契约累加 |
+| 契约 unknowns | 139 条 | 同上（**现成的 FAQ 素材**） |
+| 契约 doNotInvent | 101 条 | 同上 |
+| 设计令牌 | 75 个 | `site/data.json` → `tokens.length` |
+| i18n 字典 | 330 条 | `site/i18n.js` |
+| 测试断言 | 961 条（12.2/页） | `tests/report.json` |
+| 文档站路由 | 9 个 | home/overview/guide/design/changelog/agents/component/scenario/tests |
+
+### 1.2 质量指标
+
+| 项 | 值 | 说明 |
+|---|---|---|
+| 回归通过率 | **100%** | 八次连跑一致，0 失败 0 超时 |
+| N/A 断言 | 36（3.7%） | 静态组件无交互面、单实例组件无多变体，已逐条核实 |
+| 契约保真度 | 93.9% 逐字命中规格 | 余 22 条为同义改写，非发明 |
+| 令牌语义错配 | 0 / 1313 处 | 属性与令牌角色全部匹配 |
+| i18n 质量 | 0 残留中文、0 未翻译 | 326 条字典 |
+| 组件可换肤 | 79/79 | 逐组件改令牌比对样式签名 |
+
+### 1.3 性能基线
+
+| 指标 | 值 | 说明 |
+|---|---|---|
+| 文档站传输量 | **1247 KB** | 7 个资源 |
+| 其中 `data.js` | **1058 KB（85%）** | ← 最大优化目标 |
+| `app.js` | 101 KB | 未压缩 |
+| `style.css` | 40 KB | 未压缩 |
+| DOMContentLoaded | 345 ms | 本地 dev-server，线上更慢 |
+| 每详情页额外 | iframe 1 个 | 加载对应演示页 |
+
+### 1.4 实测缺口（按严重度）
+
+| # | 缺口 | 实测证据 | 影响 |
+|---|---|---|---|
+| **G1** | **无 LICENSE** | `ls LICENSE` → 不存在 | 法律上不可用，对外交付的硬阻塞 |
+| **G2** | **无分发机制** | 无 `package.json` / 无 CDN / 无发布流程 | 用户拿不到，只能 clone 仓库 |
+| **G3** | **CI 无测试** | `.github/workflows/` 只有 `deploy-pages.yml` | 回归靠手动，质量无持续保障 |
+| **G4** | **暗色模式是假的** | 令牌层 `aa-dark` 规则 **0** 条、组件层 **0** 条、仅站点骨架 **7** 条 | CHANGELOG 曾称"补全"，实为第 6 次声称≠实现 |
+| **G5** | **跨端一致性无验证** | 5 端 395 文件，无任何自动比对 | H5/React/Vue2/Vue3 视觉是否一致**无从知晓** |
+| **G6** | **`data.js` 1MB** | 占传输量 85% | 首屏慢，移动端更差 |
+| **G7** | **RTL 未支持** | 逻辑属性 0 处 / 物理属性 22 文件 | 阿拉伯语等市场不可用 |
+| **G8** | **断言偏结构** | 12 项/页，多为"元素存在"，无"点击后发生什么" | 行为回归无覆盖 |
+
+---
+
+## 二 · 长期愿景与阶段划分
+
+### 2.1 目标状态（12 个月）
+
+> **一句话**：从「一个做得很完整的组件库仓库」，变成「一个能被外部团队直接采用的设计系统产品」。
+
+拆成四个可验证的终态：
+
+1. **可交付** —— 有许可证、有分发渠道、有 CI 保障，外部团队 5 分钟内能用上。
+2. **可信** —— 关键声称（暗色、跨端一致、无障碍）全部有自动化证据，不靠文档承诺。
+3. **完整** —— 覆盖国际化（含 RTL）、无障碍实测、性能预算。
+4. **生态** —— 设计工具链打通（Figma）、典型页面可直接复用、有版本发布节奏。
+
+### 2.2 阶段划分与决策依据
+
+| 阶段 | 主题 | 解决 | 决策依据 |
+|---|---|---|---|
+| **S1** | 可交付 | G1 G2 G3 G6 | 前三个是**对外交付的硬阻塞**：没许可证不能商用，没分发拿不到，没 CI 质量会退化。G6 顺手做（data.js 占 85% 传输量，收益最大） |
+| **S2** | 可信 | G4 G5 G8 | 都是「声称了但没证据」。G4 是第 6 次声称≠实现，必须先止血 |
+| **S3** | 完整 | G7 + 无障碍实测 | RTL 与无障碍是竞品 7 家里的分水岭（3 家有 RTL） |
+| **S4** | 生态 | Figma/模板/发布 | 前两阶段完成后，生态建设才有意义 |
+
+**为什么这个顺序**：S1 是"能不能用"，S2 是"能不能信"，S3 是"够不够全"，S4 是"好不好用"。顺序颠倒会做出没人敢用的产品。
+
+---
+
+## 三 · 任务包
+
+> 格式：**目标 → 依据 → 依赖 → 路径 → 步骤 → 验收 → 失败判据**
+> 每个任务包独立可执行，除标注依赖外互不阻塞。
+
+---
+
+### S1-P1 · LICENSE 许可证 ｜ 预算 ~10 min ｜ 优先级 P0
+
+**目标**：仓库根目录存在 `LICENSE`，明确授权范围，移除对外交付的法律阻塞。
+
+**依据**：G1。`CONTRIBUTING.md` 与 `README.md` 都在讲如何贡献与使用，但没有许可证意味着**默认保留所有权利**，外部团队法务不会放行。
+
+**依赖**：无。需用户确认许可证类型（见下方决策点）。
+
+**路径**：`LICENSE`（新建）
+
+**步骤**：
+1. 确认许可证类型。若用户未指定，**默认 MIT**（与本项目"零依赖、鼓励复用"的定位一致），并在交付说明里标注"如需变更请告知"。
+2. 写入标准 MIT 全文，版权行为 `Copyright (c) 2026 Aurora Admin`。
+3. 在 `README.md` 增加 `## 许可证` 段，链接到 `LICENSE`。
+4. 在 `CHANGELOG.md` 的 `[Unreleased]` 下追加 `### Added — LICENSE`。
+
+**验收**：
+```bash
+# 文件存在且包含关键条款
+test -f LICENSE && grep -q "MIT License" LICENSE && grep -q "WITHOUT WARRANTY" LICENSE && echo "LICENSE OK"
+
+# README 有链接
+grep -q "LICENSE" README.md && echo "README OK"
+```
+
+**预期输出**：
+```
+LICENSE OK
+README OK
+```
+
+**失败判据**：任一条命令无输出，或 `LICENSE` 里出现非标准条款（自行增删免责声明）。
+
+**决策点（需用户输入）**：许可证类型。MIT 是默认推荐；若项目未来要商业化或要求衍生作品开源，应改 Apache-2.0 或 MPL-2.0。
+
+**✅ 完成（MIT，采用默认选择）** — 验收输出：
+
+```
+LICENSE OK
+README OK
+```
+
+同步改动：`LICENSE`（MIT 全文）、`README.md`（新增「许可证」段 + 版本号更新为 v1.4.1 + 指向本路线图）。
+如需改为 Apache-2.0 / MPL-2.0：替换 `LICENSE` 全文，同步 `README.md` 与未来 `package.json` 的 `license` 字段即可，无其他联动。
+
+---
+
+### S1-P2 · npm 分发 ｜ 预算 ~2 h ｜ 优先级 P0
+
+**目标**：`npm install aurora-admin-design` 能拿到令牌 + 组件样式；`<link>` 可直接引 CDN。
+
+**依据**：G2。当前用户只能 clone 整个仓库（5.1MB git + 2.6MB site），对"只想用几个组件"的人成本过高。
+
+**依赖**：S1-P1（package.json 需声明 `license` 字段）。
+
+**路径**：
+- `package.json`（新建）
+- `.npmignore`（新建）
+- `tools/build-dist.mjs`（新建，产出分发产物）
+- `dist/`（构建产物，加入 `.gitignore`）
+
+**步骤**：
+1. 建 `package.json`，关键字段：
+   ```json
+   {
+     "name": "aurora-admin-design",
+     "version": "1.4.1",
+     "description": "B 端中后台设计系统 · 79 组件 × 5 端 · 零运行时依赖",
+     "license": "MIT",
+     "main": "dist/tokens/tokens.css",
+     "files": ["dist/", "README.md", "LICENSE"],
+     "scripts": {
+       "build": "node tools/build-dist.mjs",
+       "test": "node tools/verify-dist.mjs"
+     },
+     "keywords": ["design-system", "admin", "css-variables", "design-tokens"],
+     "sideEffects": ["*.css"]
+   }
+   ```
+   **注意：不声明任何 `dependencies`** —— 这是硬约束。
+2. 写 `tools/build-dist.mjs`（Node ESM，零依赖），产出：
+   - `dist/tokens/tokens.css`、`tokens.json`（复用 `build-site.ps1` 的产出）
+   - `dist/components/<slug>.css` × 79 + `dist/components/index.css`（聚合）
+   - `dist/components/<slug>.html` × 79（静态演示）
+   - `dist/README.md`（用法速查，从主 README 节选）
+   - `dist/manifest.json`（组件清单 + 版本 + 文件校验和）
+3. 写 `.npmignore` 排除 `site/`、`tests/`、`frameworks/*.jsx|vue*`、`.github/`、`*.png`。
+4. 在 `README.md` 增加「安装」段，给出 npm / CDN / 直接下载三种方式。
+
+**验收**：
+```bash
+# 1) 构建产物齐全
+node tools/build-dist.mjs
+test -f dist/tokens/tokens.css && echo "tokens OK"
+test -f dist/components/index.css && echo "aggregate OK"
+test $(ls dist/components/*.css | wc -l) -ge 80 && echo "79 components + index OK"
+
+# 2) 无运行时依赖（硬约束）
+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"
+
+# 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')"
+```
+
+**预期输出**：
+```
+tokens OK
+aggregate OK
+79 components + index OK
+zero-dep OK
+pack contents OK
+css usable OK
+```
+
+**失败判据**：
+- `package.json` 出现任何 `dependencies`
+- `npm pack --dry-run` 输出含 `site/` 或 `tests/`
+- `dist/components/*.css` 少于 80 个
+
+**已知风险**：`npm pack` 需要网络（首次可能要求登录）。若无网络，跳过第 3 条验收并在交付说明注明。
+
+---
+
+### S1-P3 · CI 回归流水线 ｜ 预算 ~1.5 h ｜ 优先级 P0
+
+**目标**：每次 push/PR 自动跑回归，失败则阻止合并；结果可在 GitHub Actions 页面看到。
+
+**依据**：G3。当前只有部署 workflow，回归靠人工手动跑 `_collect.html`，质量随提交退化不可见。
+
+**依赖**：无（可与 P1/P2 并行）。
+
+**路径**：
+- `.github/workflows/regression.yml`（新建）
+- `tools/run-regression.mjs`（**已存在**，需改造为无网可用）
+
+**步骤**：
+1. 现状：`tools/run-regression.mjs` 依赖 `playwright`（npm 包），与"零依赖"约束冲突。
+   **解法**：CI 里允许用 `npx playwright`（CI 环境的临时工具，不进 `package.json` 的 dependencies），或用 `devDependencies` + 在文档说明"CI 专用，运行时不依赖"。
+   **推荐**：把 playwright 放进 `devDependencies`（这是构建期工具，不违反"零运行时依赖"）。
+2. 写 workflow：
+   ```yaml
+   name: Regression
+   on: [push, pull_request]
+   jobs:
+     test:
+       runs-on: ubuntu-latest
+       steps:
+         - uses: actions/checkout@v4
+         - uses: actions/setup-node@v4
+           with: { node-version: '20' }
+         - run: npm i -D playwright && npx playwright install --with-deps chromium
+         - run: node site/dev-server.js &
+         - run: sleep 3
+         - run: node tools/run-regression.mjs
+         - uses: actions/upload-artifact@v4
+           if: always()
+           with: { name: regression-report, path: tests/report*.json }
+   ```
+3. `run-regression.mjs` 需改造：目前是纯 Node 脚本，要确保它在 Linux 下也能找到报告输出路径（Windows 路径分隔符问题）。
+4. 增加失败阈值：`passRate < 100` 时 `process.exit(1)`。
+
+**验收**：
+```bash
+# 本地模拟 CI 步骤
+node site/dev-server.js & sleep 3
+node tools/run-regression.mjs
+echo "exit=$?"
+# 期望 exit=0 且 passRate=100
+```
+推送后在 GitHub Actions 页面确认 workflow 跑绿（需用户操作）。
+
+**预期输出**：
+```
+passRate 100% | pages 79 (all-pass 79) | assertions 925/925
+written: tests/report.json, tests/report-junit.xml
+exit=0
+```
+
+**失败判据**：
+- workflow 文件语法错误（用 `actionlint` 或 GitHub 页面报错验证）
+- 本地模拟跑出 `exit != 0`
+- `passRate < 100` 时没有 `exit 1`
+
+**已知风险**：`playwright install` 在 CI 上约需 1-2 分钟，可通过缓存加速（后续优化项）。
+
+---
+
+### S1-P4 · `data.js` 瘦身 ｜ 预算 ~3 h ｜ 优先级 P0
+
+**目标**：`site/data.js` 从 **991 KB 降到 < 150 KB**（实测可达成 ~110 KB）。
+
+**依据**：G6。实测 `data.js` = 1058 KB（传输量），占文档站总传输 **85%**。
+
+**已完成的诊断（无需重做）**：
+
+```
+data.json 体积构成（实测）
+  总计: 991KB
+  components   974KB  98.3%   ← 唯一大头
+  changelog     12KB   1.2%
+  tokens         5KB   0.5%
+
+components[] 内部（单组件）
+  .sources     15.7KB  ← 5 端源码全文
+  .contract     0.8KB
+  .specLines    0.2KB
+  .files        0.2KB
+  其余          <0.1KB
+
+全部组件 .sources 合计: 888KB（占 data.json 的 89.6%）
+```
+
+**结论**：`sources` 字段（5 端源码全文，仅供详情页代码区展示）占了 **89.6%**。把它移出 `data.js` 改为按需 fetch，`data.js` 降到 **~110 KB**（−89%）。
+
+**依赖**：无。
+
+**路径**：
+- `build-site.ps1`（改造产出：分文件写源码）
+- `site/app.js`（改造消费：按需 fetch + loading 态）
+- `site/sources/<slug>/<kind>.txt`（新增产出目录，79 × 5 = 395 个文件）
+- `site/data.js` / `site/data.json`（产出物，不手改）
+
+**步骤**：
+1. **改造 `build-site.ps1`**：
+   - 新增：把每个组件的 5 端源码写到 `site/sources/<slug>/<kind>.txt`（kind ∈ html/css/jsx/vue2/vue3）
+   - 修改：`data.js` 里 `components[].sources` 改为 `sourcesRef: "sources/<slug>/"`（只留路径，不留内容）
+   - **保持 `data.json` 完整**（For Agents 页承诺"一次请求拿到全部"，不能破坏 —— 这是硬约束）
+2. **改造 `app.js`**：
+   - 详情页渲染代码区时 `fetch('sources/<slug>/<kind>.txt')`
+   - 加 loading 态（复用现有 `.demo-code` 样式）
+   - 加失败兜底（fetch 失败显示"源码加载失败"+ 重试按钮，不留空白）
+3. **验证 For Agents 承诺未破**：`data.json` 仍然包含完整 `sources`。
+
+**验收**：
+```bash
+# 1) 体积达标（实测应约 110KB）
+node -e "
+const fs=require('fs');
+const core=fs.statSync('site/data.js').size;
+console.log('data.js:', (core/1024).toFixed(0)+'KB');
+if(core/1024 > 150) { console.error('FAIL: 超过 150KB 预算'); process.exit(1) }
+console.log('budget OK');
+"
+
+# 2) 源码文件已分离（395 个）
+n=$(ls site/sources/*/*.txt 2>/dev/null | wc -l)
+echo "sources files: $n"
+test "$n" -eq 395 && echo "split OK"
+
+# 3) data.json 未缩水（For Agents 承诺不变 —— 硬约束）
+node -e "
+const d=require('./site/data.json');
+const c=d.components.find(x=>x.slug==='button');
+if(!c.sources||Object.keys(c.sources).length!==5) { console.error('FAIL: data.json 的 sources 被破坏'); process.exit(1) }
+console.log('data.json intact OK');
+"
+
+# 4) data.js 里已无源码正文
+node -e "
+const d=require('./site/data.js')||{};
+" 2>/dev/null || node -e "
+const fs=require('fs');
+const s=fs.readFileSync('site/data.js','utf8');
+// 源码正文特征：不应再出现完整 HTML 文档
+if(s.includes('<!DOCTYPE html>')) { console.error('FAIL: data.js 仍含源码正文'); process.exit(1) }
+console.log('sources removed OK');
+"
+```
+浏览器实测：
+- 打开 `#/component/button`，代码演示区正常显示
+- Network 面板出现 `sources/button/html.txt` 请求
+- 断网/404 情况下显示兜底提示而非空白
+
+**预期输出**：
+```
+data.js: ~110KB
+budget OK
+sources files: 395
+split OK
+data.json intact OK
+sources removed OK
+```
+
+**失败判据**：
+- `data.js` > 150 KB
+- `site/sources/` 文件数 ≠ 395
+- **`data.json` 的 `sources` 字段被动过**（会破坏 For Agents 承诺）
+- 详情页代码区空白或报错
+
+**为什么不直接压缩**：gzip 能压到 ~200KB，但**解析时间**与**内存占用**仍在（1MB JSON 在低端机解析约 100-200ms）。且 Pages 默认已开 gzip，压缩不是增量收益。根治要减体积。
+
+---
+
+### S1-P4b · 首屏资源优化 ｜ 预算 ~2 h ｜ 优先级 P1
+
+**目标**：文档站首屏传输从 1247 KB 降到 **< 300 KB**。
+
+**依据**：P4 完成后 `data.js` ~110KB，但 `app.js` 101KB + `style.css` 40KB 仍是未压缩文本。
+
+**依赖**：S1-P4。
+
+**步骤**：
+1. `app.js`（101KB 单文件）按路由拆分：首页逻辑与详情页逻辑分离，详情页按需加载。
+2. 关键 CSS 内联（首屏可见部分），其余异步加载。
+3. 加入 `build-site.ps1` 的产出：`.min.js` / `.min.css`（用 Node 内置能力做简单压缩：去注释、去多余空白）。
+
+**验收**：
+```bash
+node -e "
+const fs=require('fs');
+const files=['site/data.js','site/app.js','site/style.css','site/i18n.js','.design_library/aurora-admin/colors_and_type.css'];
+const total=files.reduce((s,f)=>s+fs.statSync(f).size,0);
+console.log('首屏资源合计:', (total/1024).toFixed(0)+'KB');
+if(total/1024>300){console.error('FAIL: 超过 300KB');process.exit(1)}
+console.log('payload OK');
+"
+```
+
+---
+
+### S2-P5 · 暗色模式真正实现 ｜ 预算 ~1 天 ｜ 优先级 P0
+
+**目标**：`html.aa-dark` 下，**79 个组件的演示页**全部正常反色，对比度仍满足 WCAG AA。
+
+**依据**：G4。实测令牌层 `aa-dark` 规则 **0 条**、组件层 **0 条**，只有站点骨架 7 条。`CHANGELOG.md` 的 v1.1.1 条目称"暗色模式令牌映射补全"—— 这是第 6 次声称≠实现。
+
+**依赖**：S1-P4（体积优化后改 `app.js` 更清爽，非硬依赖）。
+
+**路径**：
+- `.design_library/aurora-admin/colors_and_type.css`（加暗色令牌组）
+- `site/style.css`（清理原有的 7 条临时规则）
+- `frameworks/*.html` 的内嵌样式（若需微调）
+- `tests/_runtime.js`（增加暗色断言）
+
+**步骤**：
+1. **设计暗色令牌组**（在 `colors_and_type.css` 里加 `html.aa-dark` 块）：
+   - 背景层：`page-bg` `#14161C` → `card-bg` `#1C1F26` → `table-header-bg` `#22262E`（三层递进）
+   - 文字层：`text-title` `#E8EAED` → `text-body` `#C9CDD4` → `text-secondary` `#9CA3AF` → `text-placeholder` `#6B7280`
+   - 边框：`border` `#2A2F38`、`border-strong` `#363B45`
+   - 品牌色：**向白提亮**（`#2F54EB` 在深底上对比度不足），推荐 `#5B7CF5` 系列
+   - 语义色：同样提亮（`#2E7D0A` → `#4CAF50` 一类）
+2. **每个色值都要算对比度**，写脚本验证（复用 v1.3.1 的方法）：
+   ```bash
+   node -e "
+   // 对每个暗色令牌算 WCAG 对比度，全部 ≥4.5:1（文字）或 ≥3:1（图标）
+   "
+   ```
+3. **演示页反色策略**：v1.4.0 的注释说"演示 iframe 保持浅色，避免样例反色失真"。这条策略要么：
+   - **A**：改成可配置 —— 站点暗色时演示页也反色（更真实，但要确保反色后不难看）
+   - **B**：保持浅色，但在设计规范页显式说明这是**有意设计**
+   **推荐 A**，因为用户开暗色就是想整体变暗，局部刺眼是体验倒退。若选 A，需给演示页传 `?theme=dark` 或用 `postMessage` 通知。
+4. **加断言**：`_runtime.js` 增加 `matrix:dark-contrast`，在暗色令牌下重跑对比度检查。
+
+**验收**：
+```bash
+# 1) 令牌组存在且完整
+grep -q "html.aa-dark" .design_library/aurora-admin/colors_and_type.css && echo "dark tokens OK"
+node -e "
+const css=require('fs').readFileSync('.design_library/aurora-admin/colors_and_type.css','utf8');
+const m=css.match(/html\.aa-dark\s*\{([^}]+)\}/s);
+if(!m){console.error('FAIL: 无暗色令牌组');process.exit(1)}
+const n=(m[1].match(/--au-/g)||[]).length;
+console.log('暗色令牌数:', n);
+if(n<15){console.error('FAIL: 令牌数不足（预期 ≥15）');process.exit(1)}
+"
+
+# 2) 浏览器实测（关键验收）
+# 打开 http://127.0.0.1:3311/site/index.html，切暗色模式，
+# 逐个打开至少 10 个组件详情页，确认无「白底黑字残留」
+```
+浏览器实测项：
+- 首页 / 总览 / 设计规范 / 组件详情 全部正常反色
+- 任意 10 个组件演示页反色后**对比度可读**
+- 截图对比（交付说明附 3 张暗色截图）
+
+**预期输出**：
+```
+dark tokens OK
+暗色令牌数: 20+（预期 ≥15）
+```
+
+**失败判据**：
+- 暗色令牌数 < 15
+- 任一页面出现"白底 + 白字"或"黑底 + 黑字"
+- 对比度脚本报出 < 4.5:1 的文字
+
+**已知风险**：79 个演示页的内嵌样式是**硬编码过令牌化**的（v1.4.0 完成），所以理论上改令牌就能全局生效 —— 这是 v1.4.0 打下的地基，本次直接受益。
+
+---
+
+### S2-P6 · 跨端一致性自动验证 ｜ 预算 ~1 天 ｜ 优先级 P0
+
+**目标**：能自动回答「H5 / React / Vue2 / Vue3 四个实现是否视觉一致」，并给出差异截图。
+
+**依据**：G5。5 端 395 个文件，但**从来没人验证过它们是否真的一致**。契约里写的"各端视觉一致"是纯声称。
+
+**依赖**：S1-P3（需要 CI 环境跑 Playwright）。
+
+**路径**：
+- `tools/verify-cross-platform.mjs`（新建）
+- `tools/render-harness/`（新建，把 React/Vue 组件渲染成静态 HTML）
+- `tests/cross-platform-report.json`（产出）
+
+**步骤**：
+1. **难点**：React/Vue 组件需要构建才能渲染（.jsx/.vue 不能直接在浏览器跑）。
+   **零依赖解法**：
+   - 方案 A：用 CDN 版 React/Vue（`<script src="unpkg.com/react">`）+ `@babel/standalone` 在浏览器里编译 JSX。缺点：依赖 CDN 可用性。
+   - 方案 B：**更推荐** —— 只做**结构性比对**而非像素比对。提取各端的 `className` 集合与 DOM 结构，比对差异。不要求渲染，纯静态分析。
+   - 方案 C：混合 —— 结构比对为主，挑选 6 个核心组件做像素比对（核心组件的 CDN 依赖可接受）。
+2. **推荐方案 B + 抽样 C**：
+   - 全部 79 组件：静态提取 class 集合与结构骨架，diff 各端
+   - 6 个核心组件（button/input/select/table/card/modal）：CDN 渲染 + 截图比对
+3. 输出报告：`{ slug, platforms: {h5:[...classes], react:[...], vue2:[...], vue3:[...]}, diffs:[...], severity }`
+
+**验收**：
+```bash
+node tools/verify-cross-platform.mjs
+node -e "
+const r=require('./tests/cross-platform-report.json');
+console.log('检查组件:', r.total);
+console.log('完全一致:', r.identical);
+console.log('有差异  :', r.differing);
+console.log('差异样本:', JSON.stringify(r.samples.slice(0,3),null,1));
+"
+```
+
+**预期输出**：一份报告，明确列出哪些组件的哪些端存在 class/结构差异。
+
+**失败判据**：
+- 脚本报错或无输出
+- 报告里 `total < 79`
+- 差异项没有具体说明（只说"不一致"而不给差异内容）
+
+**重要说明**：**这个任务的产出可能揭露一批真实的不一致**。这不是失败 —— 是这项任务的价值。发现的差异应作为新任务包列出，不在本任务内顺手修（避免范围蔓延）。
+
+---
+
+### S2-P7 · 行为断言 ｜ 预算 ~1.5 天 ｜ 优先级 P1
+
+**目标**：测试从"元素存在"升级到"交互后发生什么"，覆盖点击/输入/键盘的真实行为。
+
+**依据**：G8。当前 12 项/页断言多为结构性（元素存在、有 aria、对比度达标），**没有任何一条验证"点了按钮会怎样"**。
+
+**依赖**：无。
+
+**路径**：
+- `tests/_runtime.js`（扩展断言引擎）
+- `tests/_behaviors.js`（新建，行为断言库）
+
+**步骤**：
+1. 定义行为断言协议（在演示页里声明）：
+   ```html
+   <button data-behavior="click-toggles-class:.aa-modal|is-open">打开弹窗</button>
+   ```
+2. 实现常见行为模式：
+   - `click-toggles-class:<selector>|<class>` — 点击切换类
+   - `click-sets-attr:<selector>|<attr>|<value>` — 点击设属性
+   - `input-updates:<selector>|<text>` — 输入后状态变化
+   - `keyboard-activates:<key>` — 键盘触发
+   - `focus-trap:<container>` — 弹窗焦点锁定
+3. 在 6 个核心组件（button/modal/select/input/table/tabs）的演示页里标注行为断言作为试点。
+4. 断言结果并入现有报告结构（`matrix:behavior:*`）。
+
+**验收**：
+```bash
+# 1) 行为断言库存在且语法正确
+node --check tests/_behaviors.js && echo "syntax OK"
+
+# 2) 6 个试点组件有行为断言
+grep -l "data-behavior" frameworks/{Button,Modal,Select,Input,Table,Tabs}.html | wc -l
+# 期望输出 6
+
+# 3) 回归里出现行为断言
+# 跑 _collect.html，检查 report.json 的 failureKinds 含 matrix:behavior:*
+```
+浏览器实测：点击弹窗按钮后，`is-open` 类被添加（观察 DOM）。
+
+**预期输出**：
+```
+syntax OK
+6
+```
+
+**失败判据**：
+- 试点组件少于 6 个
+- 行为断言在回归报告里不出现
+- 断言只是"元素存在"换个名字（无实际交互逻辑）
+
+---
+
+### S3-P8 · RTL 支持 ｜ 预算 ~2 天 ｜ 优先级 P1
+
+**目标**：`<html dir="rtl">` 时布局正确镜像，无错位。
+
+**依据**：G7。逻辑属性 **0** 处，物理属性（`margin-left` 等）出现在 **22** 个文件。竞品 7 家里 3 家有 RTL。
+
+**依赖**：S2-P5（暗色完成后改样式更安全，减少冲突）。
+
+**路径**：
+- `frameworks/*.css`（22 个含物理属性的文件）
+- `frameworks/*.html` 内嵌样式
+- `.design_library/aurora-admin/colors_and_type.css`（如需要在文档说明约定）
+
+**步骤**：
+1. **批量迁移物理→逻辑属性**：
+   | 物理 | 逻辑 |
+   |---|---|
+   | `margin-left` | `margin-inline-start` |
+   | `margin-right` | `margin-inline-end` |
+   | `padding-left/right` | `padding-inline-start/end` |
+   | `left` / `right`（定位） | `inset-inline-start/end` |
+   | `text-align: left/right` | `text-align: start/end` |
+   | `border-left/right` | `border-inline-start/end` |
+2. **注意例外**：图标方向类（箭头、返回）需要 `transform: scaleX(-1)` 而非属性迁移。
+3. **写一个 RTL 演示页**：`site/scenario/user-management-rtl.html`，用于人工验收。
+4. 增加 RTL 断言：`matrix:rtl-safe`，检测是否还有物理属性的残留。
+
+**验收**：
+```bash
+# 1) 物理属性清零
+n=$(grep -l "margin-left\|margin-right\|padding-left\|padding-right" frameworks/*.css 2>/dev/null | wc -l)
+echo "剩余物理属性文件: $n"
+test "$n" -eq 0 && echo "RTL migration OK"
+
+# 2) 逻辑属性已使用
+grep -l "margin-inline\|padding-inline\|inset-inline" frameworks/*.css | wc -l
+# 期望 ≥ 22
+```
+浏览器实测：`user-management-rtl.html` 加 `dir="rtl"`，确认布局镜像无错位（附截图）。
+
+**预期输出**：
+```
+剩余物理属性文件: 0
+RTL migration OK
+22+
+```
+
+**失败判据**：
+- 仍有物理属性残留
+- RTL 下出现元素重叠/溢出
+- 图标方向错误（如右箭头在 RTL 下仍指右）
+
+---
+
+### S3-P9 · FAQ 页 ｜ 预算 ~1 天 ｜ 优先级 P2
+
+**目标**：新增 `#/faq` 页，自动聚合 139 条 `unknowns` + 101 条 `doNotInvent`，形成可检索的问答。
+
+**依据**：契约里已有 240 条结构化条目，**现成素材没被利用**。Ant Design 每组件 FAQ 是行业惯例。
+
+**依赖**：无。
+
+**路径**：
+- `site/app.js`（新增 `renderFaq`）
+- `site/index.html`（导航加 FAQ 链接）
+- `site/i18n.js`（文案）
+
+**步骤**：
+1. `build-site.ps1` 已把 contract 注入 `data.js`（字段 `unknowns` / `doNot`），直接消费即可。
+2. 渲染两种视图：
+   - **按组件**：每个组件列出它的 unknowns（"规范未明示"）与 doNotInvent（"不要自行发明"）
+   - **按分类**：把相似的 unknowns 聚类（如"最大宽度""省略方式"跨多个组件出现）
+3. 加搜索过滤（复用 `_runtime` 的思路，纯前端）。
+
+**验收**：
+```bash
+# 1) 路由可达
+curl -s http://127.0.0.1:3311/site/index.html | grep -q 'href="#/faq"' && echo "nav OK"
+# 2) 数据完整注入
+node -e "
+const d=require('./site/data.json');
+const u=d.components.reduce((s,c)=>s+((c.contract&&c.contract.unknowns)||[]).length,0);
+const dn=d.components.reduce((s,c)=>s+((c.contract&&c.contract.doNot)||[]).length,0);
+console.log('unknowns:',u,'doNotInvent:',dn);
+if(u<139||dn<101){console.error('FAIL: 契约数据缺失');process.exit(1)}
+console.log('data OK');
+"
+```
+浏览器实测：`#/faq` 显示 79 个组件的条目，搜索"宽度"能过滤出相关项。
+
+**预期输出**：
+```
+nav OK
+unknowns: 139 doNotInvent: 101
+data OK
+```
+
+**失败判据**：条目数少于 139/101，或页面空白。
+
+---
+
+### S4-P10 · Figma 资源 ｜ 预算 ~2 天 ｜ 优先级 P2
+
+**目标**：产出可导入 Figma 的变量集与组件描述，设计师能直接用同一套令牌。
+
+**依据**：竞品标配 Figma/Sketch 资源。本项目已有 `site/tokens/figma.json`（Tokens Studio 格式），但**没有 Figma Variables 原生格式**。
+
+**依赖**：S1-P2（需稳定的令牌导出管线）。
+
+**路径**：
+- `tools/export-figma.mjs`（新建）
+- `dist/figma/`（产出）
+
+**步骤**：
+1. 产出 **Figma Variables JSON**（与 Tokens Studio 格式不同，是 Figma 原生 API 格式）：
+   - 色彩变量 → `{ "color": { "brand": { "type": "COLOR", "value": {...} } } }`
+   - 数值变量（间距/圆角/字号）→ `FLOAT`
+   - 建立 Light / Dark **两种 mode**（呼应 S2-P5）
+2. 产出组件清单 Markdown（供设计师建组件时参考）：每个组件的变体维度 + 尺寸 + 状态。
+3. 写导入说明（`dist/figma/README.md`）。
+
+**验收**：
+```bash
+node tools/export-figma.mjs
+node -e "
+const v=require('./dist/figma/variables.json');
+const colors=Object.keys(v.color||{}).length;
+console.log('色彩变量:', colors);
+console.log('模式:', Object.keys(v.modes||{}).join(', '));
+if(!v.modes||!v.modes.Dark){console.error('FAIL: 缺少 Dark 模式');process.exit(1)}
+console.log('figma export OK');
+"
+```
+
+**预期输出**：
+```
+色彩变量: 24+
+模式: Light, Dark
+figma export OK
+```
+
+**失败判据**：无 Dark 模式、变量数明显少于令牌数、JSON 不符合 Figma Variables 结构。
+
+---
+
+### S4-P11 · 模板页库 ｜ 预算 ~2 天 ｜ 优先级 P2
+
+**目标**：从 1 个场景页扩展到 5 个典型后台页面模板，展示组件组合用法。
+
+**依据**：现有 `site/scenario/user-management.html` 是唯一的组合示范。模板页是"能否直接用"的关键 —— 用户要的不是组件，是页面。
+
+**依赖**：无。
+
+**路径**：`site/scenario/*.html`（新增 4 个）
+
+**步骤**：
+1. 选定 4 个典型场景（覆盖不同组件组合）：
+   - `login.html` — 登录页（输入类组件 + 表单校验）
+   - `dashboard.html` — 数据看板（图表 + 指标卡 + 表格）
+   - `order-list.html` — 列表管理（表格 + 筛选 + 分页 + 批量操作）
+   - `settings.html` — 设置页（Tab + 表单 + 开关组）
+2. 每个模板页只用现有令牌与 `components.css`，纯 HTML + 原生 JS（零依赖）。
+3. 加到首页入口与 sitemap。
+
+**验收**：每个模板页在浏览器实测可交互（筛选、分页、提交有反馈），附截图。
+
+**失败判据**：页面白屏、交互无效、用了非项目内的样式。
+
+---
+
+### S4-P12 · 版本发布流程 ｜ 预算 ~1 天 ｜ 优先级 P3
+
+**目标**：有明确的 SemVer 发布流程与自动化。
+
+**依赖**：S1-P2。
+
+**步骤**：
+1. `tools/release.mjs`：从 CHANGELOG 提取版本 → 更新 `package.json` → 打 tag → 提示推送。
+2. 文档化到 `CONTRIBUTING.md`。
+
+---
+
+## 四 · 风险登记
+
+| 风险 | 影响 | 缓解 |
+|---|---|---|
+| 约束冲突：CI 需要 Playwright，但"零依赖" | 中 | 明确区分**运行时依赖**（保持零）与**构建/测试依赖**（可引入 devDependencies），并在 README 写清 |
+| S2-P6 暴露大量跨端不一致 | 中 | 已在任务包里说明"发现即价值"，差异作为新任务列出，不顺手修 |
+| 暗色反色后视觉倒退 | 中 | 强制对比度脚本验证 + 人工截图验收 |
+| RTL 迁移破坏现有布局 | 中 | 迁移后跑八次回归；逐文件比对渲染截图 |
+| `data.js` 拆分影响 For Agents 承诺 | 高 | 明确要求 `data.json` 保持完整，只拆 `data.js` |
+| 用户未确认许可证类型 | 中 | 默认 MIT 并在交付说明标注"如需变更请告知" |
+
+---
+
+## 五 · 验收总纲
+
+任一任务包完成，必须同时满足：
+
+1. **给出验收命令的完整输出**（不是"我以为跑过了"）
+2. **跑八次回归**：`100% / 0 失败 / 0 超时`
+3. **`CHANGELOG.md` 有对应条目**（`[Unreleased]` 下）
+4. **本文件对应任务包下追加 `✅ 完成于 <commit-hash>`**
+5. **若发现新问题**：写成新任务包追加到本文件，不在原任务里顺手修
+
+---
+
+## 附 · 优先级总表
+
+| ID | 任务 | 阶段 | 优先级 | 预算 | 依赖 |
+|---|---|---|---|---|---|
+| P1 | LICENSE | S1 | **P0** | 10 min | 用户确认类型 |
+| P2 | npm 分发 | S1 | **P0** | 2 h | P1 |
+| P3 | CI 回归 | S1 | **P0** | 1.5 h | — |
+| P4 | `data.js` 瘦身 | S1 | **P0** | 3 h | — |
+| P5 | 暗色模式 | S2 | **P0** | 1 d | P4 |
+| P6 | 跨端一致性验证 | S2 | **P0** | 1 d | P3 |
+| P7 | 行为断言 | S2 | P1 | 1.5 d | — |
+| P8 | RTL | S3 | P1 | 2 d | P5 |
+| P9 | FAQ 页 | S3 | P2 | 1 d | — |
+| P10 | Figma 资源 | S4 | P2 | 2 d | P2 |
+| P11 | 模板页库 | S4 | P2 | 2 d | — |
+| P12 | 版本发布流程 | S4 | P3 | 1 d | P2 |
+
+**建议执行顺序**：P1 → P3 → P4 → P2 → P5 → P6（前六个是「可交付」与「可信」的地基）