症状：App 已经有快捷操作，但 Siri AI 找不到其中的内容，或者不能按自然语言正确调用操作。
最快判断：先把真实内容建模为 App Entities，再用适配的 App Intents 或 App Schemas 暴露操作；只有需要理解屏幕内容或跨 App 传递数据时，才补上对应能力。实现完成不等于 Siri 端到端体验已验收。
适合正在开发 iOS App、希望 Siri 查找应用内容或调用操作的独立开发者，也适合需要规划实体、Schema 与测试分工的小团队。
如果需求只是给 Shortcuts 增加一个固定动作，或产品没有值得系统识别的内容对象，先别为了 Siri AI 把全部数据都改造成实体。
最后更新于 2026 年 10 月 4 日；API 名称、能力说明与版本边界核对自 Apple Developer 的 App Intents 文档更新记录、WWDC26 App Schemas 技术视频及 Xcode 系统要求。具体支持情况仍应以项目目标系统和当前文档为准。
00先判断 Siri 要找的是内容，还是只要执行动作
如果用户会说“打开上周保存的草稿”或“查找最近一条订单”，应用需要让系统知道这些对象是什么、怎样区分、哪些属性适合用于查找。Apple 将这类应用数据的结构化表示称为 App Entity；它不是对整个数据库的导出，而是供系统识别和交互使用的模型。
先从用户真正会说的词反推字段，而不是把数据库字段全部暴露出来。比如项目管理 App 的“项目”实体可以用稳定 ID 定位，以项目名显示，再按真实检索需求提供客户名或状态；如果用户不会按内部流水号找项目，流水号就不该成为主要展示标题。
接下来判断查询方式：
- 内容稳定、适合预先建立搜索索引：评估
IndexedEntity，并挑选真正有搜索价值的属性进入索引。 - 数据实时变化，或预先索引不合适：检查实体查询能否根据输入即时查找，避免索引内容过期。
- 内容数量多、搜索结果可能重名：测试标识解析、展示名称和消歧逻辑；不能只验证某个 ID 能查回来。
Apple 的 Spotlight 实体索引指南介绍了 IndexedEntity、索引属性以及通过实体标识打开内容的处理方式。索引能让系统有机会找到内容，但不构成 Siri 必然命中或给出特定答案的保证。
⚠️ 不要把“实体已索引”写成“用户一定能通过 Siri 找到”。验收时要记录具体查询词、返回实体和目标系统版本；找不到时再分别排查索引、查询实现和属性是否贴合用户的说法。
01按动作选择 App Intent，并核对 App Schema 是否匹配
App Intent 表达应用提供的一项操作，包括参数、执行逻辑和结果；它可以被系统体验发现，但这并不等于每个自定义 Intent 都自动适合 Siri 的自然语言操作。App Intents 概览列出了动作定义、参数和结果等基本职责。
先从用户目标拆出操作合同：用户要对哪个实体执行什么动作？缺少对象或必需参数时怎么办？操作成功后返回什么？权限不足、对象已失效或网络请求失败时，系统收到的结果又是什么？这些问题应先在业务逻辑中有清楚答案，再考虑 Siri 的入口。
| 需求场景 | 优先考虑 | 验收重点 |
|---|---|---|
| 应用特有、系统没有同类约定的动作 | 通用 App Intent | 参数、执行结果、错误与 Shortcuts 中的呈现 |
| 能对应系统定义的内容或动作类别 | 匹配的 App Schema | 领域、必需属性、参数结构及该领域的采用要求 |
| 只需在应用内处理用户当前看到的对象 | 实体与屏幕上下文关联 | 系统解析的对象是否就是当前视图中的对象 |
| 内容需要交给另一款应用继续处理 | Transferable 与适当的表示方式 |
导出、接收解析、权限与失败回退 |
App Schema 文档把 Schema 说明为特定领域的结构约定，并提醒开发者只采用与实际功能相符的领域；部分领域还要求成组实现相关 Schema。因而，Schema 不是“加上就能提升 Siri 准确率”的装饰，也不是业务逻辑的替代品。若找不到匹配的 Schema，通用 App Intent 仍可用于暴露应用动作，但应单独验证目标系统如何呈现和调用它。
涉及发送、删除或其他有副作用的操作时，明确操作对象、授权状态和确认时机。尤其是共享或公开可访问的实体，Apple 的 App Intents 更新记录列出了与敏感或破坏性操作确认有关的实体能力；是否适用，应按当前 API 说明和实际数据所有权设计，而不是假设系统会替应用补齐安全判断。
02为“这个”或“刚才那项”补充屏幕上下文
用户指着当前列表说“打开这个项目”，与用户在 Siri 中报出项目名称，是不同的解析入口。屏幕上虽然能看到文字，系统却不能据此直接知道哪些文本对应应用里的哪个真实对象；应用需要在适用时把视图或用户活动与实体关联。
先看界面当前有几个重要对象：只有一个主要内容时，核对与该用户活动关联实体的方式；列表或消息流同时显示多个对象时，逐项检查视图注释能否指向正确实体。Apple 的上下文线索文档说明，可以用 App Entities 为界面内容提供结构化上下文。
不要只用“打开页面”作为验收。准备类似“总结这条消息”“打开列表中刚才选中的项目”这样的指代型输入，分别确认系统解析的实体 ID、应用实际执行的对象，以及对象消失或列表刷新后的失败处理。若界面排序会改变，尤其要确认上下文关联的是稳定实体，而非容易漂移的行位置。
03只有存在跨 App 交接时才增加内容传递
屏幕上下文解决的是“用户指的是什么”，内容传递解决的则是“另一个 App 能否接收并使用这个对象”。先分别检查提供内容的一方和接收内容的一方：实体如何导出、接收方如何解析或创建对应数据、最终触发哪个目标操作。不要把这条系统协作路径误写成当前 App 可以直接调用另一款 App 的任意操作。
当实体能够映射到系统可理解的类型时，可以进一步评估 Transferable 与 IntentValueRepresentation。Apple 的 IntentValueRepresentation 文档介绍了应用实体与系统 Intent 值之间的转换；上下文线索文档也说明，不同内容表示方式会影响其他 App 实际能利用哪些信息。
用一份最小样例验证完整交接：导出的实体是否包含接收操作所需字段？接收端能否识别已有对象，还是需要创建新对象？无权限、缺字段或类型无法转换时，是否能给出可理解的回退结果？如果产品没有明确的跨 App 内容流转需求，就先不增加这层复杂度。
04用分层验收区分代码正确与 Siri 可用
验收不要停在“编译通过”或“Intent 的 perform() 返回成功”。Apple 的 验证 App Intents 实现指南将代码层、系统入口和 Siri 端到端体验分别处理；App Intents Testing 文档说明，测试框架可用于验证 Intent、实体和查询逻辑。
按以下顺序建立证据，失败时就能定位到具体层：
- 业务逻辑：用已有单元测试验证权限、状态变化、参数边界和副作用；数据层测试不应依赖 Siri 是否正确识别语句。
- Intent 与查询：使用 App Intents Testing 运行 Intent、实体查询和结果断言，覆盖实体不存在、同名和参数不完整等情况。
- 系统入口：检查 Shortcuts 中动作名称、参数说明和返回值；若提供 Spotlight 索引，则实际搜索几种用户会用的表达，并验证结果能否打开正确对象。
- 屏幕上下文与传递：从真实界面发起指代测试，再检查跨 App 导出与接收解析；不要只测一个静态样例。
- Siri 端到端：在目标系统和设备上，用自然说法测试发现、消歧、确认、执行结果和失败回退。把实际设备上的 Siri 体验单独记录，不能以模拟器、自动化测试或远程构建结果代替。
可勾选的验收清单：
- [ ] 每个可查找实体都有稳定标识，展示名称与用户实际称呼相符。
- [ ] 每个搜索属性都对应具体检索需求；动态内容已评估即时查询，而不是默认索引。
- [ ] 每个 Intent 都定义了参数缺失、权限不足、对象失效及执行失败时的结果。
- [ ] 只有业务匹配的动作或实体才采用对应 Schema；领域要求已按当前文档复核。
- [ ] 屏幕指代测试验证了实体关联，而不是仅验证页面打开。
- [ ] 跨 App 传递测试覆盖导出、导入、权限和失败回退；没有该需求时不额外实现。
- [ ] 构建与自动化测试通过后，仍在目标设备上完成人工 Siri 端到端核验。
截至本文更新时，Apple 的 Xcode 系统要求页面列出 Xcode 27 RC 对应 macOS Tahoe 26.6 或更高版本及 iOS 27 SDK。开发环境能构建目标版本，只能证明构建工具链满足相应要求，不证明目标设备上的 Siri 体验、系统入口或用户权限条件都已验证；发布前应按项目当前采用的 Xcode 和系统版本重新核对。
如果 App Intents 逻辑已经完成，但开发机无法稳定承担构建与设备测试，可以把本地设备、远程 Mac 和其他构建环境分别按用途比较：本地 Mac 便于连接物理设备和检查即时交互，但需自行承担购置与维护；通用云构建可能适合自动化任务，却不应被当作真机 Siri 验收的替代品；远程 Mac 则可作为需要 macOS 工具链的构建与测试环境，仍要结合实际设备完成端到端验证。可先查看 NUKCLOUD 的远程 Mac 环境入口，再按项目是否需要持续构建、交互调试或短期验证，核对远程 Mac 方案页面。若工作负载长期稳定且需要物理接口，自购 Mac 可能更合适；若只是临时补足 macOS 构建和验证环境，再评估租用是否更灵活。