feat: merge阶段1: 新增文件合并及适配

.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.

.gitignore

@@ -47,6 +47,7 @@ pnpm-lock.*.yaml
 # Editor directories and files
 .idea
 .vscode
+.omx
 *.suo
 *.ntvs*
 *.njsproj