DroidRun：开源LLM原生移动自动化框架，自然语言掌控跨平台设备交互

一、DroidRun是什么

DroidRun是一款开源的移动设备自动化框架，核心定位是通过LLM（大语言模型）智能体实现对Android和iOS设备的自然语言控制，让非技术用户与专业开发者都能轻松完成移动设备的自动化操作。该项目支持多LLM提供商兼容、跨平台设备控制、复杂任务规划、视觉界面理解等核心功能，提供易用的CLI工具与可扩展的Python API，适用于自动化测试、重复任务处理、远程协助等多种场景。

从项目定位来看，DroidRun并非简单的“脚本执行工具”，而是具备“理解-规划-执行-反馈”闭环能力的智能体框架。它通过LLM的自然语言理解能力解析用户需求，结合设备界面的视觉分析与任务规划逻辑，自动生成操作步骤并执行，全程无需用户编写复杂代码。项目核心目标是“降低移动自动化门槛”与“提升复杂任务处理能力”，无论是非技术用户想要通过语音或文字指令完成手机操作，还是开发者需要快速构建自动化测试流程，DroidRun都能提供适配的解决方案。

从项目背景来看，DroidRun由开源社区共同维护，代码仓库首次提交可追溯至2025年4月（根据LICENSE文件提交日期），截至2025年11月已更新至0.4.7版本，经历了多次功能迭代与优化。项目采用Python作为核心开发语言，具备良好的跨平台兼容性与扩展性，支持主流LLM提供商与移动设备类型，其设计理念是“LLM无关性”（LLM agnostic），即用户可根据自身需求选择不同的大语言模型，无需修改核心操作逻辑。

简单来说，DroidRun就像是为移动设备配备了一位“智能助手”——你只需用日常语言告诉它要做什么（如“帮我在学习APP上完成今日打卡”“测试这款应用的注册流程是否正常”），它就能自主分析需求、规划步骤、操作设备，最终完成任务并反馈结果。

二、功能特色

DroidRun的核心优势在于“自然语言驱动”与“全流程自动化”，其功能特色覆盖了从需求解析到任务执行的全链路，以下是详细介绍：

2.1 核心功能总览

为了让读者快速了解DroidRun的功能矩阵，以下是核心功能与详细说明的汇总表格：

2.2 重点功能详细解析

2.2.1 自然语言交互，零代码门槛

这是DroidRun最核心的功能特色——无需编写脚本，只需用自然语言描述需求即可触发自动化操作。例如：

• 普通用户：“帮我在携程APP上搜索从北京到上海的周末机票”

• 测试人员：“验证这款购物APP的下单流程：选择商品→加入购物车→填写收货地址→提交订单”

• 开发者：“循环执行10次APP的登录-退出操作，检查是否存在崩溃问题”

DroidRun通过LLM的自然语言理解能力解析这些需求，自动转化为可执行的设备操作步骤，真正实现“所想即所得”。这种交互方式大幅降低了移动自动化的使用门槛，让非技术用户也能轻松上手。

2.2.2 多LLM兼容，灵活适配不同需求

DroidRun采用“LLM无关性”设计，支持多种主流大语言模型，用户可根据自身情况选择：

• 云端LLM：OpenAI（GPT-3.5/4）、Anthropic（Claude）、Gemini（Google）、DeepSeek等，适合需要强大算力与复杂推理能力的场景

• 本地LLM：Ollama（支持本地部署的开源LLM），适合对数据隐私有严格要求、不希望联网的场景

用户只需在配置文件中修改LLM提供商参数，即可无缝切换模型，无需调整任务描述或操作逻辑。这种设计让DroidRun既适配个人用户的轻量化需求（如使用Ollama本地模型完成简单任务），也能满足企业用户的高性能需求（如使用GPT-4处理复杂测试流程）。

2.2.3 跨平台+多设备支持，覆盖全场景使用

DroidRun打破了移动自动化工具的平台限制，同时支持Android和iOS设备，包括：

• 物理设备：通过USB连接或无线投屏方式接入的智能手机、平板

• 虚拟设备：Android模拟器（如Genymotion、Android Studio自带模拟器）、iOS模拟器（需搭配Mac环境）

