用途:在 shadcn/ui 项目中于 Radix UI 与 Base UI 原语之间迁移,或校验迁移的 API 转换。支持 Radix→Base UI、Base UI→Radix;React Aria 为第三基础(aria-*,2026 年 7 月),无文档化迁移路径,现有项目保持当前基础。
主要能力:提供完整 API 转换表与迁移后校验清单;强制工作流为迁移前并行启动 fuse-ai-pilot:explore-codebase(清点受影响组件)与 fuse-ai-pilot:research-expert(经 Context7 核实迁移模式),迁移后运行 fuse-ai-pilot:sniper 验证。
使用方式:官方工具命令包括 npx skills add shadcn/ui 后让智能体逐组件迁移(每组件一次提交,报告写入 .migration/<component>.md);{runner} shadcn@latest migrate radix [path];{runner} shadcn@latest migrate cn [path];{runner} shadcn@latest migrate rtl [path];{runner} shadcn@latest migrate icons --from lucide --to phosphor;{runner} shadcn@latest migrate base-color --to zinc;{runner} shadcn@latest init -b radix;{runner} shadcn@latest migrate --list 列出可用迁移(CLI 4.21.0:cn、icons、base-color、radix、rtl)。
关键规则:迁移前必须运行检测、创建备份分支、一次只迁移一种组件、同步更新 CSS 选择器、每组件迁移后运行测试。迁移顺序从叶子组件开始:Tooltip、Switch、Checkbox,再到 Accordion、Tabs,最后 Dialog、Select、Popover、Menu。
主要 API 变化:组合 asChild→render prop;Dialog.Content→Dialog.Popup(包装器保留 DialogContent);Dialog.Overlay→Dialog.Backdrop(包装器保留 DialogOverlay);定位由内置改为独立 Positioner;Accordion.Content→Accordion.Panel(包装器保留 AccordionContent);Accordion 单/多由 type="single" collapsible / type="multiple" 改为 defaultValue={[...]} / multiple;data-state="open"→data-open;包由 radix-ui(或旧 @radix-ui/react-)改为单一 @base-ui/react;components.json 样式由 radix- 改为 base-*。
限制:Base UI 自 2026 年 7 月起为新项目默认,但 Radix 未被弃用;React Aria 无迁移路径;其余细节暂未提供。