build-run-debug

构建 / 运行 / 调试

快速开始

使用此技能设置一个项目本地的 script/build_and_run.sh 入口， 配置 .codex/environments/environment.toml，让 Codex app 显示 Run 按钮， 然后将该脚本作为默认的构建 / 运行路径。

优先采用 shell 优先的工作流：

• 创建脚本后，使用 ./script/build_and_run.sh 作为唯一的停止进程 + 构建 + 运行入口
• 对于 Xcode 工作区或项目，使用 xcodebuild
• 对于真正的 SwiftPM 命令行工具，在该脚本中使用 swift build 并直接启动可执行文件
• 对于 SwiftPM AppKit/SwiftUI GUI 应用，使用 swift build，在项目本地暂存 .app 包，并通过 /usr/bin/open -n 启动
• 可选添加用于 lldb、log stream、遥测验证或启动后进程检查的脚本标志

不要假设会使用模拟器、触控交互或移动端专用工具。

如果已有支持 Xcode 的 MCP 接口，且用户明确要求使用，则只在适用的场景中使用。使用范围应当有限且恰当：优先用于面向 Xcode 的发现、日志记录或调试支持，不要将仅适用于模拟器的工作流强行用于纯 macOS 任务。

工作流

1. 确认项目结构。

   • 使用 git rev-parse --is-inside-work-tree 检查工作区是否已位于 git 仓库中。
   • 如果不存在 git 仓库，请在构建前于项目 / 工作区根目录运行 git init，以便使用 Codex app 基于 git 的功能。如果当前工作区已属于某个父级仓库，切勿在嵌套子目录中运行 git init。
   • 查找 .xcworkspace、.xcodeproj 和 Package.swift。
   • 如果存在多个候选项，请说明默认选择及其不确定性。

2. 确定可运行的目标和进程名称。

   • 对于 Xcode，列出 scheme，并优先选择会生成应用的 scheme，除非用户指定了其他 scheme。
   • 对于 SwiftPM，尽可能识别可执行产品。
   • 根据产品类型分别处理 SwiftPM 的启动方式：
     • 只有真正的命令行工具才直接启动可执行文件，
     • 对于 AppKit/SwiftUI GUI 应用，使用在项目本地生成的 .app 包。
   • 确定重启前要停止的应用 / 进程名称。

3. 创建或更新 script/build_and_run.sh。

   • 使脚本专用于当前项目并具有可执行权限。
   • 脚本应始终：
     1. 停止当前正在运行的应用 / 进程（如果存在），
     2. 构建 macOS 目标，
     3. 启动最新构建的应用或可执行文件。
   • 添加用于调试 / 查看日志的可选标志：
     • --debug：在 lldb 下启动或附加调试器
     • --logs：启动后流式传输进程日志
     • --telemetry：流式传输按应用子系统 / 类别筛选的统一日志
     • --verify：启动应用，并使用 pgrep -x <AppName> 确认进程存在
   • 默认不带标志的路径应保持简单：停止进程、构建、运行。
   • 优先编写一个负责整个工作流的脚本，而不是反复要求 Agent 手动运行 swift build、查找构建产物，然后调用临时运行命令。
   • 对于 SwiftPM GUI 应用，让脚本构建产品、创建 dist/<AppName>.app，将二进制文件复制到 Contents/MacOS/<AppName>，生成最精简的 Contents/Info.plist，其中包含 CFBundlePackageType=APPL、CFBundleExecutable、CFBundleIdentifier、CFBundleName、LSMinimumSystemVersion 和 NSPrincipalClass=NSApplication，然后使用 /usr/bin/open -n <bundle> 启动。
   • 对于 SwiftPM GUI 应用的 --logs 和 --telemetry，先使用 /usr/bin/open -n 启动包，然后通过 /usr/bin/log stream --info ... 流式传输统一日志。
   • 不要建议直接启动 SwiftPM 可执行文件来运行 AppKit/SwiftUI GUI 应用。
   • 使用 references/run-button-bootstrap.md 作为脚本结构和环境文件准确格式的规范来源。不要在其他技能或命令中另行维护第二份权威示例。
   • 将运行脚本放在应用源代码目录之外。它应位于 script/build_and_run.sh，而不是 App/、Views/、Models/、Stores/、Services/ 或 Support/ 中。