无论你使用的是Android手机还是iPhone，无论是需要测试多平台兼容性，还是个人日常使用不同系统设备，DroidRun都能提供一致的自动化体验。

2.2.4 复杂任务规划，智能拆解多步骤需求

对于单一指令无法完成的复杂任务，DroidRun具备强大的任务规划能力。它会将复杂需求拆解为多个子步骤，逐步执行并根据执行结果调整后续操作。例如用户需求“帮我预订旧金山的公寓，要求靠近市中心、价格低于200美元/晚、可免费取消”，DroidRun会拆解为：

1. 打开住宿预订APP（如Airbnb）

2. 输入目的地“旧金山市中心”

3. 设置入住与退房日期

4. 筛选条件：价格≤200美元/晚、支持免费取消

5. 浏览搜索结果，选择评分≥4.5分的房源

6. 展示筛选后的房源信息并反馈给用户

在执行过程中，如果遇到界面变化（如APP更新后按钮位置改变）或操作失败（如网络超时），DroidRun会通过截图分析识别问题，自动重试或调整操作步骤，确保任务尽可能完成。

2.2.5 可视化调试+执行追踪，问题排查更高效

为了方便用户监控任务执行过程、排查异常问题，DroidRun提供了两大核心工具：

• 增强型CLI调试：命令行界面实时输出执行日志，包括当前执行步骤、LLM思考过程、设备操作结果，支持断点调试、日志过滤等功能

• Arize Phoenix执行追踪：集成开源追踪工具，可可视化展示任务执行链路，包括每个步骤的耗时、LLM调用参数、设备状态变化，甚至可以回放操作过程，快速定位问题所在

这些功能让开发者在构建自定义自动化逻辑时，能够清晰了解每一步的执行情况，大幅提升调试效率。

2.2.6 高度可扩展，支持自定义开发

DroidRun不仅是一款“即用型工具”，更是一个“可扩展框架”。它提供了完整的Python API，允许开发者：

• 自定义自动化工具：添加专属的设备操作函数（如特定APP的专属操作）

• 扩展LLM适配：集成新的LLM提供商（如国内的通义千问、文心一言）

• 定制任务规划逻辑：根据特定场景优化任务拆解算法

• 集成第三方工具：如将自动化结果同步至测试管理平台（JIRA）、生成可视化报告

同时，项目提供了详细的开发文档与示例代码，降低了二次开发的门槛。

三、技术细节

3.1 技术架构

DroidRun的技术架构采用分层设计，从上至下分为“用户交互层→LLM智能层→核心逻辑层→设备控制层→工具支撑层”，各层职责清晰、解耦良好，以下是详细说明：

3.1.1 架构分层与核心职责

这种分层设计的优势在于：各层独立迭代，例如更新LLM适配逻辑时无需修改设备控制代码；支持灵活扩展，如新增设备类型只需在设备控制层添加对应控制器。

3.1.2 核心工作流程

DroidRun的核心工作流程可概括为“需求解析→任务规划→操作执行→结果反馈”四大步骤，具体如下：

1. 需求解析：用户通过CLI或API输入自然语言指令，LLM适配器将指令转化为标准化Prompt，调用指定的LLM模型，解析出任务目标与核心约束条件（如“预订公寓”的价格、位置约束）。

2. 任务规划：任务规划器根据LLM返回的解析结果，结合设备当前状态（如已安装的APP、当前界面），将任务拆解为可执行的子步骤（如“打开APP→输入关键词→筛选条件”），并确定步骤执行顺序与依赖关系。

3. 操作执行：操作执行器调用设备控制层的API，执行子步骤（如点击按钮、输入文本、滑动屏幕），同时通过截图捕获模块实时获取设备界面，截图分析工具识别界面元素位置与状态，确保操作准确性。

4. 结果反馈：任务执行完成后，状态管理器整理执行结果（如成功完成的步骤、未完成的原因、截图证据），通过CLI或API反馈给用户；同时，执行追踪工具记录全流程日志，便于后续查看与调试。

3.2 核心组件详解

3.2.1 LLM适配器

LLM适配器是DroidRun实现“多LLM兼容”的核心组件，其主要作用是屏蔽不同LLM提供商的API差异，为上层逻辑提供统一的调用接口。它支持：

