App Intents 是 Apple 通向你应用的全新 API

2026年2月8日清晨，我把手伸在厨房水槽下面，让 Siri 通过我的 Apple Watch 记录 8 盎司饮水量。水量记录成功。手表上的对话框显示还剩 32 盎司。我全程没有碰过屏幕。¹

十一周之前，我往 Water——我的饮水追踪 iOS 应用——里添加了一个 Swift 文件：LogWaterIntent.swift，80 行 AppIntent 加上一个 AppShortcutsProvider，声明了三种 Siri 短语变体。如今这个文件成了我所拥有的最炙手可热的 API 接口。²

下面这一点我花了一段时间才真正想明白。App Intents 不是一项 Siri 功能。 它们是第三方应用与 Apple Intelligence 签订的契约——Apple Intelligence 是 Apple 从 iOS 18 开始推出、并一路构建到 iOS 26 的系统级 AI 接口层。³ 如果你发布了一款 iOS 应用，却仍然把 App Intents 当成一个”锦上添花”的语音功能，那你就误读了 Apple 所搭建的东西。App Intents 正是那个让 Apple 的 AI 能够以你应用的身份代表用户行动的 API。其余的一切（Siri、Spotlight、Shortcuts、Apple Intelligence 摘要，以及 Watch 和 Vision Pro 等接口层）都是这份契约的下游产物。Foundation Models——iOS 26 中上线的端侧 LLM——则暴露了一套独立的 Tool 协议用于应用内的工具调用；它与 App Intents 并行运行，而非通过 App Intents 运转。

太长不看

• App Intents 以一种带类型、结构化的方式声明你的应用能做什么，让 Apple 的 AI 可以直接调用。它们就是 Apple 面向第三方应用的工具调用 API。
• 一个真实的生产案例：Water 中的 LogWaterIntent。80 行代码，完整的 SwiftData 写入、HealthKit 同步、区域感知的单位换算，以及结构化的 Siri 对话响应。
• iOS 26 引入了 Foundation Models，即 Apple 的端侧 LLM。Foundation Models 暴露了它自己的 Tool 协议用于应用内工具调用；App Intents 仍然是 Siri / Spotlight / Apple Intelligence 跨应用调用的标准接口。同一个方向，两份并行的契约。
• 在 2026 年，一款没有 App Intents 的应用对 Apple Intelligence 而言是隐形的。AI 网络要么经由你声明的 intents 路由，要么绕过你的应用、路由到竞争对手那里。
• Apple 已经向我们传达这一点三年了。这套命名（App Intents、App Shortcuts、Apple Intelligence）是有意为之。每一届 WWDC，这份契约都会在技术栈上往上挪一层。

App Intents 框架参考图，来自 Apple Developer 文档。⁵

App Intent 到底是什么

下面是 LogWaterIntent 的完整源码，正如它在 2026年2月8日的提交 e398c58 中所上线的那样：²

import AppIntents
import SwiftData

struct LogWaterIntent: AppIntent {
    static var title: LocalizedStringResource = "Log Water"
    static var description: IntentDescription = "Log a glass of water to your daily intake"

    @Parameter(title: "Amount", default: 8)
    var amount: Int

    static var parameterSummary: some ParameterSummary {
        Summary("Log \(\.$amount) oz of water")
    }

    func perform() async throws -> some IntentResult & ProvidesDialog {
        let container = try ModelContainer(for: WaterEntry.self, DailyLog.self, UserSettings.self)
        let context = ModelContext(container)

        let settingsDescriptor = FetchDescriptor<UserSettings>(
            predicate: #Predicate { $0.id == "user-settings" }
        )
        let settings = try context.fetch(settingsDescriptor).first ?? UserSettings()

        let amountMl: Double
        if settings.unitSystem == .imperial {
            amountMl = Double(amount) * 29.5735
        } else {
            amountMl = Double(amount)
        }

        let todayKey = DailyLog.todayKey()
        let logDescriptor = FetchDescriptor<DailyLog>(
            predicate: #Predicate { $0.dateKey == todayKey }
        )
        let log: DailyLog
        if let existing = try context.fetch(logDescriptor).first {
            log = existing
        } else {
            log = DailyLog(date: .now, goalAmount: settings.dailyGoal)
            context.insert(log)
        }

        let entry = WaterEntry(amount: amountMl)
        log.entries.append(entry)
        try context.save()

        if settings.healthKitEnabled {
            try? await HealthKitService.shared.logWater(amount: amountMl, date: entry.timestamp)
        }

        let unit = settings.unitSystem == .imperial ? "oz" : "mL"
        let totalDisplay = settings.formatAmount(log.totalAmount)
        return .result(dialog: "Logged \(amount) \(unit). Today's total: \(totalDisplay)")
    }
}

