構建 macOS 應用

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

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；釋出相關任務要單獨檢查。