iOS 26 中的 App Intents 2.0：视觉智能、交互式片段与延迟属性

App Intents 在 iOS 16 中作为 Apple 面向 Shortcuts、Siri 和 Spotlight 的结构化操作 API 推出；iOS 17 将其扩展到由 App Intents 驱动的小组件；iOS 18 则使其成为 Apple Intelligence 操作界面的契约。iOS 26 将 App Intents 扩展到视觉智能（来自第三方应用的图像搜索结果）、交互式片段（可融入系统上下文的小型弹出 UI 窗口）、实体视图注解（实体的内联渲染方式）以及 @DeferredProperty（异步计算的实体属性）¹。这些扩展并未改变 App Intents 的核心模型；它们为应用增加了新的参与界面。

本文将对照 Apple 官方文档梳理 iOS 26 的新增内容。讨论的视角是”已经采纳 App Intents 的应用，通过添加 iOS 26 的协议遵从可以获得哪些新界面”，因为大多数采用了 App Intents 的应用已经具备基础类型，而 iOS 26 的工作重点是把这些类型扩展到新的上下文中。

TL;DR

• IntentValueQuery 是用于视觉智能集成的新协议。该查询接收 SemanticContentDescriptor（用户的视觉上下文），并返回应用认为相关的 AppEntity 实例数组²。
• @DeferredProperty 用于声明值需异步计算的实体属性。该属性仅在系统真正需要时才会加载，从而避免实体在拥有许多展示廉价字段加上少量计算昂贵字段时承担前置开销。
• 交互式 App Intents 片段允许应用在 Spotlight、视觉智能或 Siri 响应界面等系统上下文中展示带按钮、文本和控件的小型弹出窗口。该片段是绑定到 App Intent 结果的 SwiftUI 视图。
• 实体视图注解允许应用声明 AppEntity 在不同系统上下文中的渲染方式（Spotlight 中的紧凑行、视觉智能中的主图卡片、类似 Live Activity 的小组件）。
• 集群中的 App Intents 一文介绍了基础模型；本文将其延伸到 iOS 26 的新参与界面。集群中的 App Intents 与 MCP Tools 一文 则探讨了 Apple Intelligence 意图界面与通用智能体 MCP tools 之间的路由问题。

视觉智能：IntentValueQuery 与 SemanticContentDescriptor

iOS 26 在 App Intents 上的旗舰新增是视觉智能集成²。流程如下：

1. 用户拍照、截屏或将相机对准某个物体。
2. 系统的视觉智能层提取视觉与语义上下文（图像中有什么、用户可能想了解什么）。
3. 系统使用该语义上下文向每个注册了 IntentValueQuery 的应用发起查询。
4. 每个应用返回相关的 AppEntity 实例；系统进行聚合并在视觉智能 UI 中呈现。
5. 用户点按某个实体即可在恰当的上下文中进入对应应用。

开发者面对的是一个遵循 IntentValueQuery 协议的结构体，其中的 values(for:) 方法接收一个 SemanticContentDescriptor：

import AppIntents

struct ProductLookupQuery: IntentValueQuery {
    func values(for descriptor: SemanticContentDescriptor) async throws -> [Product] {
        // descriptor.labels: detected category and content labels
        // descriptor.pixelBuffer: the visual content as a CVReadOnlyPixelBuffer
        //                        (use VideoToolbox/CoreImage to convert if needed)
        let candidates = try await catalog.search(labels: descriptor.labels)
        return candidates.map(Product.init)
    }
}

SemanticContentDescriptor 携带由系统填充的两个字段：labels（一组检测出的类别和内容标签数组，如”wine bottle”、”pinot noir”、”label text”等）以及 pixelBuffer（底层图像数据，类型为 CVReadOnlyPixelBuffer，供希望在内容上运行自有视觉模型的应用使用）。应用的职责是将这些信号映射到自身数据并返回匹配的实体。

正确的采纳模式：购物应用基于商品目录实现该查询（视觉上下文 → 匹配商品），葡萄酒应用基于酒瓶数据库实现（标签图像 → 葡萄酒条目），食谱应用基于食谱库实现（食材照片 → 匹配食谱）。

@DeferredProperty：异步实体值

现有 AppEntity 类型以静态方式声明属性。每个属性都必须在实体返回前完成计算。对于属性成本不一的实体（标题/副标题/图片很快，来自服务器的详细描述很慢），这种”全有或全无”的计算方式是浪费的。

@DeferredProperty（iOS 26+）将属性声明为异步计算³：

import AppIntents

struct Recipe: AppEntity {
    static var typeDisplayRepresentation = TypeDisplayRepresentation(...)
    static var defaultQuery = RecipeQuery()

    @Property(title: "Title")
    var title: String

    @Property(title: "Cuisine")
    var cuisine: String

