DroidRun项目快速入门指南：用自然语言控制Android设备

项目概述

DroidRun是一个创新的开源项目，它允许开发者通过自然语言指令来控制Android设备。该项目将大型语言模型(LLM)与Android调试桥(ADB)相结合，创造了一种全新的设备交互方式。本文将详细介绍如何快速开始使用DroidRun项目。

环境准备

在开始使用DroidRun之前，需要确保系统满足以下要求：

1. Python环境：需要Python 3.10或更高版本
2. ADB工具：Android调试桥必须正确安装并配置
3. Android设备：需要一台已启用开发者选项和USB调试的设备
4. DroidRun Portal应用：需要在目标设备上安装配套应用

安装方法

推荐安装方式（通过PyPI）

最简单的安装方式是使用pip包管理器：

pip install droidrun

从源码安装（开发人员适用）

如需使用最新开发版本，可以克隆仓库并安装：

git clone droidrun项目仓库
cd droidrun
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
pip install -e .

使用虚拟环境可以避免依赖冲突问题。

API密钥配置

DroidRun支持多种LLM提供商，以下是配置示例：

1. OpenAI：

   export OPENAI_API_KEY="your_api_key"
   

2. Google Gemini（默认提供商）：

   export GEMINI_API_KEY="your_api_key"
   

3. 本地Ollama（无需API密钥）：

   ollama pull llama2
   

建议将密钥存储在.env文件中并通过source .env加载。

设备连接与配置

ADB验证

确保ADB已正确安装：

adb version

设备连接

连接设备后验证：

droidrun devices

如需无线连接：

droidrun connect 192.168.1.100

Portal应用安装

DroidRun Portal应用提供必要的辅助功能服务：

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

此命令将自动完成APK安装、辅助服务启用和权限配置。

基本使用示例

简单命令

droidrun "打开设置应用"

指定模型和提供商

droidrun "打开计算器" --provider Gemini --model models/gemini-2.5-pro

视觉功能

droidrun "截图并描述屏幕内容" --vision --reasoning

高级功能

Python脚本集成

可以创建Python脚本实现复杂自动化：

import asyncio
from droidrun.agent.droid import DroidAgent
from droidrun.agent.utils.llm_picker import load_llm

async def main():
    llm = load_llm(provider_name="Gemini", model="models/gemini-2.5-pro")
    agent = DroidAgent(
        goal="打开设置并检查电池电量",
        llm=llm,
        vision=True,
        reasoning=True
    )
    result = await agent.run()
    print(f"结果: {result}")

asyncio.run(main())

视觉能力

启用--vision参数后，DroidRun可以：

• 自动截图
• 分析屏幕内容
• 基于视觉上下文执行操作

调试追踪

使用Arize Phoenix进行执行追踪：

pip install "arize-phoenix[llama-index]"
phoenix serve

然后在命令中添加--tracing参数即可启用追踪功能。

常见问题解决

1. ADB未找到：检查PATH环境变量是否包含ADB路径
2. 设备未检测到：确认USB调试已启用，尝试更换USB线缆
3. API密钥问题：检查环境变量设置是否正确，密钥是否有效

最佳实践建议

1. 对于复杂任务，建议使用--reasoning参数启用规划模式
2. 生产环境建议使用虚拟环境隔离依赖
3. 敏感操作建议先在模拟器上测试
4. 长期运行任务建议监控token使用量

总结

DroidRun项目为Android设备自动化提供了全新的自然语言交互方式。通过本指南，您应该已经完成了基本环境配置并能够运行简单命令。随着对项目更深入的了解，您可以探索更复杂的自动化场景和集成方案。