搭建 Mac 應用基礎殼

你是 Mac 應用基礎殼搭建規劃顧問，幫我用最小架構、分輪推進的方式搭起應用殼。

【角色】
你知道搭 Mac 應用殼解決什麼、什麼時候值得用、最小架構長什麼樣、為什麼推薦分兩輪做。

【輸入】
- 應用型別和核心功能：___
- 技術堆疊偏好（SwiftUI / AppKit）：___
- 是從零還是有部分程式碼：___
- 我的 macOS 開發經驗：___

【工作流程】
1. 定最小可執行架構
2. 第一輪：搭起能跑起來的空殼
3. 第二輪：補核心結構和導航
4. 給每輪的驗證點

【輸出規範】
▌一、最小架構
▌二、第一輪任務（可執行空殼）
▌三、第二輪任務（核心結構）
▌四、每輪驗證點

【硬約束】
- 第一輪先跑起來，不追求完整
- 架構最小夠用，不過度設計
- 每輪可回復、可驗證
- 真機 / 模擬器驗證執行
- 不確定的 API 標註需查官方文件
- 每輪搭完先確認能編譯執行起來再進下一輪，別在跑不起來的殼上繼續往裡加東西

這個場景的重點不是背 SwiftUI API，而是讓 Codex 先搭對 Mac-native app shell：穩定主視窗、sidebar selection、detail pane、inspector、menu commands、toolbar、keyboard shortcuts 和獨立 Settings scene。

它解決什麼

flowchart LR
    Idea["app idea"] --> Shell["SwiftUI shell"]
    Shell --> Sidebar["sidebar"]
    Shell --> Detail["detail"]
    Shell --> Inspector["inspector"]
    Shell --> Settings["settings"]
    Shell --> Commands["menus / shortcuts"]

很多新手會直接說“幫我做一個 Mac app”。這樣容易得到一個被拉寬的網頁介面，或者一個只有內容頁、沒有桌面行為的 SwiftUI demo。

更穩的做法是先讓 Codex 搭 app shell：

• WindowGroup 負責主視窗。
• NavigationSplitView 負責 sidebar 和 detail。
• inspector 放次級資訊和控制項。
• commands、toolbar、shortcuts 暴露關鍵動作。
• Settings scene 放全域偏好設定。

先有這些，再繼續做具體功能。順序反過來，後面通常會補很多結構債。

什麼時候值得用

適合：

• editor、library、admin、review tool。
• 使用者需要長期停留在 app 裡處理物件、狀態和細節。
• app 需要選單欄、快捷鍵、設定視窗。

不適合：

• 快速單頁 demo。
• 主要體驗在移動端或 Web 端。
• 還沒想清楚使用者要管理什麼物件。
• 只是測試一個演算法或 API。

最小架構

官方 Mac app shell 場景強調先選 scene model，再圍繞 sidebar、detail 和 inspector 組織主視窗。實際交付時，可以讓 Codex 先搭這一層：

App
├─ WindowGroup
│  └─ RootView
│     ├─ NavigationSplitView
│     │  ├─ SidebarList
│     │  └─ DetailView
│     └─ InspectorView
├─ Settings
└─ Commands

這個骨架裡，每個部分都有明確職責：

• WindowGroup 是主工作視窗，不塞設定和 onboarding。
• NavigationSplitView 負責物件選擇和主要內容切換。
• inspector 只放次級資訊、後設資料、除錯開關或上下文操作。
• Settings scene 負責全域偏好，不依賴目前 sidebar selection。
• commands 負責選單欄和快捷鍵，讓關鍵動作像桌面軟體一樣可達。

如果 Codex 生成的結果只有一個 ContentView，說明它還停留在 demo 層。要繼續要求它拆出 selection state、model、view 和 command wiring。

推薦分兩輪做

第一輪只要殼，不要業務：

• 建 app scene。
• 建 sidebar 資料模型和 selection。
• 建 detail 空狀態。
• 建 inspector toggle。
• 建 Settings scene。
• 建一個可觸發的 menu command、toolbar button 和 keyboard shortcut。
• 跑一次 build/run。

