---
title: "为 iOS App 增加系统动作入口"
description: "说明如何用 Codex 设计和实现 App Intents，让 iOS app 动作暴露给 Shortcuts、Siri、Spotlight 和 widgets。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

App Intents 能把 iOS app 的动作和内容暴露给 Shortcuts、Siri、Spotlight、widgets、controls 和 assistant-driven system experiences。Codex 适合先审计最有价值的 actions 和 core objects，再实现小而清晰的 intent surface。

> [!IMPORTANT]
> 第一版 App Intents 不要 mirror 整个内部 model layer。只暴露系统理解、展示和路由真正需要的最小 entity surface。

<Cards>
  <Card title="iOS App Intents" href="https://developers.openai.com/codex/use-cases/ios-app-intents">
    官方 Codex App Intents 场景。
  </Card>
  <Card title="Apple App Intents" href="https://developer.apple.com/documentation/appintents">
    Apple 官方 App Intents 文档入口。
  </Card>
  <Card title="Build for iOS" href="/docs/codex/official/08-scenarios/109-ios-app">
    先确认 iOS build、simulator 和 runtime 验证链路。
  </Card>
</Cards>

## 推荐流程

```mermaid
flowchart LR
    Audit["audit actions"] --> Surface["intent surface"]
    Surface --> Entity["AppEntity / query"]
    Entity --> Shortcut["App Shortcuts"]
    Shortcut --> Route["handoff / routing"]
    Route --> Verify["build / simulator / runtime"]
```

适合 Codex 的任务：

- 找出最适合暴露到系统的 actions 和 objects。
- 实现第一批 App Intents、AppEntity 和 App Shortcuts。
- 定义小而清楚的 entity surface。
- 把 intent-driven entry point 路由回正确 screen 或 workflow。
- build 并做 focused runtime verification。

不适合第一轮：

- 暴露所有内部模型。
- 为低价值动作做大量 shortcuts。
- 只写类型，不验证系统调用后的路由。
- 在没确认目标 SDK 和 Apple 当前文档前迁移 API。

## 起始提示词

```text
请审计这个 iOS app，并为最适合暴露给系统的 actions 和 entities 添加 App Intents。

约束：
- 先识别最高价值 user actions 和 core objects
- 第一版只选少量不打开完整 app 也真正有用的 intents
- 只定义系统理解和路由所需的最小 app entities
- 需要回到主 UI 时，实现 clean handoff 到正确 screen 或 workflow
- 先查 Apple 当前 App Intents 文档和项目目标 SDK，再写代码

交付：
- first release 推荐的 intent 和 entity surface
- 已实现 intents、entities 和 App Shortcuts
- runtime 如何 route 或 handle 这些 intents
- build 和 simulator / runtime 验证结果
```

这个 prompt 明确要求 first pass focused。不要把整个 app model layer 暴露给系统，只暴露系统理解和路由真正需要的部分。

## 从 Actions 和 Entities 开始

让 Codex 先识别：

- 用户希望不打开完整 app 也能触发的少数 actions。
- 系统为了正确路由这些 actions 需要理解的 app objects。
- 哪些 workflow 应该直接在 system surface 完成。
- 哪些 workflow 应该 open app 到特定 state。

好的第一批 intents 通常是 compose、open、find、filter、start、continue、inspect。需要很长 in-app setup 的动作，不适合第一轮暴露。

## 按 System Surfaces 思考

App Intents 不只是“加一个 shortcut”。它能让 app 在多个系统入口变得更有用：

- Shortcuts：用户直接运行 actions，或组合进 automations。
- Siri：暴露有意义的 verbs 和 deep links。
- Spotlight：app entities 和 app shortcuts 成为可发现入口。
- Widgets、Live Activities、controls 等 intent-driven UI surfaces。
- Assistant-facing experiences：structured actions 和 entities 比任意 UI flow 更容易被系统理解。

## 采用真实 App Pattern

多数 app 适合这种结构：

- 单独组织 App Intents 代码，不把 intent types 散落在无关文件里。
- 为高价值 actions 写 `AppShortcutsProvider`。
- 为系统需要理解的对象定义小型 `AppEntity`。
- intent handling 能 cleanly route 回 main app scene。
- build 和 simulator 检查覆盖 intent-driven entry point。

## 验证重点

App Intents 的难点不只是编译 target，而是证明系统调用 intent 后能进入正确状态。

验证应覆盖：

- build 是否通过。
- App Shortcuts 是否可发现。
- 参数和 display representation 是否清楚。
- entity query 是否返回正确对象。
- intent 成功和失败路径是否有可理解结果。
- open-app intent 是否路由到正确 screen。

## 验收清单

- 第一批 intents 只覆盖高价值动作。
- entity surface 小于内部 model layer。
- 所有 Apple API 使用前核对当前官方文档。
- App Shortcuts 有清楚 title、phrase 和 display representation。
- 需要 handoff 时，main app scene 能正确响应。
- build、simulator 或 runtime verification 有证据。

## 官方资料

- [Codex: iOS App Intents](https://developers.openai.com/codex/use-cases/ios-app-intents)
- [Apple App Intents](https://developer.apple.com/documentation/appintents)
- [Creating your first app intent](https://developer.apple.com/documentation/appintents/creating-your-first-app-intent)
