iOS Siri 和快捷指令接入梳理：AppIntent、AppShortcut 与常见限制

很多人在做 iOS 小组件或 AppIntent 能力时，会顺手碰到 Siri 和快捷指令，但这部分常被混在一起说，实际接入点和限制并不完全一样。本文按“能不能被看到、怎么配置、有哪些限制、最终代码怎么组织”的顺序梳理一遍，帮你快速判断什么时候该用 AppIntent、什么时候要补上 AppShortcutsProvider，以及哪些细节会直接导致快捷指令不展示。

快捷指令和 AppIntent 是什么关系

严格来说，快捷指令并不属于小组件本身，但它和小组件一样，都是通过 AppIntent 意图体系来定义能力。所以在实际开发里，这两类功能经常会放在一起讲，也经常在同一套代码结构里处理。

苹果的快捷指令（Shortcuts）本质上是一套自动化工具。开发者可以把应用中的某个动作封装成快捷指令，用户随后既可以在快捷指令 App 里手动执行，也可以通过 Siri 语音触发。这个动作可以很简单，比如新增一个待办，也可以是多步骤的业务流程。

如果你此前没接触过 Shortcuts，可以先把它理解成“把应用能力暴露给系统自动化入口”。这也是本文后面所有代码的出发点。

如何把意图暴露给快捷指令

当一个 AppIntent 被创建出来后，它在创建快捷指令这件事上的默认状态通常就是可见的，也就是 isDiscoverable 的值为 true。意图完成定义并注册后，用户在快捷指令 App 中添加操作时，就能够找到它。

添加成功后，这个动作通常有两种触发方式：

• 在快捷指令 App 中手动点击执行
• 通过 Siri 直接执行

注意：快捷指令相关能力需要 iOS 16 及以上系统版本。

从 iOS 16 开始，还可以通过实现 AppShortcutsProvider 协议，把 AppShortcut 直接暴露给快捷指令 App。这样用户不需要再手动去添加动作，应用定义的快捷指令就能直接出现在快捷指令列表里。

import AppIntents

struct MeditationShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] { }
}

可以把它理解为：AppIntent 负责定义“能做什么”，而 AppShortcutsProvider 负责告诉系统“这些能力要不要以快捷指令的形式直接展示出来”。

单指令、多指令与参数含义

单指令写法

单个快捷指令的接入方式比较直接，先定义一个 AppIntent，再在 AppShortcutsProvider 中返回一个 AppShortcut 即可。

import AppIntents

struct StartMeditationIntent: AppIntent {
    static let title: LocalizedStringResource = "Start Meditation Session"

    func perform() async throws -> some IntentResult & ProvidesDialog {
        return .result(dialog: "Okay, starting a meditation session.")
    }
}

struct MeditationShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: StartMeditationIntent(),
            phrases: [
                "(.applicationName) shortcut1",
            ],
            shortTitle: "shortcut1",
        )
    }
}

AppShortcut 里最关键的几个参数可以这样理解：

• intent：定义快捷方式真正执行的动作。用户触发后，系统会调用这个 Intent 的 perform()。
• phrases：这是一个字符串数组，用来定义 Siri 可识别的触发短语。实际测试中，如果短语里不包含 applicationName，该快捷方式将不会展示出来。
• shortTitle：用于快捷方式界面的简短标题。原文提到“暂时没看到在哪展示”，这也说明它更偏向系统展示字段，而不是核心执行逻辑。

配置完成后，可以在快捷指令的所有快捷指令页面里找到它，点击即可执行。

多指令写法

如果一个应用希望一次性暴露多个快捷动作，也可以在同一个 AppShortcutsProvider 中返回多条 AppShortcut。

注意：多指令模式最多只能添加 10条 指令。

import AppIntents

struct StartMeditationIntent: AppIntent {
    static let title: LocalizedStringResource = "Start Meditation Session"

    func perform() async throws -> some IntentResult & ProvidesDialog {
        return .result(dialog: "Okay, starting a meditation session.")
    }
}

