axiom-ios-integration

iOS 系统集成路由器

对于任何 iOS 系统集成，包括 Siri、Shortcuts、小组件、应用内购买、相机、照片图库、音频、axiom-haptics 等，你都必须使用此技能。

适用场景

在以下情况下使用此路由器：

• Siri 与 Shortcuts（App Intents）
• Apple Intelligence 集成
• 小组件与实时活动
• 应用内购买（StoreKit）
• 相机拍摄（AVCaptureSession）
• 照片图库与选择器（PHPicker、PhotosPicker）
• 音频、触觉反馈与音频识别（ShazamKit）
• 本地化
• 隐私与权限
• Spotlight 搜索
• 应用可发现性
• 闹钟（AlarmKit）
• 后台处理（BGTaskScheduler）
• 位置服务（Core Location）
• 地图与 MapKit（Map、MKMapView、注释、搜索、路线）
• Passkey 与身份验证（ASAuthorizationController、WebAuthn）
• 应用完整性与欺诈防范（App Attest、DeviceCheck）
• 日历事件与提醒事项（EventKit、EventKitUI）
• 联系人与联系人选择器（Contacts、ContactsUI、ContactProvider）

跨领域路由

当集成问题与其他领域重叠时：

Widget + 数据同步问题（Widget 未显示更新后的数据）：

• Widget 时间线未刷新 → 留在 ios-integration（extensions-widgets）
• SwiftData/Core Data 未与扩展共享 → 同时调用 ios-data——App Groups 和共享容器属于数据层问题
• 后台刷新时机 → 如果涉及异步模式，同时调用 ios-concurrency

Live Activity + 推送通知问题：

• ActivityKit 推送令牌设置、Live Activity 未更新 → 留在 ios-integration（extensions-widgets）
• 推送通知送达失败、APNs 错误 → 同时调用 ios-networking（networking-diag）
• Entitlements/证书配置错误 → 同时调用 ios-build（xcode-debugging）

Camera + 权限 + 隐私：

• Camera 代码问题 → 留在 ios-integration（camera-capture）
• 隐私清单或 Info.plist 问题 → 留在 ios-integration（privacy-ux）
• 构建/entitlement 错误 → 同时调用 ios-build

MapKit + 位置问题（用户位置未显示在地图上）：

• 地图显示、标注、搜索 → 留在 ios-integration（mapkit）
• 位置授权、监控、后台位置 → 同时调用 ios-performance 或 ios-integration（core-location）
• 标注数量较多时的地图性能 → 如果需要性能分析，同时调用 ios-performance

推送通知 + Live Activity 问题（推送未更新 Live Activity）：

• 推送传输、APNs 标头、令牌管理 → 留在 ios-integration（push-notifications、push-notifications-diag）
• ActivityKit UI、属性、Dynamic Island → 同时调用 ios-integration（extensions-widgets）
• 后台执行时机 → 如果涉及异步模式，同时调用 ios-concurrency

推送通知 + 后台处理（静默推送未触发后台工作）：

• 推送负载和送达 → 留在 ios-integration（push-notifications-diag）
• 后台执行、BGTaskScheduler → 同时调用 ios-integration（background-processing）

Calendar + 数据同步问题（事件未同步、日历数据过期）：

• EventKit 存储区变更、EKEventStoreChanged → 留在 ios-integration（eventkit）
• 通过 App Groups 与 Widget 共享数据 → 对于共享容器模式，同时调用 ios-data
• 日历同步的后台刷新 → 同时调用 ios-integration（background-processing）

Contacts + 隐私问题（联系人访问被拒、对有限访问权限感到困惑）：

• 联系人权限模型、Contact Access Button → 留在 ios-integration（contacts）
• 联系人的隐私清单或 Info.plist → 留在 ios-integration（privacy-ux）
• Contact Provider 扩展架构 → 如果存在扩展目标问题，同时调用 ios-build

ShazamKit + 麦克风权限（无匹配结果、权限被拒）：

• 麦克风 NSMicrophoneUsageDescription / Info.plist → 留在 ios-integration（privacy-ux）
• 未启用 ShazamKit App Service → 留在 ios-integration（shazamkit）