    @DeferredProperty(title: "Detailed Instructions")
    var instructions: String {
        get async throws {
            try await loadInstructionsFromBackend(id: id)
        }
    }
}

延迟属性的 getter 是异步的；只有当系统真正需要该值时（例如实体被选中以显示详情时）才会执行。对于那些只在选择 UI 中使用、由查询返回的实体而言，延迟属性永远不会被计算。

该模式适用于任何兼具构建廉价字段（id、title、summary）与构建昂贵字段（完整正文、计算指标、服务器获取数据）的实体。如果没有 @DeferredProperty，开发者要么计算所有字段（浪费），要么只计算廉价字段并另外添加”加载详情”意图（更复杂）。

交互式片段与 SnippetIntent

iOS 26 引入了专用于片段交互的 SnippetIntent 协议，与早期版本中已有的、遵循 ShowsSnippetView 的 AppIntent 模式并存⁴。SnippetIntent 增加了一个静态的 reload() 方法，系统可调用该方法在不重新调用整个 intent 的情况下刷新片段内容：

struct WeatherSnippet: SnippetIntent {
    static var title: LocalizedStringResource = "Weather Snippet"

    @Parameter(title: "City")
    var city: City

    func perform() async throws -> some IntentResult & ShowsSnippetView {
        let forecast = try await weatherService.forecast(for: city)
        return .result(view: ForecastSnippet(forecast: forecast))
    }

    static func reload() async throws {
        // Triggered by the system when it wants fresh snippet data
        // (e.g., after the data source signals an update)
    }
}

对于希望在响应中附带片段视图、但本身并非专用片段的 intent，现有的 AppIntent + ShowsSnippetView 模式仍然适用：

struct WeatherForecastIntent: AppIntent {
    static var title: LocalizedStringResource = "Weather Forecast"

    @Parameter(title: "City")
    var city: City

    func perform() async throws -> some IntentResult & ProvidesDialog & ShowsSnippetView {
        let forecast = try await weatherService.forecast(for: city)

        return .result(
            dialog: "Here's the forecast for \(city.name).",
            view: ForecastSnippet(forecast: forecast)
        )
    }
}

struct ForecastSnippet: View {
    let forecast: Forecast
    var body: some View {
        VStack(alignment: .leading) {
            Text(forecast.headline).font(.headline)
            HStack {
                ForEach(forecast.days) { day in
                    DayCell(day: day)
                }
            }
            Button("Open in App") {
                // App-launching action wired via App Intents
            }
        }
        .padding()
    }
}

结果类型遵循 ShowsSnippetView 即告诉系统在 dialog 旁渲染该 SwiftUI 视图。该片段是可交互的：其中的按钮可触发其他 App Intents，用户可滚动，视图也会参与系统的交互层。

适合采用交互式片段的场景：天气预报、日历事件、交通时间、体育比分、包裹追踪。任何用户希望在系统界面上获得超过单行 dialog 响应的地方都适用。

实体视图注解

实体视图注解允许应用声明 AppEntity 在不同系统上下文中的渲染方式⁵。该机制通过为 DisplayRepresentation 提供多种变体来实现：

struct Recipe: AppEntity {
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(
            title: "\(title)",
            subtitle: "\(cuisine) - \(time) min",
            image: .init(named: imageName)
        )
    }
}

经典模型仅返回单个 DisplayRepresentation。iOS 26 允许实体提供面向上下文的多种变体，由系统根据渲染场景（紧凑列表、主图卡片、Spotlight 结果、视觉智能面板）从中挑选。框架按上下文选择合适的变体；应用只需声明每一种。

该模式适用于需要在不同场景下使用不同实体渲染的应用，例如紧凑的 Spotlight 列表与单卡片的视觉智能响应之间。多种变体可以组合使用，应用无需自行检测上下文。

与现有 App Intents 的组合

iOS 26 的新增内容可与现有 App Intents 原语组合：

• 应用的 AppShortcutsProvider（在 无障碍即平台 中介绍）为语音、操作按钮和 Spotlight 注册 shortcuts。
• 每个 AppShortcut 都引用一个 AppIntent，其 @Parameter 属性会从用户的请求中解析得到。
• AppIntent.perform() 方法返回的结果类型可包含片段视图（ShowsSnippetView）或 dialog（ProvidesDialog）。
• 被 intent 参数引用的 AppEntity 类型现在支持 @DeferredProperty 和实体视图注解。
• 新的 IntentValueQuery 类型让相同的实体能够出现在视觉智能中。

整体形态：现有模型保持不变；iOS 26 的工作是在同一个实体界面上添加新类型（查询）和新注解（延迟属性、视图变体）。

常见失败模式

App Intents 2.0 采纳过程中常见的三种失败模式：