struct WaterShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: LogWaterIntent(),
            phrases: [
                "Log water in \(.applicationName)",
                "Add water in \(.applicationName)",
                "Drink water in \(.applicationName)",
            ],
            shortTitle: "Log Water",
            systemImageName: "drop.fill"
        )
    }
}

（Water 当前的生产版本对这个文件中的对话又做了进一步迭代，加入了”是否达成目标 / 剩余量”的条件判断。上面这段 2 月 8 日上线的代码，正是我在厨房水槽边测试的那一版。）

这里有三件事值得专门点出来，因为大多数”App Intents 教程”都一带而过。

@Parameter 就是 schema。 Apple 的 AI 看到的是 amount: Int，默认值为 8。当 Siri 解析”记录 12 盎司饮水”时，它会生成 LogWaterIntent(amount: 12) 并调用 perform()。我这边完全没有任何字符串解析。类型系统就是 schema。⁵

parameterSummary 是参数的自然语言映射。 Apple 用它在 Shortcuts UI 中、在对话中，以及越来越多地在 Apple Intelligence 的确认面板中呈现这个动作。这段摘要会被朗读给用户。写错了，用户听到的就是一个别扭的句子；写对了，整个接口就显得浑然天成。⁶

perform() 返回 IntentResult & ProvidesDialog。 这就是结构化的返回值：AI 接口拿回的不仅是成功 / 失败，还有一段用户能听到的对话字符串。Apple 越来越期望开发者提供 ProvidesDialog、ProvidesView 或 ReturnsValue，这样返回结果就能融入 Siri、Spotlight、Watch，以及（在 iOS 26 中）Apple Intelligence 的响应链。⁷

底部的 AppShortcutsProvider 代码块负责注册 Siri 短语。\(.applicationName) 这个标记是 Siri 自动插入”Water”的位置。三个使用同一 intent 的短语变体，给了 Apple 的自然语言解析器更大的匹配空间，让它能贴合用户的措辞，而无需你去维护一本短语字典。systemImageName 是一个真实的 SF Symbols 名称；Spotlight、Shortcuts 和 Apple Intelligence 正是据此来渲染这个动作的图标。

Apple Intelligence 通过 App Intents 路由用户请求，从而交付端侧 AI 功能。来源：apple.com/apple-intelligence。

为什么这是自 SwiftUI 以来最重要的 iOS API

iOS 的 API 分两种形态。有些关乎你的应用如何绘制自己（UIKit、SwiftUI、Metal）。有些关乎你的应用如何与系统集成（URL schemes、Universal Links、Widgets）。App Intents 是第三种形态：它们关乎 Apple 的 AI 如何使用你的应用。那些 widget 和 Control Center 接口本身就是 App Intents 接口——同一个 intent 在多处呈现，我在《iOS 26 的 Widget 接口》中梳理过这条脉络。

这条演进路线值得理一理。

• iOS 10（2016） 引入了 SiriKit Intents（INIntent），这是第三方应用首次能够被语音调用。这个接口范围很窄：一份固定的领域清单（消息、支付、叫车），配上严格的 schema。⁸
• iOS 12（2018） 借助 Siri Shortcuts 拓宽了这个接口：任何应用都可以捐献一个 NSUserActivity 或 INIntent，然后指望 Siri 把它推荐出来。
• iOS 13（2019） 增加了应用内的 intent 处理能力，应用无需切到后台、跳转到系统 Siri UI，就能响应快捷指令的调用。
• iOS 16（2022） 引入了 App Intents 框架：带类型、声明式，配有 @Parameter 和 AppShortcutsProvider。对新开发而言，前身 INIntent 实际上已被取代。⁹
• iOS 18（2024） 引入了 Apple Intelligence，并开始尽可能地把 Siri 请求路由经 App Intents。Apple Intelligence 的”个人情境”功能就从 App Entities（App Intents 的数据版本）中读取信息。¹⁰ iOS 27 通过 App Schemas 把这一点推得更远——它让 Siri 能用自己已经理解的术语对你的 entities 进行推理和操作，无需任何训练短语，此处有详述。
• iOS 26（2025） 引入了 Foundation Models 框架，即 Apple 的端侧 LLM。Foundation Models 暴露了一套独立的 Tool 协议用于应用内工具调用。App Intents 仍然是 Apple Intelligence 的标准跨应用接口，而 Tool 则是直接 LLM 调用的应用内接口。两份契约并行运行。⁴