struct MeditationShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: StartMeditationIntent(),
            phrases: [
                "(.applicationName) shortcut1",
            ],
            shortTitle: "shortcut1"
        )

        AppShortcut(
            intent: StartMeditationIntent(),
            phrases: [
                "(.applicationName) shortcut2",
            ],
            shortTitle: "shortcut2"
        )
    }
}

这里的重点不在代码形式，而在平台限制：多指令最多只能添加 10条，超过 10条 就会报错。因此，如果你的应用动作很多，不能简单地把所有能力都平铺到 appShortcuts 中，而要优先挑选最常用、最适合被 Siri 触发的几个入口。

如何给指令配置图标

为了让快捷指令在列表里更容易被识别，可以继续给 AppShortcut 配置系统图标。这里使用的是 systemImageName。

import AppIntents

struct AddTodoIntent: AppIntent {
    static var title: LocalizedStringResource = "Add Todo"

    func perform() async throws -> some IntentResult & ProvidesDialog {
        // 实现添加待办事项的逻辑
        .result(dialog: "New todo added successfully.")
    }
}

struct TodoAppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: AddTodoIntent(),
            phrases: ["(.applicationName) Add a new todo"],
            shortTitle: "New Todo",
            systemImageName: "plus.circle"
        )
    }
}

systemImageName 对应系统图标名称，它会和快捷方式一起显示。虽然这不影响执行逻辑，但对于快捷指令较多的应用来说，图标能明显提升用户查找效率。

接入时的限制与 Siri、搜索入口

这部分是最容易踩坑的地方，尤其适合在开发时提前自查。

两个需要优先记住的限制

第一，快捷指令中的 applicationName 基本可以视为必填项。原文经过试验指出，如果 phrases 里不包含它，快捷方式将不会展示。

第二，快捷指令并不完全属于小组件能力本身。经过测试，相关代码文件即便放在主 App 中，依然可以生效。这意味着你在工程组织上不必强行把它塞进 Widget Extension，只要能力声明和系统识别链路是通的即可。

Siri 调用与系统搜索表现

如果需要配置 Siri 调用，可以进入快捷指令详情页，点击右上角按钮开启 Siri。

除了语音入口，在系统搜索里输入项目名称，也可以看到对应的快捷指令。原文还提到，执行状态会在灵动岛上展示，这说明它不只是“能不能被调用”的问题，也会影响系统层的反馈体验。

完整示例代码

如果你想直接对照一个最小可用示例，下面这份代码同时包含两个 AppIntent，并通过同一个 AppShortcutsProvider 暴露两条快捷指令，适合拿来验证整体接入流程。

import AppIntents

struct AddTodoIntent: AppIntent {
    static var title: LocalizedStringResource = "Add Todo"

    func perform() async throws -> some IntentResult & ProvidesDialog {
        // 实现添加待办事项的逻辑
        .result(dialog: "New todo added successfully.")
    }
}

struct ViewTodosIntent: AppIntent {
    static var title: LocalizedStringResource = "View Todos"

    func perform() async throws -> some IntentResult & ProvidesDialog {
        // 实现查看待办事项的逻辑
        .result(dialog: "Here are your todos...")
    }
}

struct TodoAppShortcuts: AppShortcutsProvider {
    static var appShortcuts: [AppShortcut] {
        AppShortcut(
            intent: AddTodoIntent(),
            phrases: ["(.applicationName) Add a new todo"],
            shortTitle: "New Todo",
            systemImageName: "plus.circle"
        )

        AppShortcut(
            intent: ViewTodosIntent(),
            phrases: ["(.applicationName) Show my todoso"],
            shortTitle: "Show todos",
            systemImageName: "plus.app"
        )
    }
}

从结构上看，这套写法已经覆盖了几个关键点：定义意图、暴露系统短语、设置简短标题、补充系统图标，以及在一个 provider 中同时管理多条快捷指令。对刚开始接入 Siri 和快捷指令的项目来说，这就是一套足够清晰的起点。