@skyroc/scripts 2.5.0 → 2.5.2

package/templates/admin-root/.agents/skills/skyroc-admin-prd-prototype/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: skyroc-admin-prd-prototype
+description: 为 Skyroc Admin / RuoYi Plus Fast 模块编写来源可追溯的 PRD，并生成可独立打开、可交互、经过桌面端和移动端验收的 HTML 设计原型。仅在用户明确要求使用本 Skill 时启用。
+---
+
+# Skyroc Admin PRD 与 HTML 原型
+
+本 Skill 用于把当前 FastAPI 契约、React 实现、仓库设计规范以及可用的历史或外部参考整理成一套可实施的 PRD，并为每个真实页面生成独立 HTML 原型。
+
+不要把历史接口、字段或权限字符当作永久事实。每次任务都必须重新读取当前源码。
+
+## 适用范围
+
+在用户明确说出以下任一表达时使用本 Skill：
+
+- “使用 `skyroc-admin-prd-prototype`”
+- “按 Skyroc Admin PRD 原型 Skill 做”
+- “用之前那套 PRD 和 HTML 设计流程”且明确指向本 Skill
+
+典型任务包括：
+
+- 为一个管理模块编写 PRD。
+- 判断模块需要拆成几个页面。
+- 生成一个或多个独立 HTML 设计图。
+- 在已有 PRD 或原型基础上继续设计。
+- 对照当前 FastAPI、React 实现和可用参考资料修订设计。
+
+本 Skill 不负责把 HTML 原型直接改造成生产 React 页面，除非用户同时明确要求实施前端功能。
+
+## 默认交付物
+
+没有另行指定时，交付：
+
+1. 一份 Markdown PRD。
+2. 每个真实页面一份独立的 `index.html`。
+3. 必要的桌面端和移动端验收截图。
+4. 一份简短验收结论，区分已验证内容和未验证内容。
+
+默认路径：
+
+```text
+design/ruoyi-plus-fast/pages/<domain>/<module>.md
+design/ruoyi-plus-fast/prototypes/<page-slug>/index.html
+design/ruoyi-plus-fast/prototypes/<page-slug>/qa/*.png
+```
+
+如果相邻模块使用不同目录层级，沿用相邻模块，不为统一路径而搬动旧文件。
+
+## 必须读取的资料
+
+开始设计前，完整执行 [证据读取顺序](references/evidence-order.md)。至少确认：
+
+- 当前设计系统和信息架构。
+- 至少一个业务形态相近的 PRD 和一个视觉或交互形态相近的原型；需要比较设计模式时再读取两个以上样例。
+- FastAPI 当前 routes、schemas、service/use case、权限，以及与当前模块直接相关的测试或接口文档。
+- 当前 React 路由、页面、API 类型与请求封装（如果已经存在）。
+- 用户提供或仓库中确实存在的历史、外部参考实现（如果有）。
+
+用户给出的路径优先于默认路径。路径不存在时，先在相邻仓库中搜索实际位置，不要直接向用户索要可自行发现的信息。
+
+## 工作流
+
+### 1. 明确架构和事实边界
+
+在动手写文件前，用简短说明明确：
+
+- 模块解决什么问题。
+- 前端、后端、基础设施各自负责什么。
+- 哪些是当前源码确认的事实。
+- 哪些是为了补齐体验提出的设计假设。
+- 哪些能力当前不存在，原型不得伪装成已经对接。
+
+创建一份内部事实表，至少包含：
+
+| 证据             | 已确认能力 | 缺口或冲突 | 对设计的影响 |
+| ---------------- | ---------- | ---------- | ------------ |
+| 当前 FastAPI     |            |            |              |
+| 当前 React       |            |            |              |
+| 设计系统和旧原型 |            |            |              |
+| 可选参考资料     |            |            |              |
+
+遇到冲突时，以当前目标系统的真实后端契约为实现事实；历史或外部参考只用于理解业务边界和比较设计方案。不要为了视觉一致而虚构接口。
+
+### 2. 决定页面数量
+
+按照任务目标而不是参考页面的文件数量拆分页面：
+
+- 不同菜单入口、权限边界、用户角色或长期工作区通常是独立页面。
+- 新增、编辑、详情、确认等短任务通常使用抽屉或弹窗。
+- 用户明确要求两个页面时，必须生成两个能独立打开的 HTML 文件；不能用一个页面里的 Tab 或状态切换冒充两个页面。
+- 独立页面之间需要真实导航关系时，使用相对链接互相跳转。
+
+在 PRD 中先给出页面清单、页面 ID、路由、使用者和边界，再展开页面细节。
+
+### 3. 编写 PRD
+
+以 [PRD 产物规范](references/prd-rules.md) 为准，并从 [PRD 模板](templates/prd.md) 起草。
+
+PRD 必须做到：
+
+- 来源可追溯，事实与假设分开。
+- 页面结构、字段、表格列、筛选、状态和交互足够具体。
+- 接口、权限、错误、空状态、并发和危险操作有明确设计。
+- 同时说明桌面端和窄屏行为。
+- 明确原型与当前生产实现之间的差距。
+
+### 4. 生成独立 HTML 原型
+
+以 [HTML 原型规范](references/prototype-rules.md) 为准。
+
+优先参考当前仓库中的黄金样例：
+
+- `design/ruoyi-plus-fast/prototypes/user/index.html`
+- `design/ruoyi-plus-fast/prototypes/role/index.html`
+- `design/ruoyi-plus-fast/prototypes/menu-final/index.html`
+- `design/ruoyi-plus-fast/prototypes/oss/index.html`
+- `design/ruoyi-plus-fast/prototypes/oss-config/index.html`
+
+黄金样例用于理解布局、层级、信息密度和交互质量，不是复制固定业务内容。新页面应保持同一产品家族感，同时让业务特征决定局部布局。
+
+可以从 [后台页面骨架](templates/admin-page.html) 起步。交付前必须替换模板占位内容，并删除未使用的演示结构。
+
+### 5. 验收
+
+完整执行 [验收清单](references/acceptance-checklist.md)。最低要求：
+
+1. 使用 Oxfmt 检查 PRD 和 HTML。
+2. 使用本 Skill 的静态检查脚本检查每个原型。
+3. 启动本地静态服务，通过浏览器访问，不只使用文件预览。
+4. 分别检查桌面、窄屏和手机宽度。
+5. 点击查询、重置、新增、编辑、详情、危险操作、关闭浮层等主要交互。
+6. 检查浏览器控制台错误和页面横向溢出。
+7. 截取能证明主页面、关键浮层和移动端状态的图片。
+
+静态检查命令示例：
+
+```bash
+node .agents/skills/skyroc-admin-prd-prototype/scripts/verify-prototypes.mjs \
+  design/ruoyi-plus-fast/prototypes/example-a \
+  design/ruoyi-plus-fast/prototypes/example-b
+```
+
+## 不可妥协的规则
+
+- 不复制旧 PRD 中可能已经过期的接口事实。
+- 不把历史或外部参考行为描述成 FastAPI 已实现行为。
+- 不把静态 HTML 描述成已经完成后端联调。
+- 不用 Tab 冒充用户要求的多个页面。
+- 不把所有业务塞进一个超长弹窗。
+- 不生成只有视觉、没有关键点击反馈的“截图式页面”。
+- 不使用外部图标 CDN 作为关键依赖；优先内联 SVG。
+- 不在原型中写入真实密钥、Token、个人信息或生产地址。
+- 不因制作原型而修改当前 React 生产代码，除非用户明确要求。
+
+## 完成报告
+
+最终只需要说明：
+
+1. PRD 和页面数量。
+2. 每个页面的主要内容和关键交互。
+3. 生成文件的绝对路径。
+4. 执行过的格式、静态和浏览器验证。
+5. 当前仍属于设计假设或尚未真实联调的部分。

