---
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="/docs/codex/official/08-scenarios/106-mac-telemetry">
    壳搭好后，再给真实功能加可验证事件。
  </Card>
  <Card title="SwiftUI refactor" href="/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)
