构建 macOS 应用
说明用 Codex 构建 macOS app 时，如何从 scene、window、menus、settings 和 desktop UX 出发。
📖 本篇术语速查表
| 英文 / 缩写 | 中文 | 一句话解释 |
|---|---|---|
| macOS 应用 | macOS app | 面向 Mac 的桌面应用。 |
| 桌面交互 | desktop interaction | 窗口、菜单栏等桌面特性。 |
| 分阶段构建 | phased build | 从壳到功能逐步搭。 |
不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你把一个 macOS 应用的构建拆成分阶段、可交给 Codex 的任务。
你是 macOS 应用构建规划顾问，帮我把一个 macOS 应用的构建拆成分阶段、可交给 Codex 的任务序列。
【角色】
你熟悉构建 macOS 应用适合交给 Codex 的部分、用到的能力、起始方式、推荐技术面，也知道桌面交互的特殊点。
【输入】
- 应用核心功能和目标用户：___
- 技术栈（SwiftUI / AppKit）：___
- 当前进度：___
- 我的 macOS 经验：___
【工作流程】
1. 把应用拆成壳 → 核心功能 → 桌面交互打磨
2. 每阶段给可交给 Codex 的任务
3. 标出窗口 / 菜单等需人验证的部分
4. 给各阶段验证点
【输出规范】
▌一、分阶段拆解
▌二、各阶段可交给 Codex 的任务
▌三、需人验证的桌面交互
▌四、各阶段验证点
【硬约束】
- 先跑起来再加功能
- 桌面交互（窗口 / 菜单 / 快捷键）实际验证
- 系统权限最小必要
- 小步可回滚
- 不确定的 API 标注需查官方文档用 Codex 构建 macOS app，要先按 Mac 的 scene、window、menus、settings 和 desktop UX 思考，而不是从一个 iOS-style ContentView 开始。执行上保持 shell-first：Xcode project 用 xcodebuild，package-first app 用 swift build，再用项目内 script/build_and_run.sh 统一本地验证。
官方页面：https://developers.openai.com/codex/use-cases/native-macos-apps
适合什么任务
| 场景 | Codex 应该做什么 |
|---|---|
| greenfield macOS SwiftUI app | scaffold desktop-native app shell 和 repeatable build script |
| 现有 Mac app 需要改 windows、menus、sidebars、settings、AppKit interop 或 signing | 按 Mac UX convention 修改并验证 |
| 团队希望 macOS 工作保持 shell-first | 用 terminal build/test/log loop，同时尊重 native desktop conventions |
使用的能力
| 能力 | 用法 | 链接 |
|---|---|---|
build-macos-apps | 用 shell-first workflow 构建和调试 macOS apps，设计 desktop-native SwiftUI scenes/windows，需要时接 AppKit，并准备 signing/notarization paths | https://github.com/openai/plugins/tree/main/plugins/build-macos-apps |
相关官方说明：
- Model Context Protocol：https://developers.openai.com/codex/mcp
- Agent skills：https://developers.openai.com/codex/skills
起始提示词
请使用 Build macOS Apps plugin，scaffold 一个 starter macOS SwiftUI app，并添加项目本地 `script/build_and_run.sh` entrypoint，方便我接到 `Run` action。
约束：
- 保持 shell-first。Xcode projects 优先使用 `xcodebuild`，package-first apps 使用 `swift build`。
- 显式建模 Mac scenes：main window 加 `Settings`、`MenuBarExtra` 或 utility windows；只有符合产品时才加入后者。
- 优先使用 desktop-native sidebars、toolbars、menus、keyboard shortcuts 和 system materials，不要用 iOS-style push navigation。
- 只有 SwiftUI 无法干净表达 desktop behavior 时，才使用窄 AppKit bridge。
- 每次 change 保持一个小 validation loop，并准确告诉我运行了哪些 build、launch 或 log commands。
交付：
- app scaffold 或 requested Mac feature slice
- 可复用 build-and-run script
- 你运行过的最小 validation steps
- 你建议的 desktop-specific follow-up work这个 prompt 的关键是先选 scene model，再搭 build/run loop。
推荐技术面
| 需要 | 推荐默认值 | 原因 |
|---|---|---|
| UI framework | SwiftUI | 适合 windows、sidebars、toolbars、settings 和 scene-driven Mac app structure |
| AppKit bridge | AppKit | SwiftUI 表达不到某个桌面行为时，用小 NSViewRepresentable、NSViewControllerRepresentable 或 NSWindow bridge |
| Build and packaging | xcodebuild、swift build、App Store Connect CLI | 保持 local builds、manual archives、script-based notarization、App Store uploads 的 terminal-first loop |
Scaffold App 和 Build Loop
新 Mac app 第一件事是让 Codex 选择 scene model：
WindowGroupWindowSettingsMenuBarExtraDocumentGroup
执行 loop 保持 shell-first。Xcode projects 用 xcodebuild；package-first apps 用 swift build；项目内加 script/build_and_run.sh，负责停止旧进程、build app、launch 新 artifact，并按需暴露 logs 或 telemetry。
如果纯 SwiftPM app 是 GUI app，要 bundle 并 launch 为 .app，不要直接运行 raw executable。否则本地验证可能遇到 Dock、activation、bundle identity 问题。
使用 Build macOS Apps Plugin
当任务进入 desktop-specific 层面时，加入 Build macOS Apps plugin。它覆盖：
- shell-first build/debug loops。
- SwiftPM app packaging。
- native SwiftUI scene/window patterns。
- AppKit interop。
- unified logging。
- test triage。
- signing/notarization workflows。
构建 Desktop-Native UI
优先用 Mac conventions：
NavigationSplitView做 sidebar/detail。Settingsscene 放 preferences。- toolbars 和 commands 暴露可发现 actions。
- menu bar extras 做轻量常驻工具。
先用 system materials、semantic colors 和 standard controls。custom window styling、drag regions 或 Liquid Glass surfaces 只有产品需要时再加。
如果 SwiftUI 只差一点，用最小 AppKit bridge 补缺口，例如 open/save panels、first-responder control、menu validation、drag-and-drop edges，或一个特定 NSView。
Debug、Test、Ship
runtime 行为不清楚时，让 Codex 围绕 window opening、sidebar selection、menu commands 或 background sync 加少量 Logger events，然后用 log stream 验证。
tests 失败时，先跑最小有用范围的 xcodebuild test 或 swift test，并分类：
- compilation。
- assertion failure。
- crash。
- flake。
- environment/setup problem。
进入 distribution 时，让 Codex 同时准备：
- Xcode manual archive path。
- script-based archive and notarization path。
codesign和plutil检查 app bundle、entitlements、hardened runtime。- 需要 terminal upload 时，用 App Store Connect CLI。
实用建议
- main window、settings window、utility windows、menu bar extras 建成 separate scene roots。
- 标准 SwiftUI scene/window APIs 能解决时，不要先写 custom chrome。
- AppKit 只做窄边缘，SwiftUI 仍是 selection 和 app state 的 source of truth。
- local launch 成功不等于 app 已签名或已准备 notarization；发布相关任务要单独检查。