package/templates/admin-root/.agents/skills/skyroc-admin-prd-prototype/references/acceptance-checklist.md

@@ -0,0 +1,75 @@
+# 验收清单
+
+## 1. 文件与格式
+
+- [ ] PRD 位于约定路径，链接有效。
+- [ ] 每个真实页面都有独立 `index.html`。
+- [ ] 页面之间的相对链接指向存在的文件。
+- [ ] Oxfmt 检查通过。
+- [ ] 静态检查脚本通过。
+- [ ] 没有遗留 `TODO`、模板占位符或真实敏感信息。
+
+## 2. 内容一致性
+
+- [ ] 页面数量与 PRD 页面清单一致。
+- [ ] 查询字段、表格列、表单字段和状态与 PRD 一致。
+- [ ] 当前 FastAPI 已实现与未实现能力没有混写。
+- [ ] 历史或外部参考能力（如果使用）已标明只是参考。
+- [ ] 权限字符、接口路径和响应字段来自当前源码。
+- [ ] 危险操作的影响和阻塞原因可见。
+
+## 3. 浏览器尺寸
+
+至少逐一检查：
+
+- [ ] `1440 × 1000` 桌面端。
+- [ ] `1024 × 768` 窄屏。
+- [ ] `390 × 844` 手机端。
+
+每个尺寸确认：
+
+- [ ] 没有意外的页面级横向滚动。
+- [ ] 固定区、抽屉和弹窗没有超出可视区域。
+- [ ] 文字没有严重截断或覆盖。
+- [ ] 主操作始终可发现。
+- [ ] 手机端触控目标足够大。
+
+## 4. 关键交互
+
+根据页面实际能力检查：
+
+- [ ] 查询、重置和更多筛选。
+- [ ] 分页、刷新、列设置和批量选择。
+- [ ] 新增、编辑、详情和保存校验。
+- [ ] 浮层关闭、遮罩关闭和 Escape。
+- [ ] 删除、停用、设为默认等危险确认。
+- [ ] 成功、错误和警告反馈。
+- [ ] 明暗主题或密度切换（页面提供时）。
+- [ ] 跨页面相对链接。
+
+## 5. 浏览器技术检查
+
+- [ ] 控制台没有未处理异常。
+- [ ] 本地资源没有 404。
+- [ ] 所有图标和图片可见，失败时有降级。
+- [ ] 焦点样式可见，Tab 顺序基本合理。
+- [ ] 抽屉和弹窗有可访问名称。
+- [ ] `prefers-reduced-motion` 下没有强制大动画。
+
+## 6. 截图证据
+
+每个页面至少保存：
+
+- [ ] 桌面端主页面。
+- [ ] 一个关键抽屉或弹窗。
+- [ ] 手机端主页面或关键任务。
+
+截图默认放在对应原型目录的 `qa/` 下，使用能表达内容的文件名，例如：
+
+```text
+qa/file-list-desktop.png
+qa/upload-drawer.png
+qa/file-list-mobile.png
+```
+
+截图只能证明视觉状态，不能替代真实点击、控制台和接口验证。

