Intents Extension：关键概念与iOS中Siri Intents集成

什么是iOS中的Intents Extension

Intents Extension 是一个应用程序扩展，允许Siri、Shortcuts和其他系统服务通过标准化的INIntentHandler协议调用应用程序的功能。当用户说“嘿Siri，在X Messenger中发送消息”时，Siri激活相应的扩展，传递请求参数，并接收结果以进行语音播报。

与其他类型的扩展不同，Intents Extension在后台工作，没有可见界面——Siri本身通过语音或文本卡片显示响应。扩展可以选择通过INUIHostedViewProviding提供自定义界面，该界面在执行命令前显示在Siri内部以供确认。

扩展无权访问设备屏幕，也不能独立发起操作——仅响应来自Siri或Shortcuts的请求。这确保了安全性：用户始终控制应用程序通过语音命令执行哪些操作。

SiriKit和intent领域

SiriKit 是Apple的Siri集成框架，在iOS 10中引入。它定义了领域——Siri可以处理的操作类别：消息、电话、支付、列表、提醒、照片、锻炼、预订等。每个领域都有固定的intents和响应集。

标准领域

INSendMessageIntent —— 发送消息。INStartWorkoutIntent —— 开始锻炼。INSearchForPhotosIntent —— 搜索照片。INRequestRideIntent —— 叫出租车。每个领域定义了Siri从语音请求中提取的必需和可选参数。根据Apple的说法，标准领域不需要intentdefinition文件——只需实现相应的处理程序即可。

对于不适合标准领域的应用程序，从iOS 14开始有了自定义intents的可能性。应用程序通过Intents.intentdefinition定义自己的命令类型和参数，Siri根据开发人员提供的示例学习识别相应的短语。

在Info.plist中的配置

Intents Extension通过Info.plist中的IntentsSupported键注册，其中列出了扩展处理的所有intent类。Siri在识别语音命令时使用此列表选择适当的扩展。如果多个扩展支持同一个intent，Siri会为用户提供选择。

class MessageIntentHandler: NSObject,
    INSendMessageIntentHandling {

    func handle(
        intent: INSendMessageIntent,
        completion: @escaping
            (INSendMessageIntentResponse) -> Void
    ) {
        let response = INSendMessageIntentResponse(
            code: .success, userActivity: nil)
        completion(response)
    }
}

INIntentHandler：处理请求

INIntentHandler —— 定义处理intent工作各阶段的方法的协议：参数解析、确认和执行。扩展为其支持的每种intent类型实现这些方法。

三个阶段处理

resolve —— 检查和澄清intent参数。Siri为每个参数调用此方法。如果参数未指定或不正确，扩展返回澄清请求，Siri向用户提出额外问题。confirm —— 确认意图。扩展检查是否可以在当前上下文中执行intent。handle —— 实际执行操作并返回结果。

分为三个阶段对于语音用户体验至关重要：如果参数未被识别，Siri不执行操作，而是再次询问。例如，如果用户说“给Alexei发消息”，但通讯录中有三个Alexei——扩展返回带有澄清请求的resolve，Siri就问“给哪个Alexei？”。

INIntentResponse和状态

INIntentResponse —— 扩展在执行intent后在completion中返回的对象。Response包含结果代码（success、failure、requiresAuthentication、inProgress）以及供Siri播报的可选数据。代码决定了Siri的反应：success —— 语音确认，failure —— 错误消息，inProgress —— 长时操作指示。

func resolve(
    for intent: INSendMessageIntent,
    with completion: @escaping
        (INStringResolutionResult) -> Void
) {
    if let text = intent.content, !text.isEmpty {
        completion(.success(with: text))
    } else {
        completion(.needsValue())
    }
}

创建自定义intents

从iOS 14开始，开发人员能够在标准SiriKit领域之外定义自己的intents。自定义intents在Intents.intentdefinition文件中描述——这是Xcode内部的一个可视化编辑器，用于创建带有参数和响应的新命令类型。

自定义intent的结构

每个自定义intent由INIntent（请求定义）和INIntentResponse（响应定义）组成。INIntent包含带有数据类型的参数——String、Integer、CurrencyAmount、找到的对象等。INIntentResponse包含返回结果的属性和响应代码数组。Xcode根据此定义自动生成Swift类。

Apple建议自定义intent不要超过5个参数——过多会降低语音识别质量并使用户体验复杂化。对于每个参数，最好在Assistant Dialog中提供示例短语，以便Siri学习正确识别它们。

Siri的示例短语

在Intents.intentdefinition中，可以为每个intent指定示例句子——用户将对Siri说的用于激活intent的短语。示例：“在我的应用中点咖啡”，“让我的应用找到披萨食谱”。Siri使用这些短语进行识别训练，并在设置Shortcuts时将其提供给用户。

// Intents.intentdefinition（可视化编辑器）
Intent: OrderCoffeeIntent
Parameters:
  - beverage (String)
  - size (String)
  - quantity (Integer)
Response:
  - orderNumber (String)
  - price (CurrencyAmount)
Phrases:
  - "Order coffee in MyApp"
  - "Get a latte from MyApp"

语音交互和INUIHostedViewProviding

INUIHostedViewProviding —— 允许Intents Extension在执行命令前在Siri内部显示自定义界面的协议。例如，叫出租车时，扩展可以显示带有路线和费用的地图，用户通过触摸确认操作。

界面配置

该协议定义了configure(with:for:completion:)方法，扩展在其中接收intent并返回将嵌入Siri的UIViewController。控制器的尺寸有限——最大高度200点。建议使用包含关键信息（金额、时间、地址）的紧凑卡片。

自定义界面是可选的——如果扩展没有实现INUIHostedViewProviding，Siri会显示带有intent类型和应用程序的标准卡片。对于大多数intents，标准UI已足够，Apple建议仅在真正改善理解时才添加自定义界面——例如显示路线或确认支付。

安全与确认

对于与财务或个人数据相关的intents，需要进行身份验证。INIntentResponse支持requiresAuthentication代码，该代码强制Siri在执行前请求Face ID或Touch ID。身份验证后，扩展通过单独的handle调用接收确认，其中会检查身份验证状态。

Apple特别强调：Intents Extension不应要求自己的密码或生物识别信息——应使用系统身份验证。在Keychain中存储访问令牌并在应用程序和扩展之间共享访问是实现长期会话的标准做法。

class IntentViewController: UIViewController {

    func configure(
        with intent: INIntent,
        completion: @escaping
            (UIViewController?) -> Void
    ) {
        let cardView = ConfirmationCardView()
        let hostingController =
            UIHostingController(rootView: cardView)
        completion(hostingController)
    }
}