assess-react-native-migration

评估 React Native 迁移

给出只读的迁移决策。诊断产品和交付系统；不要执行迁移。

明确产品范围

应从能让 Agent 接触到尽可能多生产客户端代码库的工作区开展评估。当前检出内容并不能证明它包含了整个产品。

评估就绪情况之前：

1. 检查当前仓库以及 Agent 可访问的每个工作区根目录。
2. 根据产品文档、CI、发布配置、工作区清单、子模块以及对同级仓库的引用，推断受支持的客户端平台。
3. 找到每个生产客户端代码库，包括独立的原生 iOS 和 Android 仓库、应用变体，以及与人员配置或拟议代码共享相关的任何 Web 客户端。
4. 记录平台清单，注明客户端、仓库或路径、证明其属于产品的证据，以及访问状态。

如果同时支持 iOS 和 Android，推荐迁移路径前必须检查这两个原生代码库。如果某个代码库仍不可访问，将其证据标记为 unknown，说明评估仅涵盖可访问的平台，并相应降低置信度。不能仅仅因为当前仓库中没有某个平台的项目，就推断该平台不受支持。

范围门槛： 列出每个受支持的生产客户端，并确认每个代码库均可访问、明确不可访问，或已确认不存在。

首次响应门槛

未通过范围门槛时，首次响应必须严格为：

**Question:** Where can I access the production codebase for each client platform this product supports, including iOS and Android if both exist?

**Why it matters:** A migration path based on only one platform can miss native dependencies, product behavior, and delivery constraints that change the decision.

通过范围门槛后，若仓库证据不可得，应深入追问，而非泛泛调查。

如果尚不清楚可衡量的迁移动因，首次响应必须严格为：

**Question:** What measurable delivery or business problem should a React Native migration solve?

**Why it matters:** This determines whether migration is relevant and which outcomes the assessment must test.

如果迁移动因已知，只询问下一个影响最大的未知事项，并使用相同的两行格式。提问和理由之后立即结束本轮。不要添加开场白、问卷、建议或实施指导。

规则

• 将每个生产应用都视为事实来源，包括未记录的行为。
• 提问前，先检查可用的代码、CI、测试、发布配置、产品文档和运行时证据。
• 对 iOS 和 Android 的实现、行为、依赖、交付或路线图差异进行明确比较。
• 只有在证据涵盖所有受支持平台时，才能提出产品整体结论；否则须注明其平台覆盖范围。
• 将重要主张标记为 observed、measured、reported、assumed 或 unknown。
• 根据证据提出建议，而不是依据汇总的就绪度评分。
• 默认收集证据，而不是默认采用棕地、绿地或迁移方案本身。
• 负责决策阶段。在接受路径 A 之前，不要应用实施技能，也不要选择 Expo 或裸 React Native。
• 只计算 React Native 相较于当前原生系统的边际价值。
• 按已验收且经验证的工作衡量 Agent，而非 token、生成的代码或拉取请求。
• 不要对时长、成本、代码共享、Agent 生产力或投资回报率作出普遍性断言。

选择证据模式

当有源代码或交付产物可用时，使用基于代码库的评估：

1. 完成平台清单，并确定评估可以检查哪些代码库。
2. 对于每个可访问的移动端代码库，查找应用变体、CI、测试、发布配置、架构记录和产品文档。
3. 在每个原生代码库中搜索 SDK、权限、应用扩展、存储、身份验证、推送、深层链接、分析、实验和平台特定行为。
4. 引用代码库名称以及文件路径和行号，确保在代码库彼此分离时，证据仍可追溯。
5. 仅就缺失的代码库位置，或代码库无法确认的产品、组织和运营事实询问利益相关者。

当代码库不可用或重要证据仍缺失时，使用访谈评估：

1. 除非用户已提供，否则先询问可衡量的交付或业务问题。
2. 每轮只问一个会影响决策的问题。
3. 用一句话说明答案会影响哪条路径、哪项风险或哪种假设。
4. 对含糊或相互矛盾的回答提出更明确的后续问题，而不是将其视为证据。
5. 记录答案，更新证据状态，并选择影响最大的下一个未知项。
6. 当另一个答案无法改变建议、置信度或检查点时，停止追问。