这份契约在每一次发布时都在技术栈上往上延伸。最初，一个 App Intent 的消费者是点击 Shortcuts 的人。然后是 Siri 语音。再然后是 Spotlight。再然后是 Apple Intelligence 摘要。如今，Apple Intelligence 以 LLM 为后盾的系统接口用它们来对用户请求采取行动。你在 2026 年上线的 App Intent 接口，正是 Apple Intelligence 将在 iOS 27、28、29 上调用的那个接口。

上面这套模式，正是我说”App Intents 不是一项 Siri 功能”时所指的意思。它们是整个 Apple AI 网络的结构化工具调用 API。SwiftUI 之所以是最重要的 UI API，是因为它成了为 visionOS、watchOS 10+ 和 iOS 17+ 编写应用的唯一方式。App Intents 正在 AI 这一侧沿着相同的弧线前进：这是 Apple 押下全部赌注的接口。

Foundation Models 上线之后，现在有什么变化

Foundation Models 是一个会随附在每一台符合 Apple Intelligence 条件的设备上的框架。其硬件门槛与 Apple Intelligence 的清单一致：iPhone 15 Pro 和 15 Pro Max（A17 Pro）、iPhone 16 系列、iPhone 17 系列、iPhone Air、iPhone 17e、搭载 M1 或更新芯片的 iPad Pro、搭载 M1 或更新芯片的 iPad Air、搭载 A17 Pro 的 iPad mini、搭载 M2 或更新芯片的 Vision Pro，以及搭载 M1 或更新芯片的 Mac。值得注意的是，基础款 iPhone 15 / 15 Plus 不在其列。⁴¹²

由此可推：如果 Apple 的系统接口（Siri、Spotlight、Apple Intelligence）会调用你的应用，那它们只会通过 App Intents 和 App Entities 来调用。在系统 AI 网络中，没有面向第三方应用的 setSystemPrompt(...) API。有的只是 intent 注册表。Foundation Models 为那些想拥有自己端侧 LLM 功能的开发者，额外提供了一个并行的应用内 Tool 接口。而跨应用的契约（Apple Intelligence 和 Siri 用来找到你应用的那一份）走的是 App Intents。

对应用开发者而言，有三个具体的后果：

一款在其品类中没有相关 App Intent 的应用，无法被该品类的 Siri 语音命令触达。 Apple Intelligence 会把”嘿 Siri，记录我的饮水量”这类短语，优先路由到已声明匹配 intent 的应用。我在 2026 年 2 月就上线了 Water 的 intent。我对这个框架走向的判断是：在 2027 年才上线 intent 的饮水类应用，将进入一个路由权重早已向先行者倾斜的市场。同样的逻辑也适用于购物清单、健身记录、日历条目、照片搜索。我预计 intent 声明上的先发优势会持续复利累积，就像 Apple 在其他平台押注的 API（HealthKit 类目、Spotlight 富结果、Live Activities tokens）所表现的那样。

Apple Intelligence 的个性化不仅读取 intents，还会读取 App Entities。 一个 AppEntity 声明的是”这款应用拥有这种形态的数据”。当用户问”我加进阅读清单的上一本书是什么”时，Apple Intelligence 会在每一款已安装应用中搜索匹配 Book 的每一个 AppEntity。如果你的应用有阅读清单，却没有声明 BookEntity，那你的数据对 Apple 的 AI 接口就是隐形的。Apple Intelligence 无法检索或引用你的数据。¹¹

IntentResult & ProvidesDialog 这种返回形态越来越重要。 Apple Intelligence 正在跨 Siri、Spotlight 和 Watch，把 intent 结果编排进更长的响应中。一个只返回成功、却不带结构化对话的 perform()，系统更难把它编排进一段连贯的回复里。ProvidesDialog 和 ProvidesView 不是可有可无的客套；它们是你的动作得以成为用户 AI 接口中一处引用的方式。

如果重来，我会怎么做

Water 上线十一周的生产日志告诉我三件本该更早去做的事。

上线的 intents 要比你以为需要的更多。 我只上线了一个。我本该上线四个：LogWaterIntent、CheckTodaysProgressIntent、AdjustGoalIntent、ShowHistoryIntent。每一个都对应着用户真的会去尝试的某句 Siri 短语（”我今天喝了多少水”被路由给了 Apple 的通用 AI，而不是我应用的数据）。每一个缺失的 intent，都是 Apple Intelligence 绕过我去路由的一次查询。

