用途
这是一个用于将 React 项目和组件从 Radix UI 迁移到 Base UI 的技能。当用户要求从 radix 迁移、迁移到 base-ui、转换 radix 原语或切换组件库时使用。它会迁移 shadcn 包装器、手写的 radix 组合及其消费方到 @base-ui/react，并在每一步都保持项目可构建。
主要能力
- 执行预检：使用
npx shadcn@latest info --json获取当前 base、STYLE、tailwind 版本、别名、已安装组件和包管理器。检测包管理器（通过 packageManager 字段或锁文件）并用于每次安装。要求干净的 git 工作树，在分支上工作，每个组件一次提交。在改动依赖前运行项目的类型检查/构建作为基线。 - 安装 @base-ui/react 与 radix 并存，仅在所有组件迁移完成后移除 radix 包。
- 采用“金标准对优先，转换引擎其次”的策略：通过 CLI 生成金标准对（优先），对定制包装器进行三方合并回放用户差异，对遗留样式仅做分类和检测定制，然后使用转换引擎处理用户自己的文件。
- 提供转换引擎作为后备方案，使用通用模式、按家族的 props 表、类映射和包装器形状参考进行转换。
- 支持渐进式（默认）和全项目两种迁移模式。渐进式模式逐个组件迁移，先写为 <component>-base.tsx，逐步重定向消费方，最后删除原文件并重命名。全项目模式按依赖顺序迁移所有组件，然后扫描全部应用代码。
- 强制在每次金标准对文件上执行遗留扫描（grep 检查 radix-ui、@radix-ui、IconPlaceholder）。
- 严格执行硬性规则：绝不触碰非 radix 库（如 cmdk、vaul、sonner、input-otp、react-day-picker、recharts）；对没有 Base UI 对应物的组件（如 AspectRatio、Label、VisuallyHidden、Direction）采用替代方案；button.tsx 迁移到真实的 @base-ui/react/button 原语；行为差异需标记而非修补；诚实报告。
- 验证与报告：按文件类型检查、按批次构建、最后与基线进行完整构建对比。报告位于项目根目录的 .migration/ 目录，每个组件一个文件，使用固定结构（# 组件名、日期、策略、结论、Changed、Left alone、Behavior changes、Verify by hand）。多组件运行会为每个组件生成独立文件；全项目模式还会生成 .migration/project.md。没有索引文件，迁移状态通过扫描项目 ui 目录中剩余的 radix 导入来推导。每次运行总结以“N 个包装器仍在 Radix 上”结尾。
使用方式
该技能主要通过自然语言指令触发，例如“migrate accordion”或“migrate alert-dialog and dropdown-menu”。它会自动执行预检，然后根据项目情况选择迁移策略和模式。用户无需手动编写迁移代码，但需要确保项目满足前提条件（如干净的 git 工作树）。具体命令行操作由技能内部执行，用户只需提供迁移目标。
适用场景
- shadcn 项目从 Radix UI 迁移到 Base UI。
- 手写 radix 组合或非 shadcn 项目的迁移。
- 需要逐步迁移、保持项目始终可构建的场景。
- 需要精确映射和详细报告的大型项目迁移。
限制
- 不会修改非 radix 库及其包装器（cmdk、vaul、sonner、input-otp、react-day-picker、recharts），这些会被报告为有意不触碰。
- 对于没有 Base UI 对应物的组件，采用替代方案（如 AspectRatio 转为 CSS aspect-ratio div，Label 转为原生 <label>，VisuallyHidden 转为 sr-only，Direction 转为 Direction Provider）。Popover Anchor 和 NavigationMenu Indicator 没有等价物，会保持惰性传递并标记。
- 行为差异会被标记，不会静默修补。
- 跳过或回退的文件会被列为标记，不会报告为已迁移。
- 遗留样式（new-york、new-york-v4、default）没有 base 对应物，迁移后会标记样式名仍被 CLI 识别为 radix 的问题，由用户决定是否切换样式或手动添加。
- 报告结构固定，不能更改。