software-mobile

移动开发

在选择平台、权衡跨平台方案，以及处理身份验证、通知、深度链接、发布就绪情况和政策检查等移动端通用问题时，使用此技能。对于深入的原生 iOS 实现或重写工作，请转到 software-ios-native。对于原生 iOS 构建、安装、打包或旧版应用调试，请转到 software-ios-runtime-debugging。对于原生 Android 实现，请转到 software-android-native。

快速参考

任务	iOS	Android	跨平台	默认方案
UI	SwiftUI + UIKit 互操作	Jetpack Compose + Views 互操作	React Native、Flutter、KMP + 原生 UI	平台功能密集型工作优先选择原生方案
状态	@State、@Observable、@Environment	ViewModel + StateFlow	Zustand/RTK、Riverpod、共享领域状态	使用平台原生状态模型
导航	NavigationStack	Navigation Compose / Navigation Component	Expo Router 或 React Navigation	全新 Expo 应用优先使用 Expo Router
网络	URLSession + async/await	Retrofit/OkHttp/Ktor + 协程	Fetch/Axios、生成的客户端	使用类型化客户端，而不是临时编写 fetch
存储	SwiftData/Core Data、Keychain	Room/DataStore、Keystore	MMKV/SQLite/WatermelonDB、安全存储	将机密信息存放在平台安全存储中
测试	Swift Testing + XCTest UI	JUnit + Compose Test + Macrobenchmark	Detox/Maestro、框架原生测试	衡量性能，不要想当然
发布	隐私清单、App Review 检查	Play 目标 SDK、Data safety、签名	Expo/EAS 或原生流水线	每次发布前重新检查应用商店政策
CI / 签名	Xcode Cloud 或原生 CI	Gradle 签名 / Play App Signing	EAS Build 或原生流水线	单独验证发布签名与应用证明
推送验证	Xcode 真机 → APNs sandbox	按配置区分 FCM 调试版 / 生产版	必须证明生产发送路径在每个环境中均可送达	切勿将本地推送成功视为 TestFlight 验证通过

何时使用此技能

在以下情况下使用此技能：

• 在原生 iOS、原生 Android、React Native、Flutter、Kotlin Multiplatform 和封装壳之间选择平台
• 针对 React Native、Expo、Flutter、Kotlin Multiplatform 和 WebView 壳进行跨平台决策
• 处理移动端身份验证、通行密钥、推送通知、离线优先同步、深度链接和应用商店发布准备

不应使用此技能的情况

需求	改用
仅限 Web 的前端	software-frontend
字符串、复数形式、目录、翻译流水线、由后端生成的本地化文案	software-localisation（后端文案参考）
后端 API 实现	software-backend
托管式应用后端（Supabase、Firebase、Appwrite）	software-baas-platforms
包含 iCloud/CloudKit/App Intents/Foundation Models 的原生 iOS 应用骨架	software-ios-native + software-ios-ai-engine
原生 iOS 改写、SwiftUI 或 Xcode 工作流	software-ios-native
原生 iOS 构建/安装/启动失败、应用版本过旧、模拟器状态漂移	software-ios-runtime-debugging
原生 iOS 视觉审查	software-ios-design
iOS 专项测试深入分析	qa-testing-ios
原生 Android 改写、Kotlin、Gradle、Android Studio	software-android-native
原生 Android 构建/安装/启动失败、模拟器状态漂移	software-android-runtime-debugging
原生 Android 视觉审查	software-android-design

平台选择

Need to ship mobile product?
    │
    ├─ Single platform only?
    │   ├─ iOS → SwiftUI for new code, UIKit interop where needed
    │   └─ Android → Jetpack Compose for new code, Views interop where needed
    │
    ├─ Both iOS and Android?
    │   ├─ Native integrations / performance / platform fidelity dominate? → Separate native apps
    │   ├─ JS/TS team and fastest shared delivery? → React Native + Expo-managed for greenfield
    │   ├─ Fully shared rendering and custom UI control? → Flutter
    │   └─ Kotlin team, shared logic, native UI? → Kotlin Multiplatform
    │
    └─ Existing web app wrapper?
        ├─ Low-complexity shell → WebView / Capacitor
        └─ Meaningful native features → React Native or native modules

跨平台默认选择

