DroidRun 使用与启动教程

DroidRun 使用与启动教程

droidrun 项目地址: https://gitcode.com/gh_mirrors/dr/droidrun

1. 项目介绍

DroidRun 是一个强大的框架，用于通过 LLM 代理控制 Android 设备。它允许用户使用自然语言命令自动化 Android 设备的交互。

特点

• 使用自然语言命令控制 Android 设备
• 支持多种 LLM 提供商（OpenAI、Anthropic、Gemini）
• 易用的 CLI
• 可扩展的 Python API 以实现自定义自动化
• 屏幕截图分析，用于对设备进行视觉理解

2. 项目快速启动

安装

方法一：从 PyPI 安装（推荐）

pip install droidrun

方法二：从源码安装

git clone https://github.com/droidrun/droidrun.git
cd droidrun
pip install -e .

准备工作

• 一个通过 USB 或 ADB over TCP/IP 连接的 Android 设备
• 安装并配置好 ADB（Android Debug Bridge）
• 在 Android 设备上安装 DroidRun Portal 应用
• 至少一个支持的 LLM 提供商的 API Key：OpenAI、Anthropic、Google Gemini

设置 ADB

安装 ADB 以便 DroidRun 与 Android 设备通信：

• Windows：下载 Android SDK Platform Tools 并解压 ZIP 文件
• macOS：brew install android-platform-tools
• Linux：sudo apt install adb（Ubuntu/Debian）或 sudo pacman -S android-tools（Arch）

将 ADB 添加到系统环境变量 PATH 中：

• Windows：将解压后的 platform-tools 文件夹路径添加到系统的 PATH 环境变量中
• macOS/Linux：将以下内容添加到 ~/.bashrc 或 ~/.zshrc 中：

export PATH=$PATH:/path/to/platform-tools

验证 ADB 安装：

adb version

在 Android 设备上启用 USB 调试：

• 进入 设置 → 关于手机，连续点击 版本号 7 次以启用开发者选项
• 进入 设置 → 系统 → 开发者选项（位置可能因设备而异），启用 USB调试

设置

第 1 步：安装 DroidRun Portal 应用

DroidRun 需要在 Android 设备上安装 DroidRun Portal 应用：

• 从 DroidRun Portal 仓库 下载 DroidRun Portal APK
• 使用 DroidRun 安装门户应用：

droidrun setup --path=/path/to/droidrun-portal.apk

或者，你可以使用 ADB 手动安装：

adb install -r /path/to/droidrun-portal.apk

第 2 步：设置 API 密钥

在当前工作目录下创建一个 .env 文件或设置环境变量：

# 选择至少一个基于你偏好的提供商
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"

从 .env 文件加载环境变量：

source .env

第 3 步：连接到 Android 设备

通过 USB 连接设备或设置无线 ADB：

# 列出已连接设备
droidrun devices

# 通过 Wi-Fi 连接到设备
droidrun connect 192.168.1.100

第 4 步：验证设置

验证设置是否正确：

# 应列出你的连接设备和显示门户状态
droidrun status

使用 CLI

DroidRun 的 CLI 设计为简单直观，有两种使用方式：

基础使用

# 格式：droidrun "任务描述" [选项]
droidrun "打开设置应用"

使用提供商选项

# 使用 OpenAI
droidrun "打开计算器应用" --provider openai --model gpt-4o-mini

# 使用 Anthropic
droidrun "检查电池电量" --provider anthropic --model claude-3-sonnet-20240229

# 使用 Gemini
droidrun "安装并打开 Instagram" --provider gemini --model gemini-2.0-flash

额外选项

# 指定特定设备
droidrun "打开 Chrome 并搜索天气" --device abc123

# 设置最大步骤数
droidrun "打开设置并启用暗模式" --steps 20

创建一个最小测试脚本

如果你想在 Python 代码中使用 DroidRun 而不是通过 CLI，可以创建一个最小测试脚本：

#!/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

# 从 .env 文件加载环境变量
load_dotenv()

async def main():
    # 创建一个 LLM 实例（选择你偏好的提供商）
    llm = LLMReasoner(
        llm_provider="gemini",
        model_name="gemini-2.0-flash",
        api_key=os.environ.get("GEMINI_API_KEY"),
        temperature=0.2
    )
    # 创建并运行代理
    agent = ReActAgent(
        task="打开设置应用并检查 Android 版本",
        llm=llm
    )
    steps = await agent.run()
    print(f"执行完成，共 {len(steps)} 步")

if __name__ == "__main__":
    asyncio.run(main())

保存此脚本为 test_droidrun.py，确保你的 .env 文件有相应的 API 密钥，并运行：

python test_droidrun.py

3. 应用案例和最佳实践

• 自动化 Android 应用程序的 UI 测试
• 为非技术用户创建引导式工作流程
• 自动化 Android 设备上的重复性任务
• 为技术不熟练用户提供远程协助
• 使用自然语言命令探索 Android UI

4. 典型生态项目

• DroidRun Portal：用于在 Android 设备上接收和执行命令的应用
• DroidRun CLI：命令行界面，用于与 DroidRun 进行交互
• DroidRun Python API：用于在 Python 代码中控制 DroidRun 的库

droidrun 项目地址: https://gitcode.com/gh_mirrors/dr/droidrun