為 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