# pi-build-ios-apps

[English](../README.md)

![pi-build-ios-apps hero](assets/hero.png)

> React Native 开发优先走浏览器快循环，需要时再做 iOS 原生 smoke test。

`pi-build-ios-apps` 是一个 Pi package。它优先给 React Native 提供快速开发闭环：
识别 Expo / React Native 项目，启动 Web 或 Storybook 预览，复用 cmux browser
surface，检查真实浏览器 DOM，并在不频繁跑 Xcode 的情况下做视觉和交互 QA。

当确实需要原生证据时，它仍然提供 iOS 工具：检查 Xcode，构建并启动 Simulator
dev client，读取 iOS accessibility tree，点击/输入原生元素，并通过 `serve-sim`
镜像 Simulator。

它的目标不是隐藏式自动化，而是可见、可打断、可验收的本地移动 App 开发。

![真实模拟器 demo](assets/demo.gif)

## 为什么需要它

很多 coding agent 能改 iOS 代码，但到了真正证明 App 能跑的时候就停住了：
构建、启动、看模拟器、点击界面、截图、报告结果，还是要人手动接上。

`pi-build-ios-apps` 补齐的就是这段本地运行时验证。

它让 Pi 可以处理 RN 快循环和原生证据循环：

- 检查 Xcode 和 iOS Simulator 环境
- 识别 React Native / Expo 项目，包括 Expo Web、Storybook、`react-native-web`
- 通过 Expo Web、Storybook、项目 web script 或 custom command 启动浏览器预览
- 复用 cmux browser，读取交互式 DOM snapshot，检查 selector、text、testID，并截图
- 用 `xcodebuild` list/build/test/clean/build-for-testing
- 通过 XcodeBuildMCP CLI provider 执行原生 build/install/launch
- 原生 iOS UI snapshot、element ref、wait/assert、tap、type、gesture 和截图
- React Native / Expo native dev-client 的 Metro 生命周期管理
- 用 `xcrun simctl` boot/install/launch/terminate/screenshot/openurl/privacy/appearance/content-size
- 为指定 Simulator UDID 启动、检查、停止和操作 `serve-sim`
- 当官方 `serve-sim` 页面卡在 `Connecting` 时，用 direct MJPEG 预览兜底
- 明确区分浏览器 DOM 检查和原生 iOS UI 自动化

## 安装

从 npm 安装：

```sh
pi install npm:pi-build-ios-apps
```

从 GitHub 安装：

```sh
pi install git:github.com/aa2246740/pi-build-ios-apps
```

项目内安装：

```sh
pi install -l git:github.com/aa2246740/pi-build-ios-apps
```

本地 checkout 安装：

```sh
pi install /path/to/pi-build-ios-apps
```

不安装，只试一次：

```sh
pi -e /path/to/pi-build-ios-apps/extensions/pi-build-ios-apps.ts \
  --skill /path/to/pi-build-ios-apps/skills/pi-build-ios-apps
```

## 快速使用

进入一个 iOS 项目：

```sh
pi
```

然后对 Pi 说：

```text
/build-ios-app
```

这个 slash command 会启动默认的 React Native 优先闭环：识别 RN 项目、启动 web
预览、复用 cmux browser、做 DOM/testID 检查和视觉 QA；只有需要原生证据时才进入
iOS native smoke check。

## 工具

这个 package 注册了 `/build-ios-app` 和 11 个 Pi 工具：

| Tool | 作用 |
| --- | --- |
| `pi_ios_doctor` | 检查 Xcode、runtime、Node/npm、CocoaPods、serve-sim、XcodeBuildMCP、cmux。 |
| `pi_ios_xcodebuild` | 对 Xcode project/workspace 运行 build/test 等动作。 |
| `pi_ios_build_run` | 通过 XcodeBuildMCP 构建、安装、启动并收集运行证据。 |
| `pi_ios_simulator` | 管理 Simulator boot/install/launch/terminate/screenshot/openurl/privacy/appearance/content-size。 |
| `pi_ios_ui` | 读取原生 accessibility snapshot，并按 ref 或 selector tap/type/wait/assert。 |
| `pi_ios_serve_sim` | 为一个明确 UDID 启动、检查、停止和操作 `serve-sim`。 |
| `pi_ios_preview` | 当 `Connecting` 卡住时启动 direct MJPEG 像素预览页。 |
| `pi_ios_react_native` | 识别 React Native / Expo native 项目，并管理 Metro dev server。 |
| `pi_rn_web_preview` | 启动或复用 Expo Web、Storybook、项目 web script 或 custom RN web 预览。 |
| `pi_rn_web_verify` | 通过 HTTP、cmux DOM snapshot、selector/testID/text 检查和截图验收 RN web 预览。 |
| `pi_ios_cmux_open` | 在 cmux browser 中打开或复用 iOS 像素预览 URL。 |

## React Native 优先

对 React Native，默认路径是浏览器优先：

- `pi_rn_web_preview doctor` 识别 Expo、React Native、Storybook、web scripts、
  `react-native-web`、package manager，并给出推荐浏览器 target。
- `pi_rn_web_preview start` 启动 Expo Web、Storybook、项目 web script 或 custom
  command，并打开/复用一个 cmux browser surface。
- `pi_rn_web_verify` 检查 URL，让 cmux 生成交互式浏览器 DOM snapshot，验证
  selector/text/testID，并可截图。

布局、文案、导航、视觉调整、响应式状态和大多数 agent 自验收都应该先走这条路径。
cmux 能选中这些节点，是因为它们是真实网页 DOM，不是 Simulator 视频流。

