aurora-admin/CHANGELOG.md

Changelog

所有显著改动按 SemVer 记录于此。格式基于 Keep a Changelog。

[Unreleased]

Design system · 组件族参数化：79 个并列组件 → 48 个概念组件（S6-P21）

• 问题：79 个并列组件里有 44 个是同源变体，却各自手写了一遍。导航最典型——topmenu / sidemenu / mixednavigation 三份实现，差异只是"一级菜单横排还是竖排"；规范契约自己就写着从属关系：alertmodal 与 confirmmodal 的 doNotInvent 原文是「弹窗尺寸档位（见 Modal 契约）」，steps 与 steplist 的 semanticTypeCandidates 完全相同（均为 steps|wizard）。并列表达让消费方看到 6 个表格组件，而它们实际是「一个 Table + 一个 feature 参数」。
• 新增族层（纯追加，不破坏任何既有承诺）：新增 .design_library/aurora-admin/families.json；data.json 增顶层 families 与每组件 family / familyRole / familyParams；site/details/<slug>.json 同步三元组。13 族 / 44 成员 / 35 个独立组件；data.json 仍完整输出 79 个组件，slug 集合逐一不变（铁律 5）。
• 归族判据可核对，不按名字猜：每族在 tools/lib/family-model.mjs 里必写 mergeBasis，依据是契约中四类可核对字段——semanticTypeCandidates 重叠、anatomy 为同一骨架的子集、变体维度同构、doNotInvent 的显式从属声明。
• 实现层合并（导航族端到端切片）：tools/gen-family-impl.mjs 从 tools/lib/family-impl/nav-menu/ 的 5 端模板生成 TopMenu / SideMenu / MixedNavigation 共 15 个文件，参数为 direction=top|side|mixed。三份 CSS 的 md5 完全相同——一份样式表服务三个组件；改模板 + 重跑即三端同步，不再存在"改了 topmenu 忘了 sidemenu"。
• 为什么是「生成」而不是「抽共享模块」：tools/pack-deploy.mjs（薄壳 79 / 实现 395）、tools/precompute.mjs（79 / 395）、tools/verify-cross-platform.mjs、tools/verify-package-import.mjs 四处硬断言文件数与导出数。抽跨文件 import 会同时打破它们，并失去"单文件可拷贝"。生成把重复消除在源头，而不改动文件图。
• 生成器护栏：目标文件有未提交改动、且不含生成物标记时拒绝覆盖（除非 --force）——防止把工作区里没提交的手工调整冲掉。
• 跨端口径（两个数必须分开说，免得把自己的改动说大成整体改善）：已提交 HEAD 为 identical 2 / differing 77 / high 44；本任务改动前的工作区已是 79/79（既有未提交改动先清了跨端漂移）；本任务改造后仍为 identical 79 / differing 0，与工作区持平。中途曾掉到 76/79：族模板最初把方向写成对象字面量 { direction: 'side' }，Vue 端 class 提取器会把其中的字符串值收作变体记号、H5/JSX 端不会。探针实验确认成因后改用独立常量 FAMILY_DIRECTION 承载方向，四端回到 79/79——是改代码对齐既有约定，未放宽校验脚本。提取器本身的不对称仍未修，已登记 ROADMAP S6-P22。
• 顺带修掉一处既有 RTL 不一致：MixedNavigation.css 原文件同时写 border-inline-start 与 border-left-color（逻辑属性与物理属性混用，RTL 下两侧指示条表现不一致）；族模板统一为逻辑属性。
• 验收：族层 node tools/verify-families.mjs → OK: 族层端到端一致（13 族 / 44 成员 / 79 组件不变 / 395 文件不变），退出码 0；node tools/gen-family-impl.mjs --only=nav-menu 幂等（重跑 0 写入）；回归 100%（79/79 页，1017/1017 断言，N/A 34）连跑 8 次一致、0 超时；零运行时依赖不变（dependencies 为空）。

Package · 发布到私有 npm 源（可直接 npm install）

• 发布位置：自建 Gitea 的 npm registry https://gitea.mymoyu.top/api/packages/root/npm/（Gitea 27.3.1），匿名可读——实测无凭据 npm view / npm install 均成功。

• 已发布 3 个可互换的包名（内容一致：三端入口各 79 组件 + 令牌 + 组件样式）：

  包名	用途
  @root/ui	推荐：scoped 名，项目 .npmrc 写一行 @root:registry=… 即可，其余依赖仍走公共源
  chunyu-ui	非 scoped 别名，需 --registry= 显式指定源
  aurora-admin-design	仓库原名，同上

• 踩到的坑（已写进 README）：非 scoped 包不能用 @包名:registry= 写法——该语法只对 scoped 名生效，实测报 404。故推荐 scoped 名 + 一行 .npmrc。

• 端到端验证：建 Vite + Vue 3 工程，.npmrc 一行配置 + npm install @root/ui（公共依赖同时走公共源）→ vite build 通过（169 模块）→ 浏览器实测：AaButton 渲染、品牌色 rgb(47, 84, 235) 生效、AaTag 正常、点击计数交互正常、0 JS 报错。

• 未发布到公共 npm：本机无 npm 凭据（npm whoami → ENEEDAUTH，无 ~/.npmrc、无 token 环境变量），npm publish 到 registry.npmjs.org 被拒。公共 npm 上 chunyu-ui / aurora-admin-design 均未被占用（可用），是否发布待定。

• README 增补「从私有 npm 源安装」段（含正确的 .npmrc 写法与三端 import 示例）。

Docs site · 导航语言选择改为下拉（S5-P19）

