MCP 工具

PhysiClaw 通过 Model Context Protocol 暴露 12 个工具，而 agent 使用每个工具的方式都一样： 先拍一张照片，挑一个 bbox（一个矩形 [left, top, right, bottom]，以 0–1 的屏幕比例表示）， 然后在那里做点什么。它从不直接处理像素或电机坐标——它只指定一个矩形框和一个动作， 由 PhysiClaw 把这转换成机械臂运动。

这里的工具按 传输顺序（wire order） 分组——也就是 agent 看到它们的顺序——因为最常用的工具 （peek、tap）被有意排在最前面。每个工具的第一行是它的单一职责概述；其余部分是参数、时序， 以及 PhysiClaw 追加到每次结果末尾的”下一步该做什么”提示，用来推动循环继续。

看（See）

agent 在动作 之前 调用其中一个工具来锁定目标的 bbox，并在动作 之后再次 调用以确认屏幕已发生变化。 两者返回相同的结构：[Image, listing]——一张画出了图标框的 JPEG，外加一段纯文本清单，每个元素一行：

id [kind] "label" [left,top,right,bottom] conf

peek()

默认视图——来自 俯拍相机 的一帧画面，约 4 秒，不会改变屏幕状态。

• 参数： 无。
• 时机： 在任何 tap/swipe 之前用来找到目标；动作之后再用来验证。两次 peek 返回 完全相同 的清单， 说明屏幕没有变化。

读取结果

peek 会把检测到的框直接画到 JPEG 上，这样 agent 在操作前可以把 bbox 与清单做可视化交叉核对。

screenshot()

手机自身的 像素级精确截图，约 12 秒，会改变屏幕状态——升级备用工具。

• 参数： 无。
• 为什么会改变状态： 它会触发 iOS 的截图手势，而 app 可以观察并对其作出反应 （分享面板、“相似商品”面板、带水印的画面）。在 screenshot 之后、tap 之前务必先 peek—— 屏幕状态可能已经变了。
• 仅在 peek 无法胜任时使用：目标太小相机无法分辨、眩光或运动模糊导致画面无法读取、 或者有需要阅读的小字。

peek 速度快三倍且不留痕迹，所以它是默认选择；screenshot 是后备方案。 为什么要这样划分，详见 它如何看见。

操作（Act）

每个动作工具都接收一个 bbox，并在其 中心 处操作。机械臂把触控笔驱动到那里； 电磁铁（solenoid） 让笔尖落下，而手势的持续时长决定它被识别为 单击、双击还是长按。

tap(bbox)

在 bbox 中心单击一次——按钮、链接、列表项、关闭对话框。

• 下一步： peek 来验证并锁定下一个目标。清单完全相同意味着 tap 没点中（重试一次）， 或者 bbox 错了（从新的 peek 中挑选另一个元素）。

double_tap(bbox)

在 bbox 中心快速点两下，间隔约 150ms——用于缩放或选中一个词。

• 用于 缩放地图 / 照片 / 网页，或在可编辑文本中选中一个词。
• 对于按钮，请用 tap。

long_press(bbox)

在 bbox 中心按住约 1.2 秒——上下文菜单、编辑模式、粘贴弹窗。

• 用于 打开上下文菜单、进入图标重排的编辑模式，或在 send_to_clipboard 之后触发粘贴弹窗。
• 下一步： 始终 peek——你需要从刚出现的弹窗中（Paste / Copy 等）获取一个新的 bbox 才能点击它。

swipe(bbox, direction, size="m", speed="medium")

让触控笔沿 direction 方向滑过 bbox——用于滚动、翻页、划掉卡片，以及打开控制中心 / 通知中心。

参数	取值	说明
bbox	[l,t,r,b]，0–1 区间	手势起点
direction	up down left right	触控笔 的运动方向，不是页面的运动方向
size	s m l xl xxl	滑动行程长度，默认 m
speed	slow medium fast	触控笔速度，默认 medium

