droidrun: 通过 AI MCP 控制 Android 设备的强大框架

欢迎大家来到IT世界,在知识的湖畔探索吧!

欢迎大家来到IT世界,在知识的湖畔探索吧!

droidrun 是一个功能强大的框架，它允许用户通过大型语言模型（LLM）代理来控制 Android 设备。用户可以利用自然语言命令来自动化 Android 设备的交互过程，这为自动化测试、远程协助以及日常任务执行提供了极大的便利。

项目目录结构

https://gitee.com/pplus_open_source/droidrun

droidrun/ ├── docs/ # 项目文档目录 ├── droidrun/ # 项目主要代码目录 ├── static/ # 静态文件目录，如图片、样式表等 ├── .gitignore # Git 忽略文件列表 ├── LICENSE # 项目许可证文件 ├── MANIFEST.in # 打包配置文件 ├── README.md # 项目说明文件 ├── pyproject.toml # 项目配置文件 ├── setup.py # 项目安装脚本 docs/: 包含项目的文档和相关说明。 droidrun/: 包含项目的主要代码，包括 Python 类和函数。 static/: 存放静态文件，如项目所需的图片、样式表等。 .gitignore: 指定 Git 忽略跟踪的文件和目录。 LICENSE: 项目使用的许可证信息，本项目采用 MIT 许可。 MANIFEST.in: 指定项目打包时包含的文件。 README.md: 项目说明文件，包含项目简介、安装步骤和使用说明。 pyproject.toml: 包含项目元数据和依赖关系的配置文件。 setup.py: 用于安装 Python 包的脚本。

欢迎大家来到IT世界,在知识的湖畔探索吧!

一、 核心功能

1.1 自然语言交互控制

指令解析与执行

用户通过自然语言（如“打开微信，给张三发消息说晚上一起吃饭”）发出指令，框架自动分解为点击、输入等原子操作序列。

支持复杂任务链（例如：“在 TikTok 浏览猫咪视频，点赞并评论‘I love cats’”），实现多步骤自动化。

多模型兼容性

集成 OpenAI、Anthropic、Google Gemini 等主流 LLM 接口，用户可灵活切换底层模型引擎。

1.2 双模态界面解析

视觉动态捕捉

实时屏幕截图分析，结合 OCR 识别文字内容及图标元素。

UI 结构深度提取

解析 Android 控件树（View Hierarchy），精准定位可交互元素（按钮、输入框等），标记类型与坐标边界。

可视化辅助层

叠加交互式热力图：红色标识高频操作元素，蓝色标识低频元素，辅助动作决策。

1.3 智能纠错与自适应

异常处理机制

自动检测执行中断原因（如网络波动、界面加载超时），动态调整操作路径。

元素状态追踪

持久化记录 UI 元素生命周期，应对动态页面变化（如列表滚动更新）。

1.4 扩展性与集成方案

开放接口支持

提供 Python API 开发套件，支持自定义自动化脚本（如社交媒体批量管理、应用测试）。

跨设备管理

支持多台 Android 设备并行控制，适用于集群任务调度。

1.5 技术架构关键组件

⚠️ 注意事项

• 部署限制：需 Android 开发者模式/USB 调试授权，通过 ADB 连接主机与设备。
• 网络依赖：任务执行需 LLM API 持续可用性，本地化部署尚未支持。

当前开源生态持续演进，更多功能（如凭证管理器、元素追踪）处于开发阶段。

二、技术架构

2.1 全局架构

三层核心组件

智能体层（LLM Agent）：

运行于主机，解析自然语言指令并生成设备操作序列（如点击、输入、滑动），支持OpenAI/Anthropic/Gemini等模型接入。

执行层（Portal App）：

部署于Android设备，接收操作指令并调用系统API执行具体交互动作。

连接层（ADB Bridge）：通过ADB协议实现主机与设备间的实时通信，传输指令及屏幕数据。

双向数据流

2.2 、智能体层关键技术

指令解析引擎

将自然语言（如“微信发消息给张三”）拆解为原子操作链（启动App→定位联系人→输入内容→发送）。

支持动态路径调整：当操作受阻（如弹窗干扰）时，自动触发重试或路径切换。

多模型适配器

2.3 设备执行层设计

Portal App 功能模块

指令接收器：

监听ADB Socket，解析JSON格式操作指令（{“action”: “click”, “coordinates”: [x,y]}）。

安全沙箱：

限制敏感操作权限，需用户授权访问通知栏、通讯录等隐私区域6。

