WebAppForAndroid 供研发人员通过浏览器操作已开启 USB 调试的 Android 手机或平板，支持在 Windows、Linux、macOS 上运行。在页面上即可查看设备、管理应用、截图录屏，并用 scrcpy 做互动投屏；也可以把 AAB 签成可安装的通用 APK。
同一局域网内的浏览器均可打开控制台。启动后访问 http://<本机IP>:5001。
- 浏览器即控制台 — 连接、刷新和日常操作都在网页完成，无需再记一套 ADB 命令。
- 覆盖真机调试主路径 — 设备信息、应用安装与启停、截图、录屏、按键、重启和语言设置集中在同一页面。
- USB 与无线调试 — 先用数据线接入，再在页面打开无线调试（端口
5555），同一 Wi-Fi 下可拔线继续操作。 - 互动投屏 — 本机已有当前平台的 scrcpy 时直接使用；没有则在应用启动时从 官方 Release 下载对应包，缓存到
runtime/scrcpy/。 - AAB 转 APK — 用本机证书或现场生成的随机证书，经 bundletool 打出 universal APK，并在浏览器中下载。
环境： Python 3.10+ · Windows / macOS / Linux · 已开启 USB 调试并授权本机的真机。AAB 转化与随机证书另需 JDK（java 与 keytool 在 PATH 中）。
# Windows
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -r requirements.txt# Linux / macOS
python3.12 -m venv .venv
./.venv/bin/python -m pip install -U pip
./.venv/bin/python -m pip install -r requirements.txt运行依赖为 Flask、adbutils、psutil、Pillow。adb 使用 resources/re_adb 里按系统放好的 platform-tools：已在 PATH 中则直接用，否则解压到 resources/runpath/。项目内没有当前平台的 scrcpy 时，应用启动就会从官方 Release 下载，不等到点击投屏。
# Windows
.\.venv\Scripts\python.exe web_function\app.py# Linux / macOS
./.venv/bin/python web_function/app.py服务监听本机局域网地址的 5001 端口，并尝试打开浏览器。日志：runtime/logs/android_app.log（首次运行会创建 runtime/logs/，单文件超过 10MB 后轮转，保留 5 个备份）。
- 在设备上打开开发者选项，开启 USB 调试，并用数据线连接后点「允许 USB 调试」。
- 在页面点击 刷新设备，选择列表中的设备。
- 按页面分区操作：查看设备信息、管理应用、截图或录屏、模拟按键，或启用互动投屏。
- 需要无线调试时，先保持 USB 连接并点击 启用无线调试，确认手机与电脑在同一 Wi-Fi，再拔线。
已连接真机时，可用下面的脚本核对前台应用信息：
.\.venv\Scripts\python.exe tests\test_current_app.py| 区域 | 能力 | 说明 |
|---|---|---|
| 设备 | 列表、详情、打开网址、查看 IP | 详情含型号、品牌、系统与 SDK、CPU、序列号；查看 IP 会在设备上打开查询页 |
| 剪贴板 | 发送文本、从设备读取 | 通过随仓库提供的 Clipper；设备未安装时会自动安装 |
| 应用 | 第三方包名列表、搜索、卸载、安装 APK / XAPK | 支持单个或多个安装；可清缓存后启动，或强制停止 |
| 前台 | 当前包名与 Activity | 需亮屏且有应用在前台 |
| 画面 | 截图、按秒录屏 | 截图写入 runtime/screenshot_and_record/mobile_screenshot/，录屏写入 runtime/screenshot_and_record/mobile_record/，均可在浏览器下载 |
| 按键 | 电源、HOME、菜单、返回、重启 | 电源键用于息屏 / 亮屏 |
| 连接 | 无线调试、scrcpy 互动投屏 | 无线调试使用 5555；投屏使用当前平台的 scrcpy，项目内没有时在应用启动时下载 |
| 系统 | 语言设置、XTest | 打开系统语言页；XTest 会把 xtest-agent 推到 /data/local/tmp/ 后启动 |
| 包体 | AAB 转 universal APK、随机证书、删除证书 | 依赖 runtime/aab_conversion/bundletool.jar 与 JDK；结果在浏览器中下载 |
设备与应用 — 刷新已连接设备，查看型号、系统版本和芯片信息，安装 APK 或 XAPK，卸载、强停，或清缓存后重新启动。
截图与录屏 — 亮屏时可截取当前画面。录屏在页面输入大于 1 秒的时长，结束后把 MP4 拉回本机供下载。锁屏状态下这两项都会失败。
按键、投屏与无线调试 — 模拟电源、HOME、菜单和返回，或重启设备。互动投屏打开 scrcpy 窗口，adb 使用 resources/re_adb 解出的可执行文件。停用投屏会结束本机的 scrcpy 进程。无线调试把设备切到 5555 并用 adb connect 接上。
剪贴板与 XTest — 文本经 Clipper 写入或读出设备剪贴板。启用 XTest 时，若设备上还没有 agent，会先推送 resources/apks/xtest-agent 并赋予可执行权限。
AAB 转化 — 选择已有证书或生成随机 JKS，上传 .aab 后用 bundletool 以 universal 模式签名并解出 APK。证书文件在 runtime/aab_conversion/certificate_folder/，别名与口令记在 certificate_var/certificate_var.json。
web_function/
app.py Web 入口（监听本机局域网 5001）
templates/ 页面模板
static/
wcss/ wjss/ 样式与脚本
wresource/ 图标
backend_function/
adb_utils.py 设备操作、投屏、AAB、剪贴板与 XTest
adb_setup.py 按平台从 resources/re_adb 准备 adb
scrcpy_setup.py 按平台准备或下载 scrcpy
paths.py 仓库根目录
resources/
re_adb/ 各平台 platform-tools 压缩包（随仓库提交）
re_scrcpy/ 仓库自带的 Windows scrcpy，可离线投屏
apks/ Clipper 与 xtest-agent（随仓库提交）
runpath/ 解压后的 adb（首次使用时生成）
runtime/
logs/ 服务日志 android_app.log（首次运行时创建）
scrcpy/ 按当前平台下载的 scrcpy（不提交）
screenshot_and_record/ 截图与录屏（首次使用时创建）
aab_conversion/
bundletool.jar AAB 转化工具（随仓库提交）
certificate_folder/ 签名证书（运行时写入）
download_folder/ 上传的 AAB（运行时）
upload_folder/ 转化得到的 APK（运行时）
tests/
test_current_app.py 前台应用信息的手工检查
test_scrcpy_setup.py 平台选择与 adb 解压的离线检查
页面路由在 web_function/app.py，设备与文件操作在 backend_function/adb_utils.py。
| 文档 | 适合谁 | 说明 |
|---|---|---|
| 本文 | 新用户 | 安装、启动、能力范围 |
| README_en.md | English | 英文说明 |
| LICENSE | 使用与再分发 | MIT 许可 |
列表里没有设备 — 确认数据线、USB 调试，以及设备上已点「允许」。然后点刷新。服务日志在 runtime/logs/android_app.log。
无线调试连不上 — 手机与电脑需在同一 Wi-Fi，且能读到 wlan0 地址。仍失败时，保持 USB 连接，在终端执行一次 adb tcpip 5555，再在页面上启用无线调试。
截图或录屏失败 — 设备需要亮屏解锁。录屏时长须大于 1 秒。文件保存在 runtime/screenshot_and_record/ 下，也可从页面下载。
剪贴板读写失败 — 同样需要亮屏。确认 resources/apks/clipper_1.0.0.apk 还在；未安装时控制台会尝试自动安装。
AAB 转化或随机证书失败 — PATH 中需要 java 和 keytool，且 runtime/aab_conversion/bundletool.jar 存在。转化前先在页面选中一张证书，或先点「生成随机签名」。
互动投屏打不开 — 确认本机能访问 GitHub Releases。已有匹配包时不会重复下载：Windows 可直接用 resources/re_scrcpy 里的 scrcpy，其它平台缓存在 runtime/scrcpy/。官方包目前提供 Windows、Linux x86_64、macOS（Intel 与 Apple Silicon）。停用投屏会结束名为 scrcpy 或 scrcpy.exe 的进程。adb 来自 resources/re_adb，与投屏包无关。
仓库中的 WebAppForAndroidDebugger.spec 已包含页面模板、静态资源、AAB 工具、自带 scrcpy 和 resources/。
.\.venv\Scripts\python.exe -m pip install pyinstaller
.\.venv\Scripts\python.exe -m PyInstaller WebAppForAndroidDebugger.spec产物为 dist\WebAppForAndroidDebugger.exe。目标机器仍需能访问已开启 USB 调试的设备；做 AAB 转化时还需要本机 JDK。
本项目采用 MIT License。
设备画面镜像基于开源项目 scrcpy。设备通信使用 adbutils 与 Android Debug Bridge。AAB 转 APK 使用 Google 的 bundletool。
本工具用于开发与测试调试。请只操作你有权调试的设备，并遵守所在地法律。