為 iOS App 增加系統動作入口
說明如何用 Codex 設計和實現 App Intents，讓 iOS app 動作暴露給 Shortcuts、Siri、Spotlight 和 widgets。
App Intents 能把 iOS app 的動作和內容暴露給 Shortcuts、Siri、Spotlight、widgets、controls 和 assistant-driven system experiences。Codex 適合先審計最有價值的 actions 和 core objects，再實現小而清晰的 intent surface。
第一版 App Intents 不要 mirror 整個內部 model layer。只暴露系統理解、展示和路由真正需要的最小 entity surface。
iOS App Intents
官方 Codex App Intents 場景。
Apple App Intents
Apple 官方 App Intents 文件入口。
Build for iOS
先確認 iOS build、simulator 和 runtime 驗證鏈路。
推薦流程
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。
起始提示詞
请审计这个 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 有證據。