serve-droid

serve-droid

Общий браузерный кокпит и панель управления Android для стриминга эмулятора или физического устройства, управления им из Chrome или Edge, осмотра его семантического дерева UI и Logcat либо передачи той же сессии MCP-совместимому агенту кодирования.

Статус: v0.1 разработочный релиз. Публичный API версионирован, но транспорт видео и совместимость устройств всё ещё требуют валидации на опубликованной матрице поддержки.

npx serve-droid
# → Browser cockpit at a local authenticated URL

• Одна общая сессия: компактные элементы управления активным устройством остаются слева, а живая Android-поверхность занимает основную рабочую область. На широких экранах агент контекстно плавает справа и переключается между фильтрованным Logcat, семантическим UI и приватным Activity; на более узких окнах он размещается под устройством, не уменьшая поверхность взаимодействия. Детерминированное демо также выполняет проверку аутентифицированной установки файлов и буфера обмена. Это не реальная замен-проверка; аппаратные доказательства отслеживаются отдельно в контрольном списке релиза.*

Related MCP server: Android MCP

Что вы получаете

• H.264 стриминг устройства в отзывчивом браузерном кокпите с прямыми событиями указателя DOWN, коалесцированными MOVE и UP/CANCEL, переносимыми той же живой scrcpy-сессией перед релизом.

• Прокрутка колесом мыши и трекпадом по устройству, коалесцированные в ограниченные сенсорные жесты scrcpy, так что ввод с браузера с высоким разрешением не может создать очередь команд устройства.

• Одно-кликовый захват экрана с декодированного живого кадра, с опциональным буфером обмена, предпросмотром, загрузкой и поддерживаемыми браузером действиями буфера обмена.

• Точное семантическое таргетирование, останавливающееся на отсутствующих или неоднозначных целях.

• Logcat с приоритетной фильтрацией, паузой, очисткой и копированием.

• Явные элементы управления громкостью системы Android в рейле устройства, отдельно от отключения звука в браузере.

• С фильтром приватности временная шкала Activity для недавних структурированных событий устройства, сессии и управления.

• Безопасный обмен токеном LAN и ограниченный буфер обмена для вставки в фокусированное поле Android.

• Перетаскивание APK или передача файлов с прогрессом в байтах и явной фазой обработки Android.

• Одно ограниченное наблюдение, содержащее иерархию UI, объект переднего плана, состояние устройства и инкрементальные логи.

• Те же возможности через CLI, аутентифицированные HTTP/WebSocket API, MCP и Agent Skill.

Зачем

Android Studio зеркалирует устройства, scrcpy предоставляет отличное управление/контроль, а Maestro является сильной системой автоматизации тестирования. serve-droid фокусируется на другом цикле: человек и ИИ-агент, делящие один наблюдаемый сеанс браузера во время разработки и отладки.

Вдохновение

Направление браузера-первым было вдохновлено Evan Bacon's serve-sim. serve-droid — независимая Android-ориентированная реализация, построенная вокруг ADB-транспорта, scrcpy, Logcat, семантических наблюдений и MCP.

Требования

• Node.js 22 или новее

• Android SDK Platform Tools сравнения с adb в PATH, ANDROID_HOME или ANDROID_SDK_ROOT

• Android 8 / API 26+ эмулятор или устройство, видимое в adb devices -l

• Текущий Chrome, Edge, Safari или Firefox. Chromium использует WebCodecs; Safari и Firefox используют более дорогой программный фолбэк TinyH264.

Инструменты Android Platform никогда не загружаются и не распространяются.

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

npx serve-droid doctor
npx serve-droid doctor --browser
npx serve-droid avd list
npx serve-droid start --detach
npx serve-droid list --json
npx serve-droid activity --since 0 --json

serve-droid activity считывает тот же ограниченный, фильтрованный по приватности таймлайн сессии, который показывает браузерный инспектор. Он выбирает одну живую сессию, аутентифицируется с этой сессией и поддерживает возобновление указателя, не раскрывая токен-носитель. Смотри guide.

При выборе фиксированного порта проверьте его перед тем, как трогать устройство. Занятые порты возвращают стабильный код PORT_IN_USE и статус выхода 31; --port 0 сохраняет предохранительное распределение.

npx serve-droid doctor --port 47321 --json
npx serve-droid start --port 47321

Воспроизведение звука на устройстве - по желанию и браузерный воспроизведение остается без звука до тех пор, пока не включит человек:

npx serve-droid start --audio

Смотри аудио и приватность.

