react-native-update

React Native Update / Pushy / Cresc

概述

使用此技能，将项目从“尚未集成”推进到“热更新可在发布构建中正常工作”。 优先采用可安全复制粘贴的步骤、最小可行改动和明确的验证检查点。

Agent 和宿主的可移植性

• 将此技能用于任何能够加载 Agent Skills 的 Agent。不要假定特定宿主、模型、插件系统、工作区布局或工具名称。
• 根据包含此 SKILL.md 的目录解析 references/ 和 scripts/，而不是相对于应用根目录或进程工作目录。使用宿主提供的文件读取工具加载参考资料。
• agents/openai.yaml 是可选的宿主专用元数据，不是依赖项，也不是 Agent 许可列表。即使没有 agents/，这些说明仍然适用；任何关键集成行为都不应只存在于适配器中。
• 根据宿主提供的工具和审批策略调整文件编辑和命令执行。如果无法执行命令或使用 Node.js，请采用手动检查清单，为用户提供命令，并说明这些检查尚未运行。不要仅为使用此技能而安装特定 Agent。
• 如果使用 Node.js 22+ 且拥有执行权限，优先运行 node <skill-root>/scripts/integration_doctor.mjs <app-root>。旁边的 .sh 封装脚本只是可选的 Bash 便利工具，并非必需。保持技能根目录和应用根目录彼此独立，并为包含空格的路径加上引号。
• 技能的安装和更新由所属宿主/安装程序或明确配置的外部管理器负责。不要将仓库维护或自更新工具用于应用集成。

服务路由

• 中国服务使用 Pushy：pushy CLI、new Pushy(...)、Pushy 控制台。
• 全球服务使用 Cresc：cresc CLI、new Cresc(...)、Cresc 控制台。
• CLI、控制台、应用记录、update.json 和 JS 客户端类必须使用同一服务。不要将 pushy createApp 与 new Cresc(...) 混用，反之亦然。
• 如果服务未知，请根据用户的措辞、现有导入、注册表/域名或文档语言推断。如果仍无法确定，请实现中立结构，并明确指出用户需要选择的一行：Pushy 或 Cresc。

工作流

1. 检测应用根目录、包管理器、已安装的 React Native/Expo/react-native-update 版本、全局 CLI 版本、服务和目标平台（ios、android、harmony；Apple TV 使用 ios）。
2. 在提供或应用步骤前，先阅读 references/integration-playbook.md。对于 tvOS、RN 0.87、RN 0.88 SceneDelegate、元数据/源映射、非交互式发布和 Hermes 基础诊断，还需阅读 references/modern-integration.md。
3. 在应用中安装 react-native-update，并全局安装 react-native-update-cli。直接调用 pushy 或 cresc；不要将工作流切换为项目本地 CLI 或 npx。
4. 为检测到的平台和应用结构配置原生 bundle 加载：
   • iOS/tvOS：使用 RCTPushy.bundleURL() 或 Expo 自动集成。RN 0.88+ 模板中的 bundleURL() 重写位于 SceneDelegate，而非 AppDelegate。
   • Android：通过 ReactHost、ReactNativeHost 或自定义实例管理器调用 UpdateContext.getBundleUrl(...)。
   • Harmony：配置 package/provider/bundle-provider。
   • Brownfield：使用运行时钩子，而不是更改宿主继承结构。
5. 在根组件外添加单个 Pushy 或 Cresc 客户端，并使用 UpdateProvider 包裹实际应用树。
6. 如果可以执行命令，请运行 node <skill-root>/scripts/integration_doctor.mjs <app-root> 并修复可操作的问题。自动化场景使用 --strict --json；缺少必需项时返回 2，诊断出错时返回 1。否则采用手动检查清单，并说明诊断尚未运行。静态检查无法验证设备上的原生二进制文件。
7. 如果用户需要端到端集成，最后完成发布构建验证、基线包上传和热更新发布检查。

防护措施

