DroidAction Studio 1.0

DroidAction Studio — настольная IDE для автоматизации Android-телефона через Android Debug Bridge (ADB). Проект запускается на Linux, позволяет писать сценарии, наблюдать за экраном подключённого телефона и запускать установленные Android-приложения.

Branding: Made by VEYRA · Developer: Abduali · License: MIT

При запуске показывается короткая анимация MADE BY VEYRA; автора проекта можно также увидеть в меню Справка → О программе.

Возможности

• Экран Android для просмотра. Студия периодически получает скриншоты устройства через ADB. Предпросмотр не принимает клики и не отправляет касания сам по себе.
• Редактор сценариев .das. Номера строк, подсветка команд, строк и комментариев, сохранение/открытие файлов, позиция курсора и переход к строке ошибки.
• Собственный безопасный DSL. Каждая строка содержит одну команду. Сценарии разбираются через AST и список разрешённых команд; произвольный Python-код не запускается.
• Отладка выполнения. Запуск, остановка, пауза между командами и выполнение одного шага.
• План запуска. Читабельный список предполагаемых действий и предупреждений без отправки команд устройству.
• Поиск и запуск приложений. Ищет доступные к запуску приложения на телефоне; поддерживает быстрые действия для известных пакетов и поиск по названию/идентификатору.
• UI-селекторы. Поиск элементов Android по тексту, описанию доступности или resource-id, если приложение публикует соответствующее дерево интерфейса.
• Диагностика. Скрипт doctor.py проверяет Python, PySide6, ADB, структуру проекта и состояние подключённых устройств.
• Linux setup-скрипты. Есть сценарии установки для Arch Linux, Debian/Ubuntu, Fedora и openSUSE Tumbleweed, а также пользовательский ярлык в меню приложений.
• Полноэкранный режим. F11 включает/выключает его, Esc выходит из полноэкранного режима; верхние кнопки управления окном остаются доступны в обычном режиме.

Требования

• Linux с графической сессией (X11 или Wayland — в зависимости от рабочего окружения и Qt-плагинов).
• Python 3.10 или новее.
• PySide6 6.6 или новее.
• Android Platform Tools с командой adb.
• Android-телефон с включённой USB-отладкой, разблокированным экраном и подтверждённым запросом доверия к этому компьютеру.

Для большинства функций не требуется root на Linux или root на Android. Не запускай приложение через sudo. Используй sudo только тогда, когда установщик пакетов просит разрешение для системных пакетов.

Установка

Скачай архив релиза и распакуй его. Либо клонируй репозиторий, если работаешь с Git.

Автоматическая установка

В терминале перейди в папку проекта и выполни:

chmod +x setup.sh run.sh install-user.sh
./setup.sh

setup.sh определяет дистрибутив и передаёт управление подходящему установщику:

Дистрибутив	Скрипт	Что устанавливается
Arch Linux и совместимые	scripts/setup-arch.sh	python, pyside6, android-tools, xdg-utils через pacman; виртуальная среда видит системный PySide6
Debian / Ubuntu и совместимые	scripts/setup-debian.sh	Python, venv, ADB и системные библиотеки через apt; PySide6 ставится в .venv
Fedora	scripts/setup-fedora.sh	Python, ADB и библиотеки через dnf; PySide6 ставится в .venv
openSUSE Tumbleweed	scripts/setup-opensuse.sh	Python, ADB и зависимости через zypper; PySide6 ставится в .venv

Скрипт попросит sudo только для установки системных пакетов. На системах, не перечисленных выше, установи Python 3.10+, PySide6 6.6+ и Android Platform Tools вручную, а затем выполни проверку.

Arch Linux вручную

sudo pacman -S --needed python pyside6 android-tools xdg-utils
python -m venv --system-site-packages .venv
./run.sh

Debian / Ubuntu вручную

sudo apt update
sudo apt install -y python3 python3-venv python3-pip adb xdg-utils \
  libxcb-cursor0 libxkbcommon-x11-0 libegl1 libgl1
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
./run.sh

Fedora вручную

sudo dnf install -y python3 python3-pip android-tools xdg-utils \
  mesa-libGL libxkbcommon-x11 xcb-util-cursor
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
./run.sh

Запуск

После настройки зависимостей запускай программу из папки проекта:

./run.sh

