Droidline README

项目的 README,来自 github.com/KnifeLemon/Droidline。合并为一个 markdown 文件:README.md。

Droidline: Android automation, one line at a time.

Automate real Android phones from your code.
Test your apps, script the tasks you repeat, run a shelf of phones, or let an AI agent use one.
Python, Node.js, the shell or HTTP. No ADB, no USB cable, no root.

Website · Docs · Download · Sponsor · Quick start · Languages · Guides

CI Latest release Android 9 or later Windows, macOS and Linux MIT license

English · 한국어 · 简体中文

No ADB, no cable
Install one app on the phone, turn on its permissions and pair it with a QR code. No developer options, no USB debugging, no root.
The same command everywhere
touch is touch in Python, Node.js, the CLI, HTTP and as an MCP tool, all generated from one spec.
Phones anywhere
The phone connects out to your PC, so it works on the same Wi-Fi or on mobile data through a tunnel or a relay you run. Every line is encrypted end to end.

What people use it for

Droidline uses only permissions an ordinary app can get, so a few things are out of reach: see What it cannot do.

See it in action

A script sends six lines to a phone: launch the demo app, close the ad, type an email, tick Keep me signed in, tap Log in, and wait for the main screen. Each line gets a reply with how the tap was delivered, and the phone screen changes to match.
Try the same demo in your browser, and pick elements on a simulated screen, on droidline.dev

Quick start

You need a PC (Windows, macOS or Linux) and an Android phone with Android 9 or later, on the same Wi-Fi for a first try. The installation guide walks through each step with screenshots.

  1. Run the server on your PC. Download the droidline archive for your system from Releases, put droidline on your PATH, and start it. Leave it running.

    droidline serve
    
  2. Install the app on the phone. Download droidline-agent.apk from the same release page and open it. On the app's Setup tab, turn on the accessibility service, the Droidline keyboard, notifications and unrestricted battery use. On Android 13 and later, allow restricted settings for the app first; the app shows where.

  3. Pair them. Run this on the PC and scan the QR code with the app's Pair tab:

    droidline pair
    

    No camera? Tap Pair on this Wi-Fi in the app and type the 6-digit code it shows: droidline pair 482913.

  4. Send a command.

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

No phone at hand? droidline-fakephone, included in every release, simulates one with a small demo app. The first-script tutorial builds a complete login script against it.

Use it from your language

Every interface talks to droidline serve on localhost:8780 and uses the same command names.

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 and 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# and .NET (dotnet add package Droidline, .NET 8+ or .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"));

Command line (comes with the server)

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

HTTP (any language, any tool)

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

AI agents over MCP (Claude, Cursor, VS Code and others)

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

With Claude Code: claude mcp add droidline -- droidline mcp. In Claude Desktop you can instead open droidline.mcpb from Releases, which carries its own droidline; it is also listed in the MCP Registry as io.github.KnifeLemon/droidline. To give an agent fewer tools, add --tools dump,screenshot,touch or --read-only to the args; see Limit what an agent can use. Other languages can open a TCP socket and send one JSON line per command; see Other languages for Go, Java and PHP.

Features

Screenshots

Setup tab with every permission switched on Pair tab after pairing with a PC Status tab of a connected phone with its route and permissions
Setup: each permission with a button to its settings screen Pair: scan the QR code or use a 6-digit code Status: connection, route and permissions

Reach phones anywhere

The phone always opens the connection, so it needs no open port. Pick the route that fits your network; the phone tries them in order and returns to Wi-Fi when it can.

Route You need How it works
Same Wi-Fi Nothing The phone finds the PC with a UDP broadcast and connects directly.
Port forward One forwarded port The phone connects to your public address over TLS, pinned to the PC's certificate.
Tunnel cloudflared, ngrok or similar Your PC keeps a tunnel open; the phone reaches it through the tunnel's address.
Your relay Cloudflare Workers or a VPS PC and phone both connect out to a relay you deploy. It forwards lines it cannot read.

Past the two-line handshake every line is encrypted with keys only your PC and phone hold (P-256 and AES-256-GCM), so a tunnel or relay only carries ciphertext. The remote connection guides cover each route step by step.

What it cannot do

Droidline only uses permissions an ordinary app can get, so some things are out of reach. Better to know before you start:

The full list explains each one.

Documentation

I want to… Start here
Install everything step by step Installation
Write a first script without a phone Your first script
Use my language Python · Node.js · CLI · HTTP · AI agents
Find the right element on a screen Finding elements
Open apps, links and Settings pages, or list what is installed Apps
Point at elements, or record a script Inspector and recorder
Run Appium scripts Appium and WebDriver
Test with pytest or Node.js Test frameworks
Copy a working pattern Recipes
Look up a command Command reference
Reach phones on mobile data Remote phones
Fix something that does not work Troubleshooting
Understand the wire format spec/PROTOCOL.md

