编译并安装 iOS App

当前版本的 Agent 在 ESP32 Agent 手机 App 内运行。首次安装使用 Mac 和 Xcode；「运行时不需要电脑」不代表安装过程也不需要。

准备本地配置

在项目根目录执行：

cp ios/Config/Local.xcconfig.example ios/Config/Local.xcconfig

编辑新建的 ios/Config/Local.xcconfig，填写自己的团队 ID 和独立的 App 标识：

DEVELOPMENT_TEAM = YOUR_TEAM_ID
IA_BUNDLE_ID = com.yourname.esp32agent

以上都是示例，必须替换。Widget 的标识和 App Group 会由 App Bundle ID 派生。本地配置不要提交，尤其不要把模型密钥写进公开仓库。

免费 Apple ID 与可选权限

免费 Apple ID 可以签名开发版，签名有效期为七天，之后需要重新签名安装。

示例配置启用了可选 entitlement 文件。如果 Xcode 提示你的团队无法配置相应能力，可以使用配置文件本身支持的退出方式：

IA_ENTITLEMENTS =
IA_WIDGET_ENTITLEMENTS =

这样会让本地构建不再使用这两个可选权限文件。一键加入热点需要 Hotspot Configuration 和付费开发者账号；关闭后，使用 App 提供的名称与密码手动加入。依赖 App Group 或通知权限的可选功能也可能受影响。

不要用他人的团队 ID 或随意添加 entitlement 来绕过签名错误。根据 Xcode 的实际报错，检查你自己的账号权限。

在真机上编译运行

open ios/IPhoneAgent.xcodeproj

1. 将 iPhone 连接到 Mac，按提示信任电脑。
2. 选择 IPhoneAgent scheme 和连接的真机。
3. 检查 Signing & Capabilities 中的团队与 Bundle ID。
4. 编译运行；如果当前 iOS 或 Xcode 要求信任开发者或开启开发者模式，按照设备提示完成。

项目最低支持 iOS 18。模拟器可以用于检查界面，但不能替代真实 iPhone 和板子完成整套链路验证。

什么时候需要 XcodeGen

工程通过 XcodeGen 从 ios/project.yml 生成。修改工程定义后，在 ios 目录重新生成：

cd ios
xcodegen

如果克隆后已有工程且没有改动定义，可以先直接打开现有工程。

安装之后

打开 ESP32 Agent，把板子从 Mac 移到 iPhone，继续蓝牙、投屏与指针设置。

当前 App 使用私有 suspend API 离开自己的界面。这份指南描述自行编译的开发版本，不代表 App Store 发布流程。