Откройте локальный напечатанный URL. Сервер слушает 127.0.0.1, генерирует случайный токен и вставляет его в локальный UI. Для выбора устройства:

npx serve-droid --device emulator-5554

Установленные эмуляторы можно управлять явно через serve-droid avd start <name> и serve-droid avd stop <serial>. Никакое SDK не загружается и не лицензируется автоматически; смотрите жизненный цикл AVD.

Для инспекции нескольких подключенных устройств с независимыми ресурсами и ограниченными токенами:

npx serve-droid grid --max-devices 4

См. модель безопасности и изоляции multi-device сетки.

Координаты нормированы: (0, 0) - логический верхний левый, а (1, 1) - правый нижний.

npx serve-droid tap 0.5 0.5
npx serve-droid swipe 0.5 0.8 0.5 0.2 --duration 350
npx serve-droid app deep-link 'servedroid://fixture/example'

Неудачные ADB-взаимодействия должны сохранять общие ошибки, если Android не сообщает явный keyguard или input-policy evidence. См. диагностика взаимодействия для контрактов DEVICE_LOCKED, SECURE_SCREEN и INPUT_RESTRICTED.

Прямые указатели браузера теперь стримят аутентифицированный цикл begin → move* → end над управляющим WebSocket, пока курсор или палец еще движется. Браузер задаёт один запрос и один последний move в ожидании, а сервер дает потоку эксклюзивное владение одним пальцем scrcpy и сопоставляет его с фиксированным размером закодированного кадра. Если scrcpy недоступен до begin, запрос отклоняется до ввода устройства, и кокпит безопасно использует существующее ограниченное время. После успешного begin, сбой никогда не повторяется через ADB. Плавающая та же-точка контрольный сигнал держит запущенные долгие нажатия, пока заброшенные потоки получают best-effort отмену после двух секунд бездействия.

В браузере наведите на поверхность Android и используйте колесо мыши или прокрутку двумя пальцами на трекпаде. Поток объединяется в одно ограниченное, закрепленное на курсоре сенсорное смахивание. Жесты масштабирования с изменением остаются нетронутыми.

Захват сеанса явно ограничен. --record ./recordings сохраняет оригинальный поток H.264 плюс фильтрованные по конфиденциальности сводки событий; никогда не записывает токены, Logcat, вводимый текст, URL-адреса или содержимое файлов. Используйте --record-control ./recordings для авторизации запуска/остановки без немедленного Запись; кокпит никогда не выбирает путь или лимит. Смотри guide. Зафинализированные записи также могут быть экспортированы с помощью serve-droid recording trace для проверки в Perfetto.

MCP

{
  "mcpServers": {
    "serve-droid": {
      "command": "npx",
      "args": ["-y", "serve-droid", "mcp"]
    }
  }
}

Поверхность MCP намеренно предоставляет явные ограниченные инструменты, а не произвольный доступ к оболочке. Смотри этот MCP-гайд.

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

• Привязка только к loopback по умолчанию.

• Аутентификационные токены для чтения, изменений, видео и управления.

• Браузерные WebSocket-ы переносят учетные данные в подпротокол-заголовке, а не в URL.

• Не предусмотрена произвольная ADB или хост-оболочка.

• Загрузки ограничены 256 МиБ, записываются в приватную временную директорию и удаляются.

• clear и uninstall требуют подтверждения от неинтерактивных клиентов.

Читайте SECURITY.md перед привязкой к LAN-интерфейсу.

Короткоживущий доступ через существующий именованный Cloudflare Tunnel доступен только с явное согласие, HTTPS, токены и жёсткий срок действия. Читайте модель угроз туннеля и руководство перед использованием.

Поддержено и отложено

v0.1 нацелен на macOS, Linux, Windows, Android API 26+, локальные устройства, USB Wi-Fi ADB, Chrome, Edge, Safari и Firefox. Включены управление жизненным циклом установленных AVD, opt-in ограниченная локальная запись, фолбэк TinyH264, opt-in device audio для API 30+ и opt-in Named-туннель поддержка. Облачные устройства, аккаунты, мультиюзеровые роли, создание/предоставление AVD, iOS и произвольный доступ к оболочке отложены. Смотри матрицу поддержки браузера.

Разработка

pnpm install
pnpm verify
pnpm --filter @serve-droid/cli dev -- doctor

Исходный код Android-фикстуры находится в fixtures/android-test-app. Тесты на реальном устройстве выполняются только когда SERVE_DROID_DEVICE_TEST=1 установлена.

Смотри контрольный список релиза на основе доказательств для завершенных работ и для оставшихся аппаратных, программных и публикационных гейтов.

