该技能用于把 React 项目中的 Radix UI 组件迁移到 Base UI（@base-ui/react）。它的核心目标是让项目在每一步迁移后仍然可构建，并确保迁移不会误改非 Radix 库或破坏用户自定义样式。
用途
- 迁移 shadcn 包装器、手写的 Radix 组合以及使用这些组件的消费方代码。
- 支持渐进式迁移（默认，一次一个组件）和全项目迁移（仅在明确要求时）。
- 在迁移过程中记录变更、行为差异和遗留项。
主要能力
- 通过 shadcn CLI 获取“黄金对”（golden pair）变体，并据此分类包装器是否被定制。
- 对定制包装器使用三方合并，把用户的定制复用到 Base UI 变体上。
- 对无法使用黄金对的情况，使用转换引擎：通用模式、各组件族属性表、类名映射和包装器形状。
- 强制遗留扫描：每个黄金对文件都要 grep
radix-ui、@radix-ui、IconPlaceholder，因为合并干净不代表没有残留。 - 支持渐进式迁移的 strangler-fig 模式：先写
<component>-base.tsx，逐个重指向消费方，最后删除原文件并翻转导入。 - 对无 Base UI 对应物的组件给出替代方案：AspectRatio → CSS aspect-ratio div；Label → 原生
<label>；VisuallyHidden →sr-only；Direction → Direction Provider；Popover Anchor 和 NavigationMenu Indicator 标记为惰性透传并记录。 - 行为差异（如标签页手动激活、菜单项点击不关闭、导航菜单 50ms 延迟）会被标记但不会被静默修补。
使用方式
- 预检：运行
npx shadcn@latest info --json获取项目基础、样式、Tailwind 版本、别名、已安装组件和包管理器；检测包管理器并使用它安装依赖；要求干净的 git 树，在分支上工作，每个组件一次提交。 - 基线检查：在修改依赖前运行项目的类型检查/构建，记录已有失败。
- 安装
@base-ui/react，并与 Radix 共存；只有在最后一个组件迁移完成后才移除 Radix 包。 - 策略：优先使用黄金对（通过 CLI 获取变体），否则使用转换引擎。
- 渐进式模式：先检测进行中状态；若组件依赖其他仍为 Radix 的包装器，先迁移底层；写
<component>-base.tsx，类型检查，逐个重指向消费方并类型检查；无消费方引用原文件后删除、重命名、翻转导入、最终检查并提交。 - 全项目模式：按依赖顺序逐组件迁移（叶/共享包装器如 button、label 优先），然后对照
consumer-props.md扫描所有应用代码，最后移除 Radix 依赖、安装、完整构建。 - 验证：逐文件类型检查，分批构建，最终与基线比较完整构建。
- 报告：在项目根目录
.migration/下每个组件一个文件，如.migration/accordion.md，结构严格为：标题、日期/策略/结论、Changed、Left alone、Behavior changes、Verify by hand。全项目模式额外写.migration/project.md。没有索引文件，迁移状态从磁盘派生。
适用场景
- 需要把 shadcn/ui 项目从 Radix 样式迁移到 Base UI 样式。
- 需要保留用户自定义样式和手写 Radix 组合的迁移。
- 需要渐进式、可回滚、每步可构建的迁移。
限制
- 不触碰非 Radix 库及其包装器：cmdk（command）、vaul（drawer）、sonner、input-otp、react-day-picker（calendar）、recharts（chart），并报告为有意未触碰。
- 部分 Radix 组件没有 Base UI 对应物，需按替代方案处理并记录。
- 行为差异只标记不修补，目标是符合 Base UI 习惯用法并与 shadcn base 注册表一致。
- 遗留样式（new-york、new-york-v4、default）没有 base 对应样式，只用于检测定制，然后对用户自己的文件运行转换引擎，保留其原有外观；迁移结束时标记样式名仍被 CLI 读作 radix，由用户决定是否切换样式或手动添加。
- 报告必须符合公开文档结构，缺失事实（如具体价格、平台限制）暂未提供。