第二輪再塞業務：

• 把真實物件接入 detail 區域。
• 給 detail 加主要工作流。
• 給 inspector 加次級編輯項。
• 給 menu command 接真實 action。
• 為關鍵 action 加 Logger 或最小 telemetry。
• 用實際視窗尺寸檢查 sidebar、detail、inspector 是否可用。

這個拆法能避免“功能做到一半才發現架構不對”。桌面殼一旦穩定，後續功能可以按物件和 action 逐個補。

起始提示詞

請先不要實現完整業務功能。基於我的產品想法，先搭一個 Mac-native SwiftUI app shell：

- 主視窗使用 sidebar + detail + inspector。
- 全域設定放到獨立 Settings scene。
- 關鍵動作透過 menu、toolbar、keyboard shortcut 暴露。
- 只做最小可執行殼，並說明如何 build/run 驗證。

這段提示詞的重點是“先不要實現完整業務”。它能限制範圍，讓你先檢查桌面結構是否正確。

更完整的商業專案提示詞

Use the Build macOS Apps plugin to turn this idea into a Mac-native SwiftUI app shell.

Product object:
- [使用者要管理的核心物件]

Shell requirements:
- Choose the scene model first.
- Use WindowGroup for the main window.
- Use NavigationSplitView with explicit selection state.
- Keep sidebar rows native and lightweight.
- Use a detail pane for the selected object.
- Add an inspector(isPresented:) panel for secondary metadata or controls.
- Add a dedicated Settings scene for global preferences.
- Add menu command, toolbar action, and keyboard shortcut wiring for one core action.

Validation:
- Create or update scripts/build_and_run.sh if the repo uses a script-based loop.
- Run the smallest useful build/run check.
- Tell me the exact commands used and any desktop UX follow-up.

英文提示詞不是必須，但在官方 use case 和外掛說明裡，關鍵 API 名稱、外掛名稱、scene model 描述都是英文。做真實專案時，中英混合通常更穩：業務背景用中文，框架、API、檔名和驗證命令用英文。

說清產品物件

你要描述的是產品物件，不是介面裝飾：

• app 管理什麼物件。
• sidebar 裡選中的是什麼。
• detail 展示什麼主資訊。
• inspector 只放哪些次級資訊。
• 哪些動作必須能從選單欄或快捷鍵觸發。
• 哪些偏好設定是全域的。

“做得像原生一點”太寬。物件、狀態和驗收方式清楚，Codex 才有穩定目標。

常見坑

• 先做漂亮頁面，後補 sidebar/detail/inspector。
• 把 Settings 做成主視窗裡的一個頁面。
• 所有動作只放按鈕，不接 menu 和 shortcuts。
• sidebar row 做成大卡片，掃視效率很差。
• 過早使用 AppKit bridge。
• 沒讓 Codex 跑 build/run check。

驗收清單

• app 有穩定主視窗，不是臨時 demo view。
• sidebar 選擇物件後，detail 會跟著變化。
• inspector 可以展示和隱藏，且不承載主流程。
• Settings 是獨立入口。
• 至少一個關鍵動作能從選單、toolbar 或快捷鍵觸發。
• Codex 說明了 build/run 驗證，或明確說哪些驗證還沒跑。

這些都成立後，再繼續讓 Codex 填業務功能。

繼續深化

殼完成後，後續通常按這三個方向推進：

• 功能化：把 sidebar 物件換成真實資料，把 detail 的空狀態變成主流程。
• 可觀測：給關鍵 action 加 Logger，後面用 Mac telemetry 場景驗證真實點選。
• 維護性：把大型 SwiftUI screen 拆成小 view，避免一個 ContentView 繼續膨脹。

不要同時做這三件事。先讓殼透過 build/run，再接一個真實物件，再做 telemetry 或 refactor。Codex 在原生專案裡最怕目標過寬，尤其是同時要求 UI、資料、系統整合和 AppKit bridge。

官方資料

• OpenAI Codex use case: Build a Mac app shell
• OpenAI Codex native development collection
• Build macOS Apps plugin
• Codex Agent skills