构建 Mac 应用外壳

概览

使用 Codex 和 Build macOS Apps plugin，将应用创意转化为桌面原生的 `NavigationSplitView` 应用；保持侧边栏选择稳定；添加菜单、工具栏和键盘快捷键；并将偏好设置移到专门的 `Settings` scene 中。

适合场景

新的 Mac 应用创意，或以 iPad 为先、以 Web 为先的概念，需要真正的桌面应用外壳，具备持久导航、菜单、工具栏和键盘快捷键
编辑器、资料库、管理或审核工具，其中侧边栏选择驱动详情面板，而检查器展示次级元数据或操作
Mac 应用中，设置应位于专门的偏好设置窗口，而不是主内容堆栈中的另一个被推入的界面

构建原生 Mac 风格的侧边栏与检查器外壳

使用 Build macOS Apps plugin，将 [describe your app idea] 转化为一个原生 Mac 风格的 SwiftUI 应用外壳，包含侧边栏、详情面板、检查器、命令和 Settings。

约束：
- 先选择 scene 模型。主窗口优先使用 `WindowGroup`，并为偏好设置添加专门的 `Settings` scene。
- 围绕 `NavigationSplitView` 构建主界面，使用显式选择状态、原生 `.sidebar` 列表、详情区域，以及用于次级元数据或控件的 `inspector(isPresented:)` 面板。
- 保持侧边栏行轻量且原生：一个图标、一行标题，最多再加一行简短的次级信息。除非有充分的产品理由，不要把每一行都包成大型自定义卡片。
- 通过 scene 级别的 `commands`、`CommandMenu`、工具栏按钮和键盘快捷键公开重要操作。不要把关键操作的唯一入口隐藏在手势后面。
- 窗口范围的 UI 状态使用 `@SceneStorage`，偏好设置使用 `@AppStorage`，侧边栏/详情联动使用由父级显式持有的选择绑定。
- 优先使用系统材质、语义化颜色和标准侧边栏背景。仅在需要时，为详情或检查器中的内容卡片添加自定义样式。
- 只有在 SwiftUI 无法干净地表达某个特定桌面行为时，才使用范围尽量小的 AppKit bridge。
- 创建或更新 `script/build_and_run.sh`，运行最小但有用的构建/运行检查，并告诉我你使用的确切命令。

交付内容：
- scene 结构，以及主侧边栏/详情/检查器视图
- 菜单、工具栏和键盘快捷键的连接方式
- `Settings` scene 和偏好设置状态模型
- 你添加的任何 AppKit bridge，以及为什么有必要
- 构建/运行验证步骤，以及你建议的任何桌面 UX 后续优化

从 Mac 的 scene 模型开始

这个用例适合把应用创意转化为真正为桌面而生的 Mac 应用外壳，而不是从触控优先的堆栈生硬拉伸而来。让 Codex 先选择 scene 模型，然后围绕稳定的侧边栏选择、详情区域，以及用于次级控件或元数据的检查器来设计主窗口。

一个原生 Mac 风格的侧边栏与详情应用外壳，侧边栏中有一个已选项目，详情面板中显示内容

当你希望 Codex 应用这种桌面结构，并让构建/运行循环以外壳优先时，请使用 Build macOS Apps 插件。它的 macOS SwiftUI patterns skill 非常适合 scene 设计、侧边栏、检查器、命令、设置，以及在 SwiftUI 只差一点点无法覆盖某个 Mac 特定行为时使用的小型 AppKit bridge。

构建侧边栏、详情面板和检查器

当功能受益于持久导航和稳定的选中项时，优先使用 NavigationSplitView。保持侧边栏行原生且轻量，让侧边栏使用系统背景，并把自定义卡片或密集元数据留给详情面板或检查器。

struct LibraryRootView: View {
  @SceneStorage("LibraryRootView.selection") private var selection: Item.ID?
  @SceneStorage("LibraryRootView.showInspector") private var showInspector = true

  var body: some View {
    NavigationSplitView {
      List(selection: $selection) {
        ForEach(items) { item in
          Label(item.title, systemImage: item.systemImage)
            .tag(item.id)
        }
      }
      .listStyle(.sidebar)
      .navigationTitle("Library")
    } detail: {
      ItemDetailView(selection: selection)
        .inspector(isPresented: $showInspector) {
          ItemInspectorView(selection: selection)
        }
    }
  }
}

如果应用需要非标准的分栏尺寸、底层窗口协调，或自定义 responder chain 行为，请让 Codex 保持 SwiftUI 外壳不变，只为那个缺口添加所需的最小 AppKit bridge。

在桌面层中放置命令、工具栏和快捷键

Mac 用户应该能在菜单栏、工具栏和键盘快捷键中发现重要操作。让 Codex 围绕同一组应用操作连接 scene 级别的 commands、上下文敏感的菜单项和工具栏按钮，这样桌面用户就不必去寻找只靠手势触发的控件。

@main
struct LibraryApp: App {
  var body: some Scene {
    WindowGroup {
      LibraryRootView()
    }
    .commands {
      CommandMenu("Library") {
        Button("New Item") {
          // Create a new item.
        }
        .keyboardShortcut("n")

        Button("Toggle Inspector") {
          // Route this command to the focused window or selected item state.
        }
        .keyboardShortcut("i", modifiers: [.command, .option])
      }
    }

    Settings {
      LibrarySettingsView()
    }
  }
}

当命令应作用于当前详情项时，可使用 FocusedValue、scene 状态或显式选择状态。如果某个快捷键会在多个位置注册，请让 Codex 统一其归属，让应用只有一条清晰的命令路径。

将偏好设置保留在 `Settings` 中

对于应用偏好设置，使用专门的 Settings scene，并用 @AppStorage 持久化用户的长期选择。相比在主内容窗口内部推入一个设置界面，这通常更符合 Mac 的使用方式。

struct LibrarySettingsView: View {
  @AppStorage("showItemMetadata") private var showItemMetadata = true

  var body: some View {
    TabView {
      Form {
        Toggle("Show Item Metadata", isOn: $showItemMetadata)
      }
      .tabItem { Label("General", systemImage: "gearshape") }
    }
    .frame(width: 460, height: 260)
    .scenePadding()
  }
}

先描述应用概念，再验证外壳

当你的提示词明确说明应用概念、主要内容对象和核心操作，然后要求 Codex 先围绕该工作流构建桌面外壳时，这个页面效果最佳。让 agent 运行一个小型构建/运行检查，并总结 scene 结构、命令连接方式、状态归属，以及它不得不 bridge 的任何 AppKit 边缘问题。

实用建议

保持侧边栏原生

侧边栏行使用一个图标、一行标题，最多再加一行简短的次级信息。把更丰富的卡片、计数器和元数据移到详情面板或检查器中，这样源列表会更易于浏览。

不要把设置隐藏在主堆栈中

如果某个用户偏好会影响整个应用，让 Codex 使用 @AppStorage 将该控件放入 Settings，并通过应用菜单提供入口，而不是再构建一个被推入的设置界面。

仅将 AppKit 用于狭窄的桌面缺口

如果某个功能需要打开/保存面板、first-responder 控制或自定义 NSView，应将 AppKit 作为 SwiftUI 持有状态模型外侧的一小圈边缘来使用，而不是用 AppKit 重写整个窗口。

概览