run.sh использует .venv/bin/python, если виртуальная среда создана установщиком; в противном случае запускает системный python3.

Опциональная установка как Python-приложения

Внутри отдельной виртуальной среды можно установить проект вместе с командой droidaction-studio:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install .
droidaction-studio

Этот способ подходит, когда зависимости PySide6 нужно изолировать от системного Python. Команда droidaction-doctor запускает диагностику окружения. Для обычного использования из распакованной папки проще запустить ./setup.sh, а затем ./run.sh.

Ярлык в меню приложений

Чтобы добавить пункт DroidAction Studio в меню рабочего стола текущего пользователя:

./install-user.sh

Это создаёт ~/.local/bin/droidaction-studio, .desktop-ярлык и пользовательскую копию SVG-иконки. Установщик не копирует исходники — ярлык указывает на текущую папку проекта, поэтому не перемещай и не удаляй её после установки ярлыка.

Удалить только ярлык можно так:

./uninstall-user.sh

Команда не удаляет сам проект, настройки системы или зависимости.

Подключение Android-телефона

1. На телефоне открой Настройки → О телефоне и несколько раз нажми на Номер сборки, чтобы включить параметры разработчика. Пункты меню могут отличаться у производителя.

2. В параметрах разработчика включи USB-отладку.

3. Подключи телефон кабелем USB, разблокируй экран и подтверди диалог «Разрешить USB-отладку».

4. Проверь соединение:

   adb devices -l

   Телефон должен иметь состояние device. unauthorized означает, что разрешение не подтверждено; offline обычно требует переподключения или перезапуска ADB.

5. Запусти ./run.sh и нажми «Найти телефон», если устройство не выбрано автоматически.

Если подключено несколько устройств, явно выбери нужный телефон в выпадающем списке перед запуском сценария.

Быстрая диагностика и тесты

python3 doctor.py
python3 -m py_compile main.py engine.py doctor.py
python3 -m unittest discover -s tests -v
./scripts/validate-release.sh

На Debian/Ubuntu/Fedora/openSUSE, где PySide6 лежит в .venv, запускай диагностику именно в той среде:

.venv/bin/python doctor.py

или используй ./scripts/validate-release.sh, который автоматически выбирает Python из .venv, если он доступен.

Тесты разбора сценариев не требуют подключённого телефона. Они подменяют вызовы ADB, когда проверяют действия двигателя. Тесты наличия элементов интерфейса выполняют статические проверки исходников и не заменяют проверку окна в настоящей графической сессии.

Анимация запуска и авторство

При запуске на экране показывается короткая анимированная заставка:

• DroidAction Studio — название программы;
• MADE BY VEYRA — брендинг заставки;
• Developer · Abduali — разработчик.

Заставку можно пропустить нажатием Esc, Enter, Space или щелчком мыши. Авторство также отображается в Справка → О программе. Информация об авторстве не означает, что сторонние библиотеки принадлежат проекту: их лицензии остаются у соответствующих правообладателей.

Горячие клавиши

Клавиши	Действие
F5	Запустить текущий сценарий
Shift+F5	Остановить сценарий
F6	Пауза / продолжение между командами
F10	Выполнить один шаг во время паузы
F11	Переключить полноэкранный режим
Esc	Выйти из полноэкранного режима; на заставке — пропустить её
Ctrl+S	Сохранить сценарий
Ctrl+Shift+S	Сохранить сценарий как…
Ctrl+Shift+V	Проверить сценарий без выполнения на телефоне

Пауза не может отменить ADB-команду, которая уже отправлена и выполняется. Команда Стоп останавливает сценарий между шагами, но не всегда может отменить уже запущенную операцию Android.

Язык сценариев

Файлы сценариев обычно имеют расширение .das. Одна строка — одна команда; пустые строки и комментарии с # игнорируются. Поддерживаются только явно разрешённые команды. Python-выражения, импорт модулей, циклы, произвольные функции и вычисления запрещены.

Пример

# Открыть Настройки Android и дождаться приложения
press("HOME")
open_app("com.android.settings")
wait_app("com.android.settings", timeout=10)
assert_app("com.android.settings")
screenshot("settings.png")
press("HOME")

Команды