框架	默认选择	状态
React Native	当前 RN 版本必须使用新架构：旧版架构已移除，newArchEnabled=false 会被忽略。请查看 RN 发行说明，确认停止支持旧版架构的版本，并查看 Expo SDK 更新日志，确认最后一个支持旧版架构的 SDK。决策的关键在于“我们依赖的所有原生模块/库是否都已迁移，或已由互操作层支持”	必须启用，不可选
Expo + Expo Router	JS/TS 全新项目的团队默认选择；使用开发构建来支持自定义原生代码，并查看已安装的 Router 版本是否支持嵌入	当前默认选择
Flutter	当共享渲染和动画控制比原生体验更重要时，是不错的选择	当前可用
Kotlin Multiplatform	最适合共享业务逻辑并使用原生 UI 的场景；面向 iOS 的 Compose Multiplatform 已稳定；请查看发行说明，了解当前版本新增的内容	应根据每个版本验证库的成熟度，而不要仅凭一项稳定性公告判断

工作流

1. 确认产品范围、目标平台、原生需求和发布限制。
2. 将仅限 Web、后端或原生 iOS 的深入分析转交给相关技能。
3. 根据上述选择指南选定技术栈。
4. 应用有关身份验证、推送、离线行为、发布门槛和测试的指南。
   • 对于 iOS 推送，分别验证本地 sandbox 路径和 production 路径。
   • 将推送验收视为两个门槛：传输验证（通知已被接受并显示）和打开路径验证（从冷启动和热启动状态点击通知后，不会卡死或崩溃）。
5. 在给出最终建议前，重新核查当前的平台政策和框架信息。

平台选择验证关卡

在决定采用原生、React Native、Flutter 还是 KMP 之前，先列出产品可能遇到的最棘手能力：后台执行、相机/媒体管线、蓝牙/硬件 SDK、小组件/扩展、深层链接、离线冲突解决、支付、无障碍功能或平台特定 UI。评估每个候选方案的不确定性和影响。若现有证据涵盖相同的框架和版本范围、原生依赖、发布配置、能力及有代表性的设备类别，则复用这些证据；同时记录日期和负责人。

仅当严肃候选方案存在尚未解决的重大原生、性能、生命周期、无障碍或打包风险时，才开展有时间限制的验证。事先定义通过/失败标准：构建和打包、原生 SDK 集成、冷启动和交互预算、无障碍行为、离线/恢复行为，以及维护者技能。使用真实的发布配置和与该风险相关的最旧设备类别。如果验证会在约定任务预算之外消耗付费服务、签名能力、稀缺设备或共享 CI 配额，须先获得该资源使用的授权。对于低风险产品，只要记录决策、适用的生产环境证据和明确的假设即可。如果最棘手的能力验证失败，或需要永久维护定制原生模块，则须将该模块的双平台维护成本纳入决策；如果不存在棘手能力，则优先选择能减少重复产品开发工作的技术栈。

能力与原生扩展点

在权衡共享交付与原生自主权时，加载 cross-platform-comparison.md。使用此目录确定所选技术栈仍需完成的原生工作：

技术栈	扩展点	承诺采用前需验证的能力
独立原生应用	直接使用 Swift/Objective-C 和 Kotlin/Java SDK	双平台实现与发布管理
React Native / Expo	Turbo Native Modules，或在开发构建中使用 Expo Modules	硬件 SDK、后台生命周期和原生依赖兼容性；Expo Go 无法加载任意原生模块
Flutter	Platform channels / Pigeon、插件、原生视图	摄像头/媒体吞吐量、平台视图组合和通道线程处理
KMP 搭配原生 UI	平台源集和 iOS 框架集成	面向 Swift 的 API、Kotlin/Native 库支持、打包和符号化
Compose Multiplatform	共享 UI 缺少所需界面时使用平台 API 和原生 UI 互操作	无障碍、输入、平台专属 UI、扩展和生命周期
Capacitor / WebView	Native plugins 和原生宿主	后台执行、硬件 API 和扩展目标；仅靠浏览器 API 无法提供这些能力