对话字符串不是一封电子邮件的正文。 我从一开始就有 ProvidesDialog，但早期的对话是散文式的。透过 CarPlay 或 AirPods 听它的用户，需要的是简短、具体、以事实打头的结构：”已记录 8 盎司。还差 32 盎司。” Watch 接口尤其会激进地截断内容。对话式的措辞，是比直陈事实式的措辞更糟的用户体验。我在第 4 周重写了我的对话。²

App Entities 比我以为的更重要。 我有一个 WaterEntry SwiftData 模型。我还应该声明一个 WaterEntryEntity: AppEntity，外加它的配套 WaterEntryQuery: EntityQuery，这样 Apple Intelligence 才能回答”给我看看我昨天喝水的时间点”。最小化的桥接代码是这样的：¹¹

struct WaterEntryEntity: AppEntity {
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Water Entry"
    static var defaultQuery = WaterEntryQuery()
    var id: UUID
    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(amount) oz at \(timestamp.formatted())")
    }
    @Property(title: "Amount") var amount: Int
    @Property(title: "Timestamp") var timestamp: Date
}

struct WaterEntryQuery: EntityQuery {
    func entities(for identifiers: [UUID]) async throws -> [WaterEntryEntity] {
        // Fetch matching entries from SwiftData
    }
    func suggestedEntities() async throws -> [WaterEntryEntity] {
        // Recent entries Apple Intelligence can suggest
    }
}

两个小小的 Swift 类型，外加 SwiftData 取数的胶水代码。要让单条记录可以在 Spotlight 中被单独呈现（这样用户搜索”water”时就能落到正确的那条记录上），需让该 entity 遵从 IndexedEntity，并在写入时捐献索引更新。这正是 Apple 的 Spotlight 管线在裸露的 AppEntity 暴露之外所期望的东西。

同样的形态也适用于我其他的应用。Get Bananas——我的购物清单应用——已经有了一个 SwiftData @Model ShoppingItem，带 @Attribute(.unique) var id: UUID、name、amount、section、isChecked，外加一个用于 iCloud Drive 同步的 lastModified 字段。¹³ 把它包装成 ShoppingItemEntity: AppEntity，再上线几个 intents（AddShoppingItem、CheckOffItem、ShowList），就能把 Get Bananas 已经通过其 .mcpb MCP 服务器暴露给 Claude Desktop 的那同一个持久层，暴露给 Apple Intelligence。¹⁴ 两个 LLM 生态，两份不同的契约，同一份购物清单。这正是”并行契约”论点在一款已上线应用中的体现：SwiftData 模型是数据，App Intents 是 Apple 的契约，MCP 是 Anthropic 的契约，两个接口操作的是同一份真实来源。

什么时候不该上线 App Intent

懂得拒绝，也是设计的一部分。

如果你的应用纯粹由消费驱动（读取用户的照片、展示新闻、播放音频），没有任何可变的用户状态，那 App Intents 可能没什么可暴露的。Apple 的框架支持 OpenIntent（只是把应用打开到某个情境），但如果唯一有用的动作就是”打开应用”，那这个 intent 就是额外的负担。别为了有而有。

如果某个动作依赖于难以抽象的 UI 交互元素（一个复杂的多步骤画布工具、一款 3D 编辑应用），那 intent 所必需的 parameterSummary 就会退化成含糊的伪自然语言，根本没人会那么说。Siri 短语”用模糊工具以 7 的强度编辑我的照片”在技术上是可行的，但没有哪个人类会把它说出口。这个 intent 的接口就成了一笔毫无回报的开销。

正确的准则是：当存在一句用户会自然说出、并由此触发动作的话时，一个 App Intent 才物有所值。”记录 8 盎司饮水”就是这样一句话。”对图层 3 应用 sigma 为 2.4 的高斯模糊”则不是。如果你应用的动作都聚集在第二种模式上，那 intents 就不是你的转化杠杆。

收尾观点

三年来，Apple 一直在释放信号：iOS 的系统 AI 网络要走 App Intents。WWDC 2024 加入了经由它们路由的 Apple Intelligence。WWDC 2025 在旁边加入了 Foundation Models，作为一个独立的应用内工具调用接口，同时把 App Intents 留作 Siri / Spotlight / Apple Intelligence 持续使用的跨应用契约。每一个信号都指向同一个方向：带类型、声明式的 App Intent，就是如今第三方应用与系统签订的那份契约。