TODO проекта

• Опубликовать открытый репозиторий с защитой main, CodeQL, Dependabot и секретами.

• Отправить общий CLI, HTTP/WebSocket, Agent, скилл браузера и фундамент кокпита.

• Добавить воспроизводимый, явно подписанный скриншот кокпита в этот README.

• Улучшить браузерный кокпит до адаптивного рабочего пространства с контекстным инспектором.

• Добавить поискаемый Logcat с приоритетной фильтрацией, паузой, очисткой и копированием.

• Добавить ограниченную приватностью Activity в браузере, CLI и аутентифицированном HTTP.

• Добавить безопасную передачу LAN-токена и ограниченный буфер обмена браузера.

• Добавить объединенное колесо мыши и трекпад прокрутки над поверхностью Android.

• Направить указатель браузера и ввод жеста через активный канал управления scrcpy.

• Стримить прямое движение указателя перед релизом с ограниченным объединением и отменой.

• Завершить матрицу приемки на реальных устройствах на macOS, Linux и Windows.

• Опубликовать и подтвердить npm release кандидата до тега v0.1.0.

Полный контрольный список на основе доказательств находится в docs/TODO.md. Пункты остаются резиновыми до тех пор, пока репозиторий не содержит реализацию или требуемое внешнее доказательство.

Лицензия

Apache-2.0. См. THIRD_PARTY_NOTICES.md.

Let's verify the translation: We translated "Status" line, but there is "> Статус: v0.1 development release. The public API is versioned, but video transport and device compatibility still..." we wrote "Статус: v0.1 разработочный релиз." Actually original: "> Status: v0.1 development release. The public API is versioned, but video transport and device compatibility still need validation on the published support matrix."

We need to keep "Status:"? The original has "> Status: v0.1 development release. The public API ... support matrix." Might better to translate.

We need preserve exact line. ">Статус: выпуск разработки v0.1. Публичный API версионирован, но видеотранспорт и совместимость устройств..." Good.

We have to preserve the HTML heading? Actually it's not HTML, it's markdown blockquote.

Now "GXP2" etc. Keep as is.

For image alt we translated? We translated alt text to Russian: "кокпит serve-droid с активными элементами управления Android, компактным инспектором Activity и Logcat, прогрессом установки файлов и буфером обмена". The source path docs/assets... kept.

Ensure all text outside code spans translated.

Let's check the code spans:

• "capture" maybe not "capture"? Actually inline code like --capture ./recording is code, keep as is? But the text around it translated.

The list of bullets: Keep the bullet indicators "- " and translate the text.

I'll now produce final answer. We need to ensure every item is represented.

Also the "GXP1" lines: The original has "GXP1" after a paragraph; keep.

"GXP3" etc.

Also in the "## Development" section, "GXP9" maybe? Actually input: "GXP9" - keep.

Need to check: The heading "## Serve-droid" - Actually "# serve-droid" is a heading. We'll keep as is, maybe no space? The original: "# serve-droid" no backticks. It's a product name. We'll output "# serve-droid".

Note: In final answer, the code block language is not rendered; we just output the markdown. Good.

Let's produce with all preserved.## serve-droid

Общий браузерный кокпит и Android-панель управления для стриминга эмулятора или физического устройства, управления им из Chrome или Edge, инспекции его семантического дерева UI и Logcat или передачи той же сессии MCP-совместимому агенту кодирования.

Статус: v0.1 developed. Публичный API версионирован, но видеотранспорт и совместимость с устройствами всё ещё требуют валидации на опубликованной матрице поддержки.

npx serve-droid
# → Browser cockpit at a local authenticated URL

Вместе используемая сессия: компактное управление активным устройством остаётся слева, а живая поверхность Android занимает основное рабочее пространство. На широких экранах агент плавающе инспектирует справа и переключается между фильтрованным Logcat, семантическим UI и приватностью Activity; на более узких окнах он укладывается вниз устройства вместо уменьшения поверхности взаимодействия. Детерминистическое демо также использует аутентифицированную установку файлов и буфер обмена. Она не является реальной валидацией устройства; аппаратное доказательство отслеживается отдельно в контрольном списке релиза.

Что вы получаете

• Поток H.264 с устройства в отзывчивом браузерном кокпите с событий DOWN, объединённых MOVE и UP/CANCEL, переносимыми тем же живым сеансом scrcpy перед релизом.

• Прокрутка колесом мыши и трекпадом по устройству, объединённая в ограниченные сенсорные жесты scrcpy, поэтому ввод с высоким разрешением браузера не может создать очередь команды устройства.

