【GUI-Agent】阿里通义MAI-UI 代码阅读（1）--- 总体
- 【GUI-Agent】阿里通义MAI-UI 代码阅读（1）--- 总体
- 0x00 摘要
- 0x01 特色
- 1.1 端云协同
- 1.2 应对挑战
- 1.3 核心Agent
- 1.4 整体架构图
- 1.5 评测流程图
- 0x02 MCP在MAI-UI中的作用
- 2.1 MCP与GUI操作的分工
- 2.2 实现
- 2.3 一次完整MCP往返的时序
- 2.4 MCP如何把长的UI操作压缩为少量的API调用？
- 2.4.1 问题的本质
- 2.4.2 为什么MAI-UI恰好让这种“压缩“是天然成立的？
- GUI
- GUI+MCP
- 2.4.2 一张直观对比图
- A. 纯 GUI 路径（无 MCP）
- B. GUI + MCP 路径
- 0xFF 参考
0x00 摘要
MAI-UI是阿里通义实验室发布的一项重磅研究成果：是一个旨在 重塑人机交互方式 的“基础图形用户界面（GUI）智能体”，和阶跃星辰的思路非常类似，因此我们可以互相印证。
MAI-UI的信息如下：
https://arxiv.org/pdf/2512.22047
https://github.com/Tongyi-MAI/MAI-UI
0x01 特色
MAI-UI的MCP工具使用的两大好处为：
- 将冗长的UI操作压缩为少量API调用；
- 将传统桌面工作流（如GitHub提交查询）带入手机。
1.1 端云协同
MAI-UI是原生设备-云协作系统，阶跃星辰也是端-云协同，豆包应该也是类似方式。
- 本地轻量Agent：常驻设备端，负责处理大多数任务，并扮演“轨迹监控员”的角色。
- 云端强大Agent：当本地监控员发现任务执行出现偏差（如卡住、操作错误），且当前不涉及敏感隐私数据时，会触发向云端Agent的切换。
- 关键创新：本地模型经过专门训练，不仅会执行任务，还会判断是否偏离目标，并在切换时生成一个“错误摘要”发给云端，帮助云端快速理解问题、接手完成。
1.2 应对挑战
MAI-UI也使用MCP来应对现实挑战。
ask_user动作：当指令模糊时（如“把最近的文件发给他”，缺收件人和文件），MAI-UI会主动暂停，生成一个提问动作，向用户请求澄清。mcp_call动作：MAI-UI可以调用外部工具（通过Model Context Protocol, MCP）。例如，比较两个地址的开车时间，不需要在地图App里手动输入，直接调用“高德地图API”即可；在手机上查询GitHub提交历史，也只需一个API调用。
下图为MCP的动作空间。
1.3 核心Agent
两类核心Agent如下：
| Agent | 文件 | 任务 | 输出协议 |
|---|---|---|---|
| MAIGroundingAgent | src/mai_grounding_agent.py | UI 元素定位（单步） | <grounding_think>.</grounding_think> |
| MAIUINavigationAgent | src/mai_navigation_agent.py | 多步移动端GUI导航，支持ask_user与mcp_call |
1.4 整体架构图
整体架构图如下：
关键约束如下：
- src/内为扁平导入（from base import），调用方需把 src/插入sys.path；
- requirements.txt（agent 客户端）与evaluation/grounding/requirements.txt（评测，含 vLLM/torch）两套独立；
1.5 评测流程图
0x02 MCP在MAI-UI中的作用
为什么 MAI-UI 要把 MCP 拉进来？这是为了解决 GUI Agent 的三个老大难
| 问题 | 纯 GUI 路径的痛点 | MCP 给出的解法 |
|---|---|---|
| 效率 | 查个公交路线要点 5-10 屏 | 一次 mcp_call("amap_route", ...) 直接拿结构化结果 |
| 能力天花板 | 模型识别能力 / 屏幕信息有限，长链路任务容易掉链子 | 把 "查询、计算、第三方业务" 外包给确定性 API |
| 数据敏感性 / 设备-云协同 | 端上小模型搞不定的专业任务必须走云 | MCP 调用本身就是云侧能力的入口；与 README 里 "Device-Cloud Collaboration" 同源 |
这就是 “Agent-user interaction and MCP augmentation ：enabling agent to interact with user and use MCP tools to complete the task"。
MAI-UI 并不是MCP的实现方，而是MCP的消费方一它把外部MCP 工具的能力以“额外动作“的形式注入到prompt
里，让模型在合适的时候选择直接调工具，而不是去点屏幕。
MCP是给GUIAgent加一条“绕过屏幕“的快捷通道。
2.1 MCP与GUI操作的分工
分工具体如下图，三者同级共存于同一个动作集合，由模型自主判断该用哪个。
2.2 实现
代码中实现如下：
- 实例化 Agent 时把 工具清单（JSON-Schema 风格的列表）通过mcp_tools=[...]传进来；
- Agent 用 Jinja2 把这份清单渲染进 system prompt的 ##MCP Tools区块；
- 模型在某一步输出
<tool_call>{"name":"...", arguments*:{...}}</tool_call>; - 客户端外层负责真正去调那个 MCP服务（项目本身不内嵌MCP客户端 / 不内嵌网络层）
- 拿到结果后，把字符串结果塞到下一步 obs[mcp_response*]，Agent 在_build_messages 时把它作为新的 user 消息追加。
2.3 一次完整MCP往返的时序
下图是一次完整MCP往返的完整时序。
关键三步：模型吐 tool_call ──► 外层调真实 MCP ──► 结果作为纯文本 mcp_response 回灌下一步
predict。Agent 本身不执行网络调用，只负责传话。
要点：
- 模型对 GUI 动作和 MCP 调用使用同一种输出语法（都是<tool_call>{name,arguments}</tool_call>），客户端通过 name 是否在 mcp_tools 里来分流；
- 工具调用的真正执行完全在仓库之外，让你想接什么 MCP 服务（高德地图、12306、淘宝、企业内网工具）都行，只要能给出 JSON-Schema 描述并自己接通网络。
2.4 MCP如何把长的UI操作压缩为少量的API调用？
2.4.1 问题的本质
问题的本质：GUI路径 VS API路径的“步数 × 单步成本“差距
GUI路径里，每一步都包含一次完整的多模态推理：
单步GUI 成本 = encode（截图）= 几千vision token+ encode（history_n张历史截图）+ 模型decode（<thinking>+<tool_call>）+ 客户端反归一化坐标 + 真机点击 + 等待UI渲染 + 重新截图
而MCP调用一次的成本如下：
单次MCP成本 = encode（MCP返回JSON字符串）几十~几百token+ 模型decode下一个动作+ 客户端走HTTP拿结构化结果（确定性、毫秒级）
量纲上压缩比通常是10× -100× —因为一张手机截图的视觉token数 ~= 几千；而一段JSON文本 = 几百。
2.4.2 为什么MAI-UI恰好让这种“压缩“是天然成立的？
MCP之所以能把长UI操作压缩成少量API调用，核心是用“低成本、确定性、结构化“的文本通道替换“高成本、概率性、像素级“的视觉通道 ----- 而MAI-UI刚好通过统一tool_call语法 + 文本回灌mcp_response + 工具schema一次性渲染这三件事，从而让这种压缩在工程上自然成立、不需要额外特化的代码路径。
GUI
比如，mai_naivigation_agent.py的_build_messages()：每一步都把最近history_n张截图重新base64后塞回messages。
纯GUI路径下messages体积膨胀
step 0: [sys, img0] ──► ~3k tok
step 1: [sys, img0, assto, img1] ──► ~7k tok
step 2: [sys, img0, asst0, img1, asst1, img2] ──► ~10k tok
step 3: [sys, img1, asst1, img2, asst2, img3]（滑窗） ──► ~10k tok
对应公式：纯GUI完成任务N_ui × C_vision，N_ui 大、C_vision 也大，乘积爆炸。
GUI+MCP
而把同一段流程换成“GUI+MCP"以后，具体如下：
GUI+MCP路径下messages体积
step 0: [sys+MCP_tools_decl,img0]
step 1: ◄── tool_call:amap_route(...) ← 模型一次决定走MCP
step 2: [..., user(text=mcp_response_json)] ← 外层把JSON灌回◄── tool_call:open("Notes")
step 3: [...,img_after_open_notes] ← 才需要再来一张截图
step 4: ◄── tool_call：type（"行程已规划"）
要点：
- _build_messages里如果某TrajStep没有携带新screenshot而携带mcp_response，只追加一段纯文本user 消息，不会追加图片，这一步视觉token增量=0，只多几十~几百文本token。
- mcp_tools列表只在system prompt里渲染一次，由Jinja2的[%if tools%} 控制；不会每步重发。
- 模型用同一种<tool_call>语法统一表达GUI动作与MCP调用，所以decode 长度量级一致一压缩完全靠“省掉了一连串需要看屏幕的中间步”。
2.4.2 一张直观对比图
任务：“帮我规划：现在去招商银行取钱，再去城西银泰城；公交地铁；总时长 < 2h；把计划写进笔记App。
A. 纯 GUI 路径（无 MCP）
step 1 打开高德 screenshot ●
step 2 点搜索框 screenshot ●
step 3 键入"招商银行" screenshot ●
step 4 选最近一家 screenshot ●
step 5 点"路线" screenshot ●
step 6 切到"公交" screenshot ●
step 7 设起点 screenshot ●
step 8 读屏判断时长 screenshot ●
step 9 返回，再搜下一段 screenshot ●
step 10 ...重复5-8.. screenshot ●●●●
step 14退出高德 screenshot ●
step 15打开笔记 screenshot ●
step 16 新建 screenshot ●
step 17 输入标题 screenshot ●
step 18输入内容 screenshot ●
step 19保存 screenshot ●__________________~19步 x ~10k vision tok = ~190k tok ~19次模型RTT+真机渲染等待19次
B. GUI + MCP 路径
step 1 mcp_call("amap_route",{"from":"阿里云谷","to":"招商银行","constraints":{"radius_km":4,"mode":"transit"}})text-only ○step 2 mcp_call("amap_route",{"from":"招商银行","to":"城西银泰城","mode":"transit"})text-only ○step 3 open("Notes") screenshot ●
step 4 click(新建) screenshot ●
step 5 type(标题) screenshot ●
step 6 type(正文-把两段路线 JSON 拼起来) screenshot ●
step 7 click(保存) screenshot ●__________________7 步；仅 5 张截图≈ 5 × 10k + 2 × 0.5k = ~51k tok+ 2 次 HTTP RTT+ 真机渲染等待 5 次节省：步数 19→7 (-63%)，视觉 token 190k→50k (-73%)，决策延迟同比下降。
0xFF 参考
从豆包手机谈起：端侧智能的愿景与路线图
阿里发布MAI-UI，一个“活”在屏幕里的全能AI助手！手机真能全自动了？