Open-AutoGLM文档解读：核心模块与API接口使用指南-开发者社区

Open-AutoGLM文档解读：核心模块与API接口使用指南

1. 框架定位与能力全景

Open-AutoGLM 是智谱开源的轻量化手机端 AI Agent 框架，它不是传统意义上的大模型推理工具，而是一个真正能“看见”“理解”“动手”的多模态智能体系统。它的核心价值在于把复杂的视觉语言理解、任务规划和设备操控能力，封装成一套可快速部署、可远程调用、可自然交互的技术栈。

你不需要写一行自动化脚本，也不需要手动解析界面元素——只要说一句“打开小红书搜美食”，系统就能自动完成：截图识别当前界面 → 理解 App 图标布局 → 定位小红书图标 → 点击启动 → 等待加载 → 找到搜索框 → 输入“美食” → 点击搜索。整个过程无需人工干预，且全程可解释、可中断、可接管。

这背后是三个关键能力的深度协同：

屏幕感知力：基于视觉语言模型（VLM）实时理解手机屏幕画面，不依赖 UI 层级结构，对截图、模糊界面、非标准控件同样有效；
意图解析力：将自然语言指令拆解为可执行的原子动作序列，比如“关注抖音号 dycwo11nt61d”会被解析为“打开抖音 → 进入搜索页 → 输入ID → 点击用户 → 点击关注按钮”；
操作执行力：通过 ADB 协议精准控制真实设备或模拟器，支持点击、滑动、输入、返回、长按等全部基础操作，并内置防误触机制。

它不是玩具项目，而是面向真实场景打磨的工程化框架：支持 WiFi 远程调试、敏感操作二次确认、验证码/登录页人工接管、多设备并行管理——这些设计让开发者能放心把它集成进测试平台、无障碍辅助工具或企业级移动自动化流程中。

2. 核心模块拆解：从感知到执行的完整链路

Open-AutoGLM 的架构清晰分层，每个模块职责明确、接口内聚。理解它们，是你定制、调试、扩展功能的基础。

2.1 视觉理解模块（Screen Perception）

这是整个系统的“眼睛”。它接收原始屏幕截图（PNG/JPEG），经预处理后送入轻量级视觉语言模型（如 Qwen-VL-mini 或自研蒸馏版 AutoGLM-Phone-Vision），输出结构化界面描述。

不依赖 AccessibilityService，规避权限限制；
支持低分辨率截图（如 720p），在手机端 CPU 上也能实时推理（<800ms）；
输出不是简单标签，而是带坐标的元素列表，例如：

{ "elements": [ {"text": "抖音", "type": "app_icon", "bbox": [120, 340, 280, 500]}, {"text": "搜索", "type": "button", "bbox": [400, 120, 700, 180]}, {"text": "dycwo11nt61d", "type": "username", "bbox": [200, 620, 500, 660]} ] }

这个模块对外暴露perceive_screen()方法，输入路径或字节流，返回 JSON 结构。你完全可以用自己的 VLM 替换它，只要输出格式兼容。

2.2 任务规划模块（Task Planner）

这是系统的“大脑”。它接收两部分输入：用户的自然语言指令 + 视觉理解模块输出的界面状态，然后生成一个可执行的动作序列（Action Plan）。

使用轻量级 LLM（如 AutoGLM-Phone-9B）进行推理，支持本地 CPU 推理（量化后约 2.3GB 内存占用）；
动作类型固定但可扩展：tap,swipe,input_text,press_back,open_app,wait_for_element；
每个动作附带坐标、文本、超时等参数，例如：

{ "plan": [ {"action": "tap", "x": 190, "y": 420, "desc": "点击抖音图标"}, {"action": "wait_for_element", "text": "搜索", "timeout": 5000}, {"action": "tap", "x": 550, "y": 150, "desc": "点击搜索框"}, {"action": "input_text", "text": "dycwo11nt61d"} ] }

规划模块不硬编码逻辑，而是通过 prompt engineering 引导模型做决策。这意味着你可以通过修改 system prompt，让它更偏向“谨慎型”（多确认）或“高效型”（跳过等待）。