状态反馈器：

实时回传操作结果（成功/失败）及设备当前界面快照。

UI自动化引擎：

同时捕获屏幕截图（视觉数据）和UI层级结构（XML布局），通过坐标映射精准定位元素。

支持动态元素追踪：记录列表滚动位置、弹窗出现频率等状态变化。

2.4 跨设备通信协议

高效数据传输

压缩算法：对截图采用WebP格式压缩（体积减少70%），UI结构数据使用Protobuf序列化。

增量更新：仅传输界面变化区域数据，降低网络负载。

错误恢复机制

心跳检测：每3秒验证ADB连接状态，断连后自动重试。

操作回滚：当指令执行超时（>5秒未响应），自动回退至上一步界面。

三、安装环境

3.1 安装依赖

欢迎大家来到IT世界,在知识的湖畔探索吧!git clone https://github.com/droidrun/droidrun.git cd droidrun conda create --name droidrun python=3.11 -y conda activate droidrun pip install -e .

3.2 安装 ADB

• Windows:

下载 Android SDK Platform Tools 平台工具并解压 ZIP 文件

• macOS:

 brew install android-platform-tools

• Linux:

欢迎大家来到IT世界,在知识的湖畔探索吧!sudo apt install adb (Ubuntu/Debian) sudo pacman -S android-tools (Arch)

3.3 安装 DroidRun Portal App

下载

https://gitee.com/link?target=https%3A%2F%2Fgithub.com%2Fdroidrun%2Fdroidrun-portal

安装

droidrun setup --path=/Users/hejh/Desktop/droidrun-portal-v0.1.0.apk

欢迎大家来到IT世界,在知识的湖畔探索吧!(droidrun) ➜ droidrun git:(main) ✗ droidrun devices Found 1 connected device(s): • emulator-5554 (droidrun) ➜ droidrun git:(main) ✗ droidrun setup --path=/Users/hejh/Desktop/droidrun-portal-v0.1.0.apk Using device: emulator-5554 Set DROIDRUN_DEVICE_SERIAL to: emulator-5554 Step 1/2: Installing APK: /Users/hejh/Desktop/droidrun-portal-v0.1.0.apk Installation successful! Step 2/2: Enabling accessibility service Accessibility service enabled successfully! Setup complete! The DroidRun Portal is now installed and ready to use. 

四、应用示例

4.1 设置 API 密钥

项目根目录创建一个 .env 文件或设置环境变量

# Choose at least one of these based on your preferred provider export OPENAI_API_KEY="your_openai_api_key_here" export ANTHROPIC_API_KEY="your_anthropic_api_key_here" export GEMINI_API_KEY="your_gemini_api_key_here"

验证设置

欢迎大家来到IT世界,在知识的湖畔探索吧!# Should list your connected device and show portal status droidrun status

4.2 使用 CLI命令行

Basic Usage

# Format: droidrun "task description" [options] droidrun "Open the settings app" 

With Provider Options

欢迎大家来到IT世界,在知识的湖畔探索吧!# Using OpenAI droidrun "Open the calculator app" --provider openai --model gpt-4o-mini # Using Anthropic droidrun "Check the battery level" --provider anthropic --model claude-3-sonnet- # Using Gemini droidrun "Install and open Instagram" --provider gemini --model gemini-2.0-flash 

⚙️ Additional Options

# Specify a particular device droidrun "Open Chrome and search for weather" --device abc123 # Set maximum number of steps droidrun "Open settings and enable dark mode" --steps 20

4.3 使用脚本

欢迎大家来到IT世界,在知识的湖畔探索吧!#!/usr/bin/env python3 import asyncio import os from droidrun.agent.react_agent import ReActAgent from droidrun.agent.llm_reasoning import LLMReasoner from dotenv import load_dotenv # Load environment variables from .env file load_dotenv() async def main(): # Create an LLM instance (choose your preferred provider) llm = LLMReasoner( llm_provider="gemini", # Can be "openai", "anthropic", or "gemini" model_name="gemini-2.0-flash", # Choose appropriate model for your provider api_key=os.environ.get("GEMINI_API_KEY"), # Get API key from environment temperature=0.2 ) # Create and run the agent agent = ReActAgent( task="Open the Settings app and check the Android version", llm=llm ) steps = await agent.run() print(f"Execution completed with {len(steps)} steps") if __name__ == "__main__": asyncio.run(main()) 

保存上面代码到 test_droidrun.py, 执行下面命令运行:

python test_droidrun.py