• 动态加载LLM配置：用户通过配置文件指定LLM提供商、API密钥、模型参数（如温度值、最大 tokens），适配器自动加载并初始化

• 标准化Prompt模板：针对移动自动化场景优化的Prompt模板，包含设备状态、任务目标、操作约束等信息，提升LLM解析准确性

• 失败重试机制：当LLM调用超时或返回无效结果时，自动重试并调整参数（如降低温度值、增加Prompt细节）

3.2.2 任务规划器

任务规划器是DroidRun处理复杂任务的核心，基于LLM的推理能力与预设的规划逻辑，实现任务拆解与步骤调度。其核心逻辑包括：

• 子步骤拆解：将复杂任务拆分为粒度适中的子步骤，每个子步骤对应一个具体的设备操作（如“打开APP”“输入文本”）

• 依赖关系处理：识别子步骤之间的依赖关系（如“必须先登录才能搜索房源”），确保执行顺序正确

• 动态调整机制：根据设备操作结果调整后续步骤，例如搜索结果为空时，自动放宽筛选条件并重新搜索

3.2.3 设备控制层

设备控制层负责与移动设备直接通信，执行具体的操作指令，分为Android与iOS两个分支：

• Android控制：基于ADB（Android Debug Bridge）协议，支持点击、输入、滑动、安装APP、获取设备信息等操作，兼容Android 7.0及以上版本

• iOS控制：基于XCTest框架与libimobiledevice工具，支持物理设备与模拟器控制，需搭配MacOS环境，兼容iOS 12.0及以上版本

• 截图捕获：通过ADB（Android）或xcrun（iOS）命令捕获设备屏幕，生成图像文件后传递给截图分析工具

3.2.4 截图分析工具

截图分析工具是DroidRun实现“视觉理解”的核心，基于图像识别技术，识别设备界面中的关键元素（如按钮、输入框、文本信息），其主要功能包括：

• 元素定位：识别界面元素的位置坐标（如“登录按钮位于屏幕右下角”），为操作执行器提供准确的操作目标

• 文本识别：提取界面中的文本信息（如“价格标签”“错误提示”），辅助LLM判断当前状态

• 状态识别：判断操作是否成功（如“是否已进入搜索结果页”“是否显示订单提交成功提示”）

3.3 技术栈与依赖

3.3.1 核心技术栈

• 开发语言：Python 3.8+（项目指定.python-version文件，确保版本兼容性）

• 核心框架：无特定主框架，采用模块化设计，通过Python标准库与第三方库构建

• 设备通信：ADB（Android）、libimobiledevice（iOS）、XCTest（iOS）

• LLM集成：OpenAI API、Anthropic API、Gemini API、Ollama Python Client等

• 图像识别：Pillow（图像处理）、Tesseract OCR（文本识别）

• 调试与追踪：Arize Phoenix、logging模块、click（CLI工具）

• 安全工具：bandit（代码安全检测）、safety（依赖漏洞检测）

3.3.2 关键依赖包

项目的核心依赖包在pyproject.toml文件中定义，主要包括：

• 设备控制相关：adb-shell（Android通信）、pyobjc-framework-XCTest（iOS控制，MacOS专属）、libimobiledevice（iOS通信）

• LLM相关：openai（OpenAI API）、anthropic（Anthropic API）、google-generativeai（Gemini API）、ollama（Ollama客户端）

• 工具类：click（CLI构建）、pyyaml（配置文件解析）、pillow（图像处理）、tesseract（OCR识别）、arize-phoenix（执行追踪）

• 开发工具：black（代码格式化）、ruff（代码检查）、pytest（单元测试）、bandit（安全检测）、safety（依赖检测）

3.4 安全机制

DroidRun重视代码与运行环境的安全性，主要通过以下方式保障：

• 代码安全检查：集成bandit工具，扫描Python代码中的常见安全漏洞（如SQL注入、权限泄露、不安全的函数调用），开发者提交代码前需执行bandit -r droidrun确保无高危漏洞

• 依赖安全检查：集成safety工具，检查已安装依赖包是否存在已知安全漏洞，执行safety scan可生成漏洞报告并提示修复方案