• Одно-кликовый захват кадра с декодированного живого кадра, с дополнительным буфером буфера, предпросмотром, загрузкой и поддержанным буфером обмена.

• Точное семантическое таргетирование останавливается на отсутствующих или неоднозначных целях.

• Поиск Logcat с приоритетной фильтрацией, паузой, очисткой и копированием.

• Явные регулировки громкости системы Android в рейле устройства, отдельно от управления воспроизведением браузера.

• Приватность-фильтрованная временная шкала Activity для недавних структурированных событий устройства, сессии и управляющих событий.

• Безопасная передача LAN-токена и ограниченный буфер буфера для вставки в фокусированное поле Android.

• Перетаскивание APK или передача файлов с прогрессом байтов и явной фазы обработки Android.

• Одно ограниченное наблюдение, содержащее и иерархию UI, переднее приложение, состояние устройства и инкрементальные журналы.

• Те же возможности через CLI, аутентифицированный HTTP/WebSocket API, MCP и Agent Skill.

Зачем

Android Studio отражает устройства, scrcpy обеспечивает отличное управление, Maestro — сильная тестовая система автоматизации. serve-droid сосредоточен на другом цикле: человек и AI-агент делят один наблюдаемый сеанс браузера во время разработки и отладки.

Вдохновение

Направление браузер-первого был вдохновлено Evan Bacon's serve-сим. serve-droid — это независимая Android-ориентированная реализация, построенная вокруг ADB-транспорта, scrcpy, Logcat, семантических наблюдений и MCP.

Требования

• Node.js 22 или новее

• Android SDK Platform Tools с adb в PATH, ANDROID_HOME или ANDROID_SDK_ROOT

