X Openai Build Run Debug 59814d0

---
name: x-openai-build-run-debug-59814d0
description: Build, run, and debug macOS apps with shell-first Xcode and Swift workflows. Use when launching apps or diagnosing build, startup, or runtime failures.
---

### 导出副本边界与技能别名

迁移、安装、修复和经验回写只作用于当前加载的目标宿主技能副本。原 Codex 技能/MCP、下载的源码和 `original-skills` 均为来源材料，不因执行本副本而写入；只有用户另行明确要求配置 Codex 产品本身时，才按该产品流程处理指定目标。脚本需要安装目录或状态目录时，显式提供目标路径；不得从 `CODEX_HOME` 隐式推断写入位置。

跨技能名称可能沿用源库别名。先查 [技能别名表](../../skill-aliases.json)，优先选择同来源、同插件的条目，再使用其 `id` 调用或读取对应入口；不得假定旧 `$skill`、`superpowers:skill` 名称在新宿主直接注册。不能确定目标时先核对，不替换真实产品命令或 Shell 环境变量。

## 跨宿主使用约定

本副本供支持 Agent Skills 的客户端使用。先检查当前宿主实际提供的工具、权限和已连接服务，再执行正文工作流。原文中的宿主工具标识是能力参考；只有实际发现该工具时才可调用，其他宿主应使用经核验的等价 MCP、CLI 或 API。没有等价能力的步骤必须报告不可用，不能虚构调用或完成状态。

技能资源以本技能目录为基准；输出写入当前项目中用户指定的位置。通过技能名称或自然语言触发，具体快捷命令由宿主决定。涉及真实产品、模型 API、协议字段和官方网址的名称保持原意。授权、审批、隐私和工具范围限制在迁移后仍然有效；不得为兼容而扩大权限。具体依赖与迁移说明见同目录 `PORTABILITY.md`。

# Build / Run / Debug

## Quick Start

Use this skill to set up one project-local `script/build_and_run.sh` entrypoint,
then use that script as the default build/run path. Discover whether the current host offers a compatible project Run action; configure it only when supported. Codex app integration is an optional, verified-host path below.

Prefer shell-first workflows:

- `./script/build_and_run.sh` as the single kill + build + run entrypoint once it exists
- `xcodebuild` for Xcode workspaces or projects
- `swift build` plus raw executable launch inside that script for true SwiftPM command-line tools
- `swift build` plus project-local `.app` bundle staging and `/usr/bin/open -n` launch for SwiftPM AppKit/SwiftUI GUI apps
- optional script flags for `lldb`, `log stream`, telemetry verification, or post-launch process checks

Do not assume simulators, touch interaction, or mobile-specific tooling.

If an Xcode-aware MCP surface is already available and the user explicitly wants
it, use it only where it fits. Keep that usage narrow and honest: prefer it for
Xcode-oriented discovery, logging, or debugging support, and do not force
simulator-specific workflows onto pure macOS tasks.

## Workflow

1. Discover the project shape.
   - Check whether the workspace is already inside a git repo with `git rev-parse --is-inside-work-tree`.
   - If no git repo is present, initialize one only when the user's workflow or an explicitly selected, verified host integration requires it; building itself does not require Codex git-backed features. Never run `git init` inside a nested subdirectory when the current workspace already belongs to a parent repo.
   - Look for `.xcworkspace`, `.xcodeproj`, and `Package.swift`.
   - If more than one candidate exists, explain the default choice and the ambiguity.

2. Resolve the runnable target and process name.
   - For Xcode, list schemes and prefer the app-producing scheme unless the user names another one.
   - For SwiftPM, identify executable products when possible.
   - Split SwiftPM launch handling by product type:
     - use raw executable launch only for true command-line tools,
     - use a generated project-local `.app` bundle for AppKit/SwiftUI GUI apps.
   - Determine the app/process name to kill before relaunching.