ShazamKit + AVFoundation（使用 AVAudioEngine 缓冲区的自定义 SHSession）：

• 音频引擎设置、缓冲区格式、会话配置 → 留在 ios-integration（shazamkit）
• AVAudioEngine 管道、音频会话类别、格式转换 → 同时调用 avfoundation-ref

ShazamKit + MusicKit（通过 Apple Music 播放匹配的歌曲）：

• 包含 appleMusicID/appleMusicURL 的匹配结果 → 留在 ios-integration（shazamkit）
• MusicKit 播放、ApplicationMusicPlayer → 同时调用 ios-integration（now-playing-musickit）

路由逻辑

Apple Intelligence 与 Siri

App Intents → /skill axiom-app-intents-ref App Shortcuts → /skill axiom-app-shortcuts-ref App 可发现性 → /skill axiom-app-discoverability Core Spotlight → /skill axiom-core-spotlight-ref

小组件与扩展

小组件/实时活动 → /skill axiom-extensions-widgets 小组件参考 → /skill axiom-extensions-widgets-ref

App 内购买

IAP 实现 → /skill axiom-in-app-purchases StoreKit 2 参考 → /skill axiom-storekit-ref IAP 审计 → 启动 iap-auditor Agent（缺少 transaction.finish()、收据验证薄弱、缺少恢复购买、订阅跟踪） IAP 完整实现 → 启动 iap-implementation Agent（StoreKit 配置、StoreManager、交易处理、恢复购买）

相机与照片

相机捕获实现 → /skill axiom-camera-capture 相机 API 参考 → /skill axiom-camera-capture-ref 相机调试 → /skill axiom-camera-capture-diag 相机审计 → 启动 camera-auditor Agent 或 /axiom:audit camera（已弃用的 API、缺少中断处理程序、线程违规、权限反模式） 照片选择器与图库 → /skill axiom-photo-library 照片图库 API 参考 → /skill axiom-photo-library-ref

音频、触觉与音频识别

音频（AVFoundation） → /skill axiom-avfoundation-ref 触觉 → /skill axiom-haptics 正在播放 → /skill axiom-now-playing CarPlay 正在播放 → /skill axiom-now-playing-carplay MusicKit 集成 → /skill axiom-now-playing-musickit

ShazamKit 实现 → /skill axiom-shazamkit

• 歌曲识别（Shazam 目录）、自定义音频匹配
• SHManagedSession（现代）与 SHSession（旧版）的选择
• 自定义目录、签名生成、Shazam CLI
• 图库管理（SHLibrary）

ShazamKit API 参考 → /skill axiom-shazamkit-ref

• SHManagedSession、SHSession、SHCustomCatalog、SHSignatureGenerator
• SHMediaItem、SHMatchedMediaItem、SHLibrary、SHError
• 完整的属性键和错误代码

本地化与隐私

本地化 → /skill axiom-localization 隐私体验 → /skill axiom-privacy-ux

身份验证与凭据

通行密钥/WebAuthn 登录 → /skill axiom-passkeys

App 完整性与欺诈防范

App Attest/DeviceCheck → /skill axiom-app-attest

闹钟

AlarmKit（iOS 26+） → /skill axiom-alarmkit-ref

• 闹钟安排与授权
• 实时活动集成
• SwiftUI 闹钟管理视图

日历与提醒事项（EventKit）

EventKit 实现 → /skill axiom-eventkit

• 权限模型（无访问权限、仅写入、完全访问权限）
• 日历事件创建模式（EventKitUI 与直接使用 EventKit）
• 提醒事项模式（DateComponents、EKSource 选择）
• 存储生命周期（单例、变更通知）
• 从 iOS 17 之前的 API 迁移

EventKit API 参考 → /skill axiom-eventkit-ref

• EKEventStore、EKEvent、EKReminder、EKAlarm、EKRecurrenceRule
• EventKitUI 视图控制器
• Siri 日历事件建议（INReservation 捐赠）
• 虚拟会议扩展
• 基于位置的提醒事项

通讯录

通讯录实现 → /skill axiom-contacts

• 权限模型（有限访问与完全访问）
• 通讯录访问按钮（iOS 18+）
• 选择器与存储访问的选择
• CNContactStore 模式
• 通讯录提供程序扩展

