構建 macOS 應用

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
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：

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

構建 macOS 應用

本頁目錄