Repository navigation
Releases
v0.6.1
pilotdroid v0.6.1 — release notes draft
Paste into the v0.6.1 GitHub Release body. Source of truth for the
publish step; keep in sync withmainuntil the tag lands.
Device-side UiAutomation agent for Android: single-jar dex under
app_process + pilotdroid-cli (agent.jar embedded — one binary does
setup/serve/bench) + import pilotdroid uiautomator2 drop-in shim +
stdio MCP server (27 tools).
What's new in 0.6.1 (M14–M19)
u2shim API 面补齐 — openatx 官方套件 verbatim 0/27 → 8/30 pass
- Ran the pinned upstream
mobile_testssuite (openatx/uiautomator2
@96f581d, vendored underspike/e2e/u2suite/with a serial-pin-only
seam): 8 pass / 14 fail / 8 skip. All 14 fails attributed — 9
xpath (explicitly unsupported), 1 G6jsonrpc, 1 G8 session object
model, 3 G10 settings semantics (documented defers in
compat/SUPPORTED.md). - New shim surface (zero protocol changes):
settingstransparent
dict,uiautomator2.exceptionsstubs (SessionBrokenError,
UiObjectNotFoundError),Session,watch_contextctx-mgr,
_Selector.get_text,app_startfront-wait +stop=,click
implicit wait,swipehost-side duration sleep,push/pull
(BytesIO),wlan_ip,app_list_running,
app_auto_grant_permissions,app_current.pid,_WhenCtx.call,
Device ctx-mgr. - Three real bugs the suite exposed, fixed: watcher exited instantly
with zero rules (keep-alive until explicit stop); a long
_Selector.waitstarved the single control connection (sliced to
≤1s polls);_WhenCtx.callwas arming a device-sideclickinstead
of staying observation-only (nowaction:"none", callbacks invoked
host-side).
pip install pilotdroid now ships a working CLI
- New
pilotdroid-cli/pilotdroidconsole scripts lazy-download the
matching release binary on first run — sha256-verified against
SHA256SUMS.txt(cache-hit re-verified; refuses unverified bytes),
cached under~/.cache/pilotdroid/<tag>/,os.execvpassthrough.
Unblocks the MCP registryuvx pilotdroidpath. PILOTDROID_SERIALenv var as device fallback when-sis absent.
Supply-chain & CI hardening
agent-jar-reproCI job rebuildsagent.jarfrom source
(javac 25 + build-tools 37.0.0 + android-34) and asserts byte-identity
with the committed jar — dex provenance is now verifiable, not just
commit-ordering.- CodeQL scanning (python + java) on push/PR/weekly.
adb_client2.1.15 → 4.0.0; shell exit codes preserved via
__PD_EXIT_marker + subshell wrap.
Docs & compat honesty
- Selector environment-sensitivity documented (zh-locale text/desc,
first-launch flow-state, MIUI app-lock FLAG_SECURE gates). - README live-view demo GIF; MCP registry manifest draft
(docs/mcp/, schema-validated, submit after PyPI).
Fixed
- verify-agent deterministic
shot_scalefailure: batch tap could open
a MIUI app-lock gate → FLAG_SECURE → screenshot error payload; now
backs out after batch + readable agent error instead ofKeyError. - u2shim failure hint no longer points at a
pilotdroid setupcommand
that doesn't exist in the wheel.
Base release (v0.6.0, M10–M13, agent 0.7.0 / caps 0x7ff)
Async WATCH — event-driven watchers that don't block (CAP_WATCH_ASYNC)
WATCH_ARM/WATCH_DISARM; hits arrive asWATCH_HITon the media
channel — control ops stay fully usable while armed. Measured: 40 ops
during an armed watcher, op p50 = 43ms (same magnitude as unarmed).- Shim
d.watcher.when(...).click()now uses device-async semantics on
agent ≥0.7.0 (u2 watcher-equivalent); older agents fall back to
blocking WATCH, then host polling. - MCP serve:
watch_arm/watch_disarm/watch_eventstools. Limits:
max 8 armed watchers (ERR_LIMIT),watch_eventsreturns
{type:"timeout"}instead of an error on quiet media.
Multi-pointer gestures (CAP_MULTI_PTR)
pinch_in/pinch_outin shim and serve. Shim clamps to display and
rejects fully off-screen bounds (MIUI ghost bounds → LookupError).
conn-side APP_INFO (CAP_APP_INFO)
app_current/app_waitresolve the foreground app over the agent
conn — ~51ms vs ~96ms adb spawn (~2×, low variance, no fork).
Near-complete u2 compat surface
- SUPPORTED.md ❌ is down to
xpathonly (explicitly out of scope).
New this release:app_wait/session/send_keys/open_notification/
open_quick_settings/freeze_rotation,instancealias, host
post-filter keys (*Contains/*StartsWith/*Matches, attr filters,
.count/.wait_gone, relative.left/.right/.up/.down/.child/.sibling),
u2-parityindex(XML child-position) vsinstance(Nth-match).
Real-script re-run: 23 ok / 1 unsupported(xpath) / 0 error.
Resilience & ops
- Dead/replaced control conn self-heals (lazy reconnect, ADR-007);
conn-replaced events warn on stderr (stdout stays pure JSON-RPC).
One serve per device — two instances ping-pong conn ownership. verify-agent.sh: lockscreen-proof runs (screen_off_timeout pinned +
restore), transition-stall settle, hijack retry — 37/37 green.
Benchmarks (ba0d072d, USB)
| scenario | pilotdroid | u2 | |
|---|---|---|---|
| watcher popup auto-heal (appear→dismiss, same-arm) | ~680ms | ~1790ms | 2.6× |
| detect+act floor, hot conn | 39ms | — | device-side WATCH |
| same-script e2e (M7) | — | — | 8.8× USB / 4.7–7.4× TCP |
Assets
pilotdroid-cli-linux-x86_64 · pilotdroid-cli-macos-arm64 ·
pilotdroid-cli-windows-x86_64.exe · agent.jar ·
pilotdroid-0.6.1-py3-none-any.whl + sdist · SHA256SUMS.txt
- macOS: unsigned —
xattr -d com.apple.quarantine pilotdroid-cli,
orbrew install mofanx/pilotdroid/pilotdroid - Windows: unsigned — SmartScreen "More info → Run anyway", or
Unblock-Filein PowerShell. Compile-verified only — the build
passes CI but hasn't run on a real Windows machine; report issues. - PyPI:
pip install pilotdroid
Full Changelog: v0.6.0...v0.6.1