ak-ui 复活记录
ak-ui 在 2019 年最后一天创建，最早是一组用于练习和复刻明日方舟界面语言的 SCSS 模块。2026 年重新打开仓库时，原有组件仍然有辨识度，但文档、部署和使用方式已经停留在上一代前端生态。
这次工作不是把旧代码全部推倒重写，而是保留它最有价值的部分：切角、警示色、状态层级和游戏界面气质，再为它补上一套可以继续迭代的现代基建。
为什么重新开始
旧项目的问题不是“没有组件”，而是缺少一条从设计、示例、文档到发布的稳定路径：
- VuePress 站点与旧依赖难以继续维护。
- 示例与截图各自维护，容易出现展示内容和测试内容不一致。
- 组件只有 CSS 类名，Vue 用户需要重复包装交互和类型。
- 旧部署依赖 GitHub Pages，预览、域名和 CI 职责混在一起。
- 截图产物曾进入 Git 流量路径，影响日常推送体验。
因此重启的重点不是追逐组件数量，而是先把项目变成一个能够稳定生长的系统。
新架构
src/scss/* ───────────────→ dist/ak-ui.css
│ │
│ └──→ Vue Registry adapters
│
examples/*.html ──────────→ DemoPreview + displayed source
│
└───────────────────→ Playwright visual captures
GitHub ──→ CI checks ──→ Cloudflare Pages Git deployment
Git tag ──→ verified package ──→ npm OIDC publish + provenance
│
└──→ changelogithub GitHub Release核心约束保持简单：
| Layer | Responsibility |
|---|---|
| CSS Core | 视觉、稳定类名和 --ak-* variables，不包含运行时 |
| HTML examples | 文档预览、显示源码和浏览器截图的唯一输入 |
| Vue Registry | 属性、插槽、事件、键盘交互和类型，可复制后修改 |
| VitePress theme | ak-ui 专属作品站与文档信息架构 |
| Playwright | 复用真实示例验证布局、交互和视觉结果 |
| Cloudflare Pages | 承接 Git 部署、预览地址和自定义域名 |
实现历程
1. VuePress → VitePress
站点迁移到 VitePress，并重写首页与文档主题。首页不使用默认 Hero 模板，而是围绕罗德岛终端、警示标尺和 Live Interface 构建自己的视觉叙事，同时支持协调的亮色与暗色模式。
2. 示例成为单一事实来源
所有组件示例迁移为 examples/*.html。DemoPreview 直接渲染这些文件并显示同一份源码，Playwright 也从相同清单逐个截图，因此不再维护文档示例、测试页面和截图页面三份副本。
3. 截图退出日常 Git 历史
默认测试只检查所有示例的渲染，组件截图通过 pnpm test:captures 或手动运行 CI 工作流并勾选 captures 生成。运行 pnpm test:captures:report 可打开人工预览报告；远程报告作为 14 天 CI Artifact 保存，下载解压后用 pnpm exec playwright show-report <报告目录> 查看。仓库只保留桌面与移动首页两张视觉回归基准。这样仍能发现首页级视觉变化，又不会让几十张组件截图持续扩大推送流量。
4. CSS Core + Vue Registry
框架无关 CSS 继续作为视觉核心。Vue 用户可以通过 shadcn-vue CLI 把 Adapter 源码复制到项目中，获得类型、v-model、事件和键盘交互，同时保留直接修改源码的自由。
Registry 构建物由配置自动生成，验证脚本会创建临时消费项目并真实执行安装，避免出现“JSON 能生成，但用户项目装不上”的假成功。
5. CI 与部署分离
GitHub Actions 只负责 lint、构建、Registry 安装验证和 Playwright；Cloudflare Pages 通过 Git 集成负责站点部署。pages.dev 用于先行验证，自定义域名作为正式入口，旧 GitHub Pages 分支暂时保留为回退。
6. 继续补充视觉语汇
重启后的第一批新增组件聚焦于状态表达和终端反馈：Status/Tag、Progress/Gauge、Notice/Alert、Tabs/Segmented。0.2.0 随后补齐 Text Input、Textarea、Checkbox、Radio、Switch、Select、Dialog、Popover 与 Tooltip；新模块优先复用浏览器原生语义、状态和顶层能力。
Vue Registry 保留少量交互 Adapter，但不再复制组件样式，也不扩展为独立 npm 运行时。HTML 与 Vue 都消费同一份 CSS Core。
7. npm Trusted Publishing
npm 发布由 v* Git tag 触发。Release 工作流会先确认 tag 指向的同一 commit 已通过常规 CI，再在不具备发布权限的 job 中完成 tag、构建物与 Token 契约校验，并把打包产物交给独立发布 job。发布 job 使用 OIDC 短期凭据，不保存长期 npm token，并由 npm 自动生成 provenance。
tag 必须与 package.json 版本完全一致，而且只能指向 master 历史中的提交。预发布版本进入 next，稳定版本进入 latest。tag 本身是正式发布信号，只在维护者完成人工确认后创建；工作流不会自行打 tag，也不会绕过发布前审批。
8. 自动 GitHub Release
npm Trusted Publishing 成功后，独立的 github-release job 才会运行 changelogithub，根据完整 Git 历史和 Conventional Commits 自动创建或更新当前 tag 的 GitHub Release，按类型与 scope 组织变更并列出贡献者。该 job 只获得创建 Release 所需的 contents: write，其余校验和 npm 发布 job 保持只读或仅持有 OIDC 权限。
Release 会先确认当前 tag 指向的同一 commit 已通过 docs.yml 的 push CI，再只执行发布专属的 tag 校验、CSS 构建、Token 契约验证与 tarball 打包；文档、Registry 和 Playwright 视觉回归不再重复运行。发布工具固定在 lockfile 中，CI 安装时禁用依赖生命周期脚本；checkout 也不会持久化写入凭据。维护者可以在打 tag 前运行 pnpm release:notes 预览生成结果。这个自动化只管理 GitHub Release notes，不会重写仓库中用于人工整理历史版本的 CHANGELOG.md。
这次刻意没有做什么
- 没有把 ak-ui 改造成绑定 Vue 的运行时组件库。
- 没有一次性追求几十个通用组件。
- 没有把所有截图继续提交进仓库。
- 没有让 GitHub Actions 同时承担测试与生产部署。
- 没有隐藏旧代码，而是逐步为原有视觉补齐稳定 API。
下一阶段
0.2.0 发布后会优先组合更具明日方舟辨识度的业务组件，例如 Operation Card、Stage Node 与 Operator Card；同时继续补齐现有组件的 focus、disabled、键盘交互和 CSS variables 契约。
如果你也在维护一个休眠多年的个人项目，这次重启带来的最大经验是：先恢复反馈循环和发布路径，再扩充功能。能够持续验证的小项目，比一次性完成的“大重写”更容易真正活下来。
非官方项目
ak-ui 是兴趣驱动的界面研究，与鹰角网络没有关联。游戏名称、图像及相关素材的权利归原权利人所有。
已发布视频
查看视频记录：按平台记录 B 站、微博和视频号的观看链接与版本。