为什么phone-harness不抢你的屏幕：iPhone Mirroring后台输入与SkyLight私有API揭秘

为什么phone-harness不抢你的屏幕iPhone Mirroring后台输入与SkyLight私有API揭秘【免费下载链接】phone-harnesslet your agent control your phone项目地址: https://gitcode.com/gh_mirrors/ph/phone-harnessphone-harness 是一个让 AI Agent 直接操控你 iPhone 的开源工具它把 macOS 的 iPhone Mirroring 镜像窗口当作唯一传输层用系统截图 Vision OCR 做眼睛用 SkyLight 私有 API 投递后台输入事件做双手。全程无需越狱、无需 Xcode、无需 WebDriverAgent——而本文要揭秘的重点是Agent 干活时为什么不会把镜像窗口抢到你眼前你的焦点和屏幕始终留在你手里。传统自动化为何总抢屏幕先看懂镜像窗口的真相iPhone MirroringmacOS Sequoia把手机渲染成 Mac 上的一个窗口并把鼠标键盘输入转发为触摸。但这个项目踩过不少坑总结出几条决定性的事实窗口内部是一段视频流macOS 辅助功能在里面什么都看不到AppleScript 的click at会被静默忽略只有HID 层级的 CGEvent能驱动它且窗口必须处于最前否则事件直接被系统吞掉镜像只转发原始 HID 键码并丢弃修饰键标志位——所以CmdV发进 iOS 文本框收到的只是一个光秃秃的v。于是经典后端src/phone_harness/mirror.py的做法是每次动作前把镜像窗口activate()到最前再screencapture截图、CGEventPost注入事件。副作用显而易见——整个任务期间你的屏幕被占用了。不抢屏幕的秘诀SkyLight 私有 API 事件记录真正的答案藏在src/phone_harness/background.py。macOS 窗口服务背后有一个未公开的内部框架SkyLight它接受一种合成事件记录event record可以直接投递给指定进程、指定窗口——这正是知名窗口管理工具 yabai 实现聚焦但不置顶所用的机制。phone-harness 三步走步骤做了什么关键符号1由镜像应用的 PID 换出进程句柄 ProcessSerialNumberGetProcessForPID2向窗口服务声明该进程窗口的操作来自用户_SLPSSetFrontProcessWithOptions3把带真实坐标的鼠标事件记录直投给该进程SLPSPostEventRecordTo事件记录是一个 0xf8 字节的固定布局缓冲区字段含义如下偏移内容0x04记录长度0xf80x08CGSEventType1按下2抬起6拖动0x10全局坐标屏幕点0x20窗口内局部坐标0x3c目标窗口 IDyabai 会把坐标置空来表示仅聚焦phone-harness 则写入真实坐标同一条记录就变成了一次带位置的点击——落在 iPhone Mirroring 窗口里而你最前面的应用全程纹丝不动。所有写入都限制在缓冲区之内即使某个值写错也只是无效操作不会崩掉窗口服务。键盘输入走另一条小路先用 yabai 风格的 make-key 记录坐标置空的按下抬起对让窗口成为 key window再经CGEventPostToPid把按键事件按 PID 直投进程——输入文字时焦点同样不切换。后台眼睛不激活窗口也能截图输入解决了视觉呢background.py用CGWindowListCreateImage按窗口 ID抓取镜像窗口即使窗口不活动、甚至被其他窗口遮挡也能拿到画面取不到时退回screencapture -l兜底。截图随后交给 Apple 的 Vision 框架做 OCRsrc/phone_harness/ocr.py每一段可见文字都带一个可直接点击的屏幕坐标作者称之为穷人的 DOM。Agent 的典型闭环只有一句话OCR 找到目标文字坐标 → tap 点下去 → 再截图验证 → 完成。滚动列表也有讲究滚轮事件只路由给聚焦中的窗口后台实测 0% 位移慢速触摸拖动在 iOS 列表上几乎不动于是后台后端改用快速惯性 flick模拟手指甩动实测每次可滚动约一屏的 29%。两条输入路径一个环境变量开关src/phone_harness/ios.py里有一行小开关决定走哪条路默认后台模式鼠标、滚动全程不抢焦点键盘也尽量make-key 按 PID 投递PHONE_HARNESS_BACKGROUND0经典模式每次动作前激活窗口依赖更少的私有机制兼容性更好后台模式依赖 SkyLight 私有符号跨 macOS 版本不做保证——加载失败时自动回落经典后端保证工具始终可用。快速上手clone 仓库到 --doctor 体检1️⃣ 克隆并安装需 Python 3.12 与 pyobjcgit clone https://gitcode.com/gh_mirrors/ph/phone-harness ~/.phone-harness cd ~/.phone-harness pip install pyobjc-framework-Quartz pyobjc-framework-Vision pyobjc-framework-Cocoa pip install -e . --no-deps2️⃣ 在系统设置 隐私与安全性给终端授予辅助功能点击/按键与屏幕录制看屏幕权限细节见仓库的install.md。3️⃣ 运行phone-harness --doctor它会沿权限天梯逐项检查pyobjc → 辅助功能 → 屏幕录制 → 镜像应用已装 → 正在运行 → 找到窗口 → 截图成功 → OCR 成功逻辑在src/phone_harness/admin.py第一个 FAIL 就是你要修的。边界与常见疑问手机解锁 会话暂停iPhone in Use恢复镜像是物理动作工具只提示不代点 Connect无多点触控、无相机/Face ID 流程DRM 视频渲染为黑屏一机一会话OCR 看到的是文字而非语义无文字标签的图标需要视觉模型看截图再算坐标日常用法看SKILL.mdAgent 可自由扩展的辅助函数在agent-workspace/agent_helpers.py。小结不抢屏幕的 phone-harness本质只做了两件事眼睛用按窗口 ID 截图双手用SkyLight 事件记录直投进程。私有 API 自带不稳定风险但项目用一个优雅的回退策略兜住了它——默认后台、失败回落经典路径。想让 AI Agent 安静、不打扰地操控真机 iPhone这套眼睛 双手的设计就是最值得抄的作业。【免费下载链接】phone-harnesslet your agent control your phone项目地址: https://gitcode.com/gh_mirrors/ph/phone-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考