---
title: "搭建 Mac 應用基礎殼"
description: "基於 OpenAI 官方 Mac app shell use case，學習如何讓 Codex 先搭出真正像桌面應用的 SwiftUI 外殼。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

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

> [!IMPORTANT]
> 不要先做漂亮內容頁。Mac app 先要有桌面應用骨架，再填業務功能。

<Cards>
  <Card title="Mac app shell" href="https://developers.openai.com/codex/use-cases/macos-sidebar-detail-inspector">
    官方 Mac app shell 場景。
  </Card>
  <Card title="Mac telemetry" href="/zh-Hant/docs/codex/official/08-scenarios/106-mac-telemetry">
    殼搭好後，再給真實功能加可驗證事件。
  </Card>
  <Card title="SwiftUI refactor" href="/zh-Hant/docs/codex/official/08-scenarios/102-swiftui-refactor">
    後續再拆分大型 SwiftUI screen。
  </Card>
</Cards>

## 它解決什麼

```mermaid
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 先搭這一層：

```text
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 逐個補。

## 起始提示詞

```text
请先不要实现完整业务功能。基于我的产品想法，先搭一个 Mac-native SwiftUI app shell：

- 主窗口使用 sidebar + detail + inspector。
- 全局设置放到独立 Settings scene。
- 关键动作通过 menu、toolbar、keyboard shortcut 暴露。
- 只做最小可运行壳，并说明如何 build/run 验证。
```

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

## 更完整的商業專案提示詞

```text
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](https://developers.openai.com/codex/use-cases/macos-sidebar-detail-inspector)
- [OpenAI Codex native development collection](https://developers.openai.com/codex/use-cases/collections/native-development)
- [Build macOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-macos-apps)
- [Codex Agent skills](https://developers.openai.com/codex/skills)
