在 iOS 上把 App 功能暴露给 Siri、快捷指令…

当需要让 App 的动作和实体被系统各入口（Siri、Shortcuts、Spotlight、Widget、Control Center、Apple Intelligence）发现和调用时，按此流程实现 App Intents。

适用场景

解决思路

1. 按三步分诊流程推进：Step 1 从用户想在 App 外完成的 1-3 个有价值动作出发（而非从界面层级出发），为每个动作记录一行设计：用户目标、内联结果或 App 跳转目标、共享领域操作、参数与实体查询、确认/认证需求、目标系统入口与协议；用一条显式的运行时路由处理 App 跳转，不要把导航副作用散落在各个 intent 中。
2. 根据动作选择合适的系统功能与协议：Siri/Shortcuts 用 AppIntent（iOS 16+）；可配置小组件用 WidgetConfigurationIntent（iOS 17+）；控制中心用 ControlConfigurationIntent（iOS 18+）；Spotlight 搜索用 IndexedEntity（iOS 18+）；Apple Intelligence 用 @AppIntent(schema:)（iOS 18+）；交互式 snippet 用 SnippetIntent（iOS 26+）；Visual Intelligence 用 IntentValueQuery（iOS 26+）。
3. Step 2 定义数据模型：优先为暴露给系统的 App 数据创建 AppEntity 影子模型；为固定参数选项创建 AppEnum 类型；为解析选择合适的 EntityQuery 变体；用 IndexedEntity 和 indexingKey 元数据标记可搜索实体。
4. Step 3 实现 intent：遵循 AppIntent（或专用子协议）；为所有面向用户的输入声明 @Parameter 属性；实现 perform() async throws -> some IntentResult；为 Shortcuts UI 添加 parameterSummary；通过 AppShortcutsProvider 注册短语。
5. Step 4 验证：在目标系统入口中构建并运行，确认可发现性、参数解析、取消、确认、认证、结果渲染和 App 跳转；若某步失败，重置 fixture，修复最小的 intent/entity/query 边界，再从同一入口重跑同一动作，然后再添加下一个动作；用 Xcode 的 intent preview 测试 Siri 短语；确认 IndexedEntity 实例已索引到具名 Spotlight 索引；检查 WidgetConfigurationIntent 的小组件配置。
6. 实现 AppIntent 协议：系统通过 init() 实例化 struct，设置参数后调用 perform()；声明 title 和 parameterSummary 供 Shortcuts UI 使用；可选成员包括 description（IntentDescription）、openAppWhenRun（Bool）、isDiscoverable（Bool）、authenticationPolicy（IntentAuthenticationPolicy）。
7. 使用 @Parameter 声明每个面向用户的输入：非可选参数为必填，系统会在需要时请求值；default 预填有用值；可选参数不会被自动请求，因此当 intent 无法继续时必须自己在 perform() 中请求。
8. @Parameter 支持的值类型：基础类型 Bool、Int、Double、String、Duration、Date、Decimal、Measurement、URL；集合为受支持元素类型的 Array 和 Set；框架类型 IntentPerson、IntentFile；自定义类型为任意 AppEntity 或 AppEnum。
9. @Parameter 常用初始化模式：基础 @Parameter(title: "Name") var name: String；带默认值 @Parameter(title: "Count", default: 5) var count: Int；数值滑块 @Parameter(title: "Volume", controlStyle: .slider, inclusiveRange: (0, 100)) var volume: Int；动态选项 @Parameter(title: "Category", optionsProvider: CategoryOptionsProvider()) var category: Category；带内容类型的文件 @Parameter(title: "Document", supportedContentTypes: [.pdf, .plainText]) var document: IntentFile；带单位的测量 @Parameter(title: "Distance", defaultUnit: .miles, supportsNegativeNumbers: false) var distance: Measurement<UnitLength>。
10. 实现 AppEntity：优先使用镜像 App 数据、只暴露面向系统字段的影子模型；当模型轻量、稳定且适合 App Intents 生命周期时可直接让模型遵循协议；必需项包括 id、静态 defaultQuery、displayRepresentation、静态 typeDisplayRepresentation；用 @Property(title:) 标记要暴露用于过滤/排序的属性，未标记的属性保持内部可见。
11. 按场景选择四种 EntityQuery 变体：1) 基础 EntityQuery 按 ID 解析，实现 entities(for:) 和 suggestedEntities()；2) EntityStringQuery 支持自由文本搜索，实现 entities(matching:) 和 entities(for:)；3) EnumerableEntityQuery 用于有限集合，实现 allEntities() 和 entities(for:)；4) UniqueAppEntityQuery（iOS 18+）用于单例实体（如 App 设置），实现 uniqueEntity()。
12. 当某个参数决定另一个参数的有效实体选项时，在 query 或 options provider 中使用 @IntentParameterDependency；注意处理上游为 nil 的情况和有意设置的默认值。
13. 定义 AppEnum 表示固定可选值集合：RawValue 必须遵循 LosslessStringConvertible，优先使用 String 原始值以获得可读且稳定的标识符；提供静态 typeDisplayRepresentation 和 caseDisplayRepresentations 字典。
14. 通过 AppShortcutsProvider 注册预置快捷指令：在 appShortcuts 中返回 AppShortcut(intent:phrases:shortTitle:systemImageName:)，并设置 shortcutTileColor；短语规则：每个短语必须包含 \(.applicationName)，可引用参数如 \(.$soup)，动态选项值变化时调用 updateAppShortcutParameters()，用 negativePhrases 防止 Siri 误触发。
15. 实现 SnippetIntent（iOS 26+）在系统 UI 中显示交互式 snippet：perform() 返回 some IntentResult & ShowsSnippetView；调用方 intent 返回 some IntentResult & ShowsSnippetIntent 并传入 .result(snippetIntent:)；系统可能多次调用 perform()（包括 snippet 按钮或开关动作之后），因此保持 SnippetIntent.perform() 无副作用，把变更放在调用方 action intent 或单独的按钮/开关 action 中；仅 snippet 的 intent 除非 isDiscoverable 为 true，否则不会在 Shortcuts 或 Spotlight 中可发现。
16. 实现 IntentValueQuery（Visual Intelligence，iOS 26+）：用 @UnionValue 枚举在单个 query 中返回多种 App 实体类型；只有一种 IntentValueQuery 可以接收 SemanticContentDescriptor；把 labels 当作高层英文描述符而非穷举同义词或 App 分类法，并在可用时结合 pixelBuffer；返回少量、已排序、可取消的结果，并提供 OpenIntent、URL 表示或 App 内搜索跳转以查看详情和更多结果；不要在 App Intents query 内实现相机采集、Vision VN* 请求、条码分类或 Spotlight 索引，而应调用已有的有界 App 搜索或图像匹配服务，并在工作可能超出系统 UI 预算时设置明确的结果上限和超时。
17. 避免常见错误：不要通过 AppEntity 暴露过多 App 模型状态（用专用影子模型、稳定持久 ID 和仅面向系统的属性）；短语中不要漏掉 \(.applicationName)；不要把可选 @Parameter 当作必填（可选参数不会自动请求，需要时调用 requestValue / needsValueError）；不要使用不稳定的 AppEnum 原始值（优先 String）；不要忘记 suggestedEntities()（否则 Shortcuts 选择器没有默认项）；entities(for:) 中缺失实体不要抛错而应省略；不要留下过期的 Spotlight 索引（用具名 CSSearchableIndex 重新索引）；不要漏掉 typeDisplayRepresentation（AppEntity 和 AppEnum 都必需）；不要使用已废弃的 @Assistant* schema 宏（改用 @AppIntent(schema:)、@AppEntity(schema:)、@AppEnum(schema:)）；不要阻塞或有副作用地执行 perform()（I/O 用 await，SnippetIntent.perform() 保持无副作用因为系统可能重跑）；不要在没有保护的情况下从系统入口修改敏感状态（门锁、灯、购买、删除等动作要使用确认和/或认证）。
18. 按 Review Checklist 自检：每个 AppIntent 有描述性 title（动词+名词，标题大小写）；必填 @Parameter 非可选，可选值在需要时请求；AppEntity 暴露稳定 ID 和仅面向系统的属性；AppEntity 有 displayRepresentation 和 typeDisplayRepresentation；EntityQuery.entities(for:) 省略缺失 ID 且实现了 suggestedEntities()；依赖选项使用 @IntentParameterDependency，仅在存在真正有用默认值时提供 defaultResult()；AppEnum 优先稳定 String 原始值和 caseDisplayRepresentations；AppShortcutsProvider 短语包含 \(.applicationName) 且定义了 parameterSummary；IndexedEntity 属性使用 key-path indexingKey 值且实体已索引；Control Center intent 遵循 ControlConfigurationIntent，widget intent 遵循 WidgetConfigurationIntent，无默认值的 control 参数为可选；敏感 App Intents 在修改状态前请求确认和/或认证；Visual Intelligence IntentValueQuery 使用 SemanticContentDescriptor、有界结果、打开路径和 iOS 26 可用性标注；没有已废弃的 @AssistantIntent / @AssistantEntity / @AssistantEnum schema 宏；perform() 使用 async/await（无阻塞）、在预期隔离上下文中运行、intent 类型为 Sendable。

适用边界 · 注意事项

• 不适用于非 iOS 平台或不需要把 App 功能暴露给系统入口（Siri、Shortcuts、Spotlight、Widget、Control Center、Apple Intelligence）的场景。
• 不适用于只想做 App 内导航或界面层级设计、而不打算让系统在 App 外发现和调用动作的场景。
• Visual Intelligence 的 IntentValueQuery 不适用于在 query 内实现相机采集、Vision VN* 请求、条码分类或 Spotlight 索引，这些应交给已有的有界 App 搜索或图像匹配服务。