通讯录 API 参考 → /skill axiom-contacts-ref

• CNContactStore、CNMutableContact、CNSaveRequest
• CNContactFormatter、CNContactVCardSerialization
• CNContactPickerViewController、ContactAccessButton
• ContactProvider 框架
• 变更历史记录（CNChangeHistoryFetchRequest）

后台处理

BGTaskScheduler 实现 → /skill axiom-background-processing 后台任务调试 → /skill axiom-background-processing-diag 后台任务 API 参考 → /skill axiom-background-processing-ref

推送通知

推送通知实现 → /skill axiom-push-notifications 推送通知 API 参考 → /skill axiom-push-notifications-ref 推送通知调试 → /skill axiom-push-notifications-diag

定位服务

实现模式 → /skill axiom-core-location API 参考 → /skill axiom-core-location-ref 定位问题调试 → /skill axiom-core-location-diag

地图与 MapKit

MapKit 实现模式 → /skill axiom-mapkit

• SwiftUI Map 与 MKMapView 的选择
• 按数量选择标注策略
• 搜索与路线规划
• 8 个反模式

MapKit API 参考 → /skill axiom-mapkit-ref

• SwiftUI Map API
• MKMapView 代理
• MKLocalSearch、MKDirections、Look Around
• 平台可用性矩阵

MapKit 故障排查 → /skill axiom-mapkit-diag

• 标注未显示
• 区域跳动／无限循环
• 聚类问题
• 搜索失败

决策树

1. App Intents／Siri／Apple Intelligence？→ app-intents-ref
2. App Shortcuts？→ app-shortcuts-ref
3. App 可发现性／Spotlight？→ app-discoverability、core-spotlight-ref
4. 小组件／实时活动？→ extensions-widgets、extensions-widgets-ref
5. App 内购买／StoreKit？→ in-app-purchases、storekit-ref
6. 需要 IAP 审计（遗漏 finish、收据验证）？→ iap-auditor（Agent）
7. 需要完整的 IAP 实现？→ iap-implementation（Agent）
8. 相机拍摄？→ camera-capture（模式）、camera-capture-diag（调试）、camera-capture-ref（API）
9. 需要相机代码审计？→ camera-auditor（Agent）
10. 照片选取器／图库？→ photo-library（模式）、photo-library-ref（API）
11. 音频／AVFoundation？→ avfoundation-ref
12. 正在播放？→ now-playing、now-playing-carplay、now-playing-musickit
13. 触觉反馈？→ haptics
14. 音频识别／ShazamKit／歌曲识别？→ shazamkit（模式）、shazamkit-ref（API）
15. 自定义音频目录／第二屏同步／音频匹配？→ shazamkit（模式）、shazamkit-ref（API）
16. 本地化？→ localization
17. 隐私／权限？→ privacy-ux
18. 后台处理？→ background-processing（模式）、background-processing-diag（调试）、background-processing-ref（API）
19. 推送通知实现、APNs 或远程通知处理？→ push-notifications（模式）、push-notifications-ref（API）、push-notifications-diag（调试）
20. 需要 APNs 负载格式、标头或 JWT 身份验证详情？→ push-notifications-ref
21. 推送通知未送达、令牌问题或投递失败？→ push-notifications-diag
22. 定位服务？→ core-location（模式）、core-location-diag（调试）、core-location-ref（API）
23. 地图／MapKit／标注／路线规划？→ mapkit（模式）、mapkit-ref（API）、mapkit-diag（调试）
24. 闹钟／AlarmKit？→ alarmkit-ref
25. 通行密钥／WebAuthn／替换密码／ASAuthorizationController？→ passkeys
26. App Attest／DeviceCheck／欺诈防范／App 完整性？→ app-attest
27. 日历事件／EventKit／EventKitUI／添加到日历？→ eventkit（模式）、eventkit-ref（API）
28. 提醒事项／EKReminder／提醒事项列表？→ eventkit（模式）、eventkit-ref（API）
29. Siri 事件建议／INReservation？→ eventkit-ref（API，第 9 部分）
30. 虚拟会议扩展／EKVirtualConferenceProvider？→ eventkit-ref（API，第 8 部分）
31. 联系人／联系人选取器／CNContactStore？→ contacts（模式）、contacts-ref（API）
32. 联系人访问按钮／有限访问权限／iOS 18 联系人？→ contacts（模式）、contacts-ref（API）
33. Contact Provider 扩展／向系统公开联系人？→ contacts-ref（API，第 10 部分）

