# wos-android-testbox

**Repository Path**: dushu/wos-auto-mobile-app

## Basic Information

- **Project Name**: wos-android-testbox
- **Description**: android 群控
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-01
- **Last Updated**: 2026-09-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# WOS 安卓真机测试盒

> 一套基于 ADB 的安卓真机远程测试与自动化平台。插上手机，打开浏览器，即可实时查看屏幕、远程操作、OCR 识别、编写自动化脚本并多设备批量执行。

## 平台支持

**当前仅支持 macOS。**

服务端依赖 `adb`（Android Platform Tools），已在 macOS（Apple Silicon / Intel）上实测通过。Linux/Windows 理论可行但未做适配验证，欢迎社区贡献。

## 界面预览

| 设备总览 | 实时控制 |
|:---:|:---:|
| ![设备总览](docs/screenshots/device-overview.png) | ![实时控制](docs/screenshots/realtime-control.png) |

| OCR 识别 | 脚本编辑器 |
|:---:|:---:|
| ![OCR 识别](docs/screenshots/ocr-recognition.png) | ![脚本编辑器](docs/screenshots/script-editor.png) |

## 功能特性

### 设备管理
- 自动发现 USB 连接的安卓真机（热插拔轮询）
- 在线 / 离线 / 已识别 / ADB 状态统计
- 设备卡片：型号、序列号、品牌、系统版本、分辨率、电量、充电状态
- 案例手机标记与管理

### 实时控制
- 手机屏幕实时截图与自动刷新（Socket.IO 双向通道）
- 远程操作：屏幕点击、系统操作（Home / Back / Recents / 长按）、打开应用
- 精确滑动（坐标 → 坐标）、快速滑动（上/下/左/右）
- 操作日志记录与宏录制

### OCR 识别（Tesseract.js）
- 截图区域框选 → OCR 文字识别（中英文）
- 识别能力管理：保存命名区域 + 识别类型，一键测试识别
- 识别结果自动去除空白字符

### 脚本编排系统
- 可视化脚本编辑器：变量声明 + 步骤列表（递归嵌套）
- 8 种步骤类型：调用宏、OCR 识别、设置变量、等待、条件判断、循环（前判断 / 后判断 / 直到出错）
- 变量系统：支持声明、赋值、类型推断
- 条件求值：OCR 结果匹配、变量比较
- 循环保护：最大迭代次数限制（100 次）

### 调试模式
- 脚本逐步执行，每步暂停
- 实时查看变量值变化
- 暂停时可编辑步骤属性（条件 / 值 / 时长）

### 多设备生产执行
- 设备总览页每张卡片可选脚本 + 一键运行
- 运行时绿色高亮 + 3 秒截图刷新
- Socket.IO 实时推送执行进度
- 停止后恢复卡片状态

### 宿主监控
- CPU / 内存 / 磁盘使用率实时卡片
- ADB 连接状态监控
- 阈值告警（90%）

## 技术栈

| 层 | 技术 |
| --- | --- |
| 前端 | Vue 3 + Element Plus + Vite + Vue Router |
| 后端 | Node.js + Koa 2 + Socket.IO |
| 数据库 | SQLite（better-sqlite3） |
| OCR | Tesseract.js（chi_sim + eng） |
| 设备通信 | ADB（Android Debug Bridge） |

## 快速开始

### 环境要求

| 依赖 | 版本 | 说明 |
| --- | --- | --- |
| Node.js | >= 20 | 推荐 v22+ |
| npm | >= 9 | 可配合 npmmirror 加速 |
| ADB (platform-tools) | 最新 | 真实模式必须；mock 模式无需安装 |
| Android 手机 | API 21+ | 开启开发者选项 + USB 调试 |

> **仅 macOS 已实测。** Linux/Windows 理论可行但未验证。

### 安装与启动

```bash
# 1. 克隆仓库
git clone <仓库地址>
cd wos-android-testbox

# 2. 安装服务端依赖
cd server && npm install

# 3. 安装前端依赖
cd ../web && npm install

# 4. 启动服务端（真实模式，连接真机）
cd ../server && npm run start

# 5. 另开终端，启动前端
cd web && npm run dev
```

浏览器打开 **http://localhost:5173** 即可使用。

> 前端开发服务器已配置代理指向后端 3000 端口，无需额外配置跨域。

### Mock 模式（无真机联调）

无需连接真机即可体验全部界面功能：

```bash
cd server && npm run mock
```

Mock 模式内置 2 台模拟设备（Pixel 7 Pro + Redmi K60），其中一台会周期性掉线用于测试热插拔逻辑。

## 环境变量

复制 `server/.env.example` 为 `server/.env` 后按需修改，不修改则使用默认值：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `PORT` | 3000 | 服务端端口 |
| `HOST` | 0.0.0.0 | 监听地址 |
| `ADB_BIN` | adb | 真实 adb 路径（默认取 PATH） |
| `ADB_POLL_MS` | 2000 | 设备热插拔轮询间隔（ms） |
| `MONITOR_MS` | 3000 | 宿主监控采集间隔（ms） |
| `ADB_MOCK` | 空 | `1` 启用模拟设备 |
| `ADB_DISABLED` | 空 | `1` 完全禁用 adb（纯前端联调） |

