Droidline 文档

Droidline 让你电脑上的程序像人一样使用 Android 手机：打开应用、点击按钮、输入文字、滚动、读取屏幕上的内容以及截图。每个操作写一行，例如 d.touch("text", "Log in")，可以用 Python、Node.js、shell、纯 HTTP，或任何能建立网络连接的语言。

它不需要 ADB、USB 数据线或 root。手机上只需要安装 Droidline 应用，并开启几项权限，这些权限只需开启一次。

人们用它做什么

• 在真机上测试你自己的应用，包括会跳转到其他应用的流程，例如用短信中的验证码登录。
• 让一整架手机每天执行同样的例行任务，每部手机使用各自的网络或代理。
• 给 AI 智能体一双手：通过 MCP，Claude、Cursor 等智能体可以查看手机屏幕并进行操作。
• 个人的小型自动化，例如晚上关闭 Wi-Fi，或者每小时从某个应用中读取一个数值。

Droidline 只使用普通应用能获得的权限，所以有些事情做不到。规划大型项目之前，请先阅读限制。

工作原理

Droidline 由三部分组成。前两部分只需安装一次；第三部分就是你自己写的代码。

组成部分	运行在	作用
droidline serve	你的电脑（Windows、macOS 或 Linux）	一个小型服务器，与每部已配对的手机保持加密连接，并在 localhost:8780 上接收你的代码发来的命令。
Droidline 应用	每部 Android 手机（Android 9 或更高版本）	连接服务器，借助 Android 的无障碍服务、自带的键盘，以及（如果需要）按应用 VPN 执行命令。
你的代码	你的电脑	Python 或 Node.js 脚本、shell 中的 droidline 命令、通过 MCP 连接的 AI 智能体、curl，或任何语言的原始套接字。

一条命令的传递过程如下：

your script ──one JSON line──▶ droidline serve ──encrypted──▶ phone
your script ◀──one JSON line── droidline serve ◀──encrypted── phone

总是由手机主动连接电脑，而不是反过来。所以手机上不需要开放端口；也正因如此，手机使用移动数据时，借助隧道或你自己运行的中继，同样的设置也能工作。

你需要准备什么

• 一台在脚本运行期间保持开机的电脑。Windows 10 或 11、macOS 或 Linux，64 位（x86 或 ARM）。
• 一部 Android 9 或更高版本的 Android 手机。不需要 root，也不需要开启开发者选项。
• 首次设置时，电脑和手机要连接同一个 Wi-Fi 网络。其他网络的情况见远程手机。
• 如果要用 Python 或 Node.js 写脚本，需要 Python 3.9 或更高版本，或者 Node.js 18 或更高版本。命令行不需要这两者中的任何一个。

手边还没有手机？droidline-fakephone 会在你的电脑上模拟一部手机，你的第一个脚本从头到尾都使用它。

接下来看什么

如果你想	阅读
一步步完成所有设置	安装
尽快发送第一条命令	快速开始
不用手机写一个真正的脚本，并了解每一行的作用	你的第一个脚本
理解选择器、等待和错误	概念
使用你的语言	Python、Node.js、CLI、HTTP、其他语言、AI 智能体
在屏幕上找到正确的元素	查找元素
复制一个可用的写法	实用示例
查询某条命令	命令参考
解决不能正常工作的问题	故障排查

选择器、dump、配对等你以前可能没见过的词，在术语表中都有解释。

状态

Droidline 当前版本为 0.1。服务器、CLI、MCP 适配器、中继和 SDK 都通过了针对手机模拟器的测试，Android 应用已在 Android 13 模拟器上测试过。下一步是收集真机报告，尤其是设置快捷操作在不同品牌手机上的表现。验证记录列出了具体检查过哪些内容。