package/templates/admin-root/.agents/skills/skyroc-admin-prd-prototype/references/evidence-order.md

@@ -0,0 +1,109 @@
+# 证据读取顺序
+
+目标是先确认当前事实，再设计体验。不要从单一参考项目直接推导最终页面。
+
+## 1. 用户输入
+
+先整理用户明确提供的：
+
+- 目标模块和期望产物。
+- 设计文档、PRD、原型、FastAPI、React 和可选参考资料路径。
+- 明确要求的页面数量和命名。
+- 只做设计还是还要实施生产代码。
+
+用户指定路径是本次任务的首要范围。不要擅自扩大到无关模块。
+
+## 2. 仓库级约束
+
+读取最近的 `AGENTS.md`、设计系统和信息架构：
+
+```text
+AGENTS.md
+design/ruoyi-plus-fast/design-system.md
+design/ruoyi-plus-fast/design/04-feature-map.md
+design/ruoyi-plus-fast/design/05-information-architecture.md
+design/ruoyi-plus-fast/design/07-page-registry.md
+```
+
+只读取与当前页面决策有关的设计文档。已有文档与运行时不一致时，把差异记录为设计或实现漂移。
+
+## 3. 当前 FastAPI
+
+从当前目标后端重新读取：
+
+- `routes.py` 或路由包。
+- 请求/响应 schema。
+- service、use case、repository 和 model。
+- 权限依赖、错误映射，以及与当前模块直接相关的测试或接口文档。
+
+至少核对：
+
+- 实际 HTTP 方法和路径。
+- 查询、路径和请求体字段。
+- 响应包裹结构、分页结构和字段可空性。
+- 权限字符与租户边界。
+- 业务校验、受保护记录和错误状态。
+- 已实现、部分实现和未实现能力。
+
+接口事实必须来自当前代码、接口文档或运行时证据，不从旧 PRD 反向推断。某类资料不存在时记录证据缺口，不为满足清单而虚构事实。
+
+## 4. 当前 React
+
+如果目标页面或 API 封装已经存在，读取：
+
+- TanStack Router 路由与菜单路径。
+- 页面组件、局部组件和查询参数。
+- API 类型、请求函数和 TanStack Query 封装。
+- 权限组件、字典、状态映射和共用 UI。
+
+记录现有实现可复用部分和与后端不一致之处。不要为了原型顺手修改生产页面。
+
+## 5. 运行时证据
+
+当本地服务、OpenAPI 或已有浏览器会话可用且与任务有关时，核对：
+
+- 实际请求和响应结构。
+- 权限不足、空数据和错误状态。
+- 当前页面已经呈现的字段、状态和交互。
+
+运行时证据用于确认当前行为，不能替代源码中的权限、业务约束和未覆盖分支。服务不可用时记录未验证项，不阻塞纯设计工作。
+
+## 6. 相邻 PRD 和原型
+
+至少选择：
+
+- 一个业务形态相近的 PRD。
+- 一个视觉或交互形态相近的 HTML 原型。
+
+需要在多个既有模式之间取舍时，再读取两个以上样例。选择依据优先于目录距离。例如，带树形筛选的页面应优先参考用户或菜单页面，密钥配置页面应优先参考 OSS 配置，而不是机械参考文件名最接近的页面。
+
+需要提取：
+
+- 文档章节和事实表达方式。
+- 页面壳层尺寸、筛选区、表格区、抽屉和弹窗模式。
+- 危险操作、空状态、加载状态和反馈方式。
+- 移动端降级策略。
+
+## 7. 可选参考资料
+
+仅当用户提供路径，或仓库中确实存在与任务直接相关的历史、外部参考实现时读取。参考资料可以是旧系统源码、产品文档、竞品截图或其他已确认来源。
+
+提取业务边界和设计启发，不复制参考系统的视觉或技术实现。记录：
+
+- 查询条件、数据字段和主要任务。
+- 行操作、批量操作和危险操作。
+- 系统记录保护、唯一性校验、状态变更和删除约束。
+- 与当前 FastAPI、React 和产品规范的差异。
+
+可选参考只能说明来源系统的行为，不能证明当前系统已实现。没有参考资料时跳过本节，不把缺少参考实现视为任务阻塞。
+
+## 8. 证据冲突处理
+
+按以下原则裁决：
+
+1. 当前 FastAPI 和可复现的运行时证据决定“现在能够联调什么”。
+2. 当前产品设计系统决定视觉和交互语言。
+3. 当前 React 决定已有实现和接入成本。
+4. 旧 PRD、旧原型和可选参考资料是历史或外部证据，不是实时接口契约。
+
+不能确定时，在 PRD 中写成“设计假设”或“待后端补齐”，不要伪装为事实。