• 配置安全策略：配置文件中支持设置安全相关参数（如LLM API密钥加密存储、设备操作权限限制、日志敏感信息脱敏）

• 开源许可证合规：采用MIT许可证，明确代码使用范围与责任划分，避免法律风险

四、应用场景

DroidRun的功能特性决定了其应用场景的广泛性，无论是个人用户的日常使用，还是企业级的专业需求，都能找到适配的场景。以下是主要应用场景的详细介绍：

4.1 移动应用自动化UI测试

这是DroidRun最核心的企业级应用场景之一。传统的移动UI测试需要开发者编写大量脚本（如Appium脚本），学习成本高、维护难度大，且难以适应APP界面频繁更新的情况。DroidRun通过自然语言驱动与视觉理解能力，大幅简化了UI测试流程：

适用人群

移动应用开发者、测试工程师、QA团队

具体使用场景

• 功能测试：验证APP的核心功能是否正常，如“测试注册流程：输入手机号→获取验证码→设置密码→完成注册”“测试支付流程：选择商品→提交订单→选择支付方式→支付成功”

• 兼容性测试：在不同型号、不同系统版本的设备上，测试APP的界面显示与功能可用性，如“在Android 13和iOS 17设备上，测试首页滑动是否流畅、按钮是否可点击”

• 回归测试：APP更新后，快速验证原有功能是否正常，避免新代码引入Bug，如“APP迭代版本后，测试登录、搜索、下单等核心功能是否正常工作”

• 压力测试：循环执行某一操作，测试APP的稳定性，如“循环执行100次登录-退出操作，检查是否出现崩溃、内存泄漏”

场景优势

• 降低测试成本：无需编写复杂脚本，测试人员只需用自然语言描述测试需求，即可自动生成测试用例并执行

• 提升测试效率：支持多设备并行测试、夜间自动执行测试，大幅缩短测试周期

• 适应界面变化：通过视觉识别而非固定坐标定位元素，APP界面更新后无需修改测试指令，降低维护成本

• 丰富的测试报告：自动记录测试过程、截图证据、执行结果，生成可视化报告，便于团队协作与问题追溯

4.2 个人重复任务自动化

对于个人用户而言，DroidRun可用于自动化处理手机上的重复操作，节省时间与精力：

适用人群

普通手机用户、需要处理大量重复任务的人群（如职场人士、学生）

具体使用场景

• 学习应用打卡：自动完成语言学习APP（如多邻国、百词斩）的每日打卡、课程学习，如“每天晚上8点，打开多邻国APP，完成10分钟英语学习并打卡”

• 社交平台互动：自动完成社交APP的日常互动，如“打开微博，给关注的博主最新发布的3条微博点赞”“打开微信，给家人发送每日天气提醒”

• 信息查询与整理：自动查询特定信息并整理反馈，如“每天早上7点，打开天气APP，查询今日北京天气，发送到我的邮箱”“打开股票APP，查询贵州茅台的最新股价，记录到备忘录”

• 定时操作执行：定时执行手机操作，如“每天晚上11点，关闭手机蓝牙、调低屏幕亮度”“每周日晚上，备份手机相册到云端”

场景优势

• 零学习成本：无需掌握编程知识，用日常语言即可下达指令

• 节省时间精力：摆脱重复、机械的手机操作，将时间投入到更有价值的事情上

• 个性化定制：可根据个人需求自定义任务内容、执行时间、操作逻辑

• 跨平台支持：无论是Android还是iOS手机，都能实现一致的自动化体验

4.3 非技术用户的 guided workflows

对于不熟悉手机操作的用户（如老年人、新手），DroidRun可提供引导式工作流，帮助他们完成复杂操作：

适用人群

老年人、手机操作新手、需要指导他人使用手机的人群

具体使用场景

• 长辈操作引导：帮助长辈完成手机操作，如“引导我妈妈打开微信视频通话，联系我姐姐”“指导爷爷在网上药店购买降压药”

• 新手入门指导：帮助手机新手熟悉功能，如“指导我使用手机拍摄夜景照片，开启夜景模式、调整参数”“教我如何在手机上设置闹钟、添加日程”

• 特定场景引导：引导用户完成特定场景的复杂操作，如“帮助我完成手机公积金提取申请”“指导我在银行APP上办理信用卡还款”