4. 脚本创建后，在项目根目录写入 .codex/environments/environment.toml。

   • 使用此确切路径：.codex/environments/environment.toml。
   • 使用 references/run-button-bootstrap.md 中的确切操作格式。
   • 此文件用于为用户配置 Codex 应用中的“Run”按钮，并将其连接到脚本。
   • 如果项目中已有此文件，请将 Run 操作命令更新为指向 ./script/build_and_run.sh，而不是创建重复操作。
   • 将此 Codex 环境配置与 Swift 应用源文件分开。

5. 通过脚本进行构建和运行。

   • 默认使用 ./script/build_and_run.sh。
   • 如果用户要求调试器、日志、遥测或进程验证支持，请使用 ./script/build_and_run.sh --debug、--logs、--telemetry 或 --verify。

6. 正确总结失败情况。

   • 将阻碍归类为编译器、链接器、签名、构建设置、缺少 SDK／工具链、脚本错误或运行时启动问题。
   • 引用最精简且有用的错误片段，并解释其含义。

7. 使用正确的方式调试。

   • 对于配置、权限、沙盒和操作事件验证，使用脚本的 --logs 或 --telemetry 模式。
   • 对于 SwiftPM GUI 应用，如果应用程序包已启动，但窗口仍未显示在前台，请检查入口点是否需要 NSApp.setActivationPolicy(.regular) 和 NSApp.activate(ignoringOtherApps: true)。
   • 如果需要进行带符号的崩溃调试，请使用脚本的 --debug 模式或直接使用 lldb。
   • 如果用户需要对特定窗口、侧边栏、菜单或菜单栏操作进行埋点和验证，请切换到 telemetry。
   • 提供精简、面向用户的证据。

8. 仅在有帮助时使用支持 Xcode 的 MCP 工具。

   • 如果用户明确要求使用 XcodeBuildMCP，且该工具已可用，请优先使用，而不是临时搭建方案。
   • 如果现有工具明确适用于任务，请使用 MCP 进行支持 Xcode 的发现或调试／日志工作流。
   • 如果 MCP 无法提供简洁的 macOS 方案，请立即改用 shell 命令。

首选命令

• 项目发现：
  • find . -name '*.xcworkspace' -o -name '*.xcodeproj' -o -name 'Package.swift'
• Scheme 发现：
  • xcodebuild -list -workspace <workspace>
  • xcodebuild -list -project <project>
• 构建／运行：
  • ./script/build_and_run.sh
  • ./script/build_and_run.sh --debug
  • ./script/build_and_run.sh --logs
  • ./script/build_and_run.sh --telemetry
  • ./script/build_and_run.sh --verify

参考资料

• references/run-button-bootstrap.md：build_and_run.sh 和 .codex/environments/environment.toml 的规范契约。

注意事项

• 优先使用能够证明或证伪当前判断的最小范围命令。
• 一旦稳定的 build_and_run.sh 脚本可以接管工作流，就不要只留给用户一串一次性的手动命令。
• 在运行脚本存在之前，不要写入 .codex/environments/environment.toml；也不要让 Run 操作指向过时的脚本路径。
• 除非用户明确希望诊断此类故障，否则不要将 SwiftUI／AppKit SwiftPM GUI 应用作为原始可执行文件启动：这可能导致 Dock 中没有图标、应用无法切换到前台，以及缺少 Bundle 标识符的警告。原始可执行文件启动仅适用于真正的命令行工具。
• 不要声称 UI 处于某种状态，除非你能直接检查。
• 不要将移动端或模拟器工作流描述成适用于 macOS。
• 如果构建输出过长，请总结遇到的第一个实际阻碍，并指出后续命令。

输出要求

请提供：

• 检测到的项目类型
• 配置的脚本路径和 Codex 环境操作（如适用）
• 运行的命令
• 构建和启动是否成功
• 如果失败，最主要的阻碍
• 最合理的下一步操作