IntentValueQuery 返回未限定范围的结果。 一个不顾相关性、把所有匹配描述符搜索词的商品全部返回的查询，会稀释视觉智能体验。修复方法：限定查询范围（按相关性取前 N 项、按时效加权、按用户个性化），让每个返回的实体都配得上系统 UI 中的位置。

对快速取值使用 @DeferredProperty。 延迟机制是为真正昂贵的计算准备的。把内存中可快速读取的属性标记为延迟属性只会徒增异步开销而毫无收益。修复方法：将 @DeferredProperty 留给那些延迟后真正能带来收益的属性（服务器请求、大型计算、ML 模型调用）。

把交互式片段做成完整应用。 片段是紧凑的 UI 界面；将其当作迷你应用对待会让片段显得拥挤或渲染缓慢。修复方法：让片段聚焦于即时响应和一两个相关操作；用”Open in App”按钮把复杂流程交给完整应用处理。

该模式对 iOS 26+ 应用的意义

三点要点。

1. 为任何包含视觉内容的应用添加 IntentValueQuery。 购物、食谱、商品、地点、可识别物体。视觉智能集成是新的发现界面；不参与的应用在那里就是隐形的。

2. 对昂贵的实体字段使用 @DeferredProperty。 详细描述、计算指标、服务器获取数据。默认异步的模式与现代 Swift 代码契合，并能让构建廉价的实体快速返回。

3. 为高价值查询类型采纳交互式片段。 天气、日历、交通、体育、包裹追踪。在单行 dialog 不够、但启动整个应用又过头的场景中，片段 UI 能让用户留在系统响应界面上。

完整的 Apple Ecosystem 集群：类型化的 App Intents；MCP 服务器；路由问题；Foundation Models；运行时与工具 LLM 之分；三个界面；单一事实来源模式；两个 MCP 服务器；Apple 开发中的 hooks；Live Activities；watchOS 运行时；SwiftUI 内幕；RealityKit 的空间心智模型；SwiftData 模式纪律；Liquid Glass 模式；多平台发布；平台矩阵；Vision 框架；Symbol Effects；Core ML 推理；Writing Tools API；Swift Testing；Privacy Manifest；无障碍即平台；SF Pro 排印体系；visionOS 空间模式；Speech 框架；SwiftData 迁移；tvOS 焦点引擎；@Observable 内幕；SwiftUI Layout 协议；自定义 SF Symbols；AVFoundation HDR；watchOS 训练生命周期；我拒绝撰写的内容。集群入口位于 Apple Ecosystem Series。如需更广泛的”iOS 配 AI 智能体”上下文，请参阅 iOS Agent Development guide。

FAQ

测试 IntentValueQuery 是否需要启用 Apple Intelligence？

完整的视觉智能测试需要。视觉智能要求具备 Apple Intelligence 能力的硬件（iPhone 15 Pro 或更新机型，M1 Mac 或更新机型），运行 iOS 26+ 并启用 Apple Intelligence。在开发阶段，您可以在单元测试中直接构造 SemanticContentDescriptor 并调用查询的 values(for:) 方法，无需依赖完整的系统栈。

@DeferredProperty 可以抛出错误吗？

可以。其异步 getter 的签名为 get async throws，异常会传播给系统。系统通过显示不带延迟属性值的实体（或在某些上下文中显示错误状态）来处理失败。应用应优雅地失败并返回有意义的错误状态，而不是崩溃。

交互式片段内容是否支持动画？

支持，可以使用标准的 SwiftUI 动画原语。片段视图运行在系统的响应界面中，该界面与应用内 SwiftUI 共享相同的动画基础设施。可参阅集群中的 Symbol Effects 一文，了解符合平台惯例的动画词汇表。

实体视图注解与小组件如何交互？

小组件属于独立的 WidgetKit 界面；实体视图注解适用于 App Intents 上下文（Spotlight、视觉智能、Siri 响应）。如果应用同时把同一份数据暴露为 AppEntity 和小组件，这两个界面需要分别声明各自的 UI。应用通常共享底层数据模型，并为每个界面编写薄薄的呈现视图层。

这与 MCP tools 是什么关系？

App Intents 是 Apple Intelligence 的意图界面；MCP tools 是面向通用 LLM 的智能体—服务器协议。iOS 26 把视觉智能加入了 App Intents（Apple 的界面）。对于非 Apple 智能体（Claude、GPT 类），在本地或远程运行的 MCP tools 覆盖的是相同的概念领域。集群中的 App Intents 与 MCP Tools 一文 探讨了路由问题。

IntentValueQuery 可以与 EntityQuery 结合使用吗？

可以。它们服务于不同的界面：EntityQuery 用于用户输入或念出实体名称的场景（Spotlight、Siri）；IntentValueQuery 用于用户处于带有图像上下文的视觉智能中的场景。一个应用的 AppEntity 可同时注册这两类查询；系统会根据上下文选择合适的查询。

参考资料