2.3 设备控制模块（ADB Orchestrator）

这是系统的“手”。它把动作序列翻译成真实的 ADB 命令，在真实设备上执行。

封装了完整的 ADB 操作：adb shell input tap x y、adb shell input text 'xxx'、adb shell am start -n package/activity；
自动处理坐标映射（适配不同屏幕分辨率）；
内置重试机制与失败回滚（如点击无响应时自动截图再感知）；
支持 USB 直连与 WiFi 远程双模式，连接状态实时监控。

该模块以ADBConnection类为核心，提供connect(),tap(),swipe(),get_screenshot()等方法，是 Python API 调用最频繁的部分。

2.4 安全与人机协同模块（SafeGuard）

这是系统的“刹车”和“交接手”。它确保自动化不会越界，也保留人在环路（Human-in-the-Loop）的能力。

敏感操作拦截：当检测到input_text含密码字段、或tap坐标落在“删除账户”“清除数据”区域时，自动暂停并提示用户确认；
人工接管入口：在登录页、验证码弹窗等无法自动识别的场景，系统会暂停执行，推送当前截图到 Web 控制台，等待人工点击或输入；
远程调试通道：通过内置 HTTP 服务暴露/debug/screenshot、/debug/last_action等端点，方便开发时实时查看状态。

这个模块不是附加功能，而是贯穿全流程的设计哲学：AI 辅助人，而非替代人。

3. 快速上手：三步完成本地控制端部署

不需要服务器、不依赖云服务，你可以在自己电脑上 10 分钟跑通第一个指令。整个过程分为环境准备、代码部署、指令执行三步，全部命令可复制粘贴。

3.1 环境准备：让电脑认识你的手机

先确保你的开发环境就绪：

操作系统：Windows 10+ 或 macOS Monterey+；
Python：3.10 或更高版本（推荐用 pyenv 或 conda 管理）；
安卓设备：Android 7.0+ 真机（推荐 Pixel、小米、华为等主流机型），或 Android Studio 自带模拟器；
ADB 工具：从 Android SDK Platform-Tools 下载。

配置 ADB 环境变量（以 Windows 为例）：

解压下载包，记下路径（如D:\platform-tools）；
Win + R → 输入sysdm.cpl→ 高级 → 环境变量；
在“系统变量”中找到Path→ 编辑 → 新建 → 粘贴路径；
打开新命令行，输入adb version，看到版本号即成功。

macOS 用户在终端运行：

export PATH=$PATH:~/Downloads/platform-tools # 加入 ~/.zshrc 持久生效 echo 'export PATH=$PATH:~/Downloads/platform-tools' >> ~/.zshrc source ~/.zshrc

3.2 手机设置：打开“被控制”的大门

在手机上完成三项关键设置：

开启开发者模式：
设置 → 关于手机 → 连续点击“版本号”7 次 → 输入锁屏密码 → 提示“您现在处于开发者模式”。
开启 USB 调试：
设置 → 系统 → 开发者选项 → 向下滚动 → 勾选“USB 调试”。
安装 ADB Keyboard（关键！）：
- 下载 ADB Keyboard APK；
- 在手机上安装；
- 设置 → 语言与输入法 → 当前键盘 → 选择 “ADB Keyboard”。

⚠️ 注意：部分国产手机（如 OPPO、vivo）需额外开启“USB 调试（安全设置）”和“OEM 解锁”，具体路径在“开发者选项”底部。

3.3 运行第一条指令：从命令行开始

一切就绪后，连接手机（USB 线），打开命令行：

# 1. 克隆代码库 git clone https://github.com/zai-org/Open-AutoGLM cd Open-AutoGLM # 2. 创建虚拟环境（推荐） python -m venv venv source venv/bin/activate # macOS/Linux # venv\Scripts\activate # Windows # 3. 安装依赖 pip install -r requirements.txt pip install -e . # 4. 查看设备 ID adb devices # 输出类似：XXXXXX device