package/templates/admin-root/.agents/skills/skyroc-admin-prd-prototype/references/prd-rules.md

@@ -0,0 +1,103 @@
+# PRD 产物规范
+
+PRD 是实现依据，不是页面截图说明。内容应让产品、设计、前端和后端能够对齐同一个范围。
+
+## 必要章节
+
+### 1. 文档信息
+
+包含页面族、页面 ID、页面名称、路由、终端、优先级、状态、日期和关联资料。
+
+### 2. 架构结论
+
+用简洁文字或文本图说明：
+
+- 模块在系统中的位置。
+- 前端、后端、基础设施和相邻模块的职责边界。
+- 为什么拆成当前这些页面。
+
+### 3. 已知事实与设计假设
+
+必须分开写：
+
+- 当前 FastAPI 事实。
+- 当前 React 事实。
+- 当前设计系统和既有页面事实。
+- 可选参考资料事实（存在时）。
+- 设计假设、接口缺口和风险。
+
+没有使用历史或外部参考资料时，省略对应的关联资料和事实章节，不生成空章节或“暂无”占位内容。
+
+如果字段只存在于参考系统，不要直接放入“当前接口字段”。
+
+### 4. 页面清单与目标
+
+每个页面列出：
+
+- 页面 ID、名称和路径。
+- 主要使用者。
+- 核心任务。
+- 页面内浮层。
+- 与其他页面的导航关系。
+
+### 5. 信息架构和布局
+
+使用树形文本和桌面端线框描述页面层级。多个页面分别描述，不把全部结构混成一个大图。
+
+### 6. 字段与数据展示
+
+分别定义：
+
+- 查询字段。
+- 表格列及格式。
+- 新增/编辑字段、必填、默认值和校验。
+- 详情展示字段。
+- 状态、字典、空值和敏感字段显示规则。
+
+### 7. 交互与状态
+
+至少覆盖：
+
+- 首次加载、刷新、搜索、重置和分页。
+- 新增、编辑、详情和关闭未保存表单。
+- 批量操作、权限不足和受保护数据。
+- 删除、停用、密钥轮换等危险操作。
+- 空数据、加载中、局部失败、整体失败和重试。
+- 成功反馈及数据刷新策略。
+
+### 8. 接口与权限
+
+使用表格列出：
+
+| 页面能力 | HTTP 方法与路径 | 请求 | 响应 | 权限 | 当前状态 |
+| -------- | --------------- | ---- | ---- | ---- | -------- |
+
+“当前状态”使用：已实现、部分实现、未实现、需要确认。接口路径和权限必须重新从当前源码确认。
+
+### 9. 响应式与可访问性
+
+说明：
+
+- 宽屏、常规桌面、窄屏和手机的布局变化。
+- 表格如何滚动或转为摘要卡片。
+- 抽屉在小屏是否全屏。
+- 键盘焦点、可访问名称、状态是否只依赖颜色。
+
+### 10. 验收标准
+
+验收项应可观察，例如：
+
+- 用户能从列表进入详情并返回原查询状态。
+- 删除受保护记录时显示阻塞原因且不改变列表。
+- 390px 宽度下没有页面级横向溢出。
+
+避免“体验良好”“布局美观”等不可验证表述。
+
+## 写作规则
+
+- 先给结论，再展开证据。
+- 中文业务名后保留必要的代码字段名。
+- 使用完整路径或相对链接指向实际资料。
+- 明确区分原型行为与真实后端行为。
+- 不粘贴大段后端源码，只提取契约和约束。
+- 发现参考系统与当前系统冲突时，写清取舍原因。

