root/aurora-admin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
16 Commits 2 Branches 0 Tags
c65a69c34e3cd9f58a464eee14ceb7133ff3eae7
Commit Graph
4 Commits
Author SHA1 Message Date
aurora-admin 16f365a045 feat: P4 阶段A+B — data.js 瘦身 116KB（预计算 + css 分离） 
执行 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 运行时场景提取结果逐字节一致
 2026-09-11 23:23:08 +08:00
aurora-admin f0e0d7ad1a docs: ROADMAP 细化（P4 依赖分析 / P2 前置验证 / 执行状态总览） 
趁执行模型未到，把规划里最可能导致走弯路的两个任务细化到函数级。

P4 依赖分析（关键）
- 实测 app.js 有 10 处消费 c.sources，分三类：
  · 类别 A（难点 2 处）：extractComponentAPI / extractScenarios 是
    渲染期同步解析源码，改 fetch 会波及详情页渲染流程
  · 类别 B（易改 3 处）：Playground / 代码展示
  · 类别 C（易改 2 处）：可用性判断，可用轻量字段替代
- 给出解法：把解析产物预计算进 data.js，这两个函数不再需要源码
- 体积成本实测：1.0 KB（原估 < 30KB，乐观 30 倍），净减 887 KB
- 附三阶段执行建议（先预计算+跑回归，再分离源码，最后验收）

P2 前置验证
- npm 可用：v11.17.0
- 包名 aurora-admin-design：registry 查询未被占用
- colors_and_type.css 含 :root 与 75 令牌，可直接作 dist 令牌源

新增「执行状态总览」
- 12 个任务的状态矩阵（已完成/可开工/待依赖）
- 当前 4 个可开工：P2、P3、P4、P7（后两个优先级低）
- 推荐顺序与理由：P3 第一（唯一让后续改动自动受保护的任务）、
  P4 第二（收益成本比最高）
- 指出并行机会：P2 与 P4 互不阻塞

新增「规划修正记录」
- 5 条已发生的规划修正，全部以实测为准
- 建立机制：执行中发现规划与实际不符时在此登记，不悄悄改

规划文档完整度：9 个章节齐全 / 1030 行 / 13 个任务包
回归：100%（961 断言 / 0 失败 / 79 页全通过）
 2026-09-11 22:50:11 +08:00
aurora-admin dd1e306c86 docs: AGENTS.md 执行约定 + 补全 ROADMAP 的结构性缺口 
补三处规划漏洞（自查发现，非用户指出）

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 页全通过）
 2026-09-11 22:47:51 +08:00
aurora-admin d88cdf2324 docs: 长期路线图（ROADMAP.md，12 个可执行任务包）+ 执行 P1 LICENSE 
规划师角色切换后的首份交付：把规划做成可交接工件，而非聊天里的建议。

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 页全通过）
 2026-09-11 22:40:10 +08:00