assess-react-native-migration

评估 React Native 迁移方案

仅生成只读的迁移决策报告。用于诊断产品与交付体系，切勿直接执行代码迁移。

明确产品范围

评估应在能够尽可能多接触到线上生产端客户端代码库的工作区中运行。仅凭当前签出的代码库，不足以证明它已包含产品的全部内容。

在评估就绪度之前：

1. 检查当前仓库以及 Agent 可用的每一个工作区根目录。
2. 从产品文档、CI、发布配置、工作区 Manifest、子模块（submodules）以及关联仓库的引用中，推断出产品支持的客户端平台。
3. 找到每个线上客户端的代码库，包括独立的原生 iOS 和 Android 仓库、App 变体版本，以及任何与人员配置或拟定代码共享相关的 Web 客户端。
4. 记录一份平台清单（Platform Inventory），包含客户端名称、仓库或路径、属于该产品的证据以及访问权限状态。

当同时支持 iOS 和 Android 时，在给出路线建议前必须检查这两个原生代码库。如果有代码库无法获取，将其证据标记为 unknown，声明本次评估仅覆盖可访问的平台，并相应降低置信度。切勿仅因某个平台的项目未出现在当前仓库中，就推断该平台不受支持。

范围关卡（Scope gate）： 已列出所有支持的线上客户端，且每个代码库均处于“可访问”、“明确不可用”或“确认不存在”状态。

首轮响应关卡

当范围关卡未通过时，首轮响应必须完全为：

**问题：** 我从哪里可以访问该产品支持的各个客户端平台的线上代码库（如果同时存在 iOS 和 Android，请一并提供）？

**为什么这很重要：** 仅基于单一平台制定的迁移路线，容易遗漏会改变最终决策的原生依赖、产品行为及交付约束。

在范围关卡通过后，若缺少仓库级的硬核证据，应采用单问题追问（grill）而非问卷调查（survey）的形式。

如果可衡量的迁移驱动因素未知，首轮响应必须完全为：

**问题：** 本次迁移到 React Native 旨在解决什么可衡量的交付或业务痛点？

**为什么这很重要：** 这决定了迁移是否具有相关性，以及评估过程必须验证哪些预期结果。

如果迁移驱动因素已知，则使用相同的“问题+原因”两行格式，仅询问下一个影响最大的未知项。在输出问题与原因后立即结束本轮对话。切勿添加前言、问卷表单、路线推荐或具体实施指导。

硬性规则

• 将每一个线上 App 都视为唯一真理来源（Source of Truth），包括未编写文档的既有行为。
• 在提问前，先充分检查现有的代码、CI、测试、发布配置、产品文档及运行时证据。
• 若 iOS 和 Android 在实现、行为、依赖、交付或 Roadmap 上存在差异，必须进行明确对比。
• 全局性的结论必须建立在所有受支持平台的证据之上，否则须明确限定其覆盖的平台范围。
• 为所有实质性断言标注来源标签：observed（已观察）、measured（已实测）、reported（相关方反馈）、assumed（假设）或 unknown（未知）。
• 路线推荐须依据客观证据，而非综合评分打分表。
• 默认动作是搜集证据，而非直接倾向于 Brownfield、Greenfield 或迁移本身。
• 专注做好决策阶段。在路线 A 获批之前，不要套用具体实施 Skill，也不要过早选择 Expo 或 Bare React Native。
• 仅计算 React Native 相较于当前原生体系所带来的边际价值。
• 评估 Agent 的标准应为“已接收并经过验证的成果”，而非 Token 消耗量、生成的代码行数或 PR 数量。
• 不对工期、成本、代码共享率、Agent 生产力或 ROI 作出放之四海而皆准的普适性断言。

选择证据采集模式

当可以获取源码或交付构件时，采用代码库实证评估（Repository-backed assessment）：

1. 完成平台清单梳理，确定评估可以检查哪些仓库。
2. 针对每个可访问的移动端代码库，定位其 App 变体、CI、测试、发布配置、架构记录及产品文档。
3. 检索各个原生代码库中的 SDK、权限、App Extensions、存储、认证、推送、Deep Links、埋点分析、实验旗标（experiments）及平台特定行为。
4. 引用时必须包含仓库名称、文件路径和行号，以便在代码库独立分布时仍能精准追溯证据来源。
5. 仅在缺少代码库位置，或遇到代码库无法体现的产品、组织架构与运维事实时，才向干系人提问。

当无法获取仓库或关键事实证据仍然缺失时，采用访谈追问评估（Interview assessment）：

1. 从“可衡量的交付或业务痛点”开始（除非用户已经主动提供）。
2. 每轮对话仅询问一个能改变决策的关键问题。
3. 用一句话说明该回答会影响哪条路线、风险或假设。
4. 遇到含糊或矛盾的回答时，用更具体深入的问题追问，而不是直接将其纳为有效证据。
5. 记录回答，更新证据状态，并挑选下一个影响最大的未知项。
6. 当新的回答已无法改变推荐结论、置信度或 Checkpoint 时，立即停止追问。

在证据关卡通过之前，每轮响应只能且必须包含以下格式：

**问题：** [一个问题]

**为什么这很重要：** [一句话说明影响]

在这些回合中，切勿输出问卷、路线建议、Checkpoint 或实施指导。如果用户暂停了访谈，请返回当前的证据状态和唯一影响最大的未知项，绝不可伪装评估已完成。

访谈单轮关卡（Interview turn gate）： 已请求一个回答，其对决策的影响已明确阐述，且未出现第二个问题。

1. 搜集决策证据

明确决策事项、截止时间、备选方案以及可衡量的驱动因素。单纯偏好某个框架不能算作驱动因素。

检查以下维度：

