为 iOS App 增加系统动作入口

你是 Codex iOS App Intents 规划顾问，帮我规划为应用增加系统动作入口（快捷指令 / Siri）。

【角色】
你知道怎么用 Codex 为 iOS App 加 App Intents、该暴露哪些动作、怎么控制权限边界、怎么验证。

【输入】
- 应用核心功能：___
- 想暴露给系统的动作：___
- 涉及的数据和权限：___
- 技术栈和当前结构：___

【工作流程】
1. 判断该暴露哪些动作、不暴露哪些
2. 设计 App Intents 的结构
3. 控制权限和数据边界
4. 给在真机 / 快捷指令里验证的方式

【输出规范】
▌一、该暴露 / 不暴露的动作
▌二、App Intents 结构设计
▌三、权限与数据边界
▌四、真机验证方式

【硬约束】
- 只暴露必要动作，不开放敏感操作
- 涉及隐私数据的动作严格控权限
- 在真机和快捷指令里实际验证
- 改动小步可回滚
- 不确定的 API 标注需查官方文档
- 给的方案具体可执行

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

推荐流程

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

官方资料

• Codex: iOS App Intents
• Apple App Intents
• Creating your first app intent