场景优势

• 步骤化引导：将复杂操作拆解为简单步骤，逐步引导用户执行，降低操作难度

• 自然语言交互：用户无需记忆操作路径，只需跟随语音或文字引导即可完成

• 实时反馈：操作错误时及时提示并提供修正方案，提升成功率

• 远程协助：支持远程发起引导流程，无需现场指导，方便异地家人朋友使用

4.4 远程移动设备协助

DroidRun支持远程连接移动设备并执行自动化操作，适用于需要远程协助他人或管理多台设备的场景：

适用人群

企业IT管理员、设备运维人员、需要远程帮助他人的用户

具体使用场景

• 企业设备管理：IT管理员远程管理公司员工的工作手机，如“远程为员工手机安装企业APP、配置网络设置”“远程清理员工手机的缓存文件、优化性能”

• 家庭设备协助：远程帮助家人解决手机问题，如“远程帮我爸爸修复手机无法连接WiFi的问题”“远程为妈妈的手机更新系统”

• 多设备批量操作：同时管理多台移动设备，执行批量操作，如“为10台测试手机批量安装最新版APP、清除应用数据”“为公司所有员工手机批量设置屏幕锁密码”

场景优势

• 远程无接触：无需物理接触设备，即可完成操作，提升协助效率

• 批量处理：支持多设备同时操作，节省管理成本

• 操作可追溯：记录远程操作的全流程日志，便于审计与问题排查

• 安全可控：支持设置操作权限，限制敏感操作（如删除数据），保障设备安全

4.5 移动UI探索与研究

对于移动应用设计师、产品经理或研究人员，DroidRun可用于探索移动UI的交互逻辑与用户体验：

适用人群

UI/UX设计师、产品经理、移动应用研究人员

具体使用场景

• UI交互测试：探索不同APP的UI交互逻辑，如“测试10款主流购物APP的下单流程，记录每一步的操作路径与界面元素”“分析社交APP的消息通知交互方式”

• 用户体验研究：模拟用户操作行为，评估APP的用户体验，如“模拟新用户使用APP的流程，记录遇到的操作障碍”“测试APP在不同网络环境下的加载速度与交互响应”

• 竞品分析：对比不同竞品APP的功能与界面设计，如“对比3款外卖APP的点餐流程、界面布局、功能完整性”

场景优势

• 自动化探索：无需手动操作，自动完成多APP、多场景的UI探索，提升研究效率

• 数据化记录：自动记录操作路径、界面截图、交互耗时等数据，便于量化分析

• 客观中立：模拟真实用户操作行为，避免主观因素影响研究结果

• 可重复性：支持重复执行相同的探索流程，确保研究结果的一致性

五、使用方法

DroidRun的使用流程简洁清晰，分为“安装→配置→执行任务”三大步骤，同时支持基础使用与进阶开发，以下是详细说明：

5.1 环境准备

在安装DroidRun之前，需要先完成以下环境准备：

5.1.1 基础环境

• 操作系统：支持Windows、MacOS、Linux（64位）

• Python版本：Python 3.8及以上（建议使用3.10版本，兼容性最佳）

• 网络环境：使用云端LLM时需要联网；使用本地LLM（如Ollama）时可离线使用

• 设备要求：

• Android设备：Android 7.0及以上版本，开启开发者模式与USB调试功能

• iOS设备：iOS 12.0及以上版本，需搭配MacOS环境（支持物理设备与模拟器），安装Xcode与libimobiledevice工具

5.1.2 依赖工具安装

• Android设备：安装ADB工具（Android Debug Bridge），确保电脑可通过USB或无线连接设备

• Windows/MacOS/Linux：可通过Android Studio安装，或直接下载ADB二进制文件并配置环境变量

• 验证：连接Android设备后，执行adb devices命令，若能显示设备ID则说明安装成功

• iOS设备（MacOS专属）：

• 安装Xcode：从App Store下载Xcode，安装完成后打开一次以完成初始化

• 安装libimobiledevice：通过Homebrew执行brew install libimobiledevice

• 验证：连接iOS设备后，执行idevice_id -l命令，若能显示设备UDID则说明安装成功

