fix(ci): add feat_v4.x branch coverage and release version assertion

.agents/A11Y-WORKFLOW.md

@@ -0,0 +1,42 @@
+# NutUI-React AI 无障碍开发协同指南 (A11Y Workflow)
+
+本指南旨在教开发者如何利用 `.agents/skills-a11y.md` 指令库，驱动 AI 助手自动完成组件的无障碍（A11y）适配。
+
+## 1. 核心原理
+
+AI 助手在加载 `.agents/skills-a11y.md` 后，会自动获得以下“常识”：
+
+- **双端规范**：Web 端用 `aria-xxx` (kebab-case)，Taro 端用 `ariaXxx` (CamelCase)。
+- **状态绑定**：自动将 `checked/disabled/loading` 映射至 ARIA 属性。
+- **视觉去噪**：自动为装饰性图标添加 `aria-hidden` / `ariaHidden`。
+
+## 2. 如何下达指令 (Best Practices)
+
+### 场景 A：新组件开发
+
+**指令建议**：
+
+> “请帮我开发一个新的 `Slider` 组件，并根据 `.agents/skills-a11y.md` 同步实现 Web 和 Taro 的无障碍支持。”
+
+### 场景 B：现有组件重构
+
+**指令建议**：
+
+> “请对比 `.agents/skills-a11y.md` 中的校验清单，审计 `src/packages/xxx/xxx.tsx` 的无障碍实现，并给出重构代码。”
+
+### 场景 C：批量 A11y 检查
+
+**指令建议**：
+
+> “检查当前组件是否在 Taro 环境下正确使用了驼峰式的 `ariaLabel` 而非 `aria-label`。”
+
+## 3. 常见避坑指南
+
+- **Taro 属性丢失**：如果发现 `ariaLabel` 没生效，检查是否在 `View` 标签上透传了 `...rest`。
+- **重复 Label**：如果组件已经通过 `children` 渲染了文字，不必再在 `ariaLabel` 中重复，除非是为了给读屏器提供更清晰的上下文。
+- **图标隐藏**：不要忘记给所有的辅助性 Icon 加上 `ariaHidden` / `aria-hidden="true"`，否则读屏器会尝试读取图标的 Unicode 字符。
+
+## 4. 验证方式
+
+- **Web 端**：使用 Chrome DevTools 的 `Accessibility` 面板查看 `Accessibility Tree`。
+- **Taro 端**：在真机读屏模式（iOS VoiceOver / Android TalkBack）下测试。

.agents/skills-a11y.md

