信息卡

一句话定位

通过一台 Mac 作为"全程传输层"，让 Claude Code、Codex 等 AI 代理操控你的真机 iPhone 或 Android——无需越狱、无需 Xcode、无需 WebDriverAgent、无需在手机上装 App。

走红原因分析

"给代理一双手"是当下 harness 类项目的热门方向，而它把方案做到了极简：iPhone 复用 macOS 的 iPhone Mirroring 窗口，Android 只走 adb，感知与操作完全本机完成。README 直白地自称"穷人版 DOM"，加上一段可直接粘进 Claude Code 的自然语言安装提示词，让代理自己完成安装与技能注册，这种"agent-friendly"体验极具传播性。

核心功能拆解

• iPhone 感知：`screencapture` 截屏 + Apple Vision 框架 OCR，返回每个可见文本及其可点击坐标。
• iPhone 操作：HID 级 CGEvent 实现点按、长按、拖拽/快滑、滚动、Unicode 输入，另有 Cmd+1/2/3 快捷键直达主屏/多任务/Spotlight。
• Android：`screencap` 截屏、无障碍树（uiautomator）拿精确文本与控件框、`input tap/swipe/text` 执行动作，坐标即设备像素。
• 平台自动识别：自动发现已连接设备，并拒绝驱动处于锁屏状态的 Android。
• 代理自扩展：执行中缺失的函数由代理现场写入 `agent-workspace/agent_helpers.py` 并自动加载。

架构与技术栈浅析

核心在 `src/phone_harness/`：`transport.py` 是唯一接缝（操作词汇表 + `connect("ios"|"android")`），`helpers.py` 提供平台无关原语；iOS 侧由 `ios.py/mirror.py/ocr.py` 处理窗口发现、聚焦、截屏与 Vision OCR；Android 侧 `android.py` 封装 adb 与配对。两侧每次调用均无状态、无常驻守护进程。

安装与环境要求

要求 macOS Sequoia+（iPhone Mirroring 所需）、终端的辅助功能与屏幕录制权限；Android 需开发者模式 + USB 或无线调试。安装方式是把这段提示词交给你的编码代理执行：

Set up phone-harness for me. Clone https://github.com/ShawnPana/phone-harness into ~/.phone-harness ... register it as an agent skill named phone-harness using `phone-harness skill` as the body ...

随后 onboarding 引导配对，`phone-harness --doctor` 验证环境。

快速上手示例

./phone-harness <<'PY'
open_app("Notes")
tap_text("New Note")
type_text("hello from the harness")
print([o["text"] for o in ocr()][:10])
PY

进阶使用要点

• 坐标陷阱：`tap(x, y)` 用 Mac 全局屏幕点，截图坐标是图像像素，需用 `tap_image_point()` 或 `image_point()` 转换。
• iPhone 局限：AppleScript 点击被静默忽略、Unicode 键载荷失效、慢速拖拽几乎不动列表，建议用滚轮或快速 flick。
• Android 局限：无障碍树解析要数秒、输入仅限 ASCII、不支持组合键。
• 双平台都不支持多点触控/捏合、相机与 Face ID 流程，DRM 视频渲染为黑屏。
• 新机器可能在中途弹出额外 macOS 授权弹窗导致点击静默失败，留意重授权。

典型应用场景

• 让代理代替你完成 App 内重复性手工操作（填表、签到、消息回复）；
• 移动端 UI 回归测试：OCR 定位 + 截图比对；
• 手机端数据采集与批量操作脚本化；
• 无障碍演示与远程协助的场景复现。

同类生态位对比

相比 Appium、WebDriverAgent 一类重型移动自动化框架，phone-harness 不需要任何手机侧注入，代价是没有元素等待机制与多平台 CI 能力；相比纯 adb 方案，它把 iPhone 这条"无越狱"路径补齐了。两者同源互补：iOS 走镜像窗口，Android 走原生 adb。

资源导航

• README / install.md / SKILL.md / onboarding.md
• 状态目录：`~/.config/phone-harness` 与 `~/.local/state/phone-harness`
• 可通过 GitHub Sponsors 支持作者 ShawnPana