Git 分支说明

第一次使用，从现在的 Handsy AI App 开始。 App 运行在 iPhone 上，小小的 ESP32 板子负责接收画面、点按、滑动和输入。板子设置好后，就可以把电脑放到一边。

开源项目也在 legacy 分支保留了最早的电脑方案。如果你想了解项目从哪里开始，或探索源码，可以继续往下看。

两种方案有什么不同？

	当前 · main	早期 · legacy
Agent 在哪里运行	iPhone 上的 App，连接你选择的模型	电脑上的 Python 服务和网页界面
怎样看到屏幕	ESP32 板子接收 AirPlay 镜像	电脑上的 UxPlay 接收镜像
怎样操作手机	板子作为 USB 鼠标和键盘连接手机	电脑通过 Wi-Fi 控制板子
任务运行时的电脑	不需要	需要一直运行
屏幕镜像名称	ESP32 Agent	iPhone Agent
手机上需要什么	Handsy App	不安装 App

使用当前方案，请按开始使用操作。浏览器安装页为这套方案准备板子。Legacy 使用另一套固件，两套固件不能互换。

新 CLI 与这两种方案的关系

即将发布的 Handsy CLI让电脑 Agent 通过蓝牙直连板子，屏幕镜像由板子接收，与当前 App 的架构一致。它与 legacy 中的 Python CLI / MCP 桥是不同的工具；legacy 的版本标签不能用来表示新 CLI 的发布。

看看最早的版本

这是项目最早的 Linux 电脑演示：AI 看着真实的 iPhone，再通过物理指针动手操作。

Handsy 早期电脑方案演示

探索 legacy

Legacy 在电脑上运行 UxPlay 和 Python 服务。手机与电脑连到同一网络，ESP32 通过 Wi-Fi 连接服务端。分支里还提供了蓝牙 HID 板子变体，以及可选的 CLI / stdio MCP 桥。

体验这套方案的顺序是：

1. 检出 legacy 分支，用其中的 hardware/flash.sh 刷写板子。
2. 在电脑上安装 UxPlay。macOS 可以用 brew install uxplay，Linux 和 Windows 的步骤见分支 README。
3. 在 server/ 安装 Python 包、配置模型地址和密钥，再运行 python -m hidagent。
4. 在手机上打开辅助触控，镜像到 iPhone Agent。在电脑上打开 http://127.0.0.1:8890，进入 Manual controls → Calibrate。

Legacy README有各平台的完整命令和硬件变体说明。CLI 桥属于这套电脑方案。

版本沿革

Legacy 已有 v0.1.0 和 v0.1.1 标签。v0.1.0 是首个正式 GitHub Release，v0.1.1 是后续标签；legacy 分支还在这两个标签之后继续更新。

当前 main 的 App 架构尚无对应的公开版本标签或正式 Release。板子固件有独立的版本号，见更新记录。