智谱Open-AutoGLM开源代码解析-编程实验室

这是关于Open-AutoGLM源代码的解析文档。从架构设计、核心类逻辑、提示词工程、动作执行层以及应用场景五个维度进行拆解。

1 整体架构设计

1.1 系统概述

基于 AutoGLM（或其他视觉语言模型，VLM）构建，旨在通过自然语言指令自动化 Android 设备的操作。

与传统的基于规则或脚本（如 Appium、UiAutomator）的自动化不同，并不依赖预先编写的控件 ID 或坐标路径。相反，它模仿人类的交互方式：

看：通过 ADB 获取屏幕截图和当前应用信息。想：利用多模态大模型分析当前界面，结合任务上下文进行规划。做：将模型输出的决策转化为具体的 ADB 指令执行。反馈：观察操作后的新界面，进入下一个循环。

1.2 核心模块划分

代码结构清晰地反映了智能体的分层架构：

大脑层 (PhoneAgent)：负责任务编排、状态管理、与模型通信以及决策循环的控制。

认知层 (prompts_zh)：定义了智能体的世界观和操作手册。通过 System Prompt 约束模型的输出格式、逻辑推理方式以及可用工具集。

执行层 (actions)：负责将抽象的语义动作（如 “Tap [x,y]”）转化为底层的 Android 机器指令。

配置与接口层 (config)：提供灵活性，允许用户自定义模型参数、设备连接方式以及安全策略（如人工接管）。

2 核心编排逻辑解析

PhoneAgent类是整个系统的指挥官。它实现了智能体的主循环（Main Loop）。

2.1 初始化与依赖注入

def__init__(self,model_config:ModelConfig|None=None,agent_config:AgentConfig|None=None,confirmation_callback:Callable[[str],bool]|None=None,takeover_callback:Callable[[str],None]|None=None,):

依赖解耦：构造函数接收配置对象而非硬编码参数，体现了良好的工程实践。

ModelConfig：定义大模型的地址、API Key、参数（Temperature等）。

AgentConfig：定义运行时的行为，如最大步数 (max_steps)、语言 (lang)、设备ID等。

安全回调：引入 confirmation_callback 和 takeover_callback 是为了解决 AI 智能体在端侧落地时的安全性和鲁棒性问题。敏感操作确认防止 AI 误操作导致支付或删除数据。人工接管当遇到验证码、指纹解锁等 AI 难以处理的场景时，平滑地切换给人类。

2.2 run方法：自动化的闭环

defrun(self,task:str)->str:self._context=[]self._step_count=0# 第一步：初始化上下文并发送首个 Promptresult=self._execute_step(task,is_first=True)ifresult.finished:return...# 循环执行，直到任务完成或达到最大步数whileself._step_count<self.agent_config.max_steps:result=self._execute_step(is_first=False)ifresult.finished:return...

这个循环本质上是一个状态机的推演过程。

智能体不断地将 (当前状态 + 历史记忆) 映射到 (下一步动作)，直到达到 Finished状态。

2.3 _execute_step阶段1：环境感知

screenshot=get_screenshot(self.agent_config.device_id)current_app=get_current_app(self.agent_config.device_id)

系统通过 ADB 截取当前屏幕流，并获取前台 App 的包名。

关键点：这里不仅依靠视觉（截图），还辅助了系统信息（App包名），这有助于模型判断当前是否在正确的应用中。

2.4 _execute_step阶段2 上下文构建

ifis_first:# 注入 System Prompt (世界观与工具集)self._context.append(MessageBuilder.create_system_message(...))# 构建包含截图和任务描述的首条用户消息self._context.append(MessageBuilder.create_user_message(text=...,image_base64=...))else:# 后续步骤仅发送当前屏幕截图self._context.append(MessageBuilder.create_user_message(text="** Screen Info **...",image_base64=...))

上下文窗口管理：多轮对话中，History 列表会越来越长。虽然代码中没有显式展示 Token 截断逻辑，但在后续代码中有一行 remove_images_from_message(self._context[-1])，这是一个极其重要的优化。

优化策略：在发送新请求前，将上一轮的用户消息中的图片移除（只保留文本描述）。为什么？因为对于决策当前步骤来说，历史截图的重要性远低于历史操作记录，而图片 Token 消耗巨大。保留所有历史图片会导致上下文迅速溢出显存或 Token 限制。

2.5 _execute_step阶段3 模型推理

response=self.model_client.request(self._context)