@@ -0,0 +1,139 @@
+# Agent Skill: NutUI-React Accessibility (A11y) Adaptation
+
+本技能库指导 AI 助手如何根据 NutUI-React 的多端架构（Web & Taro）进行精准的无障碍适配。
+
+## 1. 环境感知与属性规范 (Context & Convention)
+
+AI 必须根据当前编辑的文件后缀切换属性命名风格：
+
+| 平台 | 文件后缀 | 属性格式 | 示例 |
+| --- | --- | --- | --- |
+| **Web H5** | `*.tsx` | **Kebab-case** | `aria-label`, `aria-disabled` |
+| **Taro** | `*.taro.tsx` | **CamelCase** | `ariaLabel`, `ariaDisabled` |
+
+---
+
+## 2. 核心适配规则 (Core Rules)
+
+### 2.1 状态映射逻辑
+
+自动将组件的逻辑状态映射到无障碍状态：
+
+- **选中状态**:
+  - Web: `aria-checked={checked}`
+  - Taro: `ariaChecked={checked}`
+- **禁用状态**:
+  - Web: `aria-disabled={disabled || loading}`
+  - Taro: `ariaDisabled={disabled || loading}`
+- **忙碌/加载状态**:
+  - Web: `aria-busy={loading}`
+  - Taro: `ariaBusy={loading}`
+
+### 2.2 角色显式声明 (Roles)
+
+交互式容器或承载特定功能的组件必须声明 `role` (Web) 或 `ariaRole` (Taro)：
+
+- **Button**: `role="button"` / `ariaRole="button"`
+- **Dialog/Popup**: `role="dialog"` / `ariaRole="dialog"` + `aria-modal="true"` / `ariaModal={true}`
+- **TabItem**: `role="tab"` / `ariaRole="tab"`
+
+### 2.3 视觉隐藏处理
+
+- **装饰性元素**: Icon、装饰线等对视障用户无意义的元素必须隐藏。
+  - Web: `aria-hidden="true"`
+  - Taro: `ariaHidden` (Boolean 属性)
+
+### 2.4 图标治理决策树 (Icon Strategy)
+
+治理图标时，必须识别其在上下文中的角色：
+
+1. **装饰性 (Icon + Text)**:
+   - **场景**：图标旁边有力所能及的文字说明。
+   - **规则**：彻底隐藏图标，避免信息重复。
+   - **实现**：`<Icon aria-hidden="true" />`。
+2. **交互式 (Standalone Icon as Button)**:
+   - **场景**：图标是唯一的点击入口（如关闭按钮、搜索提交）。
+   - **规则**：**容器承载语义，内部图标隐藏**。
+   - **实现**：
+     ```tsx
+     <span role="button" aria-label="搜索" tabIndex={0}>
+       <Search aria-hidden="true" />
+     </span>
+     ```
+3. **语义化 (Standalone Icon as Status)**:
+   - **场景**：图标独立表示某种状态（如“成功/失败”徽标）。
+   - **规则**：图标直接承载语义，**严禁使用 aria-hidden**。
+   - **实现**：`<Icon aria-label="已完成" />`。
+
+---
+
+## 3. 实现范式 (Implementation Patterns)
+
+### 3.1 Web H5 示例 (`button.tsx`)
+
+```tsx
+<button
+  className={classes}
+  aria-disabled={disabled || loading}
+  aria-busy={loading}
+  aria-label={props['aria-label'] || props.ariaLabel}
+>
+  <div className="nut-button-wrap" aria-hidden="true">
+    {icon}
+    <span>{children}</span>
+  </div>
+</button>
+```
+
+### 3.2 Taro 示例 (`button.taro.tsx`)
+
+```tsx
+<View
+  className={classes}
+  ariaRole="button"
+  ariaDisabled={disabled || loading}
+  ariaBusy={loading}
+  ariaLabel={props.ariaLabel}
+>
+  <View className="nut-button-wrap">
+    <View ariaHidden>{icon}</View>
+    <View>{children}</View>
+  </View>
+</View>
+```
+
+---
+
+## 4. 键盘与焦点管理 (Keyboard & Focus)
+
+- **Tab 键支持**: 确保通过原生标签或 `tabIndex={0}` 使元素可聚焦。
+- **Esc 交互**: 弹出层必须支持 Esc 键触发 `onClose`。
+- **焦点捕获**: 复杂弹出层（Modal/Drawer）应引导用户使用 `FocusTrap` 逻辑或在文档中提示焦点管理。
+
+## 5. 校验清单 (A11y Reviewer)
+
+AI 在生成的代码中必须自检：
+
+1. [ ] 所有的图片/图标是否有 `alt` 或 `aria-hidden`？
+2. [ ] 无文字的按钮是否强制要求了 `aria-label`/`ariaLabel`？
+3. [ ] 状态（Disabled/Busy）是否双向绑定到 ARIA？
+4. [ ] 弹出层是否设置了 `role="dialog"` 和 `modal` 标记？
+
+## 6. 自动化治理工具 (Automation Tools)
+
+项目提供了一个统一的自动化修复脚本 `scripts/a11y-governance.mjs`，该脚本集成了属性映射、图标隐藏与语法修复功能。
+
+### 脚本功能：
+
+- **图标安全隐藏**: 自动为 Web/Taro 端的图标添加隐藏属性，具备组件识别过滤机制（自动避开 SearchBar 等）。
+- **多端属性对齐**: 自动将 `.taro.tsx` 文件中的 `aria-*` 转换为驼峰式规范。
+- **语法自动修复**: 修复 JSX 中的语法瑕疵，并保护箭头函数不受损。
+
+### 使用建议：
+
+- 在开展新批次治理前运行：
+  ```bash
+  /usr/local/bin/node scripts/a11y-governance.mjs
+  ```
+- AI 在生成代码时，应参考该脚本的逻辑，确保装饰性图标默认隐藏，交互式图标通过容器承载语义。
+- AI 在生成新组件代码时，应参考该脚本的逻辑，确保图标默认携带隐藏属性，除非该图标具有独立的交互功能。

