用途：把项目里自定义或第三方 React UI 组件迁移到 Base UI（@base-ui/react）——Base UI 是无样式组件库，由 Material UI 团队与 Radix 作者维护，采用 Root 加部件组合模型，通过 data 属性表达状态并内置过渡。资料称其快照含 37 个组件。
主要能力：刷新组件目录快照、扫描目标路径找出可迁移候选（输出 file、line、pattern、suggested_component 的 JSON）、展示候选并确认范围（写操作前必须确认，不静默迁移）、在已确认范围内按目录与迁移模式文档改写源码、迁移后执行类型检查与构建并标记残留的自定义模式、可选卸载被替换的库。
使用方式：首次使用读取 config.json，缺失时询问 project_root（默认当前目录）、package_manager（pnpm/npm/yarn/bun，按锁文件自动检测并确认）、styling（tailwind/css-modules/styled-components/emotion/vanilla-extract/other）和 target_paths（默认 src/），保存后继续。常用脚本：scripts/refresh-catalog.sh（目录超过 7 天或大规模迁移前）、scripts/scan-candidates.sh <path>、scripts/fetch-component-doc.sh <name>、scripts/verify-migration.sh（可加 --skip-build 快速迭代）。依赖 curl、jq、ripgrep 与 Node.js 及项目自身的类型检查。
适用场景：用户明确要求迁移到 Base UI 或某个 Base UI 组件；代码中手写弹窗、基于 useState 与点击外部钩子的下拉菜单、浮动 UI，且有 Base UI 对应组件；项目使用 Radix UI、Headless UI、Reach UI 或 react-aria 组件（可一对一映射）；希望统一分散的 UI 原语；或要扫描目录寻找迁移机会。
限制与注意：不适用于新项目的组件库推荐（直接安装即可）或从 Base UI 迁出。包名已由 @base-ui-components/react 改为 @base-ui/react，应迁移到新名。弹窗类组件（Dialog、Popover、Menu、Select、Tooltip、AlertDialog）需在 Root 与 Backdrop/Positioner/Popup 之间使用 Portal，否则会渲染但不可见。状态样式依赖 data 属性（如 data-[state=open]、data-[starting-style]、data-[ending-style]）。需按源码选择受控或非受控模式。风险级别为写操作，只改源码，不强制推送、不删分支、不执行不可逆命令，开始前应提交或暂存。缺少 rg 时扫描退回 grep，速度较慢。收费、价格与效果资料未提供。