开发者 Harness

Harness 是开发 Handsy 本身时用的一套开发循环。在 Mac 上，它可以通过 Wi-Fi 安装 iPhone 上的 App、更新板子的固件，在手机上启动任务，再把这次运行的日志和每一步操作记录拿回来。整个过程不用插手机，也不用插板子。

Harness 已经开源，代码在 release-1.0 分支的 harness/ 目录，完整设置见 harness/README.md。本页是概览。有问题请联系 [email protected]。

它解决什么问题

重装太慢。没有它时，每改一次都要插上手机重装 App，拔下板子重新刷固件，再插回去拉日志。Harness 把这些都改成通过 Wi-Fi 完成。
要在真机上测。Handsy 靠看真实的 iPhone 屏幕并动手操作，模拟器做不到。Harness 在接着板子的真实手机上运行真实任务，和用户的用法一样。
要看清发生了什么。每次运行都会留下日志和逐步记录：App 看到了什么、做了什么判断、执行了什么操作。Harness 把它们拷回 Mac，你可以自己看，也可以交给编程 Agent 分析。

各部分怎么配合

Mac 只和 iPhone 通信，通过 Wi-Fi 使用 Xcode 的 devicectl。板子一直插在手机上。固件的路径是 Mac → App → 板子，和 App 自带的板子更新一样。

为此，板子不开自己的热点，而是加入 Mac 所在的 Wi-Fi（station 模式）。iPhone 留在 Mac 的网络里，也在这个网络里找到板子。

脚本

脚本	作用
`harness/app.sh`	构建 Debug 版 App，装到测试 iPhone 上并启动。
`harness/fw.sh`	构建固件，拷进 App，由 App 装到板子上。
`harness/run.sh "<任务>"`	在 App 里启动一个任务，打印结束结果。
`harness/logs.sh [--runs]`	把 App 的 `debug.log` 拷到 Mac；加 `--runs` 时再拷最近一次运行记录。
`harness/hid.sh "…"`	通过 App 向板子发送原始命令（按键、输入、移动指针），也能截图。
`harness/board.py`	一次性设置：让板子加入 Mac 的 Wi-Fi（`net sta`），或回到自己的热点（`net ap`）。

fw.sh 还能检查更新流程：--corrupt 发送损坏的固件（App 会拒绝，板子继续运行原固件）；--crash-test 发送一个无法启动的固件（板子会自动回到之前的固件）。

一次性设置

iPhone。打开开发者模式，在 Xcode 里与 Mac 配对并开启 Connect via network，再连上 Mac 所在的 Wi-Fi。把 HARNESS_IPHONE 设为这台手机的名称或 ID。
Lightning iPhone。使用 Lightning 转 USB 3 相机转换器，并在它的 Lightning 口接上充电器。见 Lightning iPhone：相机转换器与供电。
让板子加入 Mac 的 Wi-Fi。先在 iPhone 上退出 App，重新插拔板子，三分钟内运行：
终端窗口
```
uv run harness/board.py net sta
```
macOS 会弹出配对请求，再弹窗让你输入 Wi-Fi 名称和密码。它们只经加密链路发给板子。然后重新打开 App。
重新镜像。在 iPhone 上打开控制中心 → 屏幕镜像 → ESP32 Agent。

日常循环

harness/app.sh                    # 构建、安装并启动 Debug 版 App
harness/fw.sh                     # 构建固件，通过 App 更新板子
harness/run.sh "Open Settings"    # 运行任务，打印结果
harness/logs.sh --runs            # 把日志和最近一次运行拷到 Mac

每次更新固件后板子会重启，需要在屏幕镜像里重新选择 ESP32 Agent。

回到热点模式

开发结束后，让板子回到自己的热点：

uv run harness/board.py net ap

切回之前，板子在重启和固件更新后都会记住 station 模式。详见 iPhone 连到家里 Wi-Fi 而不是 ESP32 Agent 热点怎么办。

安全

只在 Debug 版本里有。Harness 命令只存在于 App 的 Debug 构建中。App Store 和 TestFlight 版本会忽略它们，只安装签名过的固件。
更新会先检查。即使是 Debug 版本，App 发送前也会核对固件大小和校验值。损坏的固件会被拒绝，板子继续运行原来的固件。
配对窗口。新的蓝牙设备只能在板子上电后的三分钟内配对。
密码不进日志。Wi-Fi 密码在 macOS 弹窗里输入，只经加密链路发送，不会写进日志。
只用可信网络。station 模式下板子依赖你的网络。只在可信网络中使用，开发结束后用 net ap 切回。

日志和记录里可能有截图和任务内容，请当作私密信息处理。不用 Harness 时如何拉日志，见调试与拉日志。