避免自我合理化

想法	实际情况
“App Intents 只是遵循一种协议”	App Intents 还包含参数验证、实体查询和后台执行。app-intents-ref 涵盖所有内容。
“Widget 很简单，我以前做过”	Widget 涉及时间线、交互和每年都会演进的 Live Activity 模式。extensions-widgets 是最新的。
“我只需调用一个简单的 API 来添加触感反馈”	每种交互类型都有对应的触感设计模式。haptics skill 符合 HIG 指南。
“本地化只需要 String Catalogs”	Xcode 26 支持类型安全的本地化、生成的符号和 #bundle 宏。localization skill 是最新的。
“相机采集只需设置 AVCaptureSession”	相机采集需要处理中断、旋转和线程要求。camera-capture 涵盖所有内容。
“我直接用 MKMapView 就行，我已经熟悉了”	对于标准地图功能，SwiftUI Map 所需代码量减少 10 倍。mapkit 提供了决策树。
“MapKit 搜索不好用，我要改用 Google Maps SDK”	MapKit 搜索需要配置区域偏置和 resultTypes。mapkit-diag 可在 5 分钟内解决这个问题。
“安排闹钟只需用 UNNotificationRequest”	AlarmKit（iOS 26+）提供专用闹钟 UI、授权和 Live Activity 集成。alarmkit-ref 涵盖该框架。
“推送通知只需要一个负载和一个令牌”	令牌生命周期、Focus 中断级别、服务扩展的易错点，以及沙盒与生产环境不匹配，会导致 80% 的推送问题。push-notifications 涵盖所有内容。
“我们的用户还没准备好使用通行密钥”	Apple、Google 和 Microsoft 已在所有平台上推出通行密钥。用户无需理解加密技术，只需轻点即可。passkeys 涵盖迁移路径。
“App Attest 对我们的应用来说太复杂了”	任何具有服务器端价值的应用（高级内容、虚拟货币、用户账户）都是欺诈目标。app-attest 提供渐进式推出策略。
“直接请求完整的日历访问权限就行”	大多数应用只需添加事件，而 EventKitUI 无需任何权限即可实现。eventkit 提供访问级别决策树。
“ShazamKit 就是 SHSession 加一个代理”	iOS 17+ 提供 SHManagedSession，可省去所有 AVAudioEngine 样板代码。shazamkit 提供版本决策树。
“我直接用 CNContactStore 来选择联系人”	CNContactPickerViewController 无需授权即可显示所有联系人。contacts 提供访问级别决策树。
“联系人访问很简单，只要请求权限并获取联系人”	iOS 18 的有限访问意味着应用可能只能看到部分联系人。ContactAccessButton 可妥善处理这种情况。contacts 涵盖完整模型。

示例调用

用户：“如何为我的应用添加 Siri 支持？” → 调用：/skill axiom-app-intents-ref

用户：“我的 Widget 没有更新” → 调用：/skill axiom-extensions-widgets

用户：“我的 Widget 没有显示更新后的 SwiftData 内容” → 调用：/skill axiom-extensions-widgets，并同时调用 ios-data 路由器来配置 App Group / 共享容器

用户：“我的 Live Activity 没有更新，而且我遇到了推送通知错误” → 调用：/skill axiom-extensions-widgets 处理 ActivityKit，并同时调用 ios-networking 路由器处理推送传递

用户：“使用 StoreKit 2 实现应用内购买” → 调用：/skill axiom-in-app-purchases

用户：“如何本地化应用字符串？” → 调用：/skill axiom-localization

用户：“为按钮轻点实现触感反馈” → 调用：/skill axiom-haptics

用户：“如何设置相机预览？” → 调用：/skill axiom-camera-capture