.agents/skills/performance_audit/SKILL.md

@@ -0,0 +1,27 @@
+# NutUI-React Performance Audit Skill
+
+## Overview
+
+This skill provides a unified workflow for auditing the performance, footprint, and codebase health of the NutUI-React component library.
+
+## Commands
+
+### `npm run performance:audit`
+
+Executes all associated scripts and generates a Markdown report at `scripts/performance/audit-report.md`.
+
+## Included Audits
+
+1.  **Bundle Size Audit**: Calculates individual component file sizes (pre/post-gzip).
+2.  **Tree-shaking Verification**: Validates the correct elimination of unused code during bundling.
+3.  **Render Performance Audit**: Checks for unnecessary re-renders in React components.
+
+## When to Run
+
+- **Before major releases**: To ensure no regression in bundle size.
+- **Reviewing new components**: To verify they align with the library's performance standards.
+- **Refactoring core logic**: To ensure Tree-shaking is not accidentally broken.
+
+## Reporting
+
+The results are output to the terminal in a formatted Markdown table for easy copy-pasting into PR reviews or documentation.

.claude/commands/nutui-analyze.md

@@ -0,0 +1,81 @@
+# NutUI 组件需求分析
+
+你是 NutUI React 组件库的需求分析专家。根据用户描述的需求，对目标组件进行全面分析。
+
+## 输入
+
+用户会描述一个组件变更需求，可能是：新增组件、修改组件、修复 Bug、样式调整、API 变更等。
+
+## 分析步骤
+
+### 1. 组件现状扫描
+
+读取目标组件的所有相关文件，建立完整视图：
+
+- `src/packages/<component>/<component>.tsx` — H5 主文件
+- `src/packages/<component>/<component>.taro.tsx` — Taro 跨端文件
+- `src/packages/<component>/<component>.harmony.css` — 鸿蒙样式
+- `src/packages/<component>/<component>.scss` — 样式文件
+- `src/packages/<component>/__tests__/` — 测试文件
+- `src/styles/variables.scss` — 全局样式变量（grep 组件前缀）
+- `src/packages/<component>/doc.md` 或 `doc.zh-TW.md` — 文档
+- `src/packages/<component>/demo.tsx` — 示例代码
+
+### 2. 影响面分析
+
+- 列出所有需要修改的文件
+- 标注跨端一致性要求（H5 / Taro / Harmony 三端需同步的变更）
+- 识别样式变量的新增、修改、删除
+- 识别对外 API（Props/Events）的变化，评估是否 Breaking Change
+- 检查是否有其他组件依赖当前组件
+
+### 3. 风险评估
+
+- 向后兼容性风险（CSS 变量重命名/删除、Props 变更）
+- 跨端差异风险（某端不支持的特性）
+- 样式回归风险（布局变化可能影响使用方）
+
+## 输出
+
+将分析结果写入 `.claude/nutui-analysis.json`，格式如下：
+
+```json
+{
+  "component": "组件名",
+  "requirement": "需求简述",
+  "currentFiles": ["涉及的现有文件列表"],
+  "changes": [
+    {
+      "file": "文件路径",
+      "type": "modify|create|delete",
+      "description": "变更说明"
+    }
+  ],
+  "variableChanges": [
+    {
+      "action": "add|modify|delete",
+      "name": "变量名",
+      "oldValue": "旧值（如适用）",
+      "newValue": "新值（如适用）"
+    }
+  ],
+  "apiChanges": [
+    {
+      "prop": "属性名",
+      "action": "add|modify|deprecate|remove",
+      "breaking": true/false,
+      "description": "说明"
+    }
+  ],
+  "risks": ["风险项列表"],
+  "crossPlatform": {
+    "h5": true/false,
+    "taro": true/false,
+    "harmony": true/false
+  }
+}
+```
+
+分析完成后，告知用户分析结果摘要，并提示运行 `/nutui-plan` 进入下一阶段。
+
+$ARGUMENTS

