需要用自然语言驱动 AI 手机代理自动操作…

通过 AutoGLM 视觉语言模型感知手机屏幕，借助 ADB/HDC/WebDriverAgent 执行多步自然语言任务

适用场景

解决思路

1. 满足前置条件：Python 3.10+；安装 ADB 并加入 PATH（Android）或 HDC（HarmonyOS）或 WebDriverAgent（iOS）；Android 设备开启开发者模式与 USB 调试；在 Android 设备安装 ADB Keyboard APK 以支持文本输入。
2. 安装框架：执行 `git clone https://github.com/zai-org/Open-AutoGLM.git`，进入 `cd Open-AutoGLM`，运行 `pip install -r requirements.txt`，再运行 `pip install -e .`。
3. 验证 ADB 连接：Android 执行 `adb devices`，期望看到 `emulator-5554 device`；HarmonyOS NEXT 执行 `hdc list targets`，期望看到类似 `7001005458323933328a01bce01c2500`。
4. 模型部署选项 A（第三方 API，推荐快速开始）— BigModel：设置 `export BIGMODEL_API_KEY="your-bigmodel-api-key"`，然后运行 `python main.py --base-url https://open.bigmodel.cn/api/paas/v4 --model "autoglm-phone" --apikey $BIGMODEL_API_KEY "打开美团搜索附近的火锅店"`。
5. 模型部署选项 A（第三方 API）— ModelScope：设置 `export MODELSCOPE_API_KEY="your-modelscope-api-key"`，然后运行 `python main.py --base-url https://api-inference.modelscope.cn/v1 --model "ZhipuAI/AutoGLM-Phone-9B" --apikey $MODELSCOPE_API_KEY "open Meituan and find nearby hotpot"`。
6. 模型部署选项 B（自托管 vLLM）：安装 vLLM（`pip install vllm`）或使用官方 Docker `docker pull vllm/vllm-openai:v0.12.0`；启动服务：`python3 -m vllm.entrypoints.openai.api_server --served-model-name autoglm-phone-9b --allowed-local-media-path / --mm-encoder-tp-mode data --mm_processor_cache_type shm --mm_processor_kwargs '{"max_pixels":5000000}' --max-model-len 25480 --chat-template-content-format string --limit-mm-per-prompt '{"image":10}' --model zai-org/AutoGLM-Phone-9B --port 8000`。
7. 模型部署选项 C（自托管 SGLang）：安装 SGLang 或使用 `docker pull lmsysorg/sglang:v0.5.6.post1`；容器内执行 `pip install nvidia-cudnn-cu12==9.16.0.29`；启动服务：`python3 -m sglang.launch_server --model-path zai-org/AutoGLM-Phone-9B --served-model-name autoglm-phone-9b --context-length 25480 --mm-enable-dp-encoder --mm-process-config '{"image":{"max_pixels":5000000}}' --port 8000`。
8. 验证模型部署：运行 `python scripts/check_deployment_cn.py --base-url http://localhost:8000/v1 --model autoglm-phone-9b`；期望输出包含 `<think>...</think>` 和 `<answer>do(action="Launch", app="...")`；如果思维链很短或乱码，说明模型部署失败。
9. 运行 Agent 基本 CLI（Android 默认）：`python main.py --base-url http://localhost:8000/v1 --model autoglm-phone-9b "打开小红书搜索美食"`。
10. 运行 Agent CLI（HarmonyOS）：`python main.py --base-url http://localhost:8000/v1 --model autoglm-phone-9b --device-type hdc "打开设置查看WiFi"`。
11. 运行 Agent CLI（多语言模型处理英文应用）：`python main.py --base-url http://localhost:8000/v1 --model autoglm-phone-9b-multilingual "Open Instagram and search for travel photos"`。
12. 使用关键 CLI 参数：`--base-url` 指定模型服务端点（必填）；`--model` 指定服务器上的模型名（必填）；`--apikey` 用于第三方服务的 API key（默认 None）；`--device-type` 可选 `adb`（Android）或 `hdc`（HarmonyOS），默认 `adb`；`--device-id` 指定设备序列号，默认自动检测。
13. Python API 基本调用：`from phone_agent import PhoneAgent`，`from phone_agent.config import AgentConfig`；创建 `config = AgentConfig(base_url="http://localhost:8000/v1", model="autoglm-phone-9b", device_type="adb")`；创建 `agent = PhoneAgent(config)`；运行 `result = agent.run("打开淘宝搜索蓝牙耳机")`；打印 `print(result)`。
14. Python API 自定义任务与设备选择：从环境变量读取 `MODEL_BASE_URL`、`MODEL_NAME`、`MODEL_API_KEY`；在 `AgentConfig` 中设置 `device_id="emulator-5554"`；对购买等敏感操作运行 `result = agent.run("在京东购买最便宜的蓝牙耳机", confirm_sensitive=True)`，在购买动作前提示用户。
15. 直接模型 API 调用（用于测试/集成）：使用 `import openai`、`import base64`、`import os`、`from pathlib import Path`；创建 `client = openai.OpenAI(base_url=os.environ["MODEL_BASE_URL"], api_key=os.environ.get("MODEL_API_KEY", "dummy"))`；读取 `screenshot.png` 并 base64 编码；调用 `client.chat.completions.create(model="autoglm-phone-9b", messages=[{"role": "user", "content": [{"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image_b64}"}}, {"type": "text", "text": "Task: 搜索附近的咖啡店\nCurrent step: Navigate to search"}]}])`；打印 `response.choices[0].message.content`。
16. 解析模型动作输出：定义 `parse_action(model_output: str) -> dict`；用 `re.search` 提取 `<answer>` 块；用 `re.search` 提取 `do(action="...")`；用 `re.finditer` 解析参数；返回 `{"action": action_name, **params}`。
17. ADB 设备控制模式 — 截图：定义 `take_screenshot(device_id: str = None) -> bytes`，使用 `adb` 和可选 `-s device_id`，执行 `exec-out screencap -p`，返回 `result.stdout`。
18. ADB 设备控制模式 — 点击：定义 `send_tap(x: int, y: int, device_id: str = None)`，使用 `adb shell input tap str(x) str(y)`。
19. ADB 设备控制模式 — 发送文本：定义 `send_text_adb_keyboard(text: str, device_id: str = None)`；先启用 ADB Keyboard：`adb shell ime set com.android.adbkeyboard/.AdbIME`；再发送文本：`adb shell am broadcast -a ADB_INPUT_TEXT --es msg text`。
20. ADB 设备控制模式 — 滑动：定义 `swipe(x1, y1, x2, y2, duration_ms=300, device_id=None)`，执行 `adb shell input swipe x1 y1 x2 y2 duration_ms`。
21. ADB 设备控制模式 — 返回键：定义 `press_back(device_id=None)`，执行 `adb shell input keyevent KEYCODE_BACK`。
22. ADB 设备控制模式 — 启动应用：定义 `launch_app(package_name, device_id=None)`，执行 `adb shell monkey -p package_name -c android.intent.category.LAUNCHER 1`。
23. Midscene.js 集成（JavaScript/TypeScript）：配置 `.env`：`MIDSCENE_MODEL_NAME=autoglm-phone`、`MIDSCENE_OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4`、`MIDSCENE_OPENAI_API_KEY=your-api-key`；导入 `{ AndroidAgent } from "@midscene/android"`；创建 `const agent = new AndroidAgent()`；执行 `await agent.aiAction("打开微信发送消息给张三")`；执行 `await agent.aiQuery("当前页面显示的消息内容是什么？")`。
24. 远程 ADB（WiFi 调试）：先用 USB 连接设备，执行 `adb tcpip 5555`；用 `adb shell ip addr show wlan0` 获取设备 IP；执行 `adb connect 192.168.1.100:5555`；执行 `adb devices` 验证出现 `192.168.1.100:5555 device`；之后可运行 `python main.py --base-url http://model-server:8000/v1 --model autoglm-phone-9b --device-id "192.168.1.100:5555" "打开支付宝查看余额"`。
25. 使用 AutoGLM 模型输出的结构化动作：`Launch` 打开应用，如 `do(action="Launch", app="微信")`；`Tap` 点击屏幕元素，如 `do(action="Tap", element="搜索框")`；`Type` 输入文本，如 `do(action="Type", text="火锅")`；`Swipe` 滚动/滑动，如 `do(action="Swipe", direction="up")`；`Back` 按返回键，如 `do(action="Back")`；`Home` 回主屏，如 `do(action="Home")`；`Finish` 任务完成，如 `do(action="Finish", result="已完成搜索")`。
26. 按场景选择模型：中文应用（微信、淘宝、美团）使用 `AutoGLM-Phone-9B`；国际应用或混合内容使用 `AutoGLM-Phone-9B-Multilingual`。HuggingFace 模型路径为 `zai-org/AutoGLM-Phone-9B` / `zai-org/AutoGLM-Phone-9B-Multilingual`；ModelScope 模型路径为 `ZhipuAI/AutoGLM-Phone-9B` / `ZhipuAI/AutoGLM-Phone-9B-Multilingual`。
27. 设置环境变量参考：模型服务 `export MODEL_BASE_URL="http://localhost:8000/v1"`、`export MODEL_NAME="autoglm-phone-9b"`、`export MODEL_API_KEY=""`（BigModel/ModelScope API 必填）；BigModel `export BIGMODEL_API_KEY=""`、`export BIGMODEL_BASE_URL="https://open.bigmodel.cn/api/paas/v4"`；ModelScope `export MODELSCOPE_API_KEY=""`、`export MODELSCOPE_BASE_URL="https://api-inference.modelscope.cn/v1"`；设备配置 `export ADB_DEVICE_ID=""`（留空自动检测）、`export HDC_DEVICE_ID=""`。
28. 故障排除 — 模型输出乱码或思维链很短：确保 vLLM 设置 `--chat-template-content-format string`，SGLang 设置 `--mm-process-config` 且 `max_pixels:5000000`，并检查 transformers 版本兼容性。
29. 故障排除 — `adb devices` 无设备：检查 USB 线支持数据传输（非仅充电）；在手机上接受“允许 USB 调试”对话框；尝试 `adb kill-server && adb start-server`；部分设备开启开发者选项后需重启。
30. 故障排除 — Android 文本输入不工作：ADB Keyboard 必须安装并启用，执行 `adb shell ime enable com.android.adbkeyboard/.AdbIME` 和 `adb shell ime set com.android.adbkeyboard/.AdbIME`。
31. 故障排除 — Agent 陷入循环：通常是模型找不到完成任务路径；对购买/删除任务确保 `confirm_sensitive=True`；登录/验证码页面支持人工接管。
32. 故障排除 — vLLM CUDA out of memory：AutoGLM-Phone-9B 约需 20GB VRAM；使用 `--tensor-parallel-size 2` 多 GPU，或改用 API 服务。
33. 故障排除 — 连接模型服务器被拒绝：检查防火墙规则；对远程服务器执行 `curl http://YOUR_SERVER_IP:8000/v1/models`，应返回模型列表 JSON。
34. 故障排除 — HDC 设备未识别（HarmonyOS）：需要 HarmonyOS NEXT（非早期版本）；在“设置 → 关于 → 版本号”快速点击 10 次开启开发者模式。
35. iOS 设置：按 `docs/ios_setup/ios_setup.md` 配置 WebDriverAgent 后，运行 `python main.py --base-url http://localhost:8000/v1 --model autoglm-phone-9b-multilingual --device-type ios "Open Maps and navigate to Central Park"`。

适用边界 · 注意事项

• 设备未开启开发者模式/USB 调试，或未安装并配置 ADB/HDC/WebDriverAgent 时，无法控制手机。
• 没有可用的模型服务（第三方 API key 或本地约 20GB VRAM 的自托管环境）时，无法运行 AutoGLM 视觉语言模型。
• 需要完全无人值守执行购买、删除等敏感操作时，应有人工确认或接管，否则风险较高。