为 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 有证据。