调用 VLM（如 AutoGLM-Phone）。模型会接收到当前的屏幕截图、任务描述以及之前的操作历史，然后输出一段包含思维链（CoT）和动作指令的文本。

模型严格输出 do(…)或finish(…)，能解析成 dict。

2.6 _execute_step阶段4 动作解析

try:action=parse_action(response.action)exceptValueError:action=finish(message=response.action)

模型输出的是字符串（例如 do(action=“Tap”, element=[500,500])），需要将其解析为结构化的 Python 字典。

如果解析失败，代码采取了防御性编程（Defensive Programming），假设任务结束或出错。

2.7 _execute_step阶段5 动作执行

result=self.action_handler.execute(action,screenshot.width,screenshot.height)

将解析后的动作交给 ActionHandler。

这里传入屏幕宽高的原因在于，模型输出的通常是归一化坐标（0-1000），需要映射回设备的物理分辨率。

2.8 _execute_step阶段6 记忆更新与反馈

self._context.append(MessageBuilder.create_assistant_message(f"<think>{response.thinking}</think><answer>{response.action}</answer>"))

将模型的思考过程和决策结果加入历史记录，形成闭环。

这使得模型在下一步时知道自己刚才做了什么，为什么这么做。

3 认知层的构建prompts_zh

System Prompt 是智能体的灵魂，它定义了模型的思维方式和操作边界。

系统提示词如图所示。

{ "role": "system", "content": "今天的日期是: 2025年12月13日 星期六\n你是一个智能体分析专家，可以根据操作历史和当前状态图执行一系列操作来完成 任务。\n你必须严格按照要求输出以下格式：\n<think>{think}</think>\n<answer>{action}</answer>\n\n其中：\n- {think} 是对你为什么选择这个操作的简短推理说明。\n- {action} 是本次执行的具体操作指令，必须严格遵循下方定义的指令格式。\n\n操作指令及其作用如下： \n- do(action=\"Launch\", app=\"xxx\") \nLaunch是启动目标app的操作，这比通过主屏幕导航更快。此操作完成后，您将自动收到结 果状态的截图。...\n\n必须遵循的规则：\n1. 在执行任何操作前，先检查当前app是否是目标app，如果不是，先执行 Launch。\n2. 如果进入到 了无关页面，先执行 Back。如果执行Back后页面没有变化，请点击页面左上角的返回键进行返回，或者右上角的X号关闭。..." }, { "role": "user", "content": [{"type": "text","text": "点击小红书查找AI帖子 \n\n{\"current_app\": \"System Home\"}"}] }

3.1 角色定义与思维链 (CoT)

SYSTEM_PROMPT=""" 你是一个智能体分析专家... 你必须严格按照要求输出以下格式： <think>{think}</think> <answer>{action}</answer> """