维度	最低证据要求
产品 (Product)	支持的平台、App 变体版本、共享与平台特有的 Roadmap、核心流程、无障碍支持（Accessibility）、埋点分析（Analytics）及边缘场景
原生能力覆盖 (Native surface)	SDK、原生模块、权限、后台任务、App Extensions、支付、硬件 API、自定义渲染，以及可行的 React Native 接入路径
业务连续性 (Continuity)	认证与 Session、安全及持久化存储、推送 Token、Deep Links、订阅、老用户覆盖更新（Installed-user update）、合规/安全与离线约束
质量验证 (Verification)	可复现构建（Reproducible builds）、测试账号、人工与自动化 QA、真机掌控力、原生对照依据、性能基线及独立评审
发布交付 (Release)	当前发布节奏与故障恢复能力、内部分发渠道、Feature Flags、AB 实验、应用商店灰度发布、预期的二进制发布及可选的 OTA 通道
权责归属 (Ownership)	构件产出、对齐度（Parity）、原生边界、公共基础设施、验证与发布的决策授权人及 Owner
Agent 治理 (Agent governance)	批准的模型与源码边界、受保护的密钥/测试数据、最小权限访问、证据留存、审计日志（Audit trail）以及人工架构与发布审批
交付基线 (Delivery baseline)	双端重复开发与 Code Review 成本、等待与交接损耗、对齐度差距、双端验证成本、发布指标、缺陷率、返工率及维护成本

对于依赖 OTA 的方案，必须指定 Owner 并具备运行时兼容性、灰度发布、可观测性、回滚/重新发布机制及审计策略。单纯“支持 OTA”本身不能直接算作迁移收益。

组建由既有产品/原生知识与 React Native 迁移专家结合的精简迁移核心小组。仅询问可能改变决策的缺失事实；其余缺失项作为“假设”明确标注。

关卡： 每个维度均有实证或明确的 unknown，且所有阻碍路径选择的未知项已全部列出。

2. 路线选择

选出一个最终路线，并阐明为何放弃其他备选方案。

路线结果	推荐适用场景
路线 A：Brownfield（混合/渐进式迁移）	发布或老用户连续性要求极高、与原生耦合较深、业务流程可独立迁移，或者全量替换 App 的风险无法承受。需将宿主边界和双架构并行成本计入考虑。
路线 B：Greenfield（全新重构）	既有行为可复现/还原、原生依赖有可靠替代方案、连续性可被验证、质量验证体系完善，且在完成替换前旧版本范围可控。
路线 C：Greenfield 优先 + Checkpoint 验证（以 Brownfield 为退路）	Greenfield 目标更简单但仍存在实质不确定性，且已完成的 React Native 工作可以在规模化推广前在原生宿主内得到验证。
暂缓 (Defer)	商业逻辑合理，但缺少必要的证据、质量验证、权责归属、预算或发布就绪度。需指出最小程度的就绪准备工作及重启评估的条件。
不迁移 (Do not migrate)	现有的原生体系完全能满足预期目标、双端重复交付问题并不突出、Roadmap 不对称、平台特有工作占主导，或者风险调整后的回报率不可信。

请将路线 C 视为 Callstack 在 2025 年之后探索的前沿工程模式，而非行业通用标准。虽然 AI Agent 的引入大大提高了行为移植的可行性，但只有在本产品上进行实测 Checkpoint 验证，才能真正确立速度与质量。

路线 A 被采纳后，将具体实施计划交接给 react-native-brownfield-migration。不要重复其关于 Expo、XCFramework、AAR 或宿主集成的相关指导。

关卡： 选出的路线有决定性证据支撑，被否决的方案有明确理由，且置信度如实反映了证据质量。

3. 定义具有代表性的验证点（Checkpoint）

针对路线 C，以及任何可能因单一不确定因素导致推荐路线失效的情况，设立 Checkpoint。设定由组织提供的固定时间表和工作量预算。挑选 2 到 3 个纵向业务流程：

1. 涵盖 UI、数据、埋点与路由导航的通用流程。
2. 涵盖持久化、错误处理与 Session 状态的已认证有状态流程。
3. 最容易推翻方案的边界流程（如原生 SDK、后台任务、硬件 API、离线行为、App Extension、无障碍需求或低端 Android 设备限制）。

将每个流程与原生源码引用、运行时证据、Owner 及对齐场景关联起来。切勿只挑选容易实现的页面。

对照现有产品定义可衡量的验收标准：

• 行为、状态、校验规则、错误处理、埋点分析、无障碍及视觉效果均与原生对照组完全一致。
• 认证、存储、Deep Links、推送及选定的原生边界在要求的设备和操作系统版本上正常运行。
• 启动速度、交互流畅度、内存占用和 Crash 表现符合约定的基线或容忍度。
• CI、内部分发、可观测性及预期的发布管道运行足够可靠，具备持续推进条件。
• 每个流程都有真机层面的验证依据，并经过上下文干净的独立评审。
• 路线 C 在每个要求的原生宿主中封装并成功打开至少一个具有代表性的 React Native 流程。

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

1. 忠实还原轮 (Faithful pass)： 严格保持既有行为、埋点、无障碍、状态及边缘场景。记录为了对齐而保留的原生风格架构。
2. 地道重构轮 (Idiomatic pass)： 引入 React 组件化组合、清晰的状态边界、强类型导航、可复用基础原件、适配的测试集及性能实测。重复进行对齐度与真机验证。

在规模化推广之前，为 MIGRATION.md、SCREENS.tsv、STATE_AND_STORAGE.tsv、DEPENDENCIES.tsv、EVENTS.tsv 以及 PARITY_CHECKS.md 指定 Owner。在……

<!-- truncated for translation batch; full body continues in source -->