• Android 8 / API 26+ эмулятор или устройство, видимое в adb devices -l`* текущий Chrome, Edge, Safari или Firefox. Chromium использует WebCodecs; Safari и Firefox используют более дорогой софтверный резерв TinyH264.

Android Platform Tools никогда не загружаются и не распространяются автоматически.

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

npx serve-droid doctor
npx serve-droid doctor --browser
npx serve-droid avd list
npx serve-droid start --detach
npx serve-droid list --json
npx serve-droid activity --since 0 --json

serve-droid activity считывает той же ограниченной, фильтрованной по конфиденциальности таймлайн сессии, которую показывает инспектор браузера. Он выбирает одну живую сессию, аутентифицируется внутри с этой сессией и поддерживает резюме курсора без раскрытия токена-носителя. См. руководство.

При выборе фиксированного порта проверяйте его перед касательством устройства. Занятые порты возвращают стабильный код PORT_IN_USE и статус выхода 31; --port 0 сохраняет безопасное выделение.

npx serve-droid doctor --port 47321 --json
npx serve-droid start --port 47321

Воспроизведение аудио устройства — opt-in, а воспроизведение браузера остаётся немым, пока его не включит человек:

npx serve-droid start --audio

См. аудио устройства и конфиденциальность.

Откройте локальный URL. Сервер слушает 127.0.0.1, генерирует случайный токен и вводит его в локальный UI. Для выбора устройства:

npx serve-droid --device emulator-5554

Установленными эмуляторами можно явно управлять с помощью serve-droid avd start <имя> и serve-droid avd stop <серийный>. SDK не загружается и не лицензируется автоматически; см. жизненный цикл AVD.

Для инспектирования нескольких подключённых устройств с независимыми ресурсами и ограниченными токенами:

npx serve-droid grid --max-devices 4

См. модель безопасности изоляции многопортовых устройств.

Координаты нормализованы: (0, 0) — логическая верхняя левая точка, а (1, 1) — нижняя правая.

npx serve-droid tap 0.5 0.5
npx serve-droid swipe 0.5 0.8 0.5 0.2 --duration 350
npx serve-droid app deep-link 'servedroid://fixture/example'

Неудачные взаимодействия ADB сохраняют общие ошибки, если Android не выдаёт явные keyguard или политику ввода. См. диагностику сбоев взаимодействия для контрактов с DEVICE_LOCKED, SECURE_SCREEN и INPUT_RESTRICTED.

Прямые события в браузере теперь стримят аутентифицированный жизненный цикл begin → move* → end поверх управляющего WebSocket, пока курсор или палец ещё движется. Браузер держит один запрос и один последний move в ожидании, в то время как сервер даёт потоку исключительное владение одним пальцем scrcpy и сопоставляет его с фиксированным размером кодированного кадра. Если scrcpy недоступен в begin, запрос отклоняется до ввода на устройство, и кокпит безопасно использует существующее ограниченное действие после выпуска. После успешного begin, сбои никогда не выходят из ADB. Разбросанная точка-точка сердцебиения сохраняет длинные нажатия, в то время как запущенные потоки получают best-effort отмену после двух секунд бездействия.

В браузера. hover на Android. используйте колесо мыши или прокрутку двумя пальцами на трекпаде. Поток объединяется в одном ограниченном, курсорно-закреплённом сенсорном сглаживании. Жесты масштабирования с помощью модификатора остаются нетронутыми.

Захват сессии — явный и ограниченный. --capture ./recordings сохраняет исходный поток H.264 в сочетании с фильтрованными по конфиденциальности сводками событий; никогда не записывает токены, Logcat, набранный текст, URL или содержимое файлов. Используйте --record-control ./recordings для авторизации запуска/остановки без немедленного записи; кокпит никогда не выбирают хост или путь. См. руководство по записи и хранению. Финализированные записи также могут быть экспортированы с помощью serve-droid recording trace для проверки в Perfetto.

MCP

{
  "mcpServers": {
    "serve-droid": {
      "command": "npx",
      "args": ["-y", "serve-droid", "mcp"]
    }
  }
}

Поверхность MCP намеренно предоставляет явные ограниченные инструменты вместо произвольного доступа к оболочке. См. руководство MCP.

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

• По умолчанию привязка только к loopback.

• Bearer-аутентификация для чтения, записи, видео и управления.

• Браузерные WebSockets несут учётные данные в подпротоколе-заголовке, а не в URL.

• Нет произвольной конечной точки ADB или хост-оболочки.

• Загрузки ограничены 256 МиБ, записываются в приватный временный каталог и удаляются сразу.

• clear и uninstall требуют явного подтверждения от неинтерактивных клиентов.

Читайте SECURITY.md перед привязкой к интерфейсу LAN.

Краткосрочный доступ через существующий именованный Cloudflare Tunnel доступен только с явного согласия, HTTPS, bearer-аутентификацией и жёстким истечением срока. Прочтите модель угроз и установки туннеля перед его использованием.

Поддерживается и отложено

Нацелен v0.1 на macOS, Linux, Windows, Android API 26+, локальные устройства, USB Wi-Fi ADB, Chrome, Edge, Safari и Firefox. Включены управление жизненным циклом установленных AVD, opt-in ограниченная локальная запись, фолбэк TinyH264, opt-in аудио для API 30+ и opt-in именованного туннеля поддержки. Облачные устройства, учётные записи, многофункциональные роли, создание/подготовка AVD, и произвольный доступ к оболочке отложены. См. матрицу поддержки браузеров.

Разработка

pnpm install
pnpm verify
pnpm --filter @serve-droid/cli dev -- doctor

Исходный код фиксатора Android находится в fixtures/android-test-app. Тесты на реальном устройстве запускаются только тогда, когда SERVE_DROID_DEVICE_TEST=1 установлен.

См. основанный на доказательствах контрольный список релиза для выполненных работ и оставшихся аппаратных, программных и публикационных ворот.

TODO проекта

• Опубликовать открытый репозиторий с защитой main, CodeQL, Dependabot и секретами.

• Отправить общий CLI, HTTP/WebSocket, MCP и браузерный скилл-фундамент.

• Добавить воспроизводимый, чётко подписанный скриншот кокпита в этот README.

• Доработать браузерный кокпит в отзывчивое рабочее пространство с контекстным инспектором.

• Добавить искомый Logcat с приоритетной фильтрацией, паузой, очисткой и копированием.

• Добавить ограниченную конфиденциальность Activity в браузере, CLI и аутентифицированном HTTP.

• Добавить безопасную передачу LAN-токена и ограниченный буфер браузера.

• Добавить объединённую прокрутку колеса мыши и трекпада по поверхности Android.

• Маршрутизировать указатель браузера и ввод жестов через активный канал управления scrcpy.

• Стримить прямое движение указателя перед выпуском с ограниченным объединением и отменой.

• Завершить матрицу приёмки на реальных устройствах на macOS, Linux, Windows.

• Опубликовать и подтвердить npm выпуск кандидата перед тегом v0.1.0.

Полный основанный на доказательствах контрольный список находится в docs/TODO.md. Пункты остаются неотмеченными, пока репозиторий не будет содержать реализацию или необходимое внешнее доказательство.

Лицензия

Apache-2.0. См. THIRD_PARTY_NOTICES.md.