Droidline

用代码自动化操作真实 Android 手机。
测试你的应用、编写脚本执行重复任务、管理一排手机，或让 AI Agent 使用手机。
支持 Python、Node.js、shell 或 HTTP。无需 ADB、USB 线缆或 root 权限。

网站 · 文档 · 下载 · 赞助 · 快速开始 · 编程语言 · 指南

English · 한국어 · 简体中文

无需 ADB 或线缆 在手机上安装一个应用，开启相应权限，然后扫描二维码配对。无需开发者选项、USB 调试或 root 权限。

命令随处通用 在 Python、Node.js、命令行、HTTP 和 MCP 工具中，touch 都是 touch，全部由同一份规范生成。

手机随处可用 手机主动连接到你的 PC，因此在同一 Wi-Fi 网络下，或通过隧道或你运行的中继服务使用移动数据，都能正常工作。所有通信均经过端到端加密。

使用场景

• 测试自己的应用：在真实手机上测试，包括跨应用的流程，例如通过短信验证码登录。
• 管理一排手机：让它们每天运行同一套例行任务，并让每台手机使用各自的网络或代理。
• 让 AI Agent 亲自操作：借助 MCP，Claude、ChatGPT、Cursor 和其他 Agent 可以查看手机屏幕并进行操作。
• 简单的个人自动化：例如夜间关闭 Wi-Fi，或每小时从应用中收集一个值。

Droidline 仅使用普通应用可以获取的权限，因此有些操作无法实现：请参阅无法执行的操作。

实际演示

_{在浏览器中试用相同的演示，并在模拟屏幕上选择元素：droidline.dev}

## 快速开始

你需要一台 PC（Windows、macOS 或 Linux）和一部搭载 Android 9 或更高版本的 Android 手机，首次尝试时两者需连接到同一 Wi-Fi。安装指南通过截图逐步介绍了每个步骤。

1. 在 PC 上运行服务。 从 Releases 下载适用于你系统的 droidline 压缩包，将 droidline 添加到 PATH，然后启动。保持运行。

   droidline serve
   

2. 在手机上安装应用。 从同一发布页面下载 droidline-agent.apk 并打开。在应用的 Setup 标签页中，启用无障碍服务、Droidline 键盘、通知和不受限制的电池使用权限。在 Android 13 及更高版本上，请先为应用允许 受限设置；应用会显示操作位置。

3. 配对两者。 在 PC 上运行以下命令，并用应用的 Pair 标签页扫描二维码：

   droidline pair
   

   没有摄像头？在应用中轻点 Pair on this Wi-Fi，然后输入显示的 6 位代码：droidline pair 482913。

4. 发送命令。

   droidline launch com.android.settings
   droidline touch text "Network & internet"
   

手边没有手机？每个发布版本都包含 droidline-fakephone，它会用一个小型演示应用模拟手机。第一个脚本教程将通过它编写一个完整的登录脚本。

使用你熟悉的语言

每种接口都会连接到 localhost:8780 上的 droidline serve，并使用相同的命令名称。

Python（pip install droidline，Python 3.9+）

from droidline import connect

d = connect()                                  # the phone paired with this PC
d.launch("dev.droidline.demo")
if d.exists("text", "Close ad"):               # conditions never wait and never fail
    d.touch("text", "Close ad")
d.input("id", "email", "knife")                # waits up to 10 s for the element
d.touch("text", "Log in")
print(d.get_text("id", "greeting"))

Node.js 和 TypeScript（npm install droidline，Node.js 18+）

import { connect } from "droidline";

const d = await connect();
await d.launch("dev.droidline.demo");
await d.input("id", "email", "knife");
await d.touch("text", "Log in", { timeout: 15 });
console.log(await d.getText("id", "greeting"));

C# 和 .NET（dotnet add package Droidline，.NET 8+ 或 .NET Framework 4.6.2+）

using Droidline;

await using var d = await DroidlineClient.ConnectAsync();
await d.LaunchAsync("dev.droidline.demo");
await d.InputAsync("id", "email", "knife");
await d.TouchAsync("text", "Log in", timeout: 15);
Console.WriteLine(await d.GetTextAsync("id", "greeting"));