在证据门槛通过之前，每次回复都必须仅包含：

**Question:** [one question]

**Why it matters:** [one sentence]

这些轮次中不得包含问卷、路径建议、检查点或实施指导。如果用户暂停访谈，返回当前证据状态和影响最大的单个未知项，不得假装评估已完成。

**访谈轮次门槛：**已提出一个问题，明确说明了其决策影响，且未出现第二个问题。

1. 收集决策证据

说明决策、截止日期、当前替代方案和可衡量的驱动因素。对框架的偏好不是驱动因素。

检查以下维度：

维度	最低证据要求
产品	支持的平台、应用变体、共享与平台特定路线图、关键流程、无障碍性、分析和边缘情况
原生能力	SDK、模块、权限、后台工作、应用扩展、支付、硬件 API、自定义渲染和可行的 React Native 路径
连续性	身份验证和会话、安全且持久化的存储、推送令牌、深层链接、订阅、已安装用户更新、法律、安全和离线限制
验证	可复现的构建、测试账号、手动和自动化 QA、设备控制、原生参考证据、性能基线和独立审查
发布	当前发布节奏和故障恢复、内部分发、功能标记、实验、应用商店发布，以及所需的二进制发布和可选 OTA 发布通道
责任归属	决策权，以及产物、功能对等性、原生边界、共享基础、验证和发布的负责人
Agent 治理	批准的模型和源代码边界、受保护的密钥和测试数据、最小权限访问、证据留存、审计跟踪，以及人工架构和发布审批
交付基线	重复实现和审查、等待和交接、功能对等性差距、双平台验证、发布指标、缺陷、返工和维护成本

对于依赖 OTA 的计划，必须明确负责人，以及运行时兼容性、发布、可观测性、回滚或重新发布和审计策略。仅有 OTA 功能并不构成迁移收益。

组建精简的迁移核心团队，结合现有产品和原生开发知识以及 React Native 迁移经验。只询问可能改变决策的缺失事实；其余内容明确列为假设。

**门槛：**每个维度都有证据或明确标注为未知，并且已指出所有阻碍路径选择的未知项。

2. 选择路径

选择一种结果，并说明为何不选择其他方案。

结果	建议采用的情况
路径 A：棕地	发布或已安装用户的连续性至关重要、原生耦合很深、各流程可独立迁移，或无法接受整款应用切换的风险。需计入宿主边界和双重架构的成本。
路径 B：绿地	行为可还原、原生依赖项有可信的替代方案、能够证明连续性、验证充分，并且在替换完成前可控制遗留范围。
路径 C：绿地优先，在检查点回退到棕地	绿地方案提供了更简单的目标，但仍存在重大不确定性；并且在扩大规模之前，可以证明已完成的 React Native 工作能够在原生宿主中运行。
暂缓	商业论证看似合理，但缺少证据、验证、负责人、预算或发布就绪条件。明确最小就绪工作和重新评估条件。
不迁移	原生系统已满足预期目标、重复的移动端交付并非重大问题、路线图不对称、平台专属工作占主导，或风险调整后的回报缺乏可信度。

将路径 C 视为 Callstack 2025 年后的新兴运营模式，而非行业基准。Agent 接入让行为移植更可行；只有在此产品上通过有数据支撑的检查点，才能确定速度和质量。

接受路径 A 后，将实施规划交给 react-native-brownfield-migration。不要重复其 Expo、XCFramework、AAR 或宿主集成指南。

关卡： 有决定性证据支持一种结果，对其他方案的否决理由明确，且置信度与证据质量相符。

3. 定义一个有代表性的检查点

为路径 C 设置检查点，并在某项不确定因素可能使推荐路径失效时设置检查点。采用组织提供的固定日历和工作量预算。选择两到三个垂直流程：

