---
name: ios-device-deploy
description: 当用户明确要求把当前项目构建、安装到连接的 iPhone 或 iPad，启动真机应用或排查构建安装失败时使用。
---

# iOS 真机安装

构建并安装用户当前要验证的应用。CI 的正式构建和 TestFlight/App Store 发布继续使用项目现有流程。

1. 阅读项目规则和现有构建配置，确认容器、scheme、设备和本次代码来源。多个目标有歧义时展示候选。
2. 使用项目已有签名与元数据配置；先定位 XcodeGen/Tuist/Info.plist 等真实配置源，不覆写其它项目的 Team ID。
3. 从当前已同步主线的任务工作树构建，可以包含本次 dirty 改动，记录来源 SHA 和未提交改动；遵循用户已有验包要求。
4. 执行本技能目录内的脚本；默认每次使用独立临时 DerivedData，显式复用缓存时传 --derived-data。
5. 安装前核对真实产物的 bundle ID、必要隐私声明和现代启动屏。--bundle-id 是预期身份，不能用来掩盖产物不一致。
6. 用户要求时启动应用；报告代码版本、设备、app 路径、bundle ID、版本/build、安装与启动结果。命令成功和界面验收分别记录。

```bash
python3 "<本技能目录>/scripts/ios_device_deploy.py" --project-root "$PWD" --launch
python3 "<本技能目录>/scripts/ios_device_deploy.py" --project-root "$PWD" --bundle-id com.example.app --device-id "<设备ID>" --launch
```

先定位安装目录或站内正本再替换命令占位符。脚本提供 --list-devices、--list-schemes 和 --dry-run；dry-run 会读取项目/设备信息但不构建安装。现代启动屏确实有意省略时才能使用 --allow-missing-modern-launch-screen。

项目 UI、设置页与版本显示的开发走相应开发任务；本入口聚焦构建、安装与排查。不默认触发 CI、上传应用或改发布状态。

本版已完成 bundle ID 选择和缓存隔离的离线回归，真实设备构建/安装未执行。