视觉模型怎么知道点哪里?ESP32 iPhone Agent 的 0-1000 归一化坐标系与动作解析
视觉模型怎么知道点哪里?ESP32 iPhone Agent 的 0-1000 归一化坐标系与动作解析
ESP32 iPhone Agent 是一个让 AI 视觉模型直接操控真实 iPhone 的开源项目:一块 $7 的 ESP32-S3 当"手",AirPlay 投屏当"眼"。本文拆解它最巧妙的工程设计——0-1000 归一化坐标系:视觉模型为什么能"看懂"屏幕上的位置?tap 152 362 这一行文本如何变成指尖的一次点击?
一、为什么用 0-1000,而不是真实的像素坐标?
iPhone 的分辨率各家各代不同(1170×2532、1290×2796……),而视觉模型看到的截图尺寸还会随投屏、缩放而变化。如果让模型输出真实像素坐标,换一台手机、换一个分辨率,整个方案就废了。
这个项目的答案是:让模型永远只在 0-1000 的虚拟网格上思考。
在 agent.py 的 actor 系统提示词中,规则写得非常直白:
Coordinates are integers 0-1000 relative to the screenshot (x left→right, y top→bottom). Aim at the visual center of the element you want, not its edge or its label.
- 原点 (0, 0) 在截图左上角,(1000, 1000) 在右下角
- x 从左到右,y 从上到下,都是整数
- 目标是元素视觉中心,不是边缘或标签
这样做的好处:
| 设计点 | 0-1000 归一化坐标 | 真实像素坐标 |
|---|---|---|
| 换分辨率/机型 | 自动适配 | 全部失效 |
| 模型输出稳定性 | 数字范围小,VLM 输出更准 | 大数字容易出错 |
| 服务端换算 | 统一除以 1000 | 依赖具体帧尺寸 |
二、动作语法:一行文本 = 一个动作
模型每轮只回复两种行:THINK:(用大白话解释"上一步生效了吗、这一步做什么")和 DO:(动作本身)。服务端用 parse_command 把 DO: 行解析成字典,比如:
tap 152 362 -> {"action": "tap", "x": 152, "y": 362}
swipe 500 900 500 400 -> {"action": "swipe", "x1": 500, "y1": 900, "x2": 500, "y2": 400}
完整动作清单(来自 agent.py):
| 动作 | 参数(0-1000) | 用途 |
|---|---|---|
tap X Y |
x, y | 点击;加 precise 可先校位再点 |
swipe X1 Y1 X2 Y2 |
起点终点 | 滑动,"向下滑"意味着 Y2 > Y1 |
path X1 Y1 X2 Y2 … |
2-20 个点 | 连续笔画,用于画画 |
circle X Y R |
圆心+半径 | 画圆,R 以 x 方向单位计 |
type TEXT |
文本 | 输入(仅限键盘已弹出) |
key COMBO |
键位 | enter、cmd+space 等 |
home / back / wait |
无 | 系统手势与等待 |
replan / done ANSWER / fail REASON |
文本 | 重新规划 / 成功 / 失败 |
一个细节很值得学习:模型可以一次输出最多 6 条 DO: 行(见 parse_actions)。当动作互相独立时——比如连续勾选三个日期、画多笔——一次说完,省去 5 轮截图+推理的延迟。
三、从 1000 到手指:坐标如何一路换算?
解析出的 0-1000 坐标不会直接发往硬件,它要经过三层换算:
- 归一化 → 屏幕比例:agent.py 的
_do方法把坐标除以 1000,得到 0-1 的屏幕比例; - 屏幕比例 → 鼠标移动量:ESP32 在 iOS 里表现为一只 USB 鼠标(配合 AssistiveTouch 变成屏幕指针),phone.py 用校准时得到的 span(横穿整个屏幕宽度/高度各需多少鼠标单位)把比例换算成
move <dx> <dy>命令; - 鼠标单位 → 指尖点击:通过 Wi-Fi 发给 ESP32,
click一次左键就是一次触摸。
tap 500 550 -> (0.5, 0.55) -> move <dx> <dy> + click -> 指尖点击
0-1000 屏幕比例 0-1 归一化 真实像素
校准过程见 phone.py:把指针甩到左上角这个"已知位置",再移动两个固定距离,在镜面上找到指针实际落点,两点定出比例尺和偏移量,存盘后重启仍有效。
四、闭环校正:点歪了怎么办?
光有坐标系还不够——相对移动的鼠标指针会漂移,iOS 的指针加速也不完全线性。这个项目的做法是每一步都验证:
precise精点:对小目标(勾选框、开关、密集列表行),phone.py 的_aim会先轻轻抖动指针,用 vision.py 的pointer函数在镜面上真正看到指针在哪,偏差超标就即时补一个move修正,再按下;- 学习式补偿:每次"瞄准点 → 实际落点"的观测都会记入直线拟合,之后所有移动自动套上这条修正线——用得越久点得越准;
- 动作后检查:vision.py 的
changed函数对比动作前后的帧,判断屏幕是否真的变了,并把结果写回提示词:screen changed或screen did NOT change。上一轮没生效时,agent.py 会强制模型换一种点法,而不是在同一个坐标上固执地重复。
这套"0-1000 坐标 + 镜上找指针 + 变化验证"的闭环,就是文章开头那张图里 Live Log 每一步都标注了点击位置的原因:模型看得见自己点到了哪。
五、小结
- 0-1000 归一化坐标系让视觉模型脱离具体分辨率,输出稳定、跨机型通用;
- 极简的动作文法(
tap/swipe/path/type/done…)让 VLM 的输出可被几行正则可靠解析; - 三层换算(1000 → 比例 → 鼠标单位)把"屏幕上的位置"翻译成 ESP32 的一条 Wi-Fi 命令;
- 闭环校正(precise 校位、直线拟合学习、屏幕变化验证)弥补了相对指针的所有漂移。
想深入阅读,核心文件都在 server/hidagent/ 下:动作与解析看 agent.py,坐标换算与校准看 phone.py,镜上视觉检测看 vision.py。


