---
name: macos-app-install
description: 当用户明确要求把当前 Xcode macOS 应用构建并安装到本机，或排查本机安装失败时使用。
---

# macOS 本机安装

项目现有 CI 负责正式构建与发布。本入口用于快速验证当前工作树，优先使用项目已有构建配置；通用脚本适用于单一 Xcode 主应用。

1. 按项目规则确认最新基线、本次改动、容器、scheme 和安装位置。
2. 使用本技能 scripts/macos_app_install.py；默认 Release，每次独立临时 DerivedData。明确要求时通过 --run-xcodegen 生成工程。
3. 从顶层构建产物选择主 app，读取真实 bundle ID。旧目标身份不同或元数据缺失时停止。
4. 在安装目录同一文件系统准备完整新副本，验证身份后替换。旧应用保存在安装目录的 .codex-app-backups，替换失败恢复旧版。
5. 用户要求时打开应用；报告来源 SHA/dirty、scheme、配置、app 身份、构建和安装路径、备份位置及实际启动结果。

```bash
python3 "<本技能目录>/scripts/macos_app_install.py" --project-root "$PWD" --open
python3 "<本技能目录>/scripts/macos_app_install.py" --project-root "$PWD" --install-dir "$HOME/Applications"
```

默认 /Applications；无写权限时使用用户指定的 ~/Applications。定位技能目录后替换占位符。应用身份冲突、多个容器/产品、构建或复制失败都报告实际阻塞，不随意选其它应用。

签名、公证、外部分发由项目流程或 macos-app-distribution 处理。不要把本机打开成功写成对外分发验收。

本版已完成临时目录的完整替换、旧版备份和失败恢复回归，真实应用构建安装未执行。