3. Create or update `script/build_and_run.sh`.
   - Make the script project-specific and executable.
   - It should always:
     1. stop the existing running app/process if present,
     2. build the macOS target,
     3. launch the freshly built app or executable.
   - Add optional flags for debugging/log inspection:
     - `--debug` to launch under `lldb` or attach the debugger
     - `--logs` to stream process logs after launch
     - `--telemetry` to stream unified logs filtered to the app subsystem/category
     - `--verify` to launch the app and confirm the process exists with `pgrep -x <AppName>`
   - Keep the default no-flag path simple: kill, build, run.
   - Prefer writing one script that owns this workflow instead of repeatedly asking the agent to manually run `swift build`, locate the artifact, then invoke an ad hoc run command.
   - For SwiftPM GUI apps, make the script build the product, create `dist/<AppName>.app`, copy the binary to `Contents/MacOS/<AppName>`, generate a minimal `Contents/Info.plist` with `CFBundlePackageType=APPL`, `CFBundleExecutable`, `CFBundleIdentifier`, `CFBundleName`, `LSMinimumSystemVersion`, and `NSPrincipalClass=NSApplication`, then launch with `/usr/bin/open -n <bundle>`.
   - For SwiftPM GUI `--logs` and `--telemetry`, launch the bundle with `/usr/bin/open -n` first, then stream unified logs with `/usr/bin/log stream --info ...`.
   - Do not recommend direct SwiftPM executable launch for AppKit/SwiftUI GUI apps.
   - Use `references/run-button-bootstrap.md` as the canonical source for the
     script shape and exact environment file format. Do not fork a second
     authoritative snippet in another skill or command.
   - Keep the run script outside app source. It belongs in `script/build_and_run.sh`, not in `App/`, `Views/`, `Models/`, `Stores/`, `Services/`, or `Support/`.

4. If the current host is Codex app and its project Run-action format is verified, write `.codex/environments/environment.toml` at the project root once the script exists. For another host, discover its equivalent task/run configuration; without one, deliver and use the local script directly.
   - Use this exact placement: `.codex/environments/environment.toml`.
   - Use the exact action shape in `references/run-button-bootstrap.md`.
   - This file is what gives the user a Codex app Run button wired to the script.
   - If the project already has this file, update the `Run` action command to point at `./script/build_and_run.sh` instead of creating a duplicate action.
   - Keep this Codex environment config separate from Swift app source files.

5. Build and run through the script.
   - Default to `./script/build_and_run.sh`.
   - Use `./script/build_and_run.sh --debug`, `--logs`, `--telemetry`, or `--verify` when the user asks for debugger/log/telemetry/process verification support.

6. Summarize failures correctly.
   - Classify the blocker as compiler, linker, signing, build settings, missing SDK/toolchain, script bug, or runtime launch.
   - Quote the smallest useful error snippet and explain what it means.

7. Debug the right way.
   - Use the script's `--logs` or `--telemetry` mode for config, entitlement, sandbox, and action-event verification.
   - For SwiftPM GUI apps, if the app bundle launches but its window still does not come forward, check whether the entrypoint needs `NSApp.setActivationPolicy(.regular)` and `NSApp.activate(ignoringOtherApps: true)`.
   - Use the script's `--debug` mode or direct `lldb` if symbolized crash debugging is needed.
   - If the user needs to instrument and verify specific window, sidebar, menu, or menu bar actions, switch to `telemetry`.
   - Keep evidence tight and user-facing.

8. Use Xcode-aware MCP tooling only when it helps.
   - If the user explicitly asks for XcodeBuildMCP and it is already available, prefer it over ad hoc setup.
   - Use the MCP for Xcode-aware discovery or debug/logging workflows when the available tool surface clearly matches the task.
   - Fall back to shell commands immediately when the MCP does not provide a clean macOS path.

## Preferred Commands

- Project discovery:
  - `find . -name '*.xcworkspace' -o -name '*.xcodeproj' -o -name 'Package.swift'`
- Scheme discovery:
  - `xcodebuild -list -workspace <workspace>`
  - `xcodebuild -list -project <project>`
- Build/run:
  - `./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

- `references/run-button-bootstrap.md`: canonical `build_and_run.sh` and `.codex/environments/environment.toml` contract.

## Guardrails

- Prefer the narrowest command that proves or disproves the current theory.
- Do not leave the user with a one-off manual command chain once a stable `build_and_run.sh` script can own the workflow.
- Do not write `.codex/environments/environment.toml` before the run script exists, and do not point the Run action at a stale script path.
- Do not launch a SwiftUI/AppKit SwiftPM GUI app as a raw executable unless the user explicitly wants to diagnose that failure mode: it can produce no Dock icon, no foreground activation, and missing bundle identifier warnings. Keep raw executable launch only for true command-line tools.
- Do not claim UI state you cannot inspect directly.
- Do not describe mobile or simulator workflows as if they apply to macOS.
- If build output is huge, summarize the first real blocker and point to follow-up commands.

## Output Expectations

Provide:
- the detected project type
- the script path and Codex environment action you configured, if applicable
- the command you ran
- whether build and launch succeeded
- the top blocker if they failed
- the smallest sensible next action