思维链强制：通过 `标签，强制模型在输出动作前先进行推理。这对于复杂任务至关重要。

例如，在点外卖时，模型需要先思考当前在购物车页面，但有非目标商品，然后才能生成先清空购物车的动作。如果没有这一步，模型容易直接生成点击购买，导致错误。

3.2 动作原语设计

Prompt 中定义了一套特定领域语言（DSL）：

导航类：
Launch(app="xxx")：冷启动应用。比手动在桌面上找图标更稳健。Back()/Home()：系统级导航Swipe(start, end)：处理列表滚动、页面切换。

交互类：
Tap(element=[x,y])：最基础的点击。坐标系定义为左上(0,0)到右下(999,999)，这是为了适配不同分辨率的通用做法。Type(text="xxx")：输入文本。Long Press/Double Tap：处理复杂交互（如长按复制、双击点赞）。

认知/元操作类：
Wait(duration)：处理网络加载延迟。Note/Call_API：用于信息提取任务（如总结当前页面的评论）。Take_over：主动请求人工干预。Interact：遇到歧义时询问用户。

3.3 业务规则知识库

Prompt 的后半部分包含了一组必须遵循的规则。这些规则是开发者将人类的领域知识蒸馏后注入给模型的：

鲁棒性规则：如果进入无关页面，先执行 Back、如果页面未加载，Wait 最多三次。这解决了自动化脚本最常见的卡死问题。

业务逻辑规则：小红书总结要筛选图文、外卖任务先清空购物车。这是针对特定 App 的优化，防止模型产生常识性错误。

容错规则：如果点击没生效…调整位置重试。教会模型进行自我修正。

4 执行层实现actions/handler.py

ActionHandler是连接 AI 大脑与 Android 系统的桥梁。它负责具体的指令落地。

4.1 安全的动作解析

defparse_action(response:str)->dict[str,Any]:# ...try:tree=ast.parse(response,mode='eval')# ...验证节点类型...

安全性设计：代码明确避免使用eval()来解析模型返回的字符串，而是使用 Python 的ast(Abstract Syntax Tree) 模块进行解析。

原因：如果直接使用eval()，恶意注入或模型幻觉生成的代码（如os.system('rm -rf')）可能会在宿主机器上执行。ast.parse限制了仅能解析函数调用结构，极大地提高了安全性。

4.2 坐标转换机制

def_convert_relative_to_absolute(self,element:list[int],...):x=int(element[0]/1000*screen_width)y=int(element[1]/1000*screen_height)

模型输出的是 0-1000 的相对坐标。

这种设计使得模型不需要关心具体的设备分辨率（1080p, 2k 等），提高了模型的泛化能力。Handler 负责将其映射回物理像素。

4.3 关键动作文本输入

def_handle_type(self,action:dict,width:int,height:int):# 1. 切换到 ADB 键盘original_ime=detect_and_set_adb_keyboard(self.device_id)# 2. 清空并输入clear_text(...)type_text(...)# 3. 恢复原始输入法restore_keyboard(original_ime,...)

技术难点：Android 原生输入法（搜狗等）通常不接受adb shell input text指令发送 Unicode 字符（如中文），且弹出的软键盘会遮挡屏幕，影响视觉识别。

解决方案：代码通过临时切换到ADB Keyboard（一种不可见、支持 Base64 输入的特殊输入法服务）来解决这个问题。输入完成后再切回用户原来的输入法，保证了用户体验的无感和输入的准确性。

4.4 关键动作点击与敏感操作

if"message"inaction:ifnotself.confirmation_callback(action["message"]):returnActionResult(...,should_finish=True,...)

人机协同：在执行点击前，检查动作是否包含message字段（通常在 System Prompt 中定义为涉及金钱、隐私时触发）。

如果存在，则阻塞执行，调用回调函数等待人类确认。这是 AI Agent 走向实际应用的关键安全栅栏。

4.5 关键动作滑动

处理滑动时，代码直接调用了adb.swipe。这对于浏览长列表、查找元素（如 Prompt 规则中提到的找不到联系人尝试滑动）至关重要。

5 扩展性与应用场景分析

5.1 远程调试与多设备支持

在AgentConfig和ADBConnection中，我们看到了device_id的设计。

这意味着该框架不仅支持 USB 连接的本地设备，也支持通过 TCP/IP (adb connect ip:port) 连接的远程设备（云手机、机房设备）。

应用场景：云测平台、远程真机调试、批量群控（通过实例化多个 Agent，每个绑定不同的device_id）。

5.2 异常处理与自我修正

框架内置了多层容错机制：

模型层：Prompt 里的规则（Retry, Back）。

代码层：try-except包裹模型请求和动作执行。

反馈层：如果动作执行失败，结果截图会反馈给模型，模型可以在下一轮通过视觉看到界面没变，从而推理出操作无效并尝试其他方案。

5.3 回调机制的灵活性

examples/basic_usage.py展示了如何通过回调实现高级功能：

人工接管 (Takeover)：当 AI 遇到登录验证码时，可以暂停，发消息给用户（如推送到 Slack/钉钉），用户在手机上操作完后按回车，AI 继续接管。这解决了全自动链路中最后一公里的难题。

message=action.get("message","User intervention required")self.takeover_callback(message)

这相当于告诉上层 UI：现在需要用户来操作。典型场景：

登录输入密码
短信验证码
图形验证码/滑块
人脸/指纹认证
支付确认（也可以用敏感确认做，但 takeover 更强调用户亲自操作）

6 本质是一个闭环控制系统

基于 AutoGLM 的手机端智能助理框架从工程角度看，本质是一个闭环控制系统：

感知：通过 ADB 截图拿到当前屏幕（get_screenshot()），再拿到前台 App 信息（get_current_app()）。

表征：把任务 + 屏幕信息 + 截图包装成多模态消息（MessageBuilder.create_user_message(text, image_base64)）。

决策/规划：把消息发给视觉语言模型（ModelClient.request(context)），模型输出下一步动作指令（字符串形式，如do(action="Tap", element=[...])或finish(message="...")）。

解析：把模型输出转为结构化 dict（parse_action()）。

执行：把动作 dict 交给ActionHandler.execute()，用 ADB 去真的点、滑、输入、返回、启动 App……

反馈：执行完再截图，进入下一轮，直到模型选择finish()或达到max_steps。

base64)`）。