react-native-brownfield-migration

迁移到 React Native

仅在决定采用棕地迁移后使用此技能。如果用户仍在考虑棕地迁移、绿地开发、基于检查点的路径、暂缓还是不迁移，请先使用 assess-react-native-migration。

概述

使用 @callstack/react-native-brownfield 在现有原生应用中逐步采用 React Native 的规定性工作流，从初始设置到分阶段集成宿主应用。

• Expo 路径
• 纯 React Native 路径

每项任务只使用一条路径，除非用户明确要求进行迁移或比较。

迁移策略

使用以下策略规划并执行棕地迁移：

1. 评估应用状态并选择 Expo 或纯 React Native 路径。
2. 使用 @callstack/react-native-brownfield 进行初始设置。
3. 从 React Native 源应用打包 RN 构件（XCFramework/AAR）。
4. 将一个 RN 界面集成到宿主应用，并验证启动和运行时。
5. 按功能或屏幕重复集成，逐步推出。

Agent 全局防护规则

对所有参考文件应用以下规则：

1. 先选择一条路径（Expo 或纯 React Native），不要混用步骤。
2. 使用文档中的占位符（<framework_target_name>、<android_module_name>、<registered_module_name>），并根据项目文件确定其实际值。
3. 验证每条打包命令后，再进行宿主应用集成。
4. 依赖这些参考资料中的任何标志表之前，先运行 npx brownfield <command> --help；以帮助输出为准。
5. 将稳定的项目设置写入 brownfield.config.* 一次，而不要反复传入标志——参见 cli-and-config.md。
6. 较长的平台代码片段和 CLI 选项详情优先参考官方文档。
7. 尽可能通过外观层方法，避免宿主应用直接依赖 React Native API。
8. 验证启动和运行时行为时，使用 agent-device 打开宿主应用，导航到 RN 界面，捕获快照或屏幕截图，并收集设备证据。如果缺少该工具且验证需要使用它，请通过环境批准或信任的途径安装，或请用户安装或启用它。

权威文档

• 快速入门
• Expo 集成
• iOS 集成
• Android 集成
• 棕地 CLI
• 配置
• 指南
• 故障排除

路径选择关卡（必须首先执行）

选择任何参考文件前，先对项目进行分类：

1. 如果尚无 React Native 应用，请使用 Expo 创建路径：
   • expo-create-app.md -> expo-quick-start.md
2. 如果已有 React Native 应用，请检查 package.json 和 app.json：
   • 如果存在 expo，或用户要求使用 Expo 插件工作流，则选择 Expo。
   • 如果使用原生目录和直接的 RN CLI 工作流，且不需要 Expo 路径要求，则选择纯 React Native。
3. 如果仍不明确，请提出一个澄清问题。
4. 只沿一条路径继续。

适用场景

在以下情况下参考此软件包：

• 实施已获批准的渐进式迁移，将仅使用原生技术的应用迁移到 React Native 或 Expo
• 为 Expo 或裸 React Native 项目创建棕地集成流程
• 使用 @callstack/react-native-brownfield 进行初始设置
• 从 React Native 应用生成 iOS XCFramework 工件
• 从 React Native 应用生成并发布 Android AAR 工件
• 将生成的工件集成到宿主 iOS/Android 应用中

快速参考

文件	说明
quick-start.md	通用预检和强制路径选择关卡
cli-and-config.md	CLI 命令、完整标志集、配置文件、工件布局、代码生成的副作用
runtime-api.md	宿主 <-> RN API 接口（JS、Swift、Kotlin）和参考应用
expo-create-app.md	在 Expo 棕地设置前搭建新的 Expo 应用
expo-quick-start.md	Expo 插件设置和打包准备
expo-ios-integration.md	Expo iOS 打包和宿主启动集成
expo-android-integration.md	Expo Android 打包、发布和宿主集成
bare-quick-start.md	裸 React Native 基线设置
bare-ios-xcframework-generation.md	裸 iOS XCFramework 生成
bare-android-aar-generation.md	裸 Android AAR 生成和发布
bare-ios-native-integration.md	裸 iOS 宿主集成
bare-android-native-integration.md	裸 Android 宿主集成

问题 -> 技能映射

问题	从这里开始
需要先决定迁移路径	assess-react-native-migration
需要决定采用 Expo 还是裸路径	quick-start.md
需要查询 CLI 标志、配置文件结构或工件路径	cli-and-config.md
需要查询宿主 <-> RN API 名称、签名或可运行的示例应用	runtime-api.md
需要在宿主和 RN 之间共享状态，或实现类型化的 RN -> 原生导航	brownie / brownfield-navigation 技能
需要为棕地集成创建新的 Expo 应用	expo-create-app.md
需要设置 Expo 棕地集成和插件连接	expo-quick-start.md
需要集成 Expo iOS 棕地项目	expo-ios-integration.md
需要集成 Expo Android 棕地项目	expo-android-integration.md
需要设置裸 RN 基线	bare-quick-start.md
需要生成裸 RN iOS XCFramework	bare-ios-xcframework-generation.md
需要生成/发布裸 RN Android AAR	bare-android-aar-generation.md
需要集成裸 RN iOS 宿主	bare-ios-native-integration.md
需要集成裸 RN Android 宿主	bare-android-native-integration.md

相关技能

• 选择迁移路径前，请先评估 React Native 迁移。
• brownie（共享宿主与 RN 状态）和 brownfield-navigation（带类型的 RN -> 原生导航）来自另一个仓库：请按名称调用；如果未安装，请改用规范文档。