revenuecat-migrate 属于 RevenueCat 的 ai-toolkit 技能，用于在应用中接入 RevenueCat，或升级 RevenueCat SDK 主版本。
用途 该技能适用于两种场景：其一，应用已通过 StoreKit 或 Google Play Billing 直接实现内购，希望在此基础上采用 RevenueCat；其二，应用已经使用 RevenueCat，希望从一个主版本升级到下一个主版本（例如 v4 到 v5、v7 到 v8）。文档指出这两条路径共享部分概念，但风险不同，因此需先确定适用哪一条再修改代码。
平台识别 技能会检查工作目录并按顺序选择第一个匹配项：
- React Native：package.json 含 react-native-purchases 条目，或 react-native 作为依赖，读取 platforms/react-native.md；若同时依赖 expo，则标记为 Expo 项目。
- Flutter：项目根目录存在 pubspec.yaml，读取 platforms/flutter.md。
- Kotlin Multiplatform：build.gradle.kts 含 kotlin { … } 多平台源集块，或依赖 com.revenuecat.purchases:purchases-kmp*，读取 platforms/kmp.md。
- Android 原生：build.gradle(.kts) 应用 com.android.application 且非 KMP，读取 platforms/android.md。
- iOS 原生：项目根目录有 Package.swift、.xcodeproj、.xcworkspace 或 Podfile，读取 platforms/ios.md。 若多个匹配（如 Flutter 项目内包含 ios/ 目录），选择拥有构建的最外层项目；仍不明确时询问用户希望配置的平台。
迁移路径 路径 A 为接入：应用已有可用的、直接基于 StoreKit 或 Google Play Billing 的内购实现，在其上新增 RevenueCat。路径 B 为版本升级：应用已使用 RevenueCat，用户希望跨主版本升级。两种路径可能同时发生（例如今天就在最新主版本上接入 RevenueCat），此时先执行路径 A，再按需执行路径 B。
共享概念 观察模式（路径 A）：观察模式是在不重写购买代码的前提下接入 RevenueCat 的关键手段。SDK 观察由现有 StoreKit / Billing 代码处理的交易，将其发送到 RevenueCat 后端进行校验并更新订阅者状态，但不发起或完成交易。现有购买界面、收据校验和交易完成逻辑保持不变。配置方式如下： iOS：在 Configuration.Builder 上设置 purchasesAreCompletedBy: .myApp，并配合 storeKitVersion: .storeKit1（或 .storeKit2）；它们是独立参数，不是单个关联值。 Android：在 PurchasesConfiguration.Builder 上设置 purchasesAreCompletedBy(PurchasesAreCompletedBy.MY_APP)。 Flutter：向 PurchasesConfiguration 传入 const PurchasesAreCompletedByMyApp(storeKitVersion: StoreKitVersion.storeKit2)。 React Native：在 configure 调用中传入 purchasesAreCompletedBy: { type: PURCHASES_ARE_COMPLETED_BY_TYPE.MY_APP, storeKitVersion: STOREKIT_VERSION.STOREKIT_2 }。 默认值为由 RevenueCat 完成（REVENUECAT / .revenueCat），即 SDK 拥有完整流程。在观察模式稳定后，可选地迁移到完整 RevenueCat 模式，移除自己的购买管线并去掉 purchasesAreCompletedBy 覆盖。
不要重复处理交易 当 purchasesAreCompletedBy 设置为 myApp 时，RevenueCat 不会在 iOS 上完成交易、也不在 Android 上确认交易，必须由现有代码继续完成这些操作。如果在保留旧交易完成代码的同时移除 myApp 标记，交易会被确认两次，订阅者状态可能表现不一致。完成/确认操作必须且只能由一方负责，选定一方并移除另一方。
用户连续性（路径 A） 如果应用已有自有认证体系，在 RevenueCat 配置完成后调用 Purchases.logIn(existingAppUserID)。这会在数据接入时把此前的购买历史关联到正确的 RevenueCat 用户。若缺少这一步，已有购买会被记录到匿名的 RC 用户下，之后无法与应用的真实用户记录匹配。仅当应用没有已认证用户概念时才可以跳过。
版本升级会改变必填字段（路径 B） 主版本升级会改变配置形态、移除已弃用 API，并改变默认行为，且随每个版本变化。该技能不重复逐版本的差异，而是要求阅读 SDK 仓库中的权威来源：
- CHANGELOG：位于 GitHub 上相关 SDK 仓库，从已安装版本逐条阅读到目标版本。
- 迁移指南：在 SDK 仓库中搜索匹配 MIGRATION.md 的文件或 migrations/ 目录；主版本升级通常会在其中提供专门指南，GitHub releases 页面上的主版本发布说明通常会链接到它。
- 发布说明：GitHub releases 页面上每个主版本的发布说明会总结破坏性变更。 SDK 仓库的文档为权威来源。平台文件 platforms/ 中会列出目标平台应查阅的具体仓库。
先规划再迁移 每个平台的推荐顺序：在分支中把 SDK 升级到新主版本；依据 CHANGELOG 的弃用与移除说明修复编译错误；通过阅读首次启动时的 SDK 日志修复运行时行为；合并前运行现有测试套件和手动沙盒场景。
实现 根据检测结果阅读对应的平台文件：platforms/ios.md、platforms/android.md、platforms/kmp.md、platforms/flutter.md、platforms/react-native.md。每个平台文件覆盖该平台的两条迁移路径。
验证 在满足以下条件前不要宣布迁移完成：应用能在新 SDK 版本上构建，且无来自你所关注的已弃用 API 的警告；沙盒购买成功，且交易以预期的 appUserID 出现在 RevenueCat 控制台的 Sandbox 视图中；迁移前的既有订阅者打开应用后权益状态正确（路径 A 证明观察模式接入生效，路径 B 证明版本升级未丢失状态）；发布前已移除调试日志级别覆盖。