• 本地LLM（如Ollama）：若使用本地模型，需先安装Ollama并下载对应模型（如ollama pull llama3）

5.2 安装DroidRun

DroidRun支持通过pip快速安装，根据使用需求选择不同的依赖组合：

5.2.1 完整安装（推荐）

安装包含所有LLM提供商支持、开发工具与扩展功能的完整版本：

pip install 'droidrun[google,anthropic,openai,deepseek,ollama,dev]'

5.2.2 自定义安装

根据需要选择特定LLM提供商依赖，减少安装体积：

• 仅安装OpenAI与Anthropic支持：

  pip install 'droidrun[openai,anthropic]'

• 仅安装本地Ollama支持（离线使用）：

  pip install 'droidrun[ollama]'

• 基础安装（无LLM依赖，仅核心功能）：

  pip install droidrun

5.2.3 安装验证

安装完成后，执行以下命令验证是否安装成功：

droidrun --version

若输出版本号（如droidrun 0.4.7），则说明安装成功。

5.3 配置DroidRun

DroidRun的配置通过YAML文件实现，支持全局配置与局部配置，以下是详细说明：

5.3.1 配置文件获取

项目提供了配置示例文件config_example.yaml，可从GitHub仓库下载（路径：https://github.com/droidrun/droidrun/blob/main/config_example.yaml），复制后重命名为`config.yaml`，放在用户主目录（如Windows：`C:\Users\用户名\.droidrun\`；MacOS/Linux：`~/.droidrun/`）。

5.3.2 核心配置项说明

配置文件包含LLM设置、设备设置、任务设置、安全设置等模块，以下是常用配置项的详细说明：

5.3.3 配置示例（简化版）

# LLM配置
llm:
 provider: openai
 api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 model: gpt-4o-mini
 temperature: 0.2

# 设备配置
device:
 platform: android
 device_id: emulator-5554
 connection_type: usb

# 任务配置
task:
 max_steps: 20
 timeout: 30
 debug_mode: true

# 安全配置
security:
 log_sensitive_data: false
 allowed_apps: ["com.tencent.mm", "com.zhihu.android"]

5.4 快速入门：执行第一个自动化任务

以下以“在Android模拟器上打开微信并搜索‘开源中国’公众号”为例，演示DroidRun的基础使用流程：

5.4.1 步骤1：连接设备

1. 启动Android模拟器（或连接物理Android设备）

2. 开启设备的开发者模式与USB调试功能

3. 执行adb devices命令，确认设备已被识别（显示设备ID）

5.4.2 步骤2：配置LLM

1. 打开config.yaml文件，配置OpenAI API密钥（需提前注册OpenAI账号并获取密钥）

2. 确保llm.provider设置为openai，llm.model设置为gpt-4o-mini（或其他可用模型）

5.4.3 步骤3：执行任务

通过CLI执行自然语言指令，启动自动化任务：

droidrun run "打开微信，搜索公众号‘开源中国’，展示搜索结果"

5.4.4 步骤4：查看执行结果

1. 命令执行后，CLI会实时输出执行日志，包括当前步骤、LLM思考过程、设备操作结果

2. 设备会自动执行操作：打开微信→点击搜索框→输入“开源中国”→点击搜索→展示结果

3. 任务完成后，CLI会输出“任务执行成功”提示，并展示相关截图（默认保存在~/.droidrun/screenshots/目录）

5.5 进阶使用：通过Python API自定义自动化逻辑

对于开发者，DroidRun提供了完整的Python API，可用于构建自定义自动化脚本。以下是一个简单示例：

5.5.1 示例：自定义打卡脚本

from droidrun import DroidRunAgent
from droidrun.config import load_config

# 加载配置文件
config = load_config("~/.droidrun/config.yaml")

# 初始化智能体
agent = DroidRunAgent(config=config)

# 定义任务：在学习APP上完成今日打卡
task = """
打开多邻国APP（包名：com.duolingo）
登录账号（使用已保存的账号密码）
进入英语学习板块
完成10分钟基础课程学习
点击“今日打卡”按钮，完成打卡
"""

# 执行任务并获取结果
result = agent.run_task(task)