大多数 iOS 应用仍然把 App Intents 当成 Siri Shortcuts：一个有时间才去上线的功能。我的判断是，这种框定方式会很快过时。随着 Apple Intelligence 的系统接口不断延伸（如今已经覆盖 Siri、Spotlight、Shortcuts 和 Apple Intelligence 摘要），没有声明 intents 的应用很可能会发现自己被排除在路由图谱之外。在我观察 Apple 其他平台押注的经验里，先发的接口会复利累积。

Water 上线 LogWaterIntent 已经十一周了。上线一个 App Intent 所需的代码量，小到足以塞进一个文件。而不上线它的代价，会随着 Apple Intelligence 的每一次发布而增长。

如果你在 2026 年发布一款 iOS 应用，却还没有声明至少一个 App Intent，那你的路线图就缺了一项。把它补上。

常见问题

iOS 开发中的 App Intent 是什么？

App Intent 是一个带类型、声明式的 Swift 结构体，它把你应用的某个动作暴露给 Apple 的系统 AI 接口。它通过 @Parameter 声明参数，通过 parameterSummary 声明自然语言摘要，再用一个异步的 perform() 主体来完成工作并返回一个结构化结果。Apple 的 Siri、Spotlight、Shortcuts 和 Apple Intelligence 都能调用它。Foundation Models（Apple 的端侧 LLM）则使用一套独立的 Tool 协议来进行直接的应用内工具调用。

App Intents 与较早的 INIntent 有何不同？

App Intents（于 iOS 16，2022 年引入）取代 INIntent 成为 Apple 主要的 intent 框架。这个更新的框架完全是 Swift 原生的，使用诸如 @Parameter 之类的属性包装器，通过 AppEntity 支持类型安全的 entity 查询，并且是 Siri、Spotlight、Shortcuts 和 Apple Intelligence 所调用的接口。较早的 INIntent 仍受支持，但不再获得任何新功能的投入。

上线一个 App Intent 需要 iOS 26 吗？

不需要。App Intents 从 iOS 16 起就可用。iOS 26 在旁边加入了 Foundation Models 框架，但 App Intent 声明本身在 iOS 16+ 上就能工作。上面的示例代码使用了 SwiftData（iOS 17+），所以部署目标取决于你的 perform() 主体引入了什么。裸露的 App Intents 可回溯支持到 iOS 16；以 SwiftData 为后盾的则需要 iOS 17。

App Intent 和 App Entity 之间有什么区别？

App Intent 是一个动作（动词）。App Entity 是你的应用所知晓的数据（名词）。LogWaterIntent 是一个 intent。让 WaterEntry 变成一个可查询的类型，则是一个 entity。Apple Intelligence 两者都用：用 intents 来采取行动，用 entities 来在响应中检索和引用数据。

App Intents 与 Foundation Models 的工具调用有何关联？

Foundation Models 暴露了它自己的 Tool 协议，用于直接的应用内 LLM 工具调用。App Intents 仍然是 Apple Intelligence、Siri 和 Spotlight 所调用的标准跨应用接口。同一个方向（带类型、声明式的工具调用），两份并行的契约。一款想被系统 AI 接口触达的应用，上线的是 App Intents；一款想用自定义工具调用自己端侧 LLM 的应用，上线的是 Tool 遵从实现。许多应用两者都会上线。

App Intents 不是一项功能。它们是契约。先上线 intent 的应用拿下接口；晚上线的应用会发现接口早已被路由到别处。十一周前，我在 Water 中上线了一个。复利已经开始累积。

Apple 生态系列的更多内容

这篇文章是入口。其余四篇覆盖架构栈的其他部分：

• 《两个 Agent 生态，一份购物清单》：Get Bananas 如何通过 iCloud Drive 中的一个 JSON 文件，把同一份数据同时暴露给 Apple Intelligence（App Intents）和 Claude Desktop（MCP）。
• 《SwiftUI 中的 Liquid Glass：上线 Return 得来的三个模式》：iOS 26 视觉层的生产级模式。
• 《五个 Apple 平台，三个共享文件》：多平台上线策略，何时共享代码、何时为不同 target 分叉。
• 《iOS 26 上的 HealthKit + SwiftUI》：授权流程、样本类型的数据源层，以及那个会把用户锁在你应用门外的陷阱。

或者直接跳到完整的中心页：Apple 生态系列。想了解更宽泛的”iOS 搭配 AI agents”背景，请参阅 iOS Agent 开发指南。

参考资料