package/templates/admin-root/.agents/skills/skyroc-admin-prd-prototype/references/prototype-rules.md

@@ -0,0 +1,85 @@
+# HTML 原型规范
+
+HTML 原型是能独立查看和操作的设计稿，不是生产页面，也不是只有一张静态截图的布局。
+
+## 页面独立性
+
+- 每个真实页面必须有独立目录和 `index.html`。
+- 用户要求多个页面时，每个文件直接打开都应呈现完整页面壳层。
+- 不使用 Tab、查询参数或隐藏区块冒充独立页面。
+- 页面间需要互通时使用相对链接，并保证离线静态服务下可访问。
+
+## 产品一致性
+
+优先使用 `design/ruoyi-plus-fast/design-system.md` 的语义：
+
+- 页面背景、容器、边框、文字、主色和反馈色使用 CSS 变量。
+- 默认字号、间距、圆角、表格密度和抽屉尺寸与相邻原型协调。
+- 同一页面最多保留一个主要操作。
+- 删除、停用和配置变更必须说明影响。
+- 图标优先使用内联 SVG，不依赖图标字体或外部 CDN。
+
+不要因为通用模板而牺牲业务辨识度。树形资源、文件预览、密钥配置、日志时间线等任务可以采用不同主工作区。
+
+## 页面结构
+
+完整管理页面通常包括：
+
+1. 侧边栏和品牌区。
+2. 顶部工具栏和已打开页签。
+3. 页面标题、说明和上下文。
+4. 可选的概览指标。
+5. 查询区。
+6. 表格、树、卡片或其他主工作区。
+7. 分页或加载更多。
+8. 新增/编辑/详情抽屉。
+9. 危险操作确认弹窗。
+10. 成功、警告和错误反馈。
+
+只保留业务真正需要的部分，不为了齐全而堆组件。
+
+## 交互要求
+
+以下可见控件必须有合理反馈：
+
+- 查询和重置改变列表或条件摘要。
+- 新增、编辑和详情打开对应浮层。
+- 浮层的关闭按钮、遮罩和 Escape 行为一致。
+- 保存执行基础校验并反馈结果。
+- 删除、停用等危险操作先确认，再更新演示状态。
+- 刷新、复制、列设置、展开筛选等按钮不能无响应。
+- 页面间导航指向真实存在的相对路径。
+
+原型数据可以在内存中变化，但应明确“原型不会提交真实数据”。
+
+## 响应式要求
+
+至少设计三个宽度：
+
+| 场景 | 建议宽度 | 重点                                   |
+| ---- | -------- | -------------------------------------- |
+| 桌面 | 1440px   | 完整信息密度和主要工作流               |
+| 窄屏 | 1024px   | 侧栏、筛选和表格压缩策略               |
+| 手机 | 390px    | 单列、全屏抽屉、触控尺寸和无页面级溢出 |
+
+手机端允许主表格区域内部横向滚动，但页面本身不能出现不可控横向溢出。高频操作保留，低频操作收进更多菜单。
+
+## 可访问性基线
+
+- 根元素包含 `lang="zh-CN"`、字符集和 viewport。
+- 所有按钮显式声明 `type="button"` 或 `type="submit"`。
+- 纯图标按钮有 `aria-label`。
+- 当前导航使用 `aria-current="page"`。
+- 抽屉和弹窗使用 `role="dialog"` 或 `alertdialog`、`aria-modal` 和可访问标题。
+- Toast 使用 `role="status"` 或 `aria-live`。
+- 键盘焦点可见。
+- 状态不能只用颜色表达。
+- 动画尊重 `prefers-reduced-motion`。
+
+## 技术边界
+
+- 默认使用原生 HTML、CSS 和 JavaScript，确保单文件可查看。
+- 不调用真实写接口，不嵌入真实 Token 或密钥。
+- 可以使用当前仓库已有本地资产；避免外部网络依赖。
+- 原型中的字段、状态和提示语必须与 PRD 对齐。
+- HTML 不是 React 生产实现，不要声称已完成接口接入。

