视觉模型怎么知道点哪里?ESP32 iPhone Agent 的 0-1000 归一化坐标系与动作解析

原创2026-10-15 19:38:111,400 阅读
文章标签:人工智能AI AgentGUI 自动化MCP 服务AI 技能嵌入式物联网硬件开发移动开发原生移动CLI音视频dsh-plugin

视觉模型怎么知道点哪里?ESP32 iPhone Agent 的 0-1000 归一化坐标系与动作解析

ESP32 iPhone Agent 是一个让 AI 视觉模型直接操控真实 iPhone 的开源项目:一块 $7 的 ESP32-S3 当"手",AirPlay 投屏当"眼"。本文拆解它最巧妙的工程设计——0-1000 归一化坐标系:视觉模型为什么能"看懂"屏幕上的位置?tap 152 362 这一行文本如何变成指尖的一次点击?

ESP32 iPhone Agent 的 Web UI:Live Log 中显示 Tap、Draw a circle 等动作的 0-1000 坐标

一、为什么用 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 轮截图+推理的延迟。

设置闹钟示例:Live Log 中每个 Tap 动作都带 0-1000 坐标,Step wall 上截图标注了实际点击位置

三、从 1000 到手指:坐标如何一路换算?

解析出的 0-1000 坐标不会直接发往硬件,它要经过三层换算:

  1. 归一化 → 屏幕比例:agent.py 的 _do 方法把坐标除以 1000,得到 0-1 的屏幕比例;
  2. 屏幕比例 → 鼠标移动量:ESP32 在 iOS 里表现为一只 USB 鼠标(配合 AssistiveTouch 变成屏幕指针),phone.py 用校准时得到的 span(横穿整个屏幕宽度/高度各需多少鼠标单位)把比例换算成 move <dx> <dy> 命令;
  3. 鼠标单位 → 指尖点击:通过 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 每一步都标注了点击位置的原因:模型看得见自己点到了哪。

硬件与 Web UI 实拍:XIAO ESP32S3 插进 iPhone,右侧页面实时显示 Live Log 与动作截图

五、小结

  • 0-1000 归一化坐标系让视觉模型脱离具体分辨率,输出稳定、跨机型通用;
  • 极简的动作文法(tap/swipe/path/type/done…)让 VLM 的输出可被几行正则可靠解析;
  • 三层换算(1000 → 比例 → 鼠标单位)把"屏幕上的位置"翻译成 ESP32 的一条 Wi-Fi 命令;
  • 闭环校正(precise 校位、直线拟合学习、屏幕变化验证)弥补了相对指针的所有漂移。

想深入阅读,核心文件都在 server/hidagent/ 下:动作与解析看 agent.py,坐标换算与校准看 phone.py,镜上视觉检测看 vision.py。

登录后查看全文
esp32-iphone-agent