## 原生 Smoke Gate

当变更碰到原生现实，再进入 iOS 路径：

- HealthKit、权限、entitlements、native modules、native navigation 边界、push/deep links、
  App Store signing 或最终验收证据。
- `pi_ios_react_native start-metro` 让 dev client 连上 Metro。
- `pi_ios_build_run`、`pi_ios_ui`、`pi_ios_serve_sim`、`pi_ios_preview` 提供
  build/install/launch、原生 accessibility 和 Simulator 截图证据。

Simulator 预览仍然不是浏览器 DOM。cmux 在 Simulator 镜像里选到的是预览壳，通常是
image/canvas/MJPEG stream，不是原生 RN 控件。原生元素级操作要用 `pi_ios_ui`，并在
RN 组件上提供 `testID`、`accessibilityLabel` 和 `accessibilityRole`。

核心闭环不依赖 Appium 或 Detox。它们仍然是成熟团队测试栈的可选方案，但这个 package
优先给 Pi 一套 RN 浏览器快循环和原生 smoke gate。

## 工作流

```text
Pi 读取项目
  -> pi_ios_react_native doctor 识别 RN/Expo/native 边界
  -> pi_rn_web_preview doctor 选择 Expo Web、Storybook、script 或 custom
  -> pi_rn_web_preview start 打开一个可复用 cmux browser surface
  -> pi_rn_web_verify 读取真实浏览器 DOM 并检查 selector/testID/text
  -> 普通 UI 工作不跑 Xcode，快速迭代
  -> 必要时再用 pi_ios_build_run + pi_ios_ui 做原生 smoke proof
  -> Pi 报告明确的验证边界
```

## 和 pi-company 的组合

`pi-build-ios-apps` 很适合搭配
[`pi-company`](https://github.com/aa2246740/pi-company)。

`pi-company` 负责把多个可见 Pi 会话组织成本地项目团队：lead、coder、reviewer、
tester、PM、issue、worktree、gate。这个 package 让这支团队具备移动开发闭环：
RN 工作走浏览器快速 QA，原生行为需要时再进 Simulator proof。

```text
人 -> pi-company lead -> coder worktree -> RN web preview
  -> tester cmux DOM/视觉验收 -> 必要时 native smoke gate
  -> review gates -> acceptance -> merge
```

如果装了 cmux，Pi 的多个角色、RN web 预览或 iOS 预览可以放在同一个可见工作区里：
左边是 agent，右边是预览，中间没有隐藏的云端编排器。

## React Native、Expo 和 HealthKit

对 React Native / Expo native 项目：

- 用 `pi_ios_react_native doctor` 识别 Expo、React Native、`ios/` workspace/project、
  Podfile、package manager 和 web targets
- 默认先用 `pi_rn_web_preview doctor/start` 做 UI 迭代
- 用 `pi_rn_web_verify` 做 cmux DOM snapshot、selector、testID、text、截图和验证边界报告
- 启动 native dev build 前先确保 Metro 在运行
- 需要 post-build relaunch 时，用 `pi_ios_simulator` 传入 `RCT_METRO_PORT` 等 launch env
- 用 `testID` 和 accessibility props，让 `pi_ios_ui` 能稳定选择原生元素
- 当 native iOS project 或模块生态需要 Pods 时，CocoaPods 仍然是现实需求
- 不要默认认为 SwiftPM 可以替代 React Native native modules 的 Pods 集成

SwiftUI 支持仍然保留在 iOS 工具里，但当前产品方向是 React Native-first。

## 安全边界

`pi-build-ios-apps` 有意保持本地、显式、可审计：

- 不修改系统代理设置。
- 不强制要求 CocoaPods，除非目标项目自己需要 Pods。
- `serve-sim` 清理只针对一个明确的 Simulator UDID。
- cmux 预览默认复用一个 browser surface。
- 开发阶段优先使用真实 RN web DOM 做验收。
- 不声称原生 iOS 控件可以像浏览器 DOM 节点一样被选择。
- 元素级 Simulator 操作走原生 accessibility 自动化。
- 要求 Pi 报告命令、URL、模拟器 ID 和验证边界。

Pi package 可以执行本地代码。安装任何第三方 package 前，都应该先审查源码。

## Demo 和隐私

仓库里的截图和 GIF 来自 synthetic `FlightDeck` demo app，在本地 iOS Simulator 上生成。
它们不包含真实健康数据、私有源码、API key、代理配置、私有 Git remote 或个人机器路径。

可复现的 SwiftUI demo 放在 `examples/FlightDeck`。它刻意保持小而无外部依赖，用一个首屏展示
Pi iOS 闭环：build 状态、Simulator runtime proof、browser 复用、agent 角色和可视化 QA。

## 需求

- macOS
- Xcode 和 iOS Simulator runtime
- Node.js 20+
- Pi coding agent
- 可通过 `npx --yes serve-sim@latest` 使用 `serve-sim`
- 可通过 `npx --yes xcodebuildmcp@2.6.2` 使用 `xcodebuildmcp`
- 可选但推荐：cmux

## 开发

```sh
npm install
npm run typecheck
npm pack --dry-run
```

本地烟测：

```sh
pi -e ./extensions/pi-build-ios-apps.ts \
  --skill ./skills/pi-build-ios-apps
```

## 非官方声明

这是一个独立的社区 package。除非特别说明，它不隶属于 Apple、OpenAI、Codex、Pi、
cmux 或 `serve-sim` 项目。

## License

Apache-2.0