wait(1.5)
press("HOME")
tap(300, 700)
swipe(400, 1100, 400, 300, duration_ms=350)
swipe_screen("down")
type_text("Hello world")
open_app("com.whatsapp")
close_app("com.whatsapp")
set_brightness(128)
brightness_test()
screenshot("result.png")
tap_text("Continue")
tap_desc("Search")
tap_id("com.example:id/button")
wait_text("Welcome", timeout=10)
assert_text("Welcome")
wait_app("com.android.settings", timeout=10)
assert_app("com.android.settings")
dump_ui()

Команда	Назначение
wait(seconds)	Подождать заданное количество секунд; диапазон ограничен валидатором
press(key)	Отправить разрешённую системную клавишу, например HOME, BACK, ENTER, APP_SWITCH, VOLUME_UP
tap(x, y)	Нажать координаты экрана телефона
swipe(x1, y1, x2, y2, duration_ms=350)	Выполнить жест по координатам
swipe_screen(direction)	Жест направления up, down, left или right
type_text(text)	Ввести текст; доступный набор символов ограничен
open_app(package)	Запустить приложение по идентификатору пакета
close_app(package)	Принудительно остановить пакет — возможна потеря несохранённых данных
set_brightness(value)	Установить яркость, обычно в диапазоне 0–255
brightness_test()	Временно проверить несколько значений и попытаться вернуть исходные настройки
screenshot(filename)	Сохранить скриншот в папку captures/
tap_text(text)	Найти доступный элемент по тексту и нажать его
tap_desc(text)	Найти доступный элемент по content-description и нажать его
tap_id(resource_id)	Найти элемент по resource-id и нажать его
wait_text(text, timeout=10)	Дождаться появления текста в UI-дереве
assert_text(text)	Ошибка, если текст не найден в UI-дереве
wait_app(package, timeout=10)	Дождаться, пока пакет определится как приложение на переднем плане
assert_app(package)	Проверить приложение на переднем плане
dump_ui()	Получить XML-дерево доступных элементов в captures/ui_dump.xml

Параметры и ограничения проверяются функцией validate_script() в engine.py. При ошибке студия показывает сообщение и пытается перейти к указанной строке.

Важные ограничения

• Это настольная IDE для автоматизации, а не замена официальной Android Studio и не эмулятор Android.
• Превью использует повторяющиеся скриншоты через ADB, а не видео-поток, поэтому небольшая задержка ожидаема.
• UI-селекторы работают только с элементами, которые Android-приложение предоставляет в accessibility/UI-дереве. Игры, canvas/WebView-контент и защищённые экраны могут не публиковать нужные элементы.
• wait_app и assert_app зависят от вывода dumpsys, который может различаться между производителями и версиями Android.
• dump_ui() может сохранить видимый текст личных сообщений или других чувствительных экранов в локальный XML. Не запускай её на личных экранах, если не хочешь сохранять их содержимое.
• brightness_test() пытается восстановить предыдущие значения, но производитель может ограничивать управление настройками, и восстановление не гарантируется на каждой прошивке.
• Пункты списка приложений определяются через ADB; некоторые системные приложения или приложения без launcher activity могут не отображаться как запускаемые.
• Для графического интерфейса необходимо рабочее окружение Linux. В контейнере или SSH-сессии без графического сервера окно не откроется.

Перед запуском незнакомого сценария прочитай его и используй «План запуска». Предпросмотр только объясняет команды; после отдельного нажатия «Выполнить код» они действительно выполняются на подключённом телефоне.

Структура проекта

.
├── main.py                    # PySide6 GUI, splash, editor, phone preview
├── engine.py                  # DSL parser, validation, ADB command engine
├── doctor.py                  # Environment and device diagnostic
├── run.sh                     # Run app with venv/system Python
├── setup.sh                   # Linux distro detection
├── install-user.sh            # Desktop launcher registration
├── uninstall-user.sh          # Remove user launcher registration
├── scripts/                   # Per-distro setup and release validation
├── desktop/                   # Desktop-entry template
├── assets/                    # SVG application icon
├── examples/                  # Ready-to-open .das scripts
├── tests/                     # Automated local tests
├── captures/                  # Local screenshots/UI dumps (ignored by Git)
├── LICENSE                    # MIT License
├── SECURITY.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── VERSION
└── .gitignore

License and credits

DroidAction Studio is distributed under the MIT License. Copyright (c) 2026 Abduali.

Made by VEYRA · Developer: Abduali.