示例：

```bash
PORT=3100 ADB_BIN=/opt/platform-tools/adb ADB_POLL_MS=1000 npm run start
```

## 项目结构

```
wos-android-testbox/
├── server/                        # 服务端
│   ├── src/
│   │   ├── index.js               # 入口
│   │   ├── config.js              # 配置（环境变量可覆盖）
│   │   ├── db/index.js            # SQLite 初始化 + 迁移
│   │   ├── routes/index.js        # REST API 路由
│   │   ├── socket/index.js        # Socket.IO 实时推送
│   │   ├── adb/                   # ADB 封装
│   │   │   ├── index.js           # 设备列表 / 命令执行
│   │   │   └── screenshot.js      # 截图（screencap）
│   │   └── services/
│   │       ├── device-manager.js  # 设备管理 + 案例手机
│   │       ├── host-monitor.js    # 宿主监控
│   │       ├── macro-manager.js   # 宏管理
│   │       ├── ocr-service.js     # Tesseract.js OCR
│   │       └── script-runner.js   # 脚本执行引擎 + 调试
│   ├── scripts/
│   │   ├── mock-adb              # 模拟 adb（2 台设备 + 周期掉线）
│   │   └── verify.js             # 服务端自测
│   ├── data/                      # 运行时数据（已 gitignore）
│   └── .env.example               # 环境变量模板
├── web/                           # 前端
│   ├── src/
│   │   ├── App.vue                # 根组件 + 导航
│   │   ├── router.js             # 路由
│   │   ├── script-utils.js        # 共享工具（步骤工厂 / 常量）
│   │   └── views/
│   │       ├── DevicesView.vue       # 设备总览 + 多设备执行
│   │       ├── ScreenshotView.vue    # 实时控制 + OCR
│   │       ├── MacrosView.vue        # 宏管理
│   │       ├── ScriptsView.vue        # 脚本列表
│   │       ├── ScriptEditorView.vue  # 脚本编辑 + 调试
│   │       ├── ScriptStepEditor.vue   # 步骤递归编辑器
│   │       ├── StepNode.vue           # 步骤节点组件
│   │       ├── CaseDevicesView.vue   # 案例手机
│   │       ├── CommandLogsView.vue   # 命令日志
│   │       └── MonitorView.vue       # 宿主监控
│   └── index.html
├── docs/screenshots/              # 界面截图
└── README.md
```

## 功能页面

| 页面 | 路径 | 能力 |
| --- | --- | --- |
| 设备总览 | `/devices` | 统计卡片 + 设备卡片 + 脚本选择 + 一键运行 |
| 实时信息 | `/screenshot` | 屏幕截图 + 远程操作 + OCR 识别 |
| 宏管理 | `/macros` | 宏列表 + 编辑 + 执行 |
| 脚本管理 | `/scripts` | 脚本列表 + 新建 |
| 脚本编辑 | `/scripts/:id` | 变量声明 + 步骤编排 + 调试面板 |
| 案例手机 | `/case-devices` | 案例设备入库管理 |
| 宿主监控 | `/monitor` | CPU / 内存 / 磁盘 / ADB 状态 |

## 开发指南

```bash
# 服务端开发模式（文件变更自动重启）
cd server && npm run dev

# 前端开发模式（HMR 热更新）
cd web && npm run dev

# 前端构建
cd web && npm run build

# 服务端自测（11 项断言）
cd server && node scripts/verify.js 20000
```

## 常见问题

**ADB 不可用（页面显示红色告警）**
确认终端 `adb devices` 能列出设备，手机已授权调试。macOS 首次连接需在手机上点「允许 USB 调试」。

**真机截图黑屏 / 失败**
本系统使用 `adb exec-out screencap -p`（兼容性最佳）；个别 ROM 需升级 platform-tools 到最新版。

**端口被占用**
`PORT=3001 npm run start` 换端口；前端代理目标可用 `VITE_PROXY_TARGET=http://127.0.0.1:3001 npm run dev` 覆盖。

**Tesseract.js 首次运行需联网**
OCR 首次使用时会下载 chi_sim 语言数据（约 20MB），下载后缓存在本地。

**调试模式限制**
暂停时仅可修改步骤属性（条件 / 值 / 时长），不可增删或重排步骤。

## 已知限制

- 截图按 serial 落盘覆盖（每设备一张），不保留历史帧
- `better-sqlite3` 原生二进制需与运行平台匹配（预编译 darwin-arm64）
- Tesseract.js 首次运行需联网下载语言数据
- 循环步骤最大迭代 100 次（防死循环保护）
- 设备信息采集含 `cmd connectivity airplane-mode` 探测，个别系统版本该命令不存在时字段显示「未知」

## License

[MIT](LICENSE)