拿到设备 ID（如ZY322XXXXX）后，执行指令：

python main.py \ --device-id ZY322XXXXX \ --base-url http://localhost:8000/v1 \ --model "autoglm-phone-9b" \ "打开微信，给张三发消息：今天会议改到下午三点了"

你会看到终端逐行打印：

[PERCEIVE] 截图已获取
[PLAN] 生成动作：tap(240, 1200) → wait_for_element('微信') → ...
[EXECUTE] 执行 tap(240, 1200)
[SUCCESS] 消息已发送

整个过程全自动，你只需看着手机屏幕一步步被操控。

4. 深度集成：Python API 的实用技巧与避坑指南

当你不再满足于命令行 demo，而是想把它嵌入自己的测试平台、客服系统或无障碍工具中，Python API 就是你的核心接口。它比命令行更灵活，也更容易出错——这里总结最常遇到的 5 个实战要点。

4.1 设备连接管理：别让 adb 成为单点故障

ADBConnection类是控制中枢，但它默认不自动重连。生产环境必须加异常处理：

from phone_agent.adb import ADBConnection import time conn = ADBConnection() # 带重试的连接 for _ in range(3): success, msg = conn.connect("192.168.1.100:5555") if success: break time.sleep(2) if not success: raise RuntimeError(f"ADB 连接失败：{msg}") # 执行后主动断开，释放资源 try: conn.tap(100, 200) finally: conn.disconnect()

4.2 截图与感知：分辨率适配是关键

不同手机截图尺寸差异巨大（720×1280 到 1440×3200）。直接传原图给 VLM 可能导致坐标偏移。正确做法是：

调用conn.get_device_size()获取真实分辨率；
对截图做等比缩放（如统一缩至 720p 宽度），同时记录缩放比例；
规划模块输出的坐标 × 比例，再传给conn.tap()。

width, height = conn.get_device_size() # 返回 (1080, 2400) scale = 720 / width # 缩放因子 resized_img = cv2.resize(img, (720, int(height * scale))) # ... 送入 VLM ... x_real = x_pred / scale # 还原真实坐标 conn.tap(x_real, y_real)

4.3 动作执行：避免“点击失效”的三大原因

坐标未校准：手机开启了“指针位置”显示或“显示触摸操作”，会导致坐标偏移。关闭即可；
界面未就绪：tap()前未加wait_for_element()，点击了空白区域。建议所有关键操作前加等待；
输入法冲突：ADB Keyboard 未设为默认，导致input_text()失效。检查手机“语言与输入法”设置。

4.4 模型调用：本地 vs 远程的取舍

--base-url参数决定模型在哪跑：

http://localhost:8000/v1：本地 vLLM 服务（需 GPU，适合开发调试）；
http://192.168.1.100:8800/v1：局域网内服务器（平衡性能与成本）；
https://api.zai.org/v1：云端 API（免运维，按 token 计费，适合 PoC）。

注意：远程调用时，--model必须与服务端部署的模型名严格一致（大小写、中横线），否则返回 404。

4.5 日志与调试：善用内置 debug 端点

Open-AutoGLM 内置轻量 Web 服务（默认:8001），无需额外启动：

http://localhost:8001/debug/screenshot：获取最新截图（PNG）；
http://localhost:8001/debug/last_plan：查看最近一次生成的动作序列；
http://localhost:8001/debug/devices：列出所有已连接设备状态。

在浏览器打开这些地址，比反复adb shell screencap高效十倍。

5. 总结：不只是框架，更是移动智能体的新范式

Open-AutoGLM 的价值，远不止于“让手机听懂人话”。它首次把多模态感知、任务规划、设备控制、人机协同四个环节，用一套简洁的 Python 接口和清晰的模块边界串了起来。它不追求参数量最大，而追求在手机端 CPU、PC 端中低端显卡、甚至树莓派上都能稳定运行；它不堆砌炫技功能，却把“登录验证人工接管”“WiFi 远程调试”“敏感操作拦截”这些真实场景中的刚需，变成了开箱即用的默认行为。

对开发者而言，它意味着：