探索适用于 Siri 和 Apple 智能的 App Intents 高级功能

一句话判断

这场 Session 最值得关注的一件事是：App Intents 终于从“被动执行死命令的脚本”进化成了“能看懂当前屏幕上下文的眼睛”，Onscreen awareness（屏幕感知）让 Siri 真正具备了处理“播放列表里第三首歌”这种模糊指令的能力。

这场 Session 讲了什么

以前我们做 Siri 适配，基本就是写一堆 Intent，用户必须像念咒语一样精准匹配参数，Siri 才能干活。现在 Apple Intelligence 需要真正的上下文，这场 Session 就是来补全这块拼图的。Apple 引入了视图实体注解（View Entity annotations）和交互捐赠（Interaction Donations），让系统知道用户屏幕上正显示什么，以及用户在 App 里习惯点什么。

对开发者的直接影响是，你不能再只盯着数据模型（AppEntity）看，还得把 UI 视图、通知、甚至 Now Playing 界面和这些模型绑定起来。那些内容庞大或者依赖服务端的 App 也不用再把全量数据塞进本地 Spotlight 索引了，新的 IntentValueQuery 提供了实时结构化搜索的优雅解法。

值得深挖的点

屏幕感知（Onscreen awareness）补齐了 AI 的“视觉”短板

Apple 做这个功能的动机很直接：Apple Intelligence 如果不知道屏幕上有什么，就永远是个瞎子。以前用户说“播放第三首”，Siri 只能干瞪眼，因为它不知道“第三首”在当前 UI 里对应哪个 Entity。现在通过给视图打上 appEntityIdentifier 注解，甚至使用集合注解（collection annotations），Siri 能直接解析屏幕上的视觉元素。

这里的 trade-off 很明显。好处是交互变得极度自然，用户不需要记住实体的具体名字。坑在于维护成本剧增。你的 UI 层级和 Entity 标识符必须保持严格同步，如果列表发生了动态重排或者分页加载，而注解没及时更新，Siri 就会执行错误的操作。这要求开发者在写 SwiftUI 或 UIKit 视图时，必须把“可访问性”和“AI 可感知性”放在同等重要的位置。

IntentValueQuery 与本地语义索引的明智分流

处理 App 内容发现时，Apple 这次给出了两条路：本地小数据用 IndexedEntity 进 Spotlight 语义索引，服务端或大数据用 IntentValueQuery 实时查。这是一个非常务实的设计选择。

以前为了支持 Siri 搜索，很多开发者被迫把成千上万条数据通过 CoreSpotlight 塞进本地，导致设备发热、索引卡顿，甚至引发隐私合规问题。IntentValueQuery 把搜索逻辑交还给 App 服务端，系统只传递结构化的搜索意图（比如 AudioSearch），App 返回 UnionValue。好在哪？它彻底解耦了索引和搜索，保护了用户隐私，也减轻了设备负担。可能的坑是，你需要自己处理网络延迟和超时，如果服务端响应慢，Siri 的体验会直接崩盘。

代码片段

1. 意图执行中途的动态提问

场景：创建定时器时，如果发现已经有一个在运行，中途询问用户给新定时器命名，而不是直接报错或覆盖。

@AppIntent(schema: .clock.createTimer)
struct CreateTimerIntent {
    var duration: Duration
    var label: String?
    var isSleepTimer: Bool

    func perform() async throws -> some ReturnsValue<TimerEntity> {
        // 检查是否有运行中的定时器，动态请求缺失的可选参数
        label = try await $label.requestValue(
            """
            你已经有一个定时器在跑了。
            我们要给这个新的起个什么名字？
            """
        )
        return .result(value: timerEntity)
    }
}

坑：requestValue 会挂起当前意图的执行，如果用户在中途取消了对话，你需要妥善处理抛出的错误，别让 App 状态卡死。

2. 服务端大数据的结构化搜索

场景：音乐 App 歌曲库庞大，不建本地索引，直接通过 IntentValueQuery 接收 Siri 的搜索条件并返回结果。

struct AudioIntentValueQuery: IntentValueQuery {
    // 接收系统传递的结构化搜索输入
    func values(for input: AudioSearch) async throws -> [AudioEntity] {
        switch input.criteria {
        case .searchQuery(let query):
            // 走服务端搜索接口
            return try await searchResults(for: query)
        case .unspecified:
            // 没给具体词，返回用户喜欢的歌
            return try await likedSongResults()
        case .url(let url):
            return try await resolveEntity(from: url)
        }
    }
}

坑：返回的数组不要太大，Siri 处理巨量 Entity 会非常慢。尽量在服务端做好分页或 Top-N 截断。

3. 捐赠 UI 交互让 AI 学习偏好

场景：用户在 App 内点击发送消息，把这个动作捐赠给系统，让 Apple Intelligence 学习用户的聊天习惯。

func sendMessage(_ message: Message, donateIntent: Bool = false) async throws {
    // 实际发送消息逻辑...
    
    if donateIntent {
        let intent = SendMessageIntent()
        intent.destination = .recipients(conversation.recipients.map(\.entity))
        
        Task {
            // 捐赠意图及结果，帮助系统学习偏好
            try await IntentDonationManager.shared.donate(
                intent: intent,
                result: .result(value: message.entity)
            )
        }
    }
}

坑：只捐赠真实的、用户主动触发的 UI 交互。千万别在后台批量伪造捐赠，系统会识别出过度捐赠并直接忽略你的 App。

最佳实践

已有项目迁移时，别急着把所有 Entity 都加上 IndexedEntity。先盘点你的数据量级，超过几千条的动态数据直接上 IntentValueQuery。优先把高频使用的核心视图加上 appEntityIdentifier，跑通“屏幕感知”的最小闭环。

新项目建议从一开始就把 AppEntity 的设计融入数据模型层，而不是等 UI 写完了再去硬凑。定义 Entity 时，把 DisplayRepresentation（展示表示）的 title、subtitle 和 image 配齐，这能免费让你的 App 在 Spotlight、Siri 和快捷指令里看起来更专业。

实战中最容易踩的坑是忽略了“纯语音设备”（如 AirPods）。当你使用 ShowsSnippetView 返回自定义 SwiftUI 视图时，必须同时提供 ProvidesDialog 的 full string。如果只给视图不给完整对话，AirPods 用户听到的将是一片死寂。

还有什么值得关注

实体所有权确认（Entity Ownership）：实现了 OwnershipProvidingEntity 协议的共享或公共内容，Siri 在执行修改操作前会自动弹出确认界面，防止误改别人的日历或文档。
通知与 Now Playing 的实体绑定：现在可以在 UNMutableNotificationContent 和 MediaSessionRepresentable 上直接挂载 appEntityIdentifier，用户可以直接对着通知或锁屏音乐控件喊 Siri 执行操作。
应用内搜索（In-app search）重定向：采用 searchInApp schema 后，Siri 可以把“在 App 里搜索 XX”的指令直接路由到你 App 原生的搜索 UI，省去了自己写一堆复杂搜索 Intent 的麻烦。