命令行（随服务附带）

droidline touch text "Log in"
droidline which text="Log in" id=main_tab --timeout 15
droidline screenshot shot.png

HTTP（任何语言、任何工具）

curl -s -X POST localhost:8780/devices/_/touch \
  -H 'content-type: application/json' -d '{"by":"text","value":"Log in"}'

通过 MCP 使用 AI Agent（Claude、Cursor、VS Code 等）

{ "mcpServers": { "droidline": { "command": "droidline", "args": ["mcp"] } } }

使用 Claude Code：claude mcp add droidline -- droidline mcp。在 Claude Desktop 中，也可以从 Releases 打开 droidline.mcpb，其中自带 droidline；它也列在 MCP Registry 中，名称为 io.github.KnifeLemon/droidline。若要减少 Agent 可使用的工具数量，请在参数中添加 --tools dump,screenshot,touch 或 --read-only；请参阅限制 Agent 可使用的功能。其他语言可以打开 TCP 套接字，并为每条命令发送一行 JSON；Go、Java 和 PHP 的相关信息请参阅其他语言。

功能

• 定位元素，而不是像素。 dump() 会将屏幕作为一棵树返回，其中每个元素都有 text、id 和 desc。命令通过字段和值来操作元素：touch("id", "login")。如果元素不响应点击，Droidline 会自行点击其父元素或其边界框的中心。
• 内置等待功能。 touch、input 和 wait 会等待目标元素，默认等待 10 秒。exists、checked 和 which 等条件会立即返回结果，且找不到元素时不会抛出异常。
• 错误信息清晰明了。 每个失败都有错误代码、英文、韩文或中文消息，以及一个说明重试是否有帮助的标记：NOT_FOUND: Could not find text 'Log in' within 10s. Current screen: com.example / .MainActivity。
• 手机架。 一台 PC 可控制多部手机。发往同一部手机的命令会按顺序运行，不同手机上的命令会并行运行，而且每部手机都可以使用自定义名称。
• 按应用配置代理。 无需 root，即可通过本地 VPN 将选定的应用流量转发到 socks5 或 http 上游服务器，每部手机可配置一个上游服务器。
• 在 PC 上接收通知。 等待通知、处理每一条通知、回复、打开或关闭通知，也可以将其转发到已签名的 webhook。
• 获取新的移动 IP。 使用 cuts_network 发送的 batch 会在手机离线时继续运行，因此开启飞行模式、等待、关闭飞行模式可以作为一次调用完成。intent 会先打开设置页面；操作指南中提供了分步说明。
• 绝不重复执行。 手机断开移动数据后，会从中断处继续运行；正在执行中的命令会从手机缓存中返回结果，而不会再次执行。
• 可靠的选择器。 可组合条件，或通过相邻元素指定目标元素：touch({"class": "android.widget.Switch", "row": {"text": "Wi-Fi"}})。find 会返回可点击并可在其中搜索的元素，wait_idle 则会等待屏幕停止变化。
• 可选工具，启动前处于关闭状态。 droidline inspect 会显示屏幕及其元素，提供代码形式的选择器建议，并在你使用手机时记录脚本。droidline webdriver 可让 Appium 客户端和脚本控制手机。此外，还有 pytest 插件、用于在脚本间共享手机的租约，以及适用于没有元素的屏幕的图片和文本匹配功能。
• 应用、错误消息和文档均支持 English、한국어、简体中文。

截图

设置：每项权限都配有一个按钮，可跳转至相应的设置页面	配对：扫描二维码或使用 6 位代码	状态：连接、路由和权限

## 随时连接手机

连接始终由手机发起，因此无需开放端口。选择适合你网络的方式；手机会按顺序尝试，并在可用时切回 Wi-Fi。

方式	所需条件	工作原理
同一 Wi-Fi	无	手机通过 UDP 广播发现 PC，并直接连接。
端口转发	一个转发端口	手机通过 TLS 连接到你的公网地址，并验证固定为 PC 证书的证书。
隧道	cloudflared、ngrok 或类似工具	PC 保持隧道连接；手机通过隧道地址访问。
自建中继	Cloudflare Workers 或 VPS	PC 和手机都向外连接到你部署的中继。中继只转发无法读取的行。