# 打印执行结果
print("任务执行状态：", result.status)
print("执行步骤：", result.steps)
print("截图路径：", result.screenshot_paths)

5.5.2 运行脚本

将上述代码保存为duolingo_checkin.py，执行以下命令运行：

python duolingo_checkin.py

5.5.3 API核心功能说明

• DroidRunAgent：核心智能体类，负责任务执行与设备交互

• run_task(task: str)：执行自然语言描述的任务，返回执行结果对象

• get_device_status()：获取当前设备状态（如当前界面、已安装APP）

• execute_action(action: str)：执行单一操作指令（如“点击屏幕坐标(100,200)”）

• load_config(config_path: str)：加载配置文件，返回配置对象

• result对象：包含任务执行状态（成功/失败）、执行步骤列表、截图路径、错误信息等

5.6 部署方式

DroidRun支持多种部署方式，适配不同使用场景：

5.6.1 本地部署（推荐个人用户）

直接在本地电脑安装DroidRun，连接移动设备执行自动化任务，适合个人日常使用、小规模测试场景。优点是配置简单、响应速度快，缺点是无法远程访问。

5.6.2 Docker部署（推荐企业用户）

项目提供Dockerfile支持容器化部署，可在服务器上部署DroidRun服务，通过API接收任务请求并执行。步骤如下：

1. 克隆仓库：git clone https://github.com/droidrun/droidrun.git

2. 构建Docker镜像：docker build -t droidrun:latest .

3. 运行容器：docker run -d --privileged -v /dev/bus/usb:/dev/bus/usb droidrun:latest（挂载USB设备，支持连接物理手机）

优点是环境隔离、易于扩展，适合企业级大规模部署与多用户共享。

5.6.3 云部署（进阶使用）

可将DroidRun部署在云服务器（如AWS、阿里云、腾讯云），结合云手机服务（如AWS Device Farm、阿里云移动测试）实现无物理设备的自动化。优点是支持大规模并行测试、无需维护物理设备，缺点是部署成本较高、配置复杂。

六、常见问题解答（FAQ）

6.1 设备连接相关问题

Q1：执行adb devices后无法识别Android设备，怎么办？

A1：可按以下步骤排查：

1. 确认设备已开启“开发者模式”与“USB调试”（路径：设置→关于手机→连续点击版本号7次，返回设置→系统→开发者选项→开启USB调试）

2. 更换USB线缆或USB端口，确保线缆支持数据传输（部分充电线仅支持充电）

3. 安装设备驱动（Windows系统需安装对应手机品牌的驱动，MacOS/Linux通常无需额外安装）

4. 执行adb kill-server && adb start-server重启ADB服务，再次执行adb devices

Q2：iOS设备无法连接，提示“设备未授权”，怎么办？

A2：需完成以下授权操作：

1. 确保电脑已安装最新版Xcode与libimobiledevice

2. 连接iOS设备后，在设备上点击“信任此电脑”

3. 打开Xcode→Window→Devices and Simulators，确认设备已显示在列表中

4. 执行sudo chmod -R 777 /var/db/lockdown/授权lockdown目录，再次尝试连接

6.2 LLM相关问题

Q3：调用LLM时提示“API密钥无效”，如何解决？

A3：排查步骤如下：

1. 确认API密钥是否正确，是否存在拼写错误或多余空格

2. 确认API密钥是否过期（部分LLM提供商的API密钥有有效期限制）

3. 确认LLM提供商的服务是否正常（可访问官方网站查看状态）

4. 若使用代理，需在配置文件中设置代理参数（llm.proxy: http://proxy_ip:proxy_port）

Q4：使用本地Ollama模型时，响应速度很慢，怎么办？

A4：优化方案如下：

1. 选择轻量化模型（如llama3:8b而非llama3:70b），减少硬件资源占用

2. 确保电脑配置满足要求（推荐CPU≥8核、内存≥16GB，支持GPU加速更佳）

3. 关闭其他占用资源的程序，为Ollama分配更多硬件资源

4. 升级Ollama至最新版本（ollama update），优化模型加载速度

6.3 任务执行相关问题

Q5：任务执行到一半失败，提示“界面元素未找到”，怎么办？

A5：解决方案如下：

1. 确认APP界面是否与预期一致（如APP是否更新了版本，导致界面元素位置变化）