1. 涵盖 UI、数据、分析和导航的常见流程。
2. 涵盖持久化、错误和会话行为的需认证、有状态流程。
3. 最可能推翻计划的边界，例如原生 SDK、后台任务、硬件 API、离线行为、应用扩展、无障碍要求或低端 Android 限制。

将每个流程与原生源代码引用、运行时证据、负责人和一致性场景关联起来。不要只选择简单的屏幕。

针对现有产品制定可衡量的验收标准：

• 行为、状态、验证、错误、分析、无障碍和视觉输出与原生参考保持一致。
• 认证、存储、深层链接、推送和选定的原生边界在所需设备和 OS 版本上正常运行。
• 启动、交互、内存和崩溃行为达到商定的基线或容差范围。
• CI、内部分发、可观测性和预期发布通道运行可靠，足以继续推进。
• 每个流程都有设备级证据，并经过独立审核，审核时上下文干净。
• 路径 C 至少在每个必需的原生宿主中打包并打开一个有代表性的 React Native 流程。

至少针对一个流程运行两轮：

1. **忠实实现轮：**保留行为、分析、无障碍、状态和边缘情况。记录为保持一致性而保留的原生形态架构。
2. **惯用实现轮：**引入 React 组件组合、清晰的状态边界、类型化导航、可复用的基础组件、合适的测试和经过衡量的性能。重复进行一致性和设备检查。

在扩大规模前，指定 MIGRATION.md、SCREENS.tsv、STATE_AND_STORAGE.tsv、DEPENDENCIES.tsv、EVENTS.tsv 和 PARITY_CHECKS.md 的负责人。评估期间，找出缺失的产物；除非有人要求，否则不要创建完整清单。

最后做出一个决定：继续采用全新开发方式、继续采用路径 C、将已完成的工作转入路径 A、推迟，或停止。不要仅仅因为检查点结果不合意就延长检查点。

**关卡：**流程、预算、标准、证据、负责人和最终决策均已明确。

4. 检验经济效益

跟踪一项有代表性的变更从准备就绪可实施到在两个平台上验证可用的全过程。记录两个时间指标：

1. **变更交付周期：**从提交到产物可供生产用户群使用；区分二进制版本交付和 OTA 交付。
2. **跨平台功能交付周期：**从准备就绪可实施到在 iOS 和 Android 上验证可用。

计算潜在收益，包括减少重复实现和业务逻辑审核、降低一致性协调成本、提高工程师在不同平台间流动的灵活性，以及经衡量的发布或恢复改进。将 iOS 和 Android 设备验证计入模型。除非另行提供资金并完成评估，否则不要将 Web 融合纳入基准情景。

计算全部投入：检查点、双重维护、原生模块、培训、惯用实现的第二轮、测试与设备自动化、可观测性、发布基础设施、平台所有权、切换，以及原生界面的退役。

不要编造投资回收期的输入数据。若所提供的数据存在不确定性，请使用范围。若验证和边界工作消耗了预期节省、原生界面持续增加、双重维护没有明确的退役期限、Agent 带来返工却没有经过验证的吞吐量提升、一致性有所改善但交付没有改善，或释放出的产能没有计划用途，则应修订、推迟或停止。

**关卡：**可比较边际收益和全部投入，且不将双平台验证视为已消除的工作。

输出约定

仅在通过证据门槛后，或用户结束访谈时，使用此约定。

按以下顺序返回简明报告：

1. 建议： 结果、信心水平、决定性理由和决策边界。
2. 证据： 平台清单、覆盖限制，以及附带来源状态和平台差异的重要发现。
3. 假设与阻碍因素： 按决策影响排序的未知事项。
4. 检查点： 预算、流程、标准、负责人、证据和最终决策。
5. 基线与 ROI： 已测量的输入、缺失的输入、计入的回报、全部投入和排除项。
6. 下一步决策： 由谁依据哪些证据、在何时决定什么。

结论应以诊断为主。如果涉及执行，仅说明编排、任务约定、提示词、重试规则和私有 Agent 均因项目而异。切勿泄露或编造私有实现材料。