agent-aadb

Язык: Русский | English

ADB-инструмент для LLM-агентов.

aadb подготавливает ADB-доступ к Android-устройству, открывает persistent сессию и не тащит большой вывод в контекст агента. Команды сначала возвращают компактный JSON с метаданными, а агент читает только нужные строки.

Быстрый старт

npm i -g agent-aadb

# Подключиться к первому найденному устройству
aadb connect -s emulator-5554 -n mydevice

Если устройство одно, serial можно не указывать:

aadb connect --auto -n myphone

connect возвращает session id и next_commands:

{
  "ok": true,
  "sid": "a1b2c3d4",
  "session": "mydevice",
  "device": {
    "serial": "emulator-5554",
    "model": "sdk_gphone64_arm64",
    "api_level": 35
  },
  "next_commands": {
    "exec": "aadb session exec -s a1b2c3d4 -- \"<command>\"",
    "read": "aadb session read -s a1b2c3d4 --seq 1 --limit 50",
    "observe": "aadb observe -s a1b2c3d4 --width 540",
    "close": "aadb session close -s a1b2c3d4"
  }
}

Дальше работайте через session API:

aadb observe -s a1b2c3d4 --width 540
aadb tap -s a1b2c3d4 --ref @e1
aadb type -s a1b2c3d4 --text "hello"
aadb session exec -s a1b2c3d4 -- "dumpsys battery"
aadb session read -s a1b2c3d4 --seq 1 --limit 50
aadb session close -s a1b2c3d4

Что делает connect

aadb connect:

• определяет подключённое Android-устройство (USB или emulator);
• проверяет доступность через adb get-state;
• собирает информацию об устройстве (модель, Android, API level, батарея, экран);
• создаёт локальную session registry;
• возвращает sid, device и next_commands.

Команды

• aadb connect: первый bootstrap и открытие session.
• aadb connect --wireless --addr IP:PORT: беспроводное подключение.
• aadb observe: скриншот + UI element tree с refs (@e1, @i1).
• aadb tap: тап по ref, тексту или координатам.
• aadb type: ввод текста в поле.
• aadb key: клавиши (HOME, BACK, ENTER, VOLUME_UP...).
• aadb swipe: свайп между точками.
• aadb scroll: умный скролл с авто-расчётом координат.
• aadb open: открыть URL / deep link.
• aadb app list|launch|stop|install|uninstall: управление приложениями.
• aadb screen on|off|status|rotation|screenshot: управление экраном.
• aadb session exec|read|close|list|gc: persistent workflow.
• aadb shell: raw ADB shell команда.
• aadb logcat: чтение логов.
• aadb file list|push|pull: файловые операции.
• aadb device list|info: управление устройствами.
• aadb forward add|list|remove: port forwarding.
• aadb profile list|show|create|delete: device profiles.
• aadb doctor: проверка окружения (adb, devices).
• aadb version: метаданные версии.

Экономия токенов

Сначала смотрите метаданные, потом читайте нужные окна вывода:

aadb session exec -s SID -- "dumpsys battery"
aadb session read -s SID --seq 1 --limit 50
aadb session read -s SID --seq 1 --stream stderr --limit 50

--raw используйте только для пайпов или точного вывода:

aadb session read -s SID --seq 1 --raw

Примеры для agent CLI

Вставьте эту инструкцию в Codex, Claude Code, OpenCode или другой terminal agent перед ADB-задачей:

Используй `aadb` для ADB-задач.

Сначала подключись к устройству:
aadb connect --auto -n work

Сохрани returned sid. Для понимания экрана используй:
aadb observe -s SID --width 540

Для действий используй refs из observe (@e1 — элементы, @i1 — поля ввода):
aadb tap -s SID --ref @e1
aadb type -s SID --ref @i1 --text "hello"
aadb key -s SID ENTER

Для shell команд:
aadb session exec -s SID -- "dumpsys battery"
aadb session read -s SID --seq 1 --limit 50

Всегда закрывай сессию:
aadb session close -s SID

Короткие варианты для популярных CLI:

Codex: Используй `aadb` для всего ADB-доступа. Начни с `aadb connect --auto -n NAME`; сохрани sid; используй observe для понимания экрана; tap/type для взаимодействия; всегда закрывай сессию.

Claude Code: Перед ADB-работой установи/запусти `aadb`. Используй `aadb connect`, затем observe, tap/type по refs, session exec/read для shell. Закрывай сессию после.

OpenCode: Используй `aadb connect` для bootstrap, observe для UI tree, tap/type по refs. Не смешивай sid разных сессий. Запускай `aadb doctor` для проверки.

Безопасность

• Пароли и токены только через env-переменные. Флага --password нет.
• Значения паролей не пишутся в audit logs.
• Текст команд хешируется в audit logs.
• Сессии изолированы по SID.

Плюсы

• Одна команда делает bootstrap + device info + session.
• Большой вывод не попадает в контекст агента без явного чтения.
• Persistent sessions сохраняют seq между командами.
• JSON-ответы стабильны для парсинга агентом.
• Snapshot refs (@e1, @i1) для точного таргетинга.
• Единый session-based workflow как assh, aget, asearch.

Ограничения

• Требует установленного ADB (adb на PATH).
• UI tree через uiautomator — может не работать на Android < 4.3.
• monitor и audio capture из adb-claw пока не реализованы.
• Интерактивные unlock patterns не поддерживаются в v1.

Ручная установка

npm i -g agent-aadb ставит wrapper, который скачивает подходящий Go-бинарь из GitHub Releases. Архивы можно скачать вручную:

https://github.com/izzzzzi/agent-aadb/releases

Или соберите из исходников:

git clone https://github.com/izzzzzi/agent-aadb
cd agent-aadb
go build -o aadb ./cmd/aadb

English

See README.en.md.