完成两行握手后，每一行都使用只有 PC 和手机持有的密钥加密（P-256 和 AES-256-GCM），因此隧道或中继只会传输密文。远程连接指南逐步介绍了每种方式。

它无法做到的事

Droidline 只能使用普通应用可以获得的权限，因此有些事情无法实现。开始之前最好先了解：

• 它无法打开其他应用未导出的界面。launch 会打开起始界面。
• 它无法解锁 PIN、图案或密码锁屏。
• 没有一条命令可以强行停止应用、清除其数据或切换网络。设置因手机制造商、Android 版本和语言而异，因此操作指南会按下相应按钮，你可能需要根据手机调整标签。在可选的设备所有者模式下，clear_data 可直接清除应用数据。
• 游戏和某些自绘界面应用不会公开任何元素。请在这些应用中使用带坐标的 tap 和 color(x, y)。
• Android 15 及更高版本会隐藏应用通知中的一次性验证码。你只能知道验证码已收到，并在应用中查看。

完整列表会逐项说明。

文档

我想要……	从这里开始
逐步安装所有内容	安装
不连接手机编写第一个脚本	你的第一个脚本
使用我的语言	Python · Node.js · CLI · HTTP · AI Agent
在屏幕上查找正确的元素	查找元素
打开应用、链接和设置页面，或列出已安装内容	应用
指向元素或录制脚本	检查器和录制器
运行 Appium 脚本	Appium 和 WebDriver
使用 pytest 或 Node.js 进行测试	测试框架
复制可用的模式	操作指南
查找命令	命令参考
通过移动数据连接手机	远程手机
解决问题	故障排除
了解线路格式	spec/PROTOCOL.md

从源代码构建

要求：Go 1.26+、Node.js 22、Python 3.9+；对于应用，还需要 JDK 17+ 和 Android SDK（Android Studio 自带的 JDK 即可）。

git clone https://github.com/KnifeLemon/Droidline.git
cd Droidline
go build ./server/cmd/...              # droidline, droidline-relay, droidline-fakephone
go test ./spec/ ./server/...
node scripts/gen.mjs --check           # SDK methods match spec/commands.json
cd sdk/python && python -m pytest
cd sdk/node && npm ci && npm test
dotnet test sdk/dotnet
cd agent && ./gradlew assembleDebug testDebugUnitTest

scripts/integration.sh 会一起运行服务、模拟手机和两个 SDK 演示，这也是 CI 的运行方式。

路径	内容
spec/	commands.json（包含三种语言的所有命令）、PROTOCOL.md、加密测试向量
server/	Go：droidline（服务、CLI、MCP）、droidline-relay、droidline-fakephone
agent/	Kotlin 编写的 Android 应用
sdk/python、sdk/node、sdk/dotnet	官方 SDK，由规范生成，并配有轻量客户端
relay/worker	用于 Cloudflare Workers 的中继
examples/	针对模拟手机运行的演示脚本

贡献

欢迎提交拉取请求；CONTRIBUTING.md 介绍了规范、生成器和测试如何协同工作。目前最有帮助的贡献是提供真实手机的测试报告：手机品牌和 Android 版本，以及用于强制停止、清除数据和切换网络的 Settings 配方是否能匹配其界面标签。如果 Droidline 帮你省下了一些点击，点个 ⭐ 就能帮助其他人发现它。

状态

版本 0.1。服务、CLI、MCP 适配器、中继和两个 SDK 均已通过针对手机模拟器的测试；应用也已通过单元测试，并能在 Android 13 模拟器上运行。下一步是在不同手机品牌上进行测试。docs/STATUS.md 列出了具体的验证内容及其方式。

安全与隐私

配对机制决定谁可以控制手机，握手完成后的所有通信均采用端到端加密。请按照 SECURITY.md 中的说明，私下报告安全问题。

Droidline 不收集使用数据，也不发送遥测信息。服务在你自己的电脑上监听；应用只与配对的电脑通信，并且每天仅连接一次 GitHub 以检查是否有新版本。请仅在你拥有或获准自动化操作的手机和账户上使用 Droidline；条款说明了它的用途。

许可证

MIT。参见 LICENSE。