size 等级对应真实的行程长度：

size	长度	用途
s	≈ 1cm	小幅轻推
m	≈ 2cm	大多数滚动
l	≈ 4cm	长滚动
xl	≈ 6cm	整页式滚动
xxl	≈ 8cm	全屏（控制中心 / 通知中心）

方向指的是触控笔，不是页面

向 上 swipe 会让页面 向下 滚动（显示下方内容）。向 下 swipe 会让页面 向上 滚动 （打开通知中心）。向 左 swipe 切到下一张照片 / 下一页。在 iOS 滚动列表里，更快的滑动还会惯性滑得更远。

• 下一步： peek 验证页面是否已滚动并规划下一步。

导航（Navigate）

这些工具不接收 bbox——它们发出固定的 iPhone 系统手势。

home_screen()

通过从底部上滑的手势返回主屏幕——一个已知的起跳点。

• 用于 开始一个新任务，或从 app 导航中迷路时恢复。
• 下一步： peek 来规划你在主屏幕图标上的下一次 tap。

go_back()

通过 iPhone 的 左边缘 滑动手势返回上一屏。

• 在带有导航栈的 app 中有效（大多数 app 都有）。peek 后屏幕仍相同，说明要么手势没被识别（重试一次）， 要么此屏幕没有返回动作（模态框、根标签页、锁屏）——试试 home_screen 后重新进入， 或点击屏幕内的 < / 返回按钮。
• 陷阱： 全屏图片查看器（商品图、Messages / WeChat 照片）会把左右滑动占用为图片切换， 所以边缘滑动不会返回。改用查看器内的 X / Done 按钮关闭。

force_quit()

通过 app 切换器手势强制退出当前 app，约 7 秒——一次硬重置。

• 用于 go_back 无法到达正确入口点之后：弹窗无法关闭、返回栈循环往复，或者总是返回错误的页面。
• 会落到主屏幕。下一步： 从那里重新打开 app。

unlock_phone()

用密码 111111 解锁手机，约 12 秒。

它会唤醒屏幕、上滑、等待 Face ID 失败、OCR 识别键盘，然后逐位点击数字。密码 硬编码为 111111—— 这是一个一次性的工具手机密码，所以真实密码绝不会通过 git 或日志泄露。

失败后不要重试

其余每个工具都需要手机处于解锁状态，所以一次解锁失败会终结整个会话。修复方法在用户一侧： 把密码设为 111111，或者关闭自动锁定（设置 → 显示与亮度 → 自动锁定 → 永不—— 代价：屏幕磨损更快）。

• 下一步： peek 确认你在主屏幕上并规划下一次 tap。

文本（Text）

send_to_clipboard(text)

把 text 复制到手机剪贴板——粘贴比逐键敲出每个字符快得多。

标准流程：

1. send_to_clipboard(text)

2. long_press(field_bbox)——打开粘贴弹窗。

3. tap 出现的 Paste（或 粘贴）按钮。

只有在输入框拒绝粘贴时（密码输入框、某些搜索栏）才退回到屏幕键盘。

序列（Sequence）

sequence(step1, step2?, step3?, step4?, step5?)

在一次调用中运行最多 5 个动作——在确定性流程上节省回合数，这类流程中间的观察不会带来任何价值 （通过 tap → tap → tap 打开一个 app，或者粘贴 + 发送一条消息）。

每一步都是一个含两个字段的字典：

• tool_name——tap / double_tap / long_press / swipe / send_to_clipboard 之一。
• arg——该工具的参数：tap/double_tap/long_press 用 bbox，swipe 用 {bbox, direction, size?, speed?}，send_to_clipboard 用字符串。

遇到第一个失败即停止——不回滚

之前的步骤 不会 被撤销。失败后先 peek 看看停在哪里，再重试。当步骤之间 可能出现也可能不出现 对话框，或目标的 bbox 不确定时，不要把流程批量执行——先用 peek 验证。

• 下一步： peek 验证最终状态并规划下一步。