• 问题：顶栏语言控件是「中 / EN」双段按钮——11px 圆角、28px 高、靠 2px 字号差和品牌色表示当前语言。两个语言标签同时高亮显示，当前语言靠粗细区分，一是看不出「点了会怎样」（无展开暗示），二是与旁边 34px 的框架选择器、搜索框不同高，三是纯鼠标控件：没有 aria-haspopup、没有键盘路径。
• 改为下拉选择：触发器 = 地球图标 + 当前语言名（简体中文 / English）+ 箭头，34px 高与相邻控件齐平，展开时箭头旋转 180°、边框转品牌色并带聚焦环；菜单 186px 卡片，含「界面语言」标题分隔线、语言名 + ZH/EN 角标 + 选中对勾，8px 顶栏令牌阴影。
• 交互与无障碍：role="listbox" + aria-selected + aria-expanded；点击展开/收起、点击外部关闭、Esc 关闭并回焦触发器、↑/↓ 循环移动、Home/End 跳首尾、Enter/Space 选中、Tab 关闭且不抢焦点；选中后触发器重新获得焦点。语言名始终以该语言自身书写（简体中文 / English），不随界面语言翻译。
• 令牌与暗色：颜色/圆角/阴影全部走 --au-* 令牌，未新增任何硬编码色值；暗色模式实测菜单底色 rgb(28,31,38)，选中项对比度 4.57、菜单标题 6.50、触发器 4.57（均 ≥ 4.5）。prefers-reduced-motion: reduce 下关闭菜单动画与箭头过渡。
• 窄屏：≤1100px 收起语言名（触发器 56px，与旧控件同宽）。实测改动前顶栏在 1024px 溢出 13px、900px 溢出 9px（旧控件同样外露），现 ≥860px 全部为 0；≤820px 的溢出与语言控件无关，已登记为 ROADMAP S5-P20。
• i18n：新增 界面语言 / 选择语言 两条，移除随之作废的 切换到简体中文 / 切换到英语（原按钮的 aria-label），一进一出净增 0 条。
• 验收适配（验收命令本身随控件形态更新，判据强度不变）：tools/verify-i18n.mjs 的两条静态检查改指新 id/绑定，并新增「旧控件不得残留」检查；tools/run-site-smoke.mjs 的点击路径改为「开菜单 → 选项」，并补 8 条下拉行为断言（aria-expanded、Esc、方向键、焦点回位、选中态、触发器文案）。
• 回归 100%（79/79 页，1017/1017 断言，N/A 34），连跑 8 次一致；smoke:site 30/30；verify:i18n 16/16；verify:theme、verify-dark、verify-site-routing 全过；零运行时依赖不变。

Package · 三端可 import（组件库真正可用）

