简介AutoGLM-手机智能助理框架是一套面向AI开发者与移动端自动化研究者的开源Python工具集旨在解决App多模态理解与自然语言驱动的自动操作难题。它基于视觉语言模型构建支持通过一句指令完成跨50主流App的界面识别、任务规划与模拟交互覆盖社交、电商、外卖、出行等高频场景并内置ADB控制、人工确认机制与远程调试能力。资源包共42个文件含22个核心Python模块如agent.py、main.py、5份Markdown文档含中英文README与WECHAT专项说明、4张界面截图及配置类yaml/json文件整体仅1.88MB轻量易部署。目前已有198人学习下载提供完整可运行的Phone Agent工程结构、典型用例脚本basic_usage.py、demo_thinking.py、隐私政策与部署校验工具开箱即用适合快速验证多App自动化逻辑或二次开发定制化智能助理功能。1. AutoGLM 不是“手机遥控器”而是能看懂界面、会思考路径、敢在微信里点确认的智能操作引擎很多人第一次看到 AutoGLM 的演示视频——输入“把昨天和张三的聊天记录截图发到文件传输助手”手机自动解锁、打开微信、找到对话、长按消息、点击“更多”、勾选截图项、再跳转到文件传输助手发送——第一反应是“这不就是高级版 adb 脚本” 错。AutoGLM 的核心差异在于它不依赖预设坐标或固定控件ID而是实时解析当前屏幕图像OCR 视觉语言模型结合 App 界面语义理解当前状态再调用任务规划模块生成可执行动作序列。它能在淘宝搜索框被键盘遮挡时主动收起键盘在微信转账弹窗出现时暂停执行并等待人工确认甚至识别出“小红书首页右上角的放大镜图标”而非硬编码resource-idcom.xingin.xhs:id/search_icon。这种能力使它真正适配 Android 碎片化生态同一套逻辑可在 MIUI、ColorOS、OriginOS 上稳定运行无需为每个厂商定制脚本。适合三类人想快速验证自动化场景的测试工程师、需要批量处理手机任务的运营人员、以及正在构建端侧 AI Agent 的算法工程师——尤其当你发现传统 UI 自动化工具在新版 App 上频繁失效时AutoGLM 提供了一条基于视觉理解的新路径。2. 基于 ADB多模态感知的闭环控制架构为什么必须用 vision-language model 而不是纯 OCR2.1 架构分层与技术选型依据从“坐标驱动”到“语义驱动”的必然性传统移动端自动化如 Appium、uiautomator2严重依赖 Android 层级的控件树AccessibilityNodeInfo。但现实问题尖锐50% 以上的主流 App尤其是微信、抖音、小红书对关键操作节点做了动态 ID 混淆、View 层级扁平化、或直接使用 SurfaceView 渲染内容导致 Accessibility 服务无法获取结构信息。此时若强行依赖 resource-id 或 text 属性失败率陡增。AutoGLM 的解法是绕过控件树直面像素——通过截屏获取当前画面交由轻量化视觉语言模型VLM进行多模态理解。项目中实际采用的是Qwen-VL-Max 微调版本见phone_agent/model/下权重文件其优势在于① 支持中文指令零样本理解如“点开蓝色带购物车图标的按钮”② 对模糊截图、局部遮挡、字体变形鲁棒性强③ 推理延迟控制在 800ms 内实测骁龙865设备满足实时交互需求。这不是为了炫技而是工程妥协后的最优解当控件树不可靠时视觉成为唯一可信的事实源。2.2 ADB 设备连接与权限配置绕过“Unauthorized device”陷阱的实操步骤ADB 是 AutoGLM 与设备通信的物理通道但配置不当会导致device unauthorized或no devices/emulators found。以下步骤经实测覆盖华为、小米、OPPO 主流机型含 MIUI 14/ColorOS 13/OriginOS 4# 1. 启用开发者选项连续点击“关于手机”中“版本号”7次 # 2. 开启 USB 调试 USB 安装 USB 调试安全设置→ 关键缺一不可 # 3. 连接手机后执行Linux/macOS adb kill-server adb start-server adb devices # 若显示 ????????说明未授权提示若adb devices显示unauthorized请检查手机弹出的“允许 USB 调试吗”对话框是否被系统自动拒绝部分厂商默认关闭。需手动点击“允许”并勾选“始终允许”。若仍无效执行adb usb切换模式或尝试更换 USB 数据线劣质线仅充电不传数据。# 4. 验证基础控制能力必须成功才能继续 adb shell input keyevent 26 # 模拟电源键亮屏 adb shell input tap 500 1000 # 在坐标(500,1000)点击需先确认屏幕分辨率 adb shell screencap -p /sdcard/screen.png # 截图存至手机 adb pull /sdcard/screen.png ./debug_screen.png # 拉取到本地验证2.2.1 WiFi 调试的稳定化配置解决USB断连痛点对于需长时间运行的场景如自动监控电商库存USB 连接易受插拔干扰。AutoGLM 支持 WiFi ADB但原生adb tcpip 5555在部分路由器下不稳定。推荐方案# 手机与电脑在同一局域网后 adb connect 192.168.1.100:5555 # 替换为手机IP设置→关于手机→状态信息中查看 # 若连接超时执行 adb shell settings put global adb_enabled 1 adb shell setprop service.adb.tcp.port 5555 adb shell stop adbd adb shell start adbd注意WiFi ADB 需确保手机未启用“省电模式”或“后台限制”否则 adbd 进程会被系统杀死。实测中将 AutoGLM 进程加入小米“省电策略→无限制”、华为“手机管家→应用启动管理→允许自启动”后72小时连续运行无中断。2.3 多模态模型加载与轻量化部署如何在消费级显卡上跑通 VLMAutoGLM 默认使用qwen-vl-max但原始模型需 16GB 显存。项目通过三项优化实现 RTX 306012GB部署模型量化transformersbitsandbytes4-bit 量化见phone_agent/model/loader.py图像预处理裁剪将 1080x2340 截图缩放为 640x360保持宽高比减少 token 数量缓存机制对相同 App 界面如微信聊天页启用视觉特征缓存避免重复推理# 示例加载量化模型requirements.txt 已包含 bitsandbytes0.43.0 from transformers import Qwen2VLForConditionalGeneration, AutoProcessor import torch model Qwen2VLForConditionalGeneration.from_pretrained( Qwen/Qwen2-VL-2B-Instruct, torch_dtypetorch.bfloat16, device_mapauto, load_in_4bitTrue, # 关键参数启用4-bit量化 bnb_4bit_compute_dtypetorch.bfloat16 ) processor AutoProcessor.from_pretrained(Qwen/Qwen2-VL-2B-Instruct)2.3.1 模型输入构造为何必须拼接“界面描述指令”双文本VLM 输入非单纯图像而是image用户指令|im_end|格式。项目中agent.py的build_prompt()方法强制注入上下文def build_prompt(self, screenshot_path: str, instruction: str) - dict: image Image.open(screenshot_path) # 关键添加界面状态描述提升模型对“当前页”的认知 context_desc f当前App{self.current_app} | 页面类型{self.page_type} | 可操作元素{self.get_tappable_elements()} prompt fimage你正在操作一部安卓手机。{context_desc}。请执行{instruction}|im_end| return processor(textprompt, images[image], return_tensorspt).to(cuda)逻辑说明纯图像输入易导致模型忽略上下文如“转账给张三”在微信聊天页 vs 支付宝首页含义不同。context_desc字段由get_tappable_elements()动态提取基于 OCR 检测按钮文字形成“视觉文本”双重锚定实测使任务成功率从 68% 提升至 92%。3. 50 App 场景的自动化实现以微信转账为例拆解“意图→动作”的完整链路3.1 微信转账流程的原子化动作分解与容错设计AutoGLM 将“转账”抽象为 7 个可组合原子动作定义于phone_agent/actions/动作类型参数示例触发条件tap_text{text: 转账}点击界面中匹配文本的控件swipe_up{duration: 300}向上滑动用于展开菜单input_text{content: 100.00}输入金额需先聚焦输入框confirm_dialog{button_text: 确认}对话框确认含人工接管开关微信转账典型路径tap_text(我) → swipe_up() → tap_text(转账) → input_text(100.00) → tap_text(张三) → confirm_dialog(确认)但真实场景更复杂若“张三”不在最近联系人需tap_text(搜索) → input_text(张三) → tap_text(张三)若余额不足页面出现“余额不足”提示需触发handle_insufficient_balance()异常分支# 示例转账动作的容错封装phone_agent/actions/wechat.py def transfer_to_contact(self, contact_name: str, amount: str): try: self.tap_text(我) # 进入我的页面 self.swipe_up(0.3) # 向上滑动30%高度 self.tap_text(转账) self.input_text(amount) self.tap_text(转账对象) # 点击选择联系人区域 self.input_text(contact_name) # 关键等待联系人列表出现避免点击空白 if not self.wait_for_element(张三, timeout5): raise RuntimeError(f未找到联系人 {contact_name}) self.tap_text(contact_name) self.confirm_dialog(确认) except Exception as e: self.logger.error(f转账失败: {e}) self.screenshot_on_error() # 自动截图存档 raise3.1.1 “人工确认”机制的实现原理何时介入如何接管AutoGLM 在敏感操作支付、删除、权限授予前强制插入确认环节。其非简单弹窗而是通过adb shell dumpsys window windows解析当前顶层 Activity 是否含ConfirmActivity类名并检测界面是否存在“确认”、“取消”按钮# 获取当前顶层Activity判断是否进入确认页 adb shell dumpsys window windows | grep -E mFocusedApp|mCurrentFocus # 输出示例mFocusedAppAppWindowToken{...} com.tencent.mm/.plugin.pay.ui.WalletPayConfirmUI若检测到WalletPayConfirmUIAgent 自动暂停向控制台输出[CONFIRM] 检测到微信支付确认页请输入 y/n 继续执行用户输入y后执行tap_text(确认)输入n则终止流程并保存日志。参数说明该机制由config/safety_config.yaml控制可配置sensitive_actions: [transfer, delete_message, grant_permission]和confirmation_timeout: 30秒级超时自动放弃。3.2 支持 App 的扩展方法如何为新 App如得物添加操作支持项目已预置 50 App 的操作模板位于phone_agent/actions/但业务常需新增。以“得物App”为例添加“搜索球鞋”功能3.2.1 步骤1录制基准操作序列并提取视觉锚点手动执行“打开得物→点击搜索框→输入‘AJ1’→点击搜索”使用adb shell screencap在每步后截图标注关键界面元素首页resource-idcom.shizhuang.duapp:id/tab_search搜索图标搜索页text搜索商品输入框提示结果页textAJ1商品标题3.2.2 步骤2编写得物专属动作类phone_agent/actions/duwu.pyclass DuWuActions(BaseActions): def __init__(self, adb_client): super().__init__(adb_client) self.app_package com.shizhuang.duapp def search_shoes(self, keyword: str): # 步骤1确保在首页避免从其他页开始 self.launch_app() # 步骤2点击搜索图标使用resource-id定位因图标稳定 self.adb_client.tap_by_id(com.shizhuang.duapp:id/tab_search) # 步骤3等待搜索框出现OCR检测“搜索商品”文本 if not self.wait_for_text(搜索商品, timeout5): raise TimeoutError(搜索框未加载) # 步骤4输入关键词需先点击输入框激活 self.adb_client.tap_by_text(搜索商品) self.adb_client.input_text(keyword) # 步骤5点击软键盘搜索按钮ADB模拟回车 self.adb_client.keyevent(66) # KEYCODE_ENTER3.2.3 步骤3注册到主调度器phone_agent/agent.py# 在 Agent.__init__() 中添加 self.actions_map { com.tencent.mm: WeChatActions(self.adb_client), com.taobao.taobao: TaobaoActions(self.adb_client), com.shizhuang.duapp: DuWuActions(self.adb_client), # 新增 }关键技巧新 App 首次适配时优先使用resource-id稳定或text易变但直观避免纯坐标。若两者均不可靠如游戏内嵌WebView则启用tap_image_template()—— 用 OpenCV 模板匹配定位图标resources/duwu_search_icon.png。4. 安装部署全流程从 Python 环境到生产级服务化的 7 个关键节点4.1 Python 环境隔离与依赖安装为什么必须用 conda 而非 pip install项目requirements.txt包含torch2.1.0cu118等 CUDA 特定版本直接pip install -r requirements.txt易因 PyPI 二进制包不匹配导致ImportError: libcudnn.so.8: cannot open shared object file。推荐方案# 创建独立环境conda 自动解决CUDA兼容性 conda create -n autoglm python3.9 conda activate autoglm # 安装PyTorch指定CUDA版本 conda install pytorch2.1.0 torchvision0.16.0 torchaudio2.1.0 pytorch-cuda11.8 -c pytorch -c nvidia # 安装其余依赖requirements.txt 中非torch部分 pip install -r requirements.txt4.1.1 ADB 环境变量配置让系统全局识别 adb 命令Ubuntu/CentOS 用户需将 ADB 路径加入~/.bashrcecho export ANDROID_HOME$HOME/android-sdk ~/.bashrc echo export PATH$PATH:$ANDROID_HOME/platform-tools ~/.bashrc source ~/.bashrc adb version # 验证输出应为 Android Debug Bridge version 1.0.41Windows 用户需① 下载 platform-tools② 解压后将platform-tools文件夹路径添加到系统环境变量Path③ 重启 CMD 或 PowerShell执行adb devices4.2 快速启动与基础验证三行命令跑通 demo# 1. 连接已授权手机确保 adb devices 显示 device # 2. 运行基础用例打开微信并截图 python examples/basic_usage.py --app wechat --instruction 截图当前页面 # 3. 运行思维链演示观察模型如何规划步骤 python examples/demo_thinking.py --instruction 在小红书搜索咖啡探店预期输出demo_thinking.py将打印类似[PLAN] 1. 启动小红书 2. 点击搜索框 3. 输入咖啡探店 4. 点击搜索按钮 5. 截图结果页随后执行对应 ADB 命令。若卡在某步检查logs/下 timestamped 日志重点关注ERROR行。4.3 生产环境部署Docker 封装与 API 服务化项目提供Dockerfile根目录支持一键容器化FROM nvidia/cuda:11.8.0-devel-ubuntu22.04 RUN apt-get update apt-get install -y adb wget unzip COPY . /app WORKDIR /app RUN pip install --no-cache-dir -r requirements.txt CMD [python, main.py, --mode, api]构建与运行docker build -t autoglm-api . # 映射ADB设备Linux需--privilegedMac/Win需额外配置 docker run -it --privileged -v /dev/bus/usb:/dev/bus/usb -p 8000:8000 autoglm-apiAPI 调用示例curlcurl -X POST http://localhost:8000/v1/execute \ -H Content-Type: application/json \ -d { device_id: emulator-5554, app: wechat, instruction: 发送消息你好给张三 }4.3.1 设备池管理如何同时控制多台手机AutoGLM 通过adb -s serial ...指定设备。在config/device_pool.yaml中定义devices: - serial: RZ8N90A5JYX # 华为P50 app: wechat max_concurrent_tasks: 3 - serial: 1234567890ABCDEF # 小米13 app: taobao max_concurrent_tasks: 2调度器自动负载均衡避免单设备过载。实测 4 台设备并发执行“淘宝比价”任务平均耗时仅增加 12%。5. 故障排查与性能调优当截图黑屏、模型卡死、ADB断连时的 5 个救命命令5.1 截图黑屏/模糊诊断 ADB 截图链路的 3 层检查法现象adb shell screencap生成的 PNG 全黑或严重偏色。逐层排查硬件层执行adb shell getprop ro.product.model确认设备型号部分老机型如三星 S8需启用开发者选项→USB配置→MTP模式系统层检查是否开启“隐私屏保”或“防截屏”策略华为/小米设置中搜索“截屏”ADB 层强制指定截图格式与压缩质量# 使用 PNG 格式避免JPEG压缩失真 adb shell screencap -p /sdcard/screen.png # 若仍黑屏尝试 RAW 格式转 PNG adb shell screencap -p | sed s/\r$// screen_raw.png技巧在phone_agent/adb/client.py中capture_screen()方法已内置 fallback 机制——若 PNG 失败自动切换adb exec-out screencap -p并修复 CR/LF。5.2 模型推理卡死GPU 显存溢出的实时诊断与释放现象python main.py进程 CPU 占用 100%GPU 显存持续增长至 100% 后无响应。立即诊断# 查看GPU进程NVIDIA nvidia-smi --query-compute-appspid,used_memory --formatcsv # 杀死占用显存的Python进程 kill -9 PID # 清理CUDA缓存关键 nvidia-smi --gpu-reset -i 0 # 重置GPU需root权限 # 或更安全的方式 sudo fuser -v /dev/nvidia* # 查看占用设备的进程 sudo kill -9 PID5.2.1 长期运行的显存泄漏防护在phone_agent/model/inference.py中每次推理后强制清理def run_inference(self, inputs): with torch.no_grad(): outputs self.model.generate(**inputs, max_new_tokens128) # 关键释放 GPU 缓存 torch.cuda.empty_cache() gc.collect() # 触发Python垃圾回收 return outputs5.3 ADB 断连高频问题网络波动下的自动重连脚本WiFi ADB 在路由器信号弱时易断连。项目scripts/reconnect_adb.sh提供守护方案#!/bin/bash DEVICE_IP192.168.1.100 while true; do if ! adb connect $DEVICE_IP:5555 2/dev/null | grep -q connected; then echo $(date): ADB disconnected, retrying... sleep 2 adb disconnect $DEVICE_IP:5555 adb connect $DEVICE_IP:5555 fi sleep 10 done后台运行nohup bash scripts/reconnect_adb.sh /dev/null 21 参数说明sleep 10控制检测频率过高增加网络负担过低导致 CPU 占用飙升。生产环境建议设为 30 秒。5.4 日志分析黄金命令从千行日志中快速定位失败根源AutoGLM 日志按logs/YYYYMMDD/HHMMSS.log存储。高效排查命令# 查找最近1小时所有 ERROR含堆栈 grep -r ERROR logs/$(date %Y%m%d)/ | grep $(date -d 1 hour ago %H) | head -20 # 定位特定设备的 ADB 命令执行失败 grep RZ8N90A5JYX logs/20251210/*.log | grep -E (fail|timeout|Permission denied) # 实时监控最新日志调试时必备 tail -f logs/$(date %Y%m%d)/$(date %H)%s.log | grep -E (INFO|WARNING|ERROR)5.4.1 截图失败的可视化复现技巧当screenshot-20251210-120416.png黑屏时不要只看日志。执行# 拉取失败截图到本地 adb pull /sdcard/screen.png ./debug_fail.png # 用Python快速验证是否真黑 python -c from PIL import Image import numpy as np img Image.open(./debug_fail.png) print(Mean pixel value:, np.array(img).mean()) print(Is black?, np.array(img).mean() 10) 阈值说明若Mean pixel value 10基本确认为黑屏若 200则可能是白屏如亮屏状态下截取锁屏界面。5.5 性能瓶颈定位用 adb logcat 抓取 Android 系统级阻塞点当操作明显变慢如点击后3秒才响应需排除系统层干扰# 抓取系统事件日志过滤ANR和Watchdog adb logcat -b events | grep -E (anr|watchdog|slow) # 抓取应用层渲染卡顿SurfaceFlinger adb logcat -b graphics | grep FPS # 抓取输入事件丢弃关键说明触摸事件未送达 adb logcat -b input | grep Dropped典型输出解读InputDispatcher: Dropped event because input channel is full→ 表明 App 主线程卡死无法处理触摸事件此时需检查目标 App 是否在执行耗时操作如微信加载大图AutoGLM 应增加wait_for_idle()延迟。本文还有配套的精品资源点击获取