构建 macOS 应用

用 Codex 构建 macOS app，要先按 Mac 的 scene、window、menus、settings 和 desktop UX 思考，而不是从一

用 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

起始提示词

请使用 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：

WindowGroup
Window
Settings
MenuBarExtra
DocumentGroup

执行 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。
Settings scene 放 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；发布相关任务要单独检查。