package/templates/admin-root/.agents/skills/skyroc-admin-prd-prototype/scripts/verify-prototypes.mjs

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+import process from "node:process";
+
+const rawArguments = process.argv.slice(2);
+const skipFormat = rawArguments.includes("--no-format");
+const targets = rawArguments.filter((argument) => argument !== "--no-format");
+
+if (targets.length === 0) {
+  console.error(
+    "用法: node verify-prototypes.mjs [--no-format] <原型目录或 index.html> [更多原型目录或文件]",
+  );
+  process.exit(2);
+}
+
+function collectHtmlFiles(targetPath) {
+  const absolutePath = resolve(targetPath);
+
+  if (!existsSync(absolutePath)) {
+    return { errors: [`路径不存在: ${absolutePath}`], files: [] };
+  }
+
+  if (statSync(absolutePath).isFile()) {
+    return absolutePath.endsWith(".html")
+      ? { errors: [], files: [absolutePath] }
+      : { errors: [`不是 HTML 文件: ${absolutePath}`], files: [] };
+  }
+
+  const indexPath = resolve(absolutePath, "index.html");
+  if (existsSync(indexPath)) {
+    return { errors: [], files: [indexPath] };
+  }
+
+  const childFiles = readdirSync(absolutePath, { withFileTypes: true }).flatMap((entry) => {
+    if (!entry.isDirectory() || entry.name === "node_modules" || entry.name === "qa") return [];
+    return collectHtmlFiles(resolve(absolutePath, entry.name)).files;
+  });
+
+  if (childFiles.length === 0) {
+    return { errors: [`目录中没有找到 index.html: ${absolutePath}`], files: [] };
+  }
+
+  return { errors: [], files: childFiles };
+}
+
+function hasPattern(source, pattern) {
+  return pattern.test(source);
+}
+
+function validateHtml(filePath) {
+  const source = readFileSync(filePath, "utf8");
+  const errors = [];
+  const warnings = [];
+
+  const requiredPatterns = [
+    ["缺少 HTML5 doctype", /<!doctype html>/i],
+    ['根元素必须声明 lang="zh-CN"', /<html\b[^>]*\blang=["']zh-CN["']/i],
+    ["缺少 UTF-8 字符集", /<meta\b[^>]*charset=["']?UTF-8["']?/i],
+    ["缺少移动端 viewport", /<meta\b[^>]*name=["']viewport["'][^>]*content=/i],
+    ["缺少非空页面标题", /<title>\s*[^<\s][^<]*<\/title>/i],
+    ["缺少全局 box-sizing", /box-sizing\s*:\s*border-box/i],
+    ["缺少可见键盘焦点样式", /:focus-visible/i],
+    ["缺少响应式媒体查询", /@media\s*\([^)]*max-width/i],
+    ["缺少减少动画偏好处理", /prefers-reduced-motion/i],
+    ["缺少页面主内容 main", /<main\b/i],
+    ["缺少可交互按钮", /<button\b/i],
+    ["缺少原型交互脚本", /<script\b/i],
+  ];
+
+  for (const [message, pattern] of requiredPatterns) {
+    if (!hasPattern(source, pattern)) errors.push(message);
+  }
+
+  if (/\{\{[A-Z0-9_]+\}\}/.test(source)) errors.push("仍包含模板占位符");
+  if (/\b(?:TODO|FIXME)\b/.test(source)) errors.push("仍包含 TODO 或 FIXME");
+  if (/https?:\/\/(?:cdn|unpkg|jsdelivr)\./i.test(source))
+    warnings.push("存在外部 CDN 依赖，请确认离线可用性");
+  if (/role=["'](?:alert)?dialog["']/i.test(source)) {
+    if (!/aria-modal=["']true["']/i.test(source)) errors.push('弹窗或抽屉缺少 aria-modal="true"');
+    if (!/aria-labelledby=["'][^"']+["']/i.test(source))
+      errors.push("弹窗或抽屉缺少 aria-labelledby");
+  }
+  if (!/(?:role=["']status["']|aria-live=["'](?:polite|assertive)["'])/i.test(source)) {
+    warnings.push("未发现 Toast 或状态反馈的可访问声明");
+  }
+
+  const buttonTags = source.match(/<button\b[\s\S]*?>/gi) ?? [];
+  const buttonsWithoutType = buttonTags.filter(
+    (tag) => !/\btype=["'](?:button|submit|reset)["']/i.test(tag),
+  );
+  if (buttonsWithoutType.length > 0) {
+    warnings.push(`${buttonsWithoutType.length} 个 button 没有显式 type`);
+  }
+
+  return { errors, warnings };
+}
+
+const collectionResults = targets.map(collectHtmlFiles);
+const collectionErrors = collectionResults.flatMap((result) => result.errors);
+const htmlFiles = [...new Set(collectionResults.flatMap((result) => result.files))];
+
+let failed = false;
+
+for (const error of collectionErrors) {
+  failed = true;
+  console.error(`✗ ${error}`);
+}
+
+for (const filePath of htmlFiles) {
+  const result = validateHtml(filePath);
+
+  if (result.errors.length === 0) {
+    console.log(`✓ 静态规范通过: ${filePath}`);
+  } else {
+    failed = true;
+    console.error(`✗ 静态规范失败: ${filePath}`);
+    for (const error of result.errors) console.error(`  - ${error}`);
+  }
+
+  for (const warning of result.warnings) console.warn(`  ! ${warning}`);
+}
+
+if (!skipFormat && htmlFiles.length > 0) {
+  const formatResult = spawnSync("pnpm", ["exec", "oxfmt", "--check", ...htmlFiles], {
+    encoding: "utf8",
+    stdio: "pipe",
+  });
+
+  if (formatResult.status === 0) {
+    console.log(`✓ Oxfmt 通过: ${htmlFiles.length} 个 HTML 文件`);
+  } else {
+    failed = true;
+    console.error("✗ Oxfmt 检查失败");
+    if (formatResult.stdout.trim()) console.error(formatResult.stdout.trim());
+    if (formatResult.stderr.trim()) console.error(formatResult.stderr.trim());
+  }
+}
+
+if (failed) process.exit(1);
+
+console.log(`完成: ${htmlFiles.length} 个原型通过基础检查。仍需执行浏览器尺寸、交互和控制台验收。`);