| name | migrate-v1-to-v2 |
| description | 将用户项目从 Wot UI v1 迁移到 v2。用户要求升级 wot-design-uni 到 @wot-ui/ui、替换旧组件/旧 API、迁移表单校验体系、修复因 v2 不兼容变更导致的编译错误或运行时报错时调用。 |
从 v1 迁移到 v2 技能
本技能用于辅助用户将项目从 Wot UI v1 (wot-design-uni) 迁移到 Wot UI v2 (@wot-ui/ui)。
完整迁移指南：中文 / English。
职责边界
- 扫描 v1 用法、替换包名/路径、迁移组件 API、迁移表单校验体系、修复不兼容变更。
- 不负责新建业务页面或重构业务逻辑，仅做最小必要的兼容性替换。
- 不负责安装依赖，由用户自行在终端执行。
首次交互确认
在开始任何操作前，先向用户确认以下三点（如果上下文已可推断则跳过对应问题）：
- 安装方式：npm 还是 uni_modules？（影响导入路径和 easycom 配置）
- 目标：
- A. 全量迁移（项目尚未升级）→ 按阶段一～七执行
- B. 升级后修错误（已升级但遇到编译/运行时报错）→ 先读
errors.md 定位问题
- 目标平台：H5 / 微信小程序 / 支付宝小程序？（影响样式隔离和 easycom 验证方式）
快速通道
根据用户描述的问题，直接加载对应子文件：
| 关键词 | 子文件 |
|---|
| 错误信息 / 编译报错 / 找不到模块 / is not defined / 升级后异常 | errors.md |
| 表单 / Form / schema / zodAdapter / FormRules / 校验 / 必填星号 | form.md |
| 包名 / easycom / Volar / vite 插件 / 国际化 / 路径替换 / uni_modules | infra.md |
| Sass / 主题 / Design Token / CSS 变量 / 样式覆盖 / 深色模式 / ConfigProvider | styles.md |
| Dialog / MessageBox / Empty / StatusTip / Cascader / ColPicker / Keyboard / NumberKeyboard / Button / Tag / Radio / Checkbox / Search / Grid / Fab / Badge / Slider / Tabs / Steps / Swiper / Tooltip / Popover / Collapse / Cell / Input / Textarea / PickerView / ImgCropper / CountTo / Segmented | components.md |
核心变更速查表
| 类型 | v1 | v2 |
|---|
| npm 包名 | wot-design-uni | @wot-ui/ui |
| uni_modules 目录 | wot-design-uni | wot-ui |
| 弹框组件 | wd-message-box | wd-dialog |
| 弹框 Hook | useMessage | useDialog |
| 缺省提示 | wd-status-tip | wd-empty |
| 多列选择器 | wd-col-picker | wd-cascader |
| 数字键盘 | wd-number-keyboard | wd-keyboard |
| 表单校验 | rules / FormRules | schema / FormSchema |
| 按钮变体 | plain / type="text" / type="icon" | variant / 图标按钮 |
| 按钮危险色 | type="error" | type="danger" |
| 标签变体 | plain | variant="plain" |
| 单选/复选形态 | shape / inline / cell | type / direction / 手动组合 wd-cell |
| 搜索框浅色样式 | light | variant="light" |
| GridItem 点击 | @itemclick | @click |
| 工具函数路径 | components/common/util | common/util |
迁移流程
推荐顺序：依赖升级 → 路径替换 → Form 页面 → 高影响组件 → 中低影响组件 → 样式与主题 → 回归测试。
每完成一个阶段后与用户确认再进入下一阶段。
阶段一：扫描与诊断
-
确定用户的安装方式（npm 还是 uni_modules）。
-
确认项目配置：pages.json easycom、tsconfig.json 类型声明、Vite 插件自动导入。
-
搜索 v1 旧用法：
rg "wot-design-uni|wd-message-box|useMessage|wd-status-tip|wd-col-picker|wd-number-keyboard|@itemclick|shape=|inline|\scell\b|\slight\b|type=\"error\"|type=\"icon\"|type=\"text\"|\splain\b|classPrefix|components/common/util|hide-label|hide-min-max|autoLineWidth|disabled-color|setRoate|useContentSlot|useMoreSlot|\bshow="
-
如果项目有表单，额外搜索：
rg "wd-form|FormRules|:rules=|rules=|errorType|resetOnChange"
-
向用户汇报发现的清单，按影响程度排序：
- 高影响：Form（结构+校验体系）、Dialog（原 MessageBox）、ColPicker、NumberKeyboard
- 中影响：Button、Tag、Radio/Checkbox、Search、Grid、Fab
- 低影响：camelCase 属性名、Badge/Slider/Tabs/Steps/Swiper 等属性微调
阶段二：依赖与路径替换
详见 infra.md（包名、easycom、Volar、Vite 插件、国际化）和 styles.md（Sass 升级）。读完后回到阶段三继续。
阶段三：高影响组件迁移
详见 components.md（MessageBox→Dialog、StatusTip→Empty、ColPicker→Cascader、NumberKeyboard→Keyboard）。
Form 表单体系详见 form.md。读完后回到阶段四继续。
阶段四：中影响组件迁移
详见 components.md（Button、Tag、Radio/Checkbox、Search、Grid、Fab）。读完后回到阶段五继续。
阶段五：低影响属性迁移
详见 components.md（Badge、Slider、Tabs、Steps、Swiper、Tooltip、Popover、Collapse、DatetimePickerView、ImgCropper、CountTo、Segmented、PickerView、camelCase 属性名）。读完后回到阶段六继续。
阶段六：样式与主题迁移
详见 styles.md（主题文件引入、全局变量覆盖、ConfigProvider、样式覆盖优先级、深色模式）。读完后进入阶段七回归验证。
阶段七：回归验证