Build from source

Requirements: Go 1.26+, Node.js 22, Python 3.9+, and for the app, JDK 17+ with the Android SDK (Android Studio's bundled JDK works).

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 runs the server, the simulated phone and both SDK demos together, which is what CI does.

Path What it is
spec/ commands.json (every command, in three languages), PROTOCOL.md, crypto test vectors
server/ Go: droidline (server, CLI, MCP), droidline-relay, droidline-fakephone
agent/ The Android app, in Kotlin
sdk/python, sdk/node, sdk/dotnet Official SDKs, generated from the spec plus a thin client
relay/worker A relay for Cloudflare Workers
examples/ Demo scripts that run against the simulated phone

Contributing

Pull requests are welcome; CONTRIBUTING.md explains how the spec, generator and tests fit together. The most useful contribution right now is a report from a real phone: which brand and Android version, and whether the Settings recipes for force stop, clearing data and the network switches work with its labels. If Droidline saves you some taps, a ⭐ helps other people find it.

Status

Version 0.1. The server, CLI, MCP adapter, relay and both SDKs pass their tests against the phone simulator, and the app passes its unit tests and runs on an Android 13 emulator. Testing across phone brands is the next step. docs/STATUS.md lists exactly what has been verified and how.

Security and privacy

Pairing decides who may control a phone, and everything after the handshake is encrypted end to end. Report security problems privately as described in SECURITY.md.

Droidline collects no usage data and sends no telemetry. The server listens on your own machine; the app talks only to the PC it is paired with, and to GitHub once a day to check for a new release. Use Droidline on phones and accounts you own or may automate; the terms say what it is for.

License

MIT. See LICENSE.

Star history

Droidline (KnifeLemon/Droidline)

正在搜索数据库…

这是什么?Droidline 让你可以通过自己的代码控制真实的 Android 手机:用 Python、Node.js、C#、命令行、HTTP,或作为 MCP 工具编写脚本,实现点击、输入、读取和查看手机屏幕,无需 ADB 数据线、无需开启 USB 调试,也无需 root 权限。
这是库还是独立服务器?它是一个小型 Go 服务器(droidline serve),你在电脑上运行它,并与手机上的代理应用配对。Python、Node.js、C#、命令行和 HTTP 接口都只是连接同一台服务器的客户端,此外它还提供 MCP 工具供 AI 代理使用。
我该怎么把它跑起来?在电脑上运行从 Releases 下载的 droidline server 二进制文件,在手机上安装 droidline-agent.apk 并开启其无障碍服务和相关权限,然后通过扫描二维码或输入 6 位数字码完成配对,即可开始发送命令。
手机本身需要什么?只需在 Android 9+ 手机上安装 Droidline 应用,并启用其无障碍服务、键盘和通知权限,无需开发者选项,也无需 USB 调试。
它不能做什么?它无法解锁锁屏,无法打开其他应用未导出的页面,也无法通过单个内置命令强制停止应用、清除应用数据或切换网络。这些操作需要通过配方(recipes)点击设置按钮来完成;使用自绘界面的游戏则需要改用坐标点击。
服务器能在任何电脑上运行,手机也都能控制吗?服务器二进制文件可在 Windows、macOS 或 Linux 上运行,可控制运行 Android 9 及以上版本的手机。连接方式可以是同一 Wi-Fi、隧道,或你自行部署的中继服务。
电脑和手机之间的连接加密吗?Droidline 会回传数据吗?配对之后的每条通信都使用 P-256 和 AES-256-GCM 进行端到端加密。Droidline 不收集任何使用数据或遥测信息,仅每天向 GitHub 检查一次是否有新版本发布。
AI 代理真的能通过它控制手机吗?能。Droidline 提供 MCP 工具,Claude、ChatGPT 或 Cursor 等代理可以通过 dump() 以元素树的形式读取屏幕并进行操作,你还可以用 --tools 或 --read-only 等参数限制其权限。
我能同时运行一整排手机吗?可以。一台电脑可以驱动一排手机:发往同一部手机的命令按顺序执行,不同手机则并行运行。每部手机都有自己的名称,并可选择按应用设置代理。
如何连接不在我 Wi-Fi 下的手机?手机始终主动发起连接,因此可以通过端口转发、cloudflared 或 ngrok 等隧道,或你自行部署在 Cloudflare Workers 或 VPS 上的中继服务来连接;有 Wi-Fi 时则回退到 Wi-Fi。
命令执行途中手机断网会怎样?手机会从断开处精确地恢复,正在执行的命令会直接从缓存中返回结果而不会重复执行。因此,切换飞行模式这类多步操作可以作为一次可靠的调用完成。
大小
2.8 MB
星标
550
时长
1个月
提交 · 90 天