UI-TARS 做 Android 自动化测试：原理先行、最短上手与排坑
【免费下载链接】UI-TARSPioneering Automated GUI Interaction with Native Agents项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS
回归用例一多，最先失控的就是手写的元素定位。UI-TARS 是一个基于视觉语言模型的视觉智能体：它从截图直接"看懂"界面，你用自然语言下达指令，全程不需要维护元素 ID。在 Android 自动化测试这条路上，它的完整链路是：截图 → 模型思考 → 动作坐标 → 可执行脚本。
🧠 先理解原理：视觉智能体如何完成 Android 自动化测试
先建立心智模型：这条链路的输入是截图加自然语言任务描述，输出是一组可执行的动作坐标。内部大致分三层：感知层从截图读取界面元素与文字；推理层在提示模板约束下产出"Thought + Action"格式的输出；执行层把动作字符串解析出来，并按 factor 与原图宽高把坐标缩放回真实屏幕，最终生成可执行代码。整体设计见下图。
这套架构的关键是"统一动作空间"：点击、长按、打开应用都表达为结构化动作，在 Android 设备上对应 MOBILE_USE 模板里的一组指令，桌面端则使用 COMPUTER_USE 模板，互不混淆。
🚀 最短上手路径：安装、连接设备、首次验证
先装环境。ui-tars 这个 Python 包只提供解析与提示词逻辑，模型本身需要另行部署，步骤见仓库内的部署文档。
pip install ui-tars再连设备：启动 Android 模拟器或接入真机，开启 adb 调试，并记下屏幕实际宽高——后面的坐标缩放要用。
最后跑一个最小示例，验证"解析 → 生成代码"这条链路是否可用：
from ui_tars.action_parser import parse_action_to_structure_output as parse, parsing_response_to_pyautogui_code as to_code r = "Thought: Click the login button\nAction: click(start_box='(100,200)')" parsed = parse(r, factor=1000, origin_resized_height=1080, origin_resized_width=1920, model_type="qwen25vl") print(to_code(responses=parsed, image_height=1080, image_width=1920))只要打印出一段 pyautogui 脚本，链路就算打通。
📝 一个登录任务从头走到尾
以"自动登录应用"为例，拆成四步。
第一步，任务描述。把目标写成自然语言，填入 MOBILE_USE 模板的 instruction 槽位：
instruction = """ 1. 打开目标应用 2. 在用户名框输入 demo_user 3. 输入密码并点击登录 """第二步，模型输出。模型针对当前截图逐步生成 Thought 加 Action，例如Action: type(content='demo_user')，思考过程可留档便于排查。
第三步，坐标解析。调用 parse_action_to_structure_output 时，factor 固定为 1000，再传入原截图宽高；qwen25vl 系列使用绝对坐标，宽高必须与截图严格一致，否则会整体偏移。
第四步，执行。用 parsing_response_to_pyautogui_code 把动作序列转成脚本，落盘后即可重放整条用例。
上图是坐标处理的可视化示例：截图上的标记点即模型识别出的交互坐标，已缩放回原始屏幕分辨率。点击落点不准时，先对照这类可视化定位问题，再谈重试。
📱 MOBILE_USE 指令速查
| 指令 | 作用 | 典型用途 |
|---|---|---|
| open_app(app_name) | 打开目标应用 | 用例首步启动入口 |
| click(point) | 点击指定坐标 | 点按按钮、输入框 |
| long_press(point) | 长按指定位置 | 触发上下文菜单 |
| type(content) | 输入文本，末尾 \n 提交 | 填写用户名密码 |
| scroll(point, direction) | 向指定方向滚动 | 翻页浏览列表 |
| drag(start, end) | 从 A 点拖拽到 B 点 | 拖拽、滑块 |
| press_home() | 回到主屏 | 步骤之间复位环境 |
| press_back() | 系统返回键 | 取消弹窗、退回上级 |
| wait() | 等待 5 秒并重新截图 | 页面加载等待 |
| finished(content) | 结束任务并附结论 | 标记用例完成 |
模板定义在 codes/ui_tars/prompt.py，模拟器与真机上的 GUI 任务统一选 MOBILE_USE 即可。
📊 基准成绩与适用边界
官方给出的成绩是：UI-TARS 在 Android World 基准测试中得分 64.2。适用场景也比较明确——可由截图加自然语言驱动的用例、跨应用通用、不同分辨率只需在解析时更换宽高参数。
边界同样需要说清楚：流程拉长到十几步之后，累计误差与页面时序问题会拉低稳定性；对细小、堆叠或动态变化的元素，识别失败率会高于普通大按钮。遇到这类情况，建议把长用例拆成子步骤，并在关键节点加重试。
🛠️ 排障清单：常见现象与处理
- 坐标点偏——解析时传入的比例或宽高与实际屏幕不一致：传 factor=1000 与原图宽高，参照 README_coordinates.md 核对缩放过程。
- 动态页面识别失败——页面还没加载完，模型就做了决策：在关键步骤插入 wait()，失败后重试，上限 3 次。
- 某个元素始终不被识别——截图模糊或指令描述过泛：重新截图，并在指令中写明元素的位置与外观特征。
- 换设备后脚本抖动——不同分辨率导致坐标漂移：用坐标可视化核对识别点，确认偏移量后固定测试分辨率。
- 小图标或重叠元素识别不稳——模型对密集区域定位有限：拆细操作步骤，避免在高密度区域直接取点。
收尾
UI-TARS 把 Android 自动化测试的输入简化成截图加自然语言，落地的关键在坐标缩放与步骤拆分。建议先按部署文档跑通最小示例，再逐步迁移真实用例，遇到偏差时先查坐标、再查时序。
相关资源：
- 主文档：README.md
- 部署与推理：README_deploy.md
- 坐标处理说明：README_coordinates.md
- 测试消息示例：data/test_messages.json
- 核心源码：codes/ui_tars/
【免费下载链接】UI-TARSPioneering Automated GUI Interaction with Native Agents项目地址: https://gitcode.com/GitHub_Trending/ui/UI-TARS
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
