OminousIndustries/PhoneDriver

# 手机驱动 一个基于 Python 的移动自动化智能体，利用 Qwen3-VL 视觉语言模型通过视觉分析和 ADB 命令来理解并与 Android 设备进行交互。

## 功能特性 - 🤖 **视觉驱动的自动化**：使用 Qwen3-VL 视觉理解手机屏幕 - 📱 **ADB 集成**：通过 ADB 命令控制 Android 设备 - 🎯 **自然语言任务**：用简单的英语描述你想做什么 - 🖥️ **Web UI**：内置 Gradio 界面，易于控制 - 📊 **实时反馈**：实时截图和执行日志 ## 系统要求 - Python 3.10+ - 已开启 USB 调试和开发者模式的 Android 设备 - 已安装 ADB (Android Debug Bridge) - 拥有足够显存的 GPU（在 24GB 显存 GPU 上使用 Qwen3-VL-8B 模型测试通过） - 本仓库默认使用 Dense Qwen3-VL 4B/8B 模型，表现非常出色。如需切换到 MoE 模型，请参阅下方的配置部分 ## 安装说明 ### 1. 安装 ADB **Linux/Ubuntu:** ``` sudo apt update sudo apt install adb ``` ### 2. 克隆仓库并安装 Python 依赖 ``` git clone https://github.com/OminousIndustries/PhoneDriver.git cd PhoneDriver ``` 创建虚拟环境 ``` python -m venv phonedriver source phonedriver/bin/activate ``` 安装 Python 依赖 ``` pip install git+https://github.com/huggingface/transformers # pip install transformers==4.57.0 # 目前 V4.57.0 尚未发布 # 安装其他依赖 pip install pillow gradio qwen_vl_utils requests ``` ### 3. 连接设备 1. 在 Android 设备上启用 USB 调试（设置 → 开发者选项） 2. 通过 USB 连接 3. 验证连接： ``` adb devices ``` 你应该能看到列出的设备。 ## 配置 ### 模型选择 编辑 `qwen_vl_agent.py` 以选择你的模型： ``` # 针对 4B 模型 model_name: str = "Qwen/Qwen3-VL-4B-Instruct" # 针对 8B 模型 #model_name: str = "Qwen/Qwen3-VL-8B-Instruct" ``` ### 如果你想尝试 Qwen3 MoE 模型，需要将 `qwen_vl_agent.py` 中的导入修改为以下内容： ``` #from transformers import Qwen3VLForConditionalGeneration, AutoProcessor - Comment this import out, it is for the Dense models # 取消下方导入的注释以使用 MoE 变体！！！ from transformers import Qwen3VLMoeForConditionalGeneration, AutoProcessor ``` 你还需要修改第 61 行： ``` self.model = Qwen3VLForConditionalGeneration.from_pretrained( ``` 将其修改为： ``` self.model = Qwen3VLMoeForConditionalGeneration.from_pretrained( ``` ### 屏幕分辨率 智能体可以从 Web UI 设置选项卡中自动检测你的设备分辨率，但你也可以在 `config.json` 中手动配置。 ``` { "screen_width": 1080, "screen_height": 2340, ... } ``` 要获取设备分辨率，请在设备连接到电脑的情况下，在终端中输入以下命令： ``` adb shell wm size ``` ## 使用方法 ### Web UI（推荐） 启动 Gradio 界面： ``` python ui.py ``` 访问 `http://localhost:7860` 并输入任务，例如： - "Open Chrome" - "Search for weather in New York" - "Open Settings and enable WiFi" ### 命令行 ``` python phone_agent.py "your task here" ``` 示例： ``` python phone_agent.py "Open the camera app" ``` ## 工作原理 1. **截图捕获**：通过 ADB 对手机进行截图 2. **视觉分析**：Qwen3-VL 分析屏幕以理解 UI 元素 3. **动作规划**：确定要执行的最佳动作（点击、滑动、输入等） 4. **执行**：发送 ADB 命令以执行动作 5. **循环**：持续执行直到任务完成或达到最大循环次数 ## 配置选项 `config.json` 中的关键设置： - `temperature`：模型创造性（0.0-1.0，默认值：0.1） - `max_tokens`：最大响应长度（默认值：512） - `step_delay`：动作之间的等待时间（秒）（默认值：1.5） - `max_retries`：最大重试次数（默认值：3） - `use_flash_attention`：启用 Flash Attention 2 以加快推理速度 ## 故障排除 **设备未检测到：** - 确保已启用 USB 调试 - 运行 `adb devices` 验证连接 - 尝试 `adb kill-server && adb start-server` **点击位置错误：** - 在 UI 的设置选项卡中自动检测分辨率 - 或使用 `adb shell wm size` 手动验证 **模型加载错误：** - 确保你有足够的显存 - 尝试使用 8B 模型以降低内存需求 - 检查 transformers 是否从源码安装 **内存不足：** - 使用 8B 模型代替 30B - 在配置中减少 `max_tokens` - 关闭其他占用 GPU 内存的应用程序 ## 许可证 Apache License 2.0 - 详情请参阅 LICENSE 文件 ## 致谢 - 由阿里巴巴云 [Qwen3-VL](https://github.com/QwenLM/Qwen-VL) 构建 - Web 界面使用 [Gradio](https://gradio.app/)

标签：ADB控制, Android自动化, DNS解析, Gradio界面, Python, Qwen3-VL, RPA, 人工智能代理, 屏幕理解, 开源项目, 手机驱动, 无后门, 智能助手, 移动设备管理, 自然语言控制, 视觉语言模型, 计算机视觉, 逆向工具