• 问题：dist/ 只发 CSS 与演示 HTML，package.json 的 main 甚至指向一个 CSS 文件，没有任何可 import 的组件——import { AaButton } from 'aurora-admin-design/vue3' 这类标准用法不成立。S1-P2 的任务范围写的是「能拿到令牌 + 组件样式」，因此这是范围缺口而非实现错误（已按 AGENTS 第五节登记为 ROADMAP S5-P18）。
• 新增三端聚合入口：dist/react/index.js、dist/vue3/index.js、dist/vue2/index.js（各导出 79 个 Aa* 组件）+ 单组件源码。组件以 .vue / .jsx 源码发布，由宿主构建链编译（无额外编译产物与源码不同步的风险，且保持零构建依赖）。
• package.json：补 exports 映射（. / ./tokens.css / ./components/* / ./react / ./vue3 / ./vue2 / ./manifest.json）与 peerDependencies（react >=17、vue >=2.6，均为 optional）。
• 修掉两个「组件无法编译」的真实缺陷（此前从未被发现，因为从未真编译过）：
  • RangeQuickPicker 的 presetRange 给 const start / const end 重新赋值 → React 与 Vue 3 两端都无法编译；已改为 let 并与 Vue 2 参照实现对齐（start 改为 new Date(...) 而非 setMonth/setDate 就地修改，行为一致）。
  • CodeInput.vue3.vue 内 function emit() 遮蔽了 const emit = defineEmits(...) → 重复声明，编译失败；已重命名为 emitChange()。
• 样式随包发布：56 个组件的 Vue 两端用 <style src="./<Prefix>.css"> 引用外部样式、79 个 JSX 用 import './<Prefix>.css'。打包时把同名 CSS 一并放入 dist/react|vue3|vue2/，否则会出现「import 成功但样式全丢」。断链检查已纳入验证脚本。
• 新增 tools/verify-package-import.mjs：结构级（入口/断链/exports/零依赖，15 项，零依赖可跑）+ 编译级（esbuild + @vue/compiler-sfc 真编译 79 个 SFC、vue/react SSR 真渲染 AaButton 断言 DOM，5 项）。编译级依赖可用 AA_VERIFY_DEPS_DIR 指向隔离目录，避免污染仓库 node_modules。
• 端到端验证（真实工程，非模拟）：分别建 Vite + Vue 3 与 Vite + React 工程，以 file: 依赖真实 npm install 本包，只写 README 里的那几行 import → vite build 通过（Vue 170 模块 / React 189 模块），浏览器实测：组件真渲染、品牌色 rgb(47, 84, 235) 生效（证明令牌与样式链正确）、loading 态 disabled 与 spinner 正确、点击交互正常、0 JS 报错。
• 回归 100%（79/79 页，1017/1017 断言，N/A 34）；S1-P2 原始验收命令（tokens/aggregate/79+index/zero-dep/css usable/pack contents）全部仍通过。

Docs site · 组件详情页代码块默认展开（含修复异步填充漏填）

• 组件详情页源码区改为默认展开：demo-strip 初始态由折叠改为展开，进页面即可看到当前框架源码，省掉一次点击；展开条箭头与提示文案随状态同步（▲ 收起代码 / ▼ 展开代码）。
• 修复既有缺陷（默认展开后被放大）：源码异步加载后的填充回调签名错位——listenSrc(slug + '/' + kind, fillCode) 直接传函数，而 notifySrc 的回调签名是 (text, error)，于是源码文本被当成 kind 与 'html' 比对，永远不相等，首次展开的代码区一片空白（实测全新加载展开后字符数 0，离开组件再回来才有内容）。已改为闭包绑定 kind；并新增 codeWrap.__fillCurrent()，在代码区插入 DOM 后补填一次（命中内存缓存时源码是同步取得的，插入前填充会被 isConnected 守卫跳过）。
• 浏览器实测（本地 dev-server）：首次进详情页即展开且有内容（cascader 7713 字符）、切到未访问组件自动填充（tree 5159 字符）、切 CSS tab 正常（1067 字符）、折叠再展开内容保留、0 JS 报错。
• 回归 100%（79/79 页，1017/1017 断言，N/A 34），文档站冒烟 ×2 全过。注：当日连跑 27 次中 2 次出现 1016/1017 的偶发失败，tests/*.html 不加载 site/app.js（grep 计数 0），与本改动无关；因 tests/report.json 不记录是哪条断言失败，已立任务包 S5-P17 追踪可追溯性。
• 顺带修掉「部署了但浏览器还在跑旧版」：nginx.conf 之前没有任何 Cache-Control，浏览器对 app.js 走启发式缓存——实测重新部署后页面仍执行旧 app.js（同一页面内 fetch 能取到新版、<script src="app.js"> 却用缓存，duration=0）。已在 server 级统一加 add_header Cache-Control "no-cache" always;：每次带 If-None-Match 重新校验，未变更返回 304（实测 app.js 带 ETag 请求 → 304），开销极小但部署立即生效。

Security · 生产部署链审计修复（2026-09-19）

• 规范原文泄漏（根因）：.dockerignore 里 *.md / *.ps1 / *.yml / *.png 等 glob 在 Docker 下只匹配构建上下文根目录，嵌套路径全部失效（真实构建实证：sub/nested.md 仍进镜像）。改为 **/ 前缀并补齐嵌套 glob；.design_library/aurora-admin/{specs,agent-reports,preview,ui_kits} 与嵌套 *.md 实测不再进入镜像（修复前线上 GET /.design_library/aurora-admin/specs/组件1.txt → 200 / 8623B）。
• nginx.conf 加固：补 absolute_redirect off;（根路径 302 曾丢失宿主端口 :3311 落到无服务的 :80）、server_tokens off;、与 site/dev-server.js 逐字一致的 CSP 及 X-Content-Type-Options / Referrer-Policy / Permissions-Policy / X-Frame-Options；/healthz 改用 default_type 修掉重复 Content-Type。
• Dockerfile：补 COPY sitemap.xml（修复前生产 /sitemap.xml → 404）。
• site/dev-server.js：修复单个 GET /site/%00 触发 ERR_INVALID_ARG_VALUE 未捕获异常打挂进程的问题——新增编码形态与解码后 NUL 双重拦截、fs.readFile try/catch；白名单、安全头、302/404 行为保持（92 条合法路径 status / content-type / 字节级一致）。新增 AA_PORT 开关（默认仍 3311）供验证脚本隔离端口。
• 消除动态求值 sink：site/app.js 与 tools/precompute.mjs 原先把 defineEmits([...]) 字面量交给函数构造器求值（实测 defineEmits([1,globalThis.__pwned='x']) 会真的执行；构建期同源 → 可打穿 CI）。改为只解析字符串字面量的 parseStringLiteralArray（构建期实现独立成 tools/lib/parse-string-literal-array.mjs），非字面量元素整体拒绝返回 null。等价性：158 个 frameworks/*.vue 双实现抽取结果不一致 0（54 处字面量 / 96 条事件名）。
• 新增验证脚本 tools/verify-dev-server.mjs（20 checks，含 3 条修复前必失败的反例断言）与 tools/verify-emits-parse.mjs（17 checks，含构建期副本漂移门）。
• ⚠️ 规划修正：PLAN.md §8「不改 site/dev-server.js（已工作良好）」的立论已被实测推翻，按 AGENTS.md 第五节「以实测为准」处理并在此标注。
• 回归：100%（79/79 页，1017/1017 断言，N/A 34），连跑 9 次一致，0 超时；主 agent 另独立复跑 1 次亦 100%。

Deploy · 线上部署（2026-09-19）

• 新增 tools/pack-deploy.mjs：以 .dockerignore 为唯一真源打包部署目录（实现 Docker 的匹配语义，含「*.md 只匹配根目录」这一实测结论），带硬断言（规范原文/agent-reports/preview/ui_kits 绝不出现；站点运行必需文件必须出现；薄壳 79、实现文件 395）。部署配置文件（docker-compose.yml 等）始终保留——.dockerignore 只管镜像构建上下文。
• 按 AGENTS §九 流程首次实际部署到 192.168.5.7：备份 → 解到暂存目录核对 → 替换 → docker compose build && up -d（回滚目录 /opt/aurora-admin.pre-audit-20260919-0609）。
• 部署后验收：specs/组件1.txt、agent-reports/*、嵌套 SKILL.md/README.md → 404；sitemap.xml → 200；tests/report.json → 200（首页通过率角标恢复数据源）；根路径 302 → Location: /site/（相对，不再丢端口）；Server: nginx 无版本号；CSP 等 5 条安全头齐备且 /healthz 只 1 条 Content-Type；396/396 条 sitemap URL 全部 200；容器 healthy。
• 顺带消除历史漂移：线上组件文件由 09-06 快照更新为当前工作树（此前后者与线上有 288 个文件不一致）。
• 决策：暂不对外公用 —— 保持 127.0.0.1:3311 回环访问（需 SSH 隧道），不加反代/域名/认证；容器运行期加固与对外承诺口径统一另立任务包（ROADMAP S5-P14/P15/P16）。

Theme modes · 日间 / 夜间 / 自动

• 文档站主题选择扩展为 light / dark / auto 三态；自动模式跟随 prefers-color-scheme 并监听系统主题变化。
• 新增可访问的主题模式菜单、跨标签页 aa-mode 同步和 iframe 主题同步。
• ThemeSwitcher H5 / React / Vue 2 / Vue 3 统一 auto 模式枚举与 ARIA 语义。

Fixed — 文档站中英切换完整性

• 修复语言切换后相关组件、主题面板、搜索分类与详情目录仍显示初始语言的问题。
• 补齐加载态、重试、契约详情等动态文案的英文词典覆盖，并为顶栏切换器补充无障碍名称与状态。
• 新增 tools/verify-i18n.mjs 静态校验与 tools/run-site-smoke.mjs 浏览器冒烟测试。

S3-P9 · 契约缺口解释层

• 为 Card 契约的 doNotInvent / unknowns 增加结构化解释：分别说明设计边界、开放问题、出现原因与待确认决策。
• 组件详情页明确区分“不要自行发明（设计边界）”与“规范未明示（待确认）”，不把现有实现值冒充正式规范。
• 保持 hover 行为与卡片网格间距待定，未擅自写入 16px/24px 或固定状态规则。

S2-P7 · 行为断言（6 试点全绿）

• 新增 tests/_behaviors.js：8 动词（click-toggles-class/click-adds-node/click-removes-node/click-sets-attr/input-clears/input-filters/keyboard-activates/tab-switches）+ @input 相对定位 + @doc 全文档查询 + 同步 pump + page-load 幂等缓存；_runtime.js 聚合 + 重载清缓存；_template.html 引入；6 演示页 data-behavior 标注；79 测试页重生成。
• 全量回归：100%（79/79 页，1009/1009 断言，N/A 35）。关键修复：runner 兜底重跑导致行为断言第二轮误报，加缓存解决。

S3-P8 · RTL 支持（28 文件迁移）

• 新增 tools/migrate-rtl.mjs（白名单 dry-run/--write 双模式）：margin/padding/border-inline + text-align start/end；剩余物理属性 0（排除例外）；逻辑属性文件 19；三代表页 RTL 零溢出零错误。
• 人工例外 14 处：margin-left:auto（3）、拼接边框（5）、left:0+right:0 并存（4）——不机械替换。

S2-P9 · FAQ 页（details 懒加载版）

• 新增 #/faq 页：自动聚合 79 组件契约的 unknowns（139）+ doNotInvent（101），共 240 条；按组件分组 + 关键词搜索过滤 + 命中统计；顶栏/侧边栏双入口；9 条 i18n 英文。
• 浏览器实测：groups 80/items 240，搜索“宽度”命中 11 条/11 组，清空恢复 240，0 JS 错误。
• 规划偏差：契约已在 P4 阶段 D 移出 data.js，FAQ 改走 details/*.json 批量懒加载（每批 10 个）而非直接消费 data.js。

S4-P12 · 版本发布流程

• 新增 tools/release.mjs：检查模式（package.json vs CHANGELOG 版本一致性 + Unreleased 提醒）与 --bump major|minor|patch --date 提升模式；只做本地准备，tag/push 由人执行。
• CONTRIBUTING.md 新增发布流程 5 步 + 版本号规则（major/minor/patch 判定）。

S2-P6 · 跨端一致性自动验证（方案 B：静态结构比对）

• 新增 tools/verify-cross-platform.mjs（零依赖零联网）：79 组件 × 4 端（H5/React/Vue2/Vue3）class 集合 + 结构骨架双 diff，演示包装类/变量名/模板残留降噪，high/medium/low 分级；产出 tests/cross-platform-report.json（79 条全量 + samples 3）。
• 实测：完全一致 2，有差异 77（high 44/medium 22/low 11）。high 主因：React 端 is-disabled/is-active 缺失、H5 演示页缺框架端结构类、Tag/Select/Input 变体类缺失——已追加为 ROADMAP 的 S2-P6-F1～F4，不在本任务内修。
• 回归零影响：tests/report.json 79/79、site/data.json 79 组件均未动（脚本只读消费）。

S2-P5 · 暗色模式真正实现（选型 A：演示页随站点同步反色）

• 令牌文件新增 html.aa-dark 组（31 个 --au-，≥15 达标）：背景三层递进、文字四层、品牌/语义色向白提亮；10 项文字对比度全部 ≥4.5:1（脚本实测）。
• site/style.css 暗色块精简为结构样式（令牌值收归令牌文件，删旧内嵌值与“演示页保持浅色”规则）；site/app.js 删死代码 DARK_TOKENS，injectIframeTheme 同步 aa-dark 类到演示 iframe。
• 附带收敛：演示壳裸类 .aa-page/.aa-h2/.aa-desc（26 页用而无定义）在令牌文件补令牌定义；table.html loading-mask、Tag.css 红/橙标签加暗色覆盖。
• 新增 tools/verify-dark.mjs 独立验证（32 断言：令牌组 2 + 对比度 10 + 10 页浏览器实测 20），不进 _runtime 计数。
• 首屏预算 292KB（< 300KB）；回归 1003/1003（pass 1003/fail 0/skip 35）零影响。

S1-P4 · data.js 瘦身（已完成 c65a69c）

• data.js 991KB → 98KB（预计算 API/场景 + 源码分离到 site/sources 395 文件），data.json 保持完整（含 5 端 sources）。
• 首屏资源合计 291KB（< 300KB 预算，S1-P4b 验收已达标，无需拆分 app.js）。
• 回归 1003/1003 全绿（79 页全过，N/A 35）。
• ROADMAP 状态：P4 已完成，P5（暗色模式）为下一版本首选。

[1.4.1] - 2026-09-11

审计轮 — 系统性质疑「这么多组件能保证不出错吗」

结论：不能保证零错误。79 组件 × 5 端 × 79 契约 × 326 译文，靠肉眼和声称都不成立。因此改为四轮机器审计 + 实测，把「我检查过了」替换成可复现的数字。

审计 1 · 契约保真度（358 条 usageHints 回规格原文核对）

• 逐字命中 336 条（93.9%）；剩余 22 条经人工比对为同义改写（如「列表项带复选框」→「列表项带复选框，项高 32px」，数值确实在规格别处），非发明。
• 发现一处真实不一致：rate.json 的选中星色仍写 #FAAD14，而规格已在 v1.3.1 改为 #2F54EB —— 修契约使其与规格同步（usageHints + anatomy）。

审计 2 · 令牌语义正确性

• 检查 1313 处含令牌的颜色声明，0 处属性/令牌角色错配（未出现「background 用文字色令牌」这类）。令牌化在语义上是干净的。

审计 3 · i18n 翻译质量

• 326 条字典：英文值含中文 0 条、中英完全相同 0 条、长度异常 0 条。
• 修正审计脚本对「副名」的误判：英文模式下 .core-en 显示中文是设计意图（主名英文 + 副名中文），不是漏翻。
• 发现并修复 4 处真漏翻：guide 页标题、Do/Don't 两个标题、guide 表格 H5 静态页、组件名渲染 4 处未做语言感知。

审计 4 · 废弃色值残留

• 扫描 91 个文件，发现 4 个文件 23 处仍引用 v1.3.1 之前的旧色值。
• 最严重：css.json —— 它是 For Agents 页宣称的「结构化令牌源」，机器读取方会拿到过时的颜色。已同步 10 处。
• README.md 设计说明 5 处同步；CHANGELOG.md 的旧值属历史变更记录，有意保留。

修复 · 低对比度图标

• 用「逐元素实测对比度」扫全部页面，发现 Rate 未选中星用 --au-color-border(#E8ECF1) 作星色，白底仅 1.19:1 —— 边框色是装饰性色值，作图标不合格。
• 新增 --au-color-icon-inactive: #8F8F8F（白底 3.23:1，满足 WCAG 1.4.11 的 3:1，且视觉最克制）。令牌 74 → 75。
• 同批扫出的另外 5 处低对比度经逐一核实为禁用态（WCAG 1.4.3 豁免）或深色遮罩上的白字（检测器把半透明底当白底），非缺陷。

修复 · 回归偶发（第三次根治）

• 现象：多次连跑偶发 99.9%（1 页失败），但单独打开该页总是通过。
• 根因：收集器的 8 秒超时兜底直接记为 fail: 1。并发 4 个 iframe 时主线程被抢占，慢页面会撞上超时。
• 修法：超时阈值 8s → 12s；重试一次后再判定；超时与断言失败分开统计（timedOut 字段，不计入通过率分母）。
• 验证：八次连跑全部 100% / 0 失败 / 79 页全通过 / 0 超时。

[1.4.0] - 2026-09-11

Changed — 组件层全面令牌化（设计系统的根基修复）

• 发现：79 个组件的 844 个颜色属性里，只有 2 个（0.2%）引用令牌，788 个（93.4%）硬编码 hex。后果是改令牌组件不跟着变、主题定制器对组件无效、For Agents 页写的「所有色值必须取自 au-* 变量」形同虚设。这是本项目第五次「声称≠实现」，且动摇了设计系统的根本。
• 两层令牌化（此前只改了从未被加载的文件，走了弯路）：
  • 组件样式表（frameworks/*.css）：915 处 / 78 文件
  • 演示页内嵌 <style>（实际生效的样式层）：287 处 / 51 文件
• 内嵌样式层是决定性的：演示页只 link colors_and_type.css + 自己的 CSS，而多数页面把关键样式写在 <style> 块里 —— 只改 CSS 文件不生效。
• 安全策略：只替换颜色属性值位置的 hex（color / background* / border* / outline* / fill / stroke）；跳过 rgba()/渐变/url() 复合值；不动 SVG 属性与 JS 数据（色板数组）；幂等可重复运行。
• 歧义色值按属性语义消解（#FFFFFF 作 color → text-inverse，作 background → card-bg）。

Added — 补齐令牌语义

• --au-color-text-tertiary #595959（三级文字/描述，规范未定义、实现补齐，7.00:1）
• --au-color-text-disabled #BFBFBF（禁用态文字，规范定义于组件1/2.txt；WCAG 1.4.3 对禁用控件豁免）
• --au-color-border-strong #F0F0F0（实线边框，规范未定义、实现补齐）
• 令牌总数 71 → 74；同步 legacy 别名映射（--color-text-tertiary 等）。
• 修复 colors_and_type.css 一处重复的注释起始行。

Fixed

• Countdown 首帧空白：setInterval(render, 1000) 首次执行要等 1 秒，期间容器为空。改为定义 renderCountdown() 后立即执行一次，再挂 interval。浏览器实测确认修复。

Verified — 令牌响应性（本轮核心验收）

• 逐组件验证「改令牌 → 元素是否跟着变」，79/79 全部响应（改 --au-color-brand / text-body / border 等，采样前后样式签名对比）。
• 过程中修正了两处测量方法缺陷（初测 40/79 是误报）：① 选择器 .demo * 在无 .demo 容器的页面抓不到元素；② 探针令牌选错——Breadcrumb 用 text-tertiary 而我只改 text-body。
• 回归保持 100%（961 断言 / 0 失败 / 79 页全通过），三次连跑一致。

[1.3.3] - 2026-09-11

Added — 中英双语（i18n）

• site/i18n.js：330 条文案字典，顶栏新增 中 / EN 切换器，偏好存 localStorage['aa-lang']，<html lang> 与 document.title 同步。
• 设计取舍：以「中文源串」作字典键而非抽象 key。中文是规范原文语言（组件1~10.txt）也是 app.js 现有字面量；源串作键意味着未收录文案自动回退原文，不会出现空白或 key 泄漏。
• 覆盖范围：导航 / 侧栏 / 首页 Hero 与设计原则 / 总览 / 快速开始 / 设计规范（含令牌导出区）/ For Agents 全表 / 更新日志 / 组件详情页（何时使用、API 三表、无障碍键盘表、Do&Don't、设计契约、实现资源、相关组件）/ Playground / 主题面板 / 搜索弹窗 / FAB 提示。
• 语言感知的显示逻辑：
  • 组件名主次调换（中文模式主显中文名，英文模式主显英文名），详情页大标题不再重复；
  • 侧栏分类名走 CAT_EN，不占字典；
  • 动态生成的键盘表、插槽说明按语言重算。

Fixed — 回归时序（根治偶发）

• DensitySwitcher 对比度偶发失败：断言在演示页内联脚本执行完之前就跑了，读到 is-active 尚未应用的中间态（白字未落到品牌蓝底 → 2.51:1）。单页打开时通过、并发收集器里偶发失败。
• 根因是固定帧数等待（load + 双 requestAnimationFrame）在多个 iframe 抢主线程时不够稳。改为就绪轮询：readyState === 'complete' 且 DOM 连续 3 次采样（约 48ms）无变化才断言，另设约 4.8s 超时兜底避免卡死。
• 验证：四次连跑全部 100%（961 断言 / 0 失败 / 79 页全通过），偶发不再复现。

Fixed — i18n 接入过程中的三个真实缺陷

• TDZ 顺序：KIND_KEYS 等模块级常量在 I18N/T 定义之前调用了 T()，抛 Cannot read properties of undefined (reading 'T')。已改为存中文源串、渲染时求值（模块级预先求值还会导致语言切换后不更新）。
• 局部变量遮蔽：renderDesign 内原有 var T = data.tokens; 遮蔽了全局翻译函数，导致设计规范页整个渲染失败。改名 TOKENS。
• 模板拼接括号：el() 调用在包装 T() 后少一个右括号，已修正。

Changed

• 回归基线：961 断言 / 925 通过 / 100% / 79 页全通过 / N/A 36，四次连跑一致。

[1.3.2] - 2026-09-11

Added — 契约第三批：全量契约化 79/79

• 补齐剩余 43 份组件契约，components/ 目录现为 79 份契约 JSON（此前 36）。
• 分两批提炼，全部逐字来自规格原文（组件1/2/5/6/7.txt）：
  • 批次 A（19）：tag / tabs / steps / breadcrumb / dropdown / popconfirm / buttongroup / expandabletable / mergedcelltable / summaryrowtable / fixedcolumntable / enhancedtabnav / sidemenu / topmenu / mixednavigation / quicknav / anchornav / backtotop / pagetransition
  • 批次 B（24）：bankcardinput / idcardinput / plateinput / listpicker / rangequickpicker / dragupload / signaturepad / messagepro / notificationpro / progressvariants / skeletonpro / emptypro / loadingoverlay / resultvariants / exceptionvariants / confirmmodal / alertmodal / formmodal / fullscreenmodal / themeswitcher / layoutswitcher / densityswitcher / shortcutpanel / bottomsheet
• 每份含 variantDimensions / representativeVariants / anatomy / structurePatterns / usageHints / doNotInvent / unknowns 七字段，与既有 36 份同 schema。
• 硬规则：只从规格提炼，不发明；规格未明示者进 unknowns，规格明确排除者进 doNotInvent。校验脚本确认 79/79 字段完整、slug 一致。

Added — 令牌导出（文档清单中的 C4 项）

• build-site.ps1 构建期生成三种标准格式，与站点展示的令牌始终同源：
  • site/tokens/tokens.css — CSS 自定义属性，可直接 @import
  • site/tokens/dtcg.json — W3C Design Tokens 社区组格式（$value / $type / $description，按 color/typography/spacing/radius/shadow/motion/size 分组）
  • site/tokens/figma.json — Figma Tokens（Tokens Studio 插件可直接导入）
• 设计规范页新增「令牌导出」区，三个文件提供下载入口。

Changed — 规格原文与实现对齐

• 同步规格中的色彩系统到 v1.3.1 的 AA 达标值（15 处）：占位文字 / 次要文字 / 五种语义色，并在原值处标注变更原因与对比度实测。
• 修正一处既有漂移：Rate 选中星色规格为 #FAAD14（白底 1.90:1，不满足 WCAG 1.4.11 的 3:1），实现取 #2F54EB，规格已对齐实现并注明原因。

Fixed

• build-site.ps1 令牌导出段的两处 PowerShell 问题：$themes / $schema 被当作变量展开导致 Null 键；Write-Output 字符串里的 {} 被当作格式占位符。

[1.3.1] - 2026-09-11

Changed — 无障碍与令牌合规（9 项矩阵断言全部达标）

• 回归通过率 85.1% → 100%（961 条断言 / 0 失败 / 36 条 N/A / 79 页全通过，三次连跑结果一致）。
• 令牌层修正（改一处、全局生效）：--au-color-text-secondary #8C8C8C→#6E6E6E（3.36:1→5.10:1）、--au-color-text-placeholder #BFBFBF→#767676（1.84:1→4.54:1）、--au-color-success #52C41A→#2E7D0A、--au-color-warning #FAAD14→#8C5A00、--au-color-error #F5222D→#CF1322、--au-color-info #1890FF→#096DD9。原值均为 Ant Design 的「填充色阶」，作文字/白字场景均不足 AA。
• 5 端同步：frameworks/ 下 150+ 文件、300+ 处硬编码色值同步到达标值。禁用态（WCAG 明示豁免）保持原弱化表现不变。
• 语义修正：演示页补齐 role / aria-* / tabindex 共 400+ 处；修正首轮误注入（分隔符、图标等装饰元素不再带 role）；TreeTable 行补键盘操作（Enter/Space 触发行点击 + aria-selected）。
• 动态元素：Rate 星、Cascader 触发器、SideMenu 菜单项、ThemeSwitcher 色点等在 className 赋值后同步 setAttribute，静态改不到的交互元素也具备语义。
• 断言判据精化（修正过严/过宽，非放水）：
  • 图标类元素适用 WCAG 1.4.11 的 3:1（新增 icon-contrast 提示项），文字仍走 1.4.3 的 4.5:1；
  • 原生表单元素（input/select/textarea）自带语义，不再强制 aria-label；
  • 键盘可达只判「自身绑定点击行为且不可聚焦」的元素，内容子元素与容器不计；
  • 状态覆盖认可「样式表定义了状态选择器」——hover/focus/open 本就不常驻 DOM；
  • 单实例组件（水印、穿梭框）的变体要求记 N/A 而非失败；
  • 内联色值豁免数据驱动色（色板、轮播卡片背景），仅约束主题性颜色；
  • 断言改为 load + 双 requestAnimationFrame 后执行，消除初始化时序造成的误报（如密度切换器的 is-active 尚未应用）。
• site/app.js 修复：--color-card-bg 令牌名笔误（正确为 --color-bg-card），该错误曾在品牌色按钮上导致深灰字压蓝底（2.59:1）。

Known limitations

• 36 条 N/A 来自「静态组件无交互面」与「单实例组件无多变体」，属合理豁免，非缺陷掩盖（已逐条人工核实）。
• 本通过率覆盖 9 项自动化矩阵断言，不等同于完整的 WCAG 2.1 AA 合规认证：屏幕阅读器实测、焦点顺序、动态内容播报仍需人工/AT 工具验证。

[1.3.0] - 2026-09-10

Fixed — 验收链路（回归通过率此前不可信）

• 测试页快照为空壳：run-tests.ps1 抽取 frameworks/<组件>.html 的 body 时删除了全部 <script>，而 79 个 H5 演示页的 DOM 全部由内联脚本渲染（body 只有 <div id="app"></div>），且测试页从未引用 frameworks/<组件>.css。断言跑在空 DOM + 无组件样式上，v1.2.0 的 75.1% 属结构性误报，不是实现质量。
• 测试页改为 iframe 加载真实演示页（tests/_template.html），tests/_runtime.js 断言改为跨帧在真实渲染结果上执行：帧内 getComputedStyle / styleSheets / outerHTML 取值，用例节点自动标注并在帧内描边可视化，结果通过 postMessage 上报。
• 断言标注改为容器下钻（.row / .demo-block → 首个含 ≥2 有效子元素的容器，最多 6 层），修复 Countdown 等 body 直接挂载页面只标出 1 个用例的问题。
• 新增 N/A 语义：无交互面的静态组件（水印、指标卡、图表）键盘可达/ARIA 记 skip 而非失败；对比度与 token 检查限定在被测组件区，页头文档文字不再计入。
• 通过率分母改为 pass / (pass + fail)，N/A 不拉低数值；tools/run-regression.mjs（CI runner）与浏览器收集器同口径。

Added — 设计系统

• 基座键盘焦点环：:focus-visible 统一 2px 描边（colors_and_type.css）。--au-color-focus-ring 此前只被定义、从未被消费，79 个组件样式里仅 20 个自带 focus 规则——此改动一次性消除 66 页 focus-visible-defined 失败。
• tests/_collect.html：零依赖浏览器批量回归收集器（并发 iframe + 汇总 + window.__aaCollectResult），替代此前"用浏览器控制台手跑 79 页"的临时做法。
• tests/_index_template.html：测试总览页模板外置（原为 run-tests.ps1 内联 here-string），读数来自 site/data.json，并显示最近回归通过率。

Added — 设计契约第二批（展示类 15 个）

• tree / collapse / calendar / carousel / imagepreview / qrcode / countdown / watermark / cardlist / treetable / timelinelist / steplist / chartpanel / dashboardcard / employeecard，逐份从规格原文（组件2/4/7/9.txt）提炼，含 variantDimensions / representativeVariants / anatomy / structurePatterns / usageHints / doNotInvent / unknowns。契约化覆盖 21 → 36/79。

Changed

• run-tests.ps1 重写：删除失效的快照抽取逻辑（其占位符替换早已不匹配模板），改为生成 iframe 版测试页；输出改 WriteAllText 无 BOM。脚本保持 ASCII-only（PS5.1 读无 BOM 文件按 ANSI），中文文案移入 UTF-8 模板。
• 回归基线更新：960 条断言 / 通过率 85.1%（N/A 27）、11 页全通过。剩余失败项即改进 backlog：状态覆盖 45、对比度 35、ARIA 33、键盘可达 15、硬编码 hex 9、变体 2。

[1.2.0] - 2026-09-10

Added — 设计契约与工程化

• B1 契约第一批：15 个输入类组件补齐契约 JSON（autocomplete / cascader / transfer / rate / slider / segmented / radiocard / checkboxcard / switchgroup / numberrangeinput / codeinput / passwordinput / phoneinput / colorpicker / mention），契约化覆盖 6 → 21/79
• C4 静态薄壳：site/components/<slug>.html × 79（每组件独立可爬 URL：title + meta description + canonical + 刷新跳转），sitemap.xml（80 URL，部署后回填 $SiteUrlBase）
• C3 headless 回归：79 个测试页全量执行 812 条断言（当前通过率 75.1%，失败项即改进 backlog），产出 tests/report.json；CI runner tools/run-regression.mjs（Playwright，含 JUnit XML 输出）
• 首页 Hero 显示「测试通过率」（读取 tests/report.json，无报告时静默隐藏）
• B3 Playground：组件详情页「▶ 在线试玩」——textarea 编辑 H5 源码，iframe srcdoc 防抖实时重渲染，支持复位 / 退出，不影响源文件
• C1 交叉引用：组件详情页新增「相关组件」（相似 / 搭配维度映射 + 同分类兜底）
• 场景示范页：site/scenario/user-management.html（筛选表单 + 数据表格 + 分页 + 新建弹窗 + 消息反馈，视觉全部来自令牌与 components.css），首页 Hero 加入口
• 部署物料：根 README.md、Pages 入口 index.html 重定向、.github/workflows/deploy-pages.yml、.gitignore

Fixed

• 测试页断言协议落地：tests/_runtime.js 运行期自动标注快照节点 data-assert（多级结构启发式：.row → .demo → .demo-block → 首层；此前 79 页实际无断言节点，PLAN v1.1 声称与实现不符）
• site/data.js / site/data.json 去除 UTF-8 BOM（PS5.1 Set-Content 默认带 BOM，严格 JSON 解析器如 node require 直接解析失败）
• 断言可见性判定放宽（getClientRects 兜底），减少隐藏变体误报

[1.1.1] - 2026-09-08

Added — 竞品对齐改造（第一批，依据《竞品网站检查报告》与《现状问题分析与改造清单》）

• For Agents 页（#/agents）：AI / Agent 消费入口——机器可读资源清单、data.json 数据形状、消费示例、使用规则
• site/llms.txt：LLM 入口清单，指向 data.json、契约 JSON、令牌文件与测试页
• 站内更新日志页（#/changelog）：build-site.ps1 解析本文件注入 data.js，站点展示与仓库同源
• 主题预设库：主题定制器内置 6 套品牌色预设（科技蓝 / 青碧 / 极夜紫 / 暖橙 / 绯红 / 松石绿），一键切换后仍可微调
• 组件详情页新增「API 源码提炼」徽章，区分契约化组件（6 核心）与源码提炼组件（69 扩展）

Fixed — 文档与实现不符

• 搜索增强补票：Ctrl+K 弹窗补齐分类 chip 过滤、命中关键词 <mark> 高亮、子序列模糊回退（PLAN v1.1 曾声称交付但代码缺失）；搜索结果行补写 data-slug 修复搜索日志点击目标为空的问题

Changed

• 暗色模式令牌映射补全：html.aa-dark 新增品牌色族 / 语义色 / focus-ring / 阴影映射，并修复「主题内联样式压过暗色类」的层级问题——暗色下品牌色自动向白色混合提亮一档，aa-mode 切换后即时重算
• build-site.ps1：meta.version 不再硬编码，改为从 CHANGELOG.md 最新版本号自动同步

[1.1.0] - 2026-09-07

Added — 文档体系补齐

• PLAN.md：完整组件文档体系规划与路线图，含 5 大模块、3 版本路线、验收标准
• CHANGELOG.md：本文档
• CONTRIBUTING.md：贡献指南（如何新增组件 / 修契约 / 加测试）
• TESTING.md：测试矩阵、断言协议、回归流程
• tests/<slug>.html × 79：每个组件独立测试页（HTML+CSS+原生 JS 零依赖）
• tests/index.html：测试总览页（按类目聚合 + 通过率 + 失败项）
• run-tests.ps1：批量构建测试目录脚本

Added — 日志系统

• site/logger.js：构建 / 渲染 / 搜索 / 测试 四类事件，落 localStorage[aa-render-log] / localStorage[aa-search-log] / localStorage[aa-test-log]
• 控制台 aaLogger.export() 导出 JSON
• 测试页内置 data-assert + data-status，便于 Playwright / Selenium 回归

Added — 搜索增强

• Ctrl+K 弹窗内新增分类 chips 过滤（general / navigation / input / display / feedback / system）
• 命中关键词 <mark> 高亮
• 模糊容错：去空格 + 子串匹配 + 大小写不敏感
• 搜索日志：query / 命中数 / 首个命中 slug / 耗时

Added — 文档骨架

• 顶栏工具新增「测试」「日志」入口（HAMBURGER 之后）
• 组件详情页新增「测试页」链接
• 首页 hero stats 加入「测试页 79」一项

Changed

• site/app.js 改为引用 site/logger.js，原搜索行为保留
• 扩展组件契约新增「doNotInvent / unknowns」字段自动从 spec 文本提取

Fixed

• 主题定制器焦点环 rgba 计算 bug：hex 转 rgba 不再被截断为 6 位
• 类别切换时滚动条保持原位（避免视觉跳动）

[1.0.0] - 2026-09-06

Added

• 79 个组件实现（H5 / React / Vue 2 / Vue 3 四端）
• 设计令牌：colors_and_type.css / css.json / components.css
• 6 个核心组件契约 JSON
• components/index.json 全量组件索引（spec 批次映射）
• site/ 文档站：首页 / 组件总览 / 快速开始 / 设计规范
• Ctrl+K 全局搜索
• 主题定制器（4 键覆盖）
• build-site.ps1 构建脚本

Notes

• 数据生成产物：site/data.js（自动生成，请勿手动编辑）

---

标签说明

• Added：新功能
• Changed：现有功能变更
• Deprecated：即将移除
• Removed：已移除
• Fixed：缺陷修复
• Security：安全相关

版本约定

• 主版本号：不兼容的 API 变更
• 次版本号：向后兼容的功能新增
• 修订号：向后兼容的问题修复