KMP iOS 工具链门槛。 即使共享业务逻辑，Apple 最终二进制文件仍需在 macOS 主机上通过 Xcode 构建。请查看项目所用 Kotlin 插件对应的 Kotlin/Gradle/AGP/Xcode 兼容性矩阵，以及适用于设备/模拟器架构的受支持目标/主机。根据现有 CocoaPods 依赖和模块分发需求，选择 直接集成 Xcode 或通过依赖管理器集成；并验证模拟器构建和签名设备归档均可成功。

证明机制门槛。 对于敏感的服务端操作，可通过技术栈的原生模块/插件评估 App Attest 和 Play Integrity。在服务端验证结果，并将其绑定到新鲜的质询或请求内容。强制执行前，检查设备/API 可用性和发布分发方式；为不受支持的设备和服务中断定义处理方式。证明机制是与身份验证和授权并用的滥用风险信号，并非所有应用提交到应用商店的通用要求。详细的威胁建模和安全存储请参阅 software-security-appsec。

平台交付门槛

• iOS： 将架构、状态、并发和性能相关工作交由 software-ios-native 处理。提交前检查隐私清单、必需理由 API 和 SDK 合规性。针对每种安装环境验证 APNs 传输和通知打开行为；检查分发归档中的 aps-environment 权限，并确保令牌路由与该环境一致。
• Android： 将 Compose、状态、后台工作和性能相关工作交由 software-android-native 处理。根据应用类型和发布轨道，阅读当前的 Play 目标 API 要求，然后验证 Data safety、签名和后台限制。若滥用风险有此需要，可评估 Play Integrity。

发布运维、陷阱与判断要点

iOS 发布运维门槛（TestFlight 渠道、上传路径、仅限后端的修复、真机冒烟测试证明、上传所需的最低 Xcode/SDK 版本）、已知的 iOS 和 Android 运行时陷阱、专家判断要点以及反模式表，详见 references/platform-traps-and-judgment.md。在发布定版、调查推送/打开路径问题或提出平台选择建议之前，请先加载该文档。

• 在归档/上传之前，查看 developer.apple.com/news/upcoming-requirements 了解最低 Xcode/SDK 版本；本地构建通过，上传审核时仍可能被拒。
• 根据适用的 App Review 条款，检查账户删除、登录服务要求以及订阅披露/取消规则；仅使用身份验证并不意味着必须支持 Sign in with Apple。

OTA 更新与外部支付

这两项都属于商店政策决策，且政策经常变化。决策逻辑、操作规则和主要页面链接见 references/store-update-and-payment-policy.md。

• OTA / 代码推送。 分别检查 Apple 指南 2.5.2 及其对解释执行代码的许可条款，以及 Google Play 的解释器例外。JS 捆绑包并不意味着可以随意更改功能。原生更改或新增功能默认使用商店构建；只有在参考文档中检查适用政策、运行时兼容性、分阶段推出和回滚之后，才使用 OTA。
• 外部支付 / 反引导。 两家商店都支持面向美国店面的外链，以及区域性替代结算或外部优惠计划。资格、权益、披露界面和剩余费用因店面而异，并会随着裁决变化。在作出决定时，根据 Apple 指南/StoreKit External Purchase 页面和 Google Play Payments/结算计划页面，逐个店面作出判断。根据商店报告的店面在服务端进行分支，并保留切换回商店结算的开关。切勿凭记忆引用费用或日期。

发布就绪检查清单

iOS App Store

• 图标、启动资源和权限说明文案均已完成
• 隐私清单和必需理由 API 均符合应用目标及列出的 SDK 要求
• 第三方 SDK 合规情况符合 Apple 当前要求
• 已在当前设备上测试无障碍功能、深层链接和推送流程
• App Store 元数据、隐私政策和 TestFlight 测试覆盖均已就绪
• 已完成完整的 App Store Connect 准备工作——参见 references/app-store-connect-checklist.md

Google Play

• 目标 SDK 符合当前 Play 目标 API 要求（请在 Play 目标 SDK 页面查看级别和截止日期；该要求每年都会变动）
• 隐私政策、内容分级和 Data safety 均已完成
• 已在现代 Android 限制条件下测试签名、身份验证和后台行为；如使用设备认证，也已完成测试
• 已妥善配置内部、封闭式和开放式测试轨道

已知陷阱