2. 开启调试模式（task.debug_mode: true），查看执行日志中的截图，确认当前界面状态

3. 优化任务描述，增加更多细节（如“点击屏幕底部中央的‘搜索’按钮”而非“点击搜索按钮”）

4. 若为常用APP，可等待项目更新对应的App Cards，提升操作准确性

Q6：复杂任务执行时，步骤顺序混乱或遗漏，如何处理？

A6：可通过以下方式优化：

1. 细化任务描述，明确步骤顺序与约束条件（如“先登录，再搜索，最后下单”）

2. 降低LLM的temperature值（如设置为0.1-0.3），减少随机决策导致的步骤混乱

3. 在配置文件中增加task.max_retries: 3，允许任务失败后自动重试

4. 查看执行追踪日志（Arize Phoenix），分析步骤混乱的原因，调整任务描述

6.4 安装与环境相关问题

Q7：安装DroidRun时提示“依赖包冲突”，怎么办？

A7：解决方法如下：

1. 使用虚拟环境安装（推荐）：

   python -m venv droidrun-env
   # Windows激活：droidrun-env\Scripts\activate
   # MacOS/Linux激活：source droidrun-env/bin/activate
   pip install 'droidrun[all]'

2. 升级pip版本：pip install --upgrade pip，再次尝试安装

3. 手动安装冲突的依赖包（指定兼容版本），如pip install pillow==10.0.0

Q8：Windows系统执行droidrun命令时提示“命令未找到”，怎么办？

A8：需配置Python环境变量：

1. 找到Python的安装目录（如C:\Python310\）与Scripts目录（如C:\Python310\Scripts\）

2. 右键此电脑→属性→高级系统设置→环境变量→系统变量→Path→编辑→添加上述两个目录

3. 重启命令行工具，再次执行droidrun --version

6.5 其他常见问题

Q9：DroidRun支持控制智能手表、平板等移动设备吗？

A9：目前主要支持智能手机（Android/iOS）与平板设备（Android/iOS），智能手表等其他移动设备暂未适配，后续可能会通过版本更新扩展支持范围。

Q10：使用DroidRun自动化操作APP时，是否会被APP检测为作弊？

A10：DroidRun的操作方式模拟真实用户的手动操作（如点击、输入、滑动），而非通过篡改APP数据或协议的方式实现自动化，被检测为作弊的概率较低。但部分APP（如游戏、金融类APP）有严格的反作弊机制，可能会限制自动化操作，建议在非敏感场景使用，避免违规。

Q11：如何自定义添加新的LLM提供商（如通义千问）？

A11：可通过以下步骤扩展LLM适配：

1. 在droidrun/llm/adapters/目录下创建新的适配器文件（如tongyi.py）

2. 实现BaseLLMAdapter抽象类的initialize与generate方法，适配新LLM的API

3. 在droidrun/llm/__init__.py中注册新的适配器

4. 在配置文件中设置llm.provider: tongyi，并填写对应的API密钥与模型参数

详细开发指南可参考项目的CONTRIBUTING.md文件。

七、相关链接

• 项目GitHub仓库：https://github.com/droidrun/droidrun

• 官方文档：https://docs.droidrun.ai

• 快速入门指南：https://docs.droidrun.ai/v3/quickstart

八、总结

DroidRun是一款基于LLM智能体的开源移动自动化框架，核心价值在于通过自然语言指令实现对Android和iOS设备的全流程自动化控制，打破了传统移动自动化工具的技术门槛与平台限制。它具备多LLM兼容、跨平台设备支持、复杂任务规划、可视化调试等核心功能，既为普通用户提供了零代码的重复任务自动化解决方案，也为开发者与企业提供了高度可扩展的定制化开发框架。其应用场景覆盖移动UI测试、个人任务自动化、非技术用户引导、远程设备协助等多个领域，搭配完善的文档支持、活跃的社区贡献与MIT开源许可证，使其成为移动自动化领域的一款极具实用性与创新性的工具。无论是想要节省日常手机操作时间的个人用户，还是需要提升测试效率、降低开发成本的企业团队，DroidRun都能通过其强大的功能与易用的设计，满足多样化的移动自动化需求。