Appium Android Adb

SKILL.md

---
name: appium-android-adb
description: Read and control any Android app via Appium. Provides a persistent bridge daemon (bridge_daemon.py) with dump/tap/scroll/type/wait commands. Use when raw ADB taps don't work (WebView apps, UC WebView) or when you need structured screen reading. Start with start_bridge.sh once, then use bridge_daemon.py for all interactions at ~1-2s per call.
---

# Appium Android Bridge

Generic Appium bridge for any Android app. Reads screens as structured JSON, executes taps/scrolling/typing via accessibility service clicks (bypasses WebView touch filtering).

## Quick Start

```bash
# Once per session (28s, starts Appium + daemon):
bash ~/.openclaw/workspace/skills/appium-android-adb/start_bridge.sh

# Then every action (~1-2s each):
python3 ~/.openclaw/workspace/skills/appium-android-adb/bridge_daemon.py dump
python3 ~/.openclaw/workspace/skills/appium-android-adb/bridge_daemon.py tap '{"text": "查询"}'
python3 ~/.openclaw/workspace/skills/appium-android-adb/bridge_daemon.py scroll '{"direction": "down"}'
```

## Commands

All from `~/.openclaw/workspace/skills/appium-android-adb/`. All return JSON.

### dump — read the screen
```bash
python3 bridge_daemon.py dump
```
Returns:
```json
{
  "ok": true,
  "package": "com.example.app",
  "activity": "...",
  "title": "...",
  "alerts": [{"text": "温馨提示"}],
  "buttons": [{"text": "查询", "id": "btn_search", "bounds": "[99,750][981,882]"}],
  "trains": [{"text": "...", "bounds": "...", "clickable": true}],
  "webview_contexts": ["NATIVE_APP"]
}
```
- `buttons[]` — all clickable elements with text, id, bounds
- `alerts[]` — dialogs/popups needing dismissal
- `trains[]` — elements containing "次列车" (app-agnostic; rename for other apps)
- `title` — page title if present

### tap — click an element
```bash
python3 bridge_daemon.py tap '{"text": "查询车票"}'       # by text (substring match)
python3 bridge_daemon.py tap '{"text": "预订", "index": 0}' # first match
python3 bridge_daemon.py tap '{"id": "btn_submit"}'         # by resource-id
```

### scroll — swipe the screen
```bash
python3 bridge_daemon.py scroll '{"direction": "down"}'               # normal
python3 bridge_daemon.py scroll '{"direction": "down", "distance": "short"}' # fine
python3 bridge_daemon.py scroll '{"direction": "up"}'                 # go back
```
Uses fast drag (100ms) — works best for WebView content.

### type — input text
```bash
python3 bridge_daemon.py type '{"text": "上海"}'
```

### wait — poll until element appears
```bash
python3 bridge_daemon.py wait '{"text": "提交订单", "timeout": 30}'
```

## When to Use This

Use `appium-android-adb` when:
- The app uses WebView (ADB taps are ignored)
- You need structured screen reading (not screenshot-based)
- You need reliable element clicking (accessibility service, not raw touch)
- You're automating a hybrid app (native + WebView)

Do NOT use for:
- Simple native-only apps where `adb shell input tap` works fine
- One-off screenshots (use `adb shell screencap`)

## Troubleshooting

**Daemon died**: Run `start_bridge.sh` again to restart.
**Device not found**: Check USB connection: `adb devices`
**App not launching**: The daemon attaches to the running app. Cold-start the app manually if needed: `adb shell monkey -p <package> 1`