• 认为一次移动框架选型就能解决发布、权益、深层链接和推送行为问题，却没有针对特定平台进行验证
• 只在本地调试构建中验证身份验证、推送或深层链接，并将其视为已达到生产就绪状态
• 混用沙盒、预发布和生产移动后端，导致无法复现特定安装环境下的行为
• 将模拟器或仿真器上的成功视为后台执行、通知送达或设备特定生命周期行为的证明
• 未列出原生集成、扩展点和可能迫使项目采用原生绕行方案的商店政策限制，就选择跨平台技术栈

导航

参考资料

• references/ios-best-practices.md — 原生 iOS 负责人指引；移交实现工作时加载
• references/android-best-practices.md — 原生 Android 负责人指引；移交实现工作时加载
• references/cross-platform-comparison.md — React Native / Flutter / KMP / 原生方案的权衡
• references/deep-linking-guide.md — Universal Links、App Links、Expo Router、Dynamic Links 后续方案
• 移动端测试（分层、设备矩阵、快照/UI/E2E、易波动测试）由 qa-testing-mobile 负责；从 test-layers-and-suite-anti-patterns.md 开始
• references/offline-first-architecture.md — 本地优先存储、同步、冲突解决
• references/push-notifications-guide.md — APNs、FCM、权限、渠道、分析
• references/operational-playbook.md — 发布运维、决策表、集中化模式
• references/app-store-connect-checklist.md — App Store Connect 逐项检查清单
• references/store-update-and-payment-policy.md — OTA/code-push 政策及外部支付 / 反引导决策
• references/platform-traps-and-judgment.md — iOS 发布运维、平台陷阱、判断要点、反模式
• data/sources.json — 当前官方和精选外部资料

共享检查清单和实用工具

• ../software-clean-code-standard/assets/checklists/mobile-release-checklist.md
• ../software-clean-code-standard/references/auth-utilities.md
• ../software-clean-code-standard/references/error-handling.md
• ../software-clean-code-standard/references/resilience-utilities.md
• ../software-clean-code-standard/references/testing-utilities.md
• ../software-clean-code-standard/references/clean-code-standard.md

模板

• 跨平台：assets/cross-platform/template-webview.md（WebView 封装，iOS + Android）
• 原生代码位于原生技能中。对于 iOS，请参阅 networking-and-data-loading.md 和 swiftui-composition-patterns.md。对于 Android，请参阅 coroutine-and-compose-recipes.md。有关 Keychain 和 Keystore 存储，请参阅 template-mobile-security.md。

相关技能

• software-ios-native — 原生 iOS 17+ 实现、重写和 Agent 工作流
• software-ios-ai-engine — Apple Foundation Models、本地 AI 引擎、设备端检索
• software-ios-runtime-debugging — 构建／安装／启动验证、模拟器偏差、打包问题排查
• software-ios-design — 原生 iOS 视觉层级、HIG、截图审查
• software-android-native — 原生 Android、Kotlin、Jetpack Compose、Agent 工作流
• software-android-design — Material Design 3、截图审查
• software-android-runtime-debugging — Android 构建／安装／启动验证、模拟器偏差
• software-frontend — Web UI 和共享产品界面
• software-backend — API 设计、身份验证、后端契约
• software-baas-platforms — Supabase、Firebase、Appwrite、PocketBase
• qa-testing-strategy — CI 门禁、可靠性、发布信心
• qa-resilience — 网络弹性和故障模式设计
• qa-testing-ios — iOS 专项测试
• software-ui-ux-design — 移动端 UX 和无障碍设计

发布核查

在给出发布建议前，使用 data/sources.json 查阅 Apple 的上传／SDK 和第三方 SDK 要求、Google 的目标 API 政策，以及已安装框架的升级说明。无法访问的提交门禁属于未验证，不能据此声称已做好就绪准备。来源列表的编辑日期并不能证明每个页面都已核查。

经验总结循环

如果以往的决策或陷阱与当前任务相关，请在 learnings.consolidated.md 存在时查阅；仅在需要了解历史记录或其为可用备用方案时使用 learnings.md。否则跳过两者。

应用经验后，如果遇到了值得记住的模式、值得避免的错误或令人意外的领域事实，请通过 agents-skills-feedback-loop/scripts/append_learning.py 在 learnings.md 中追加一条带日期的项目。不要修改 SKILL.md 本身。