截图与快照:让 AI 看得懂、点得准
这一页讲两件事:怎么拿到界面图像,以及怎么把「看到的」变成「点到对的」。 小程序和小游戏都支持,全程不需要 adb。
一、截图
bash
curl -s -X POST http://127.0.0.1:9400/v1/surface/screenshot \
-H 'Content-Type: application/json' \
-d '{"layer":"render","format":"jpeg","quality":70}'返回 {"ok":true, "png_b64":"<base64>", "format":"jpeg", "targetId":"..."}。
| 类型 | 实际走的通道 | 返回的 mode |
|---|---|---|
| 小程序 | CDP Page.captureScreenshot | (无,带 targetId) |
| 小游戏 | 容器进程 PixelCopy(SurfaceView) | container-pixelcopy-surfaceview |
为什么小游戏要特殊处理:小游戏是原生 canvas,没有 XWeb 渲染层, CDP 截图无处可发。容器进程用 PixelCopy 从 SurfaceFlinger 合成层取像素, 所以 canvas 内容能完整抓到。
若容器不可达 / 没有前台窗口,返回 E_NO_RENDER_TARGET / E_GRAB_FAIL, 并给出改用快照或状态探测的建议。
二、坐标约定(最重要)
截图里的像素 = 点击用的坐标,不需要任何换算。
bash
# 截图后按图里看到的坐标点
curl -s -X POST http://127.0.0.1:9400/v1/surface/action \
-H 'Content-Type: application/json' \
-d '{"action":"click_at","x":430,"y":640}'- 小程序:截图就是窗口物理尺寸(dpr=3 的机器上是 1440×2560), 与该机型
screenshot图片尺寸完全一致。 - 小游戏:截图是 canvas 原生尺寸(例如 240×426)。若要点的是窗口坐标系, 按比例放大:
clickX = shotX × 窗口宽 / 截图宽(1440 宽机器上 240 宽的图要 ×6)。
支持的动作:click_at / longpress / swipe(x,y,dx,dy)/ down / up。 小游戏的触摸由容器进程注入真实 MotionEvent (带 SOURCE_TOUCHSCREEN + toolType=FINGER + pressure=1), 所以 Cocos/原生引擎都能正确识别。
三、快照(元素树)
截图适合「看图点坐标」,快照适合「按语义找元素」:
bash
curl -s -X POST http://127.0.0.1:9400/v1/surface/snapshot \
-H 'Content-Type: application/json' \
-d '{"mode":"lite","onlyClickable":true,"text":"抢车"}'| 参数 | 作用 |
|---|---|
mode | lite(默认,只给关键属性)/ tree(完整层级)/ full(含扁平镜像) |
onlyClickable | 只要可点元素 |
text / tag | 按文字或标签过滤 |
maxDepth / maxNodes | 控制返回体积 |
include:"nodes" | 需要扁平节点表时才加(默认不给,省 token) |
拿到 uid 后直接操作元素,不必关心坐标:
bash
curl -s -X POST http://127.0.0.1:9400/v1/surface/action \
-H 'Content-Type: application/json' \
-d '{"action":"click","uid":"n12"}'rev 是快照代数:元素变化后旧 rev 会返回 E_STALE_UID,重新取快照即可。
小游戏没有元素树(原生 canvas),只能用截图 + 坐标, 或用
POST /v1/debugger/eval-global直接读游戏状态。
四、推荐的 AI 工作流
text
1. 截图 → 看到当前界面
2. 判断要点哪里(看图 or 快照)
3. 点击(坐标 or uid)
4. 再截图 / 读状态 → 确认这一步真的生效
5. 变了 → 继续;没变 → 先确认元素是否存在,再决定要不要换坐标原则:每点一次就验证一次。不要连点一串再回头看, 否则一旦某步失败,后面的坐标全部偏移。