用户：“接到电话时相机会卡住” → 调用：/skill axiom-camera-capture-diag

用户：“RotationCoordinator 是什么？” → 调用：/skill axiom-camera-capture-ref

用户：“如何让用户在 SwiftUI 中选择照片？” → 调用：/skill axiom-photo-library

用户：“授予访问权限后，用户仍然看不到自己的照片” → 调用：/skill axiom-photo-library

用户：“如何将照片保存到相机胶卷？” → 调用：/skill axiom-photo-library 用户：“我的后台任务始终没有运行” → 调用：/skill axiom-background-processing-diag

用户：“如何实现 BGTaskScheduler？” → 调用：/skill axiom-background-processing

用户：“BGAppRefreshTask 和 BGProcessingTask 有什么区别？” → 调用：/skill axiom-background-processing-ref

用户：“如何实现地理围栏？” → 调用：/skill axiom-core-location

用户：“后台的位置更新不起作用” → 调用：/skill axiom-core-location-diag

用户：“CLServiceSession 是什么？” → 调用：/skill axiom-core-location-ref

用户：“审核我的应用内购买实现” → 调用：iap-auditor Agent

用户：“为我的应用实现应用内购买” → 调用：iap-implementation Agent

用户：“检查我的相机代码是否有问题” → 调用：camera-auditor Agent

用户：“如何在 SwiftUI 应用中添加地图？” → 调用：/skill axiom-mapkit

用户：“我的地图标注没有显示” → 调用：/skill axiom-mapkit-diag

用户：“如何在地图上实现带自动补全的搜索？” → 调用：/skill axiom-mapkit-ref

用户：“滚动时地图区域总是跳动” → 调用：/skill axiom-mapkit-diag

用户：“如何添加两点之间的路线？” → 调用：/skill axiom-mapkit-ref

用户：“如何在 iOS 26 中安排闹钟？” → 调用：/skill axiom-alarmkit-ref

用户：“如何将 AlarmKit 与 Live Activities 集成？” → 调用：/skill axiom-alarmkit-ref

用户：“如何实现推送通知？” → 调用：/skill axiom-push-notifications

用户：“需要哪些 APNs 标头？” → 调用：/skill axiom-push-notifications-ref

用户：“推送通知在开发环境中正常，但在生产环境中不起作用” → 调用：/skill axiom-push-notifications-diag

用户：“我的 Live Activity 没有通过推送更新” → 调用：/skill axiom-push-notifications-diag + /skill axiom-extensions-widgets

用户：“应该使用 FCM 还是直接使用 APNs？” → 调用：/skill axiom-push-notifications

用户：“如何使用 pushTokenUpdates 处理 Live Activities？” → 调用：/skill axiom-extensions-widgets（ActivityKit API 负责推送令牌的监听）

用户：“如何在没有真实服务端的情况下测试推送通知？” → 调用：/skill axiom-push-notifications-ref（命令行测试部分）

用户：“如何实现通行密钥登录？” → 调用：/skill axiom-passkeys

用户：“如何用通行密钥替代密码？” → 调用：/skill axiom-passkeys

用户：“如何验证我的应用没有遭到篡改？” → 调用：/skill axiom-app-attest

用户：“如何防止促销欺诈？” → 调用：/skill axiom-app-attest

用户：“如何在用户的日历中添加事件？” → 调用：/skill axiom-eventkit

用户：“仅写入日历和完整日历访问权限有什么区别？” → 调用：/skill axiom-eventkit

用户：“如何通过编程方式创建提醒事项？” → 调用：/skill axiom-eventkit

用户：“EKEventEditViewController 是什么？” → 调用：/skill axiom-eventkit-ref

用户：“如何实现 Siri 事件建议？” → 调用：/skill axiom-eventkit-ref

用户：“如何让用户选择联系人？” → 调用：/skill axiom-contacts

用户：“联系人访问按钮是什么？” → 调用：/skill axiom-contacts

用户：“如何搜索和获取联系人？” → 调用：/skill axiom-contacts-ref

用户：“如何构建联系人提供程序扩展？” → 调用：/skill axiom-contacts-ref

用户：“如何检测联系人变更以进行同步？” → 调用：/skill axiom-contacts-ref