• 尽量减少用户代码变更，并将其限制在局部范围内。
• 保持向后兼容。使用带版本的功能前，检查已安装的 SDK 和原生二进制文件是否支持。不要发布会盲目调用旧版已安装二进制文件中不存在的原生方法的 JS；应进行功能检测或保留旧流程。新增原生功能需要发布新的原生版本并上传基线，不能只通过 OTA 软件包发布。
• 不要承诺在调试模式下可以应用更新。debug: true 有助于在开发过程中检查和下载更新，但应用补丁需要发布构建。
• 警告 Expo 项目中存在 expo-updates 冲突。
• 优先使用 useUpdate() 方法和状态，而非直接调用 client。只有在确实需要底层集成时才直接调用客户端，并说明原因。
• UI 和长生命周期流程优先使用 useUpdate() 提供的 updateInfo/lastError。checkUpdate() 也会返回 CheckResult | undefined，因此在范围明确的一次性操作中使用其返回值是有效的；将 undefined 视为已跳过或失败，并避免在 provider 旁再构建一套状态机。
• 每个进程中必须且只能有一个 Pushy 或 Cresc 客户端，以及一个已挂载的 UpdateProvider。SDK 状态为进程级单例。
• 保留现有应用架构；根据当前项目风格调整代码片段。
• 如果原生文件差异很大（monorepo/混合原生项目），应提供有针对性的补丁指导，而非大范围重写。
• 将 JS/资源视为可安全通过 OTA 更新的内容。原生代码、原生配置、原生资源、pods、Gradle 设置、HAR/AAR/XCFramework 内容和清单均需要发布新的原生版本并上传基线。
• 如果应用使用可跨线程工作的原生 SDK（如 Sentry 性能分析、性能采样），建议在调用 switchVersion() 或 restartApp() 前使用 beforeReload（10.42.2+）进行清理。
• 原生冷启动恢复要求每个目标原生二进制文件均使用 react-native-update >= 10.52.1。除非集成方明确接受失去故障恢复能力，否则应保持启用；checkStrategy: null 不会禁用原生请求。
• tvOS 支持和清理后恢复相关修复，需要使用 SDK 10.58.0+ 重新构建原生应用。10.58.0 -> 10.58.1 中针对 RN 0.87 的 TypeScript 修复仅涉及 JS。不要用 skipLibCheck 代替源代码级修复。
• 将 metaInfo 解析为 unknown 并验证其运行时结构。使用 references/rollout-whitelist.ts；格式错误的数据必须拒绝此次发布，而不是导致崩溃或匹配子字符串。客户端白名单不具备授权能力。
• 保持启用 Hermes 基线等效性验证。保留的日志可能会暴露原始字符串/路径，即使 CLI 2.28.0 会对上传的报告进行脱敏。
• 崩溃报告工具可能包含 metaInfo 和 uuid。遵循应用的隐私政策；切勿在诊断报告中公开原始用户标识符或凭据。

需要提供的内容

• 最小集成差异，包含准确的文件和代码片段。
• 验证清单：发布构建、基线上传、检查更新、下载、立即/稍后切换、回滚行为。
• 兼容性说明：已安装 SDK/原生版本下限、受保护的回退方案，以及哪些变更需要发布新的应用商店/原生版本。
• 10.52.1+ 的恢复说明：原生冷启动检查、激活策略、强制启动路径、崩溃恢复能力限制，以及 disableNativeCheck 的权衡。
• 常见故障的排查提示，包括调试错误时准确的 OTA/源映射标识信息。
• 按需提供场景示例：类组件根节点、自定义 UI、metaInfo 发布门控、二维码/深层链接测试、棕地集成、金丝雀发布，以及 tvOS 缓存清理。
• Harmony 专项指导，附上完整的逐文件代码示例（CMakeLists.txt、PackageProvider.cpp、oh-package.json5、hvigor-config.json5、hvigorfile.ts、RNPackagesFactory.ets、Index.ets）。

资源

• 给出步骤前，请先阅读 references/integration-playbook.md。
• 阅读 references/modern-integration.md，了解 SDK 10.58.1 / CLI 2.28.0 的参考快照和主要来源。
• 实现白名单时，请复制经过测试的 references/rollout-whitelist.ts 谓词。
• 可通过 Node.js 使用 scripts/integration_doctor.mjs 进行可选的项目诊断。scripts/integration_doctor.sh 是可选的 Bash 包装脚本。请从此技能目录解析这两个路径。