---
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="/zh-Hant/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)