.claude/commands/nutui-execute.md

@@ -0,0 +1,70 @@
+# NutUI 组件开发执行
+
+你是 NutUI React 组件库的代码实施专家。按照开发计划逐步执行任务。
+
+## 输入
+
+读取 `.claude/nutui-plan.json` 获取开发计划。如果文件不存在，提示用户先运行 `/nutui-plan`。
+
+## 执行规则
+
+### 1. 代码规范
+
+- **JSX 拆分**：避免生成过长的 JSX，将长内容分成多块渲染
+- **类型校验**：关键变量进行类型和空值校验，避免异常渲染
+- **注释**：仅对复杂逻辑添加简短注释
+- **样式变量**：新增的 CSS 变量必须遵循 `$组件名-属性名` 命名规范，使用 `var(--nutui-组件名-属性名, 默认值)` 格式
+- **scale-px**：注意 `scale-px()` 在 CSS 变量 fallback 中嵌套时可能有编译问题，简单值可直接用 `1px` 等
+
+### 2. 跨端同步
+
+修改 `.tsx` 后必须同步 `.taro.tsx`：
+
+- `<div>` → `<View>`，`<span>` → `<Text>` 等标签替换
+- 事件绑定方式差异
+- 保持 Props 和逻辑完全一致
+
+### 3. 执行流程
+
+按 `nutui-plan.json` 中的任务顺序执行：
+
+1. 执行当前任务
+2. 更新任务状态为 `done`
+3. 到达 checkpoint 时运行验证（测试等）
+4. 如果验证失败，修复后再继续
+5. 全部任务完成后运行完整测试
+
+### 5. 样式变量同步检查
+
+修改 `src/styles/variables.scss` 中的组件变量后，必须同步：
+
+- `src/packages/configprovider/types.ts` — 新增/删除对应类型
+- 组件 4 个 doc 文件（`doc.md`、`doc.en-US.md`、`doc.zh-TW.md`、`doc.taro.md`）的 CSS 变量表 — 更新名称、说明、默认值
+- 各 variant 文件（`variables-daojia.scss`、`variables-jmapp.scss`、`variables-jrkf.scss`）— 新增/删除对应变量
+
+### 6. 测试要求
+
+- 新增/修改的 Props 必须有对应测试
+- 结构变更需更新结构断言测试
+- 使用 `vitest` 运行：`npx vitest run src/packages/<component>`
+
+## 输出
+
+每完成一个任务，更新 `.claude/nutui-plan.json` 中对应任务的 `status` 为 `"done"`。
+
+全部完成后，生成执行报告写入 `.claude/nutui-execution-report.json`：
+
+```json
+{
+  "component": "组件名",
+  "tasksCompleted": 7,
+  "tasksFailed": 0,
+  "testResult": "pass",
+  "filesModified": ["修改的文件列表"],
+  "summary": "执行摘要"
+}
+```
+
+提示用户运行 `/nutui-review` 进行代码评审。
+
+$ARGUMENTS