用智能体驱动

智能体和 XPhoneUse 桌面端之间只有一条通道：http://127.0.0.1:7070/mcp，外加一份教它怎么用的 Skill。这一页是动词表和几条约定。

坐标是归一化的

所有坐标都是 0~1 的比例，(0,0) 是左上角，(1,1) 是右下角。不用管设备是 1080p 还是 2K，也不用管镜像被缩放成多大——同一条命令在 Android 和 iPhone 上意思完全一样。

python scripts/xphoneuse-cli.py tap 0.5 0.92      # 屏幕底部中间
python scripts/xphoneuse-cli.py longtap 0.5 0.3 1200   # 长按 1.2 秒

动词表

命令	说明
`tap <x> <y>`	默认的点击方式
`longtap <x> <y> [ms]`	长按，默认 800ms，范围 100–10000
`swipe <fx> <fy> <tx> <ty>`	滑动
`scroll <x> <y> <dx> <dy>`	滚动，dy 为负表示向下滚
`text <TEXT> [--enter]`	输入文本，完整 Unicode；`--enter` 输入后回车（聊天软件里等于直接发送）
`unicode-text <TEXT> [--method clipboard\|agentinput]`	iOS 非英文文本指定投递方式：剪贴板粘贴（默认，无需装东西但会弹「允许粘贴」）或 AgentInput 输入法（不弹框、不动剪贴板，需手机已装并切到该键盘）
`press home\|back\|recents\|power\|volume_up\|volume_down`	按键；iOS 没有 `back`
`screenshot [--compare ref.png]`	截图；带 `--compare` 时只返回像素差异结论与变化区域
`ui-tree` / `find --text ...`	Android：读控件树、按文字找控件（返回可直接用的坐标）
`launch <PACKAGE>` / `open-url <URL>`	Android：启动应用 / 打开链接
`macro record\|play`	录一次流程，之后反复回放（Android 与 iOS 都支持）
`wifi enable\|connect\|ip`	Android：无线调试

screenshot、list、shell 和 wifi * 不需要会话；输入类命令要先 connect。

三条经验

先看再做。 动作之前要知道屏幕上是什么，动作之后要知道变了什么。没验证的操作在真机上就是抛硬币。

能读文字就别看图。 Android 上 ui-tree 和 find 返回整屏文字与坐标，成本约为看图的三十分之一。只有在游戏、地图、相册这类画布界面上才值得花截图。

一次一个动作。 点一下、看一眼、再点。连点五次再截图，是走错会话的经典方式。

截图对比

智能体最贵的感官是眼睛。--compare 让它在本地做像素对比，只在画面真的变了时才需要看图：

python scripts/xphoneuse-cli.py screenshot --compare xphoneuse-screenshot.png
# VERDICT: CHANGED (86.95% of pixels differ, threshold 0.50%)
# changed region: x 0-1178, y 0-2555 (normalized 0.000-1.000, 0.000-1.001)

UNCHANGED 就跳过，CHANGED 再看图，而“变化区域”这一行往往已经说明了问题：底部三分之一变了＝键盘弹出来了，中间一小块＝弹了个对话框。

MCP 客户端

{
  "mcpServers": {
    "xphoneuse": { "url": "http://127.0.0.1:7070/mcp" }
  }
}

MCP 工具与命令行共享同一个会话：命令行连上的设备，MCP 这边直接就能用。

最后更新 2026-09-17