AI 自动化控制 Android 设备 - 快速启动指南

系统要求

浏览器

Chrome 94+ 或 Edge 94+（必须支持 WebCodecs API）
不支持 Firefox 和 Safari

设备

Android 设备（已开启 USB 调试）
USB 数据线或 WiFi 连接

软件

Python 3.11+
Node.js 16+
ADB (Android Debug Bridge)

快速启动

方式一：使用启动脚本（推荐）

macOS/Linux

启动前端：

cd frontend
bash start_frontend.sh

一键启动全部服务：

bash start_all.sh

然后选择启动模式：

选项 1: 仅启动后端
选项 2: 仅启动前端
选项 3: 同时启动前后端（推荐）
选项 4: 启动 AI 模型服务
选项 5: 全部启动

Windows

启动前端：

cd frontend
start_frontend.bat

启动后端：

cd backend
start_backend.bat

方式二：手动启动

1. 启动后端

cd backend
bash start_backend.sh

后端将在 http://localhost:8001 启动

2. 启动前端

cd frontend
npm run dev -- --host --port 3002 --clearScreen false

前端将在 http://localhost:3002 启动

💡 提示：使用 --host 参数可以让局域网内其他设备访问

3. 连接设备

通过 USB 连接 Android 设备
确保设备已开启 USB 调试
在浏览器中访问 http://localhost:5173
选择设备

4. 查看实时屏幕

点击"查看屏幕"进入实时屏幕显示页面
自动使用视频流模式（延迟 30-100ms，帧率 20-30 FPS）
可以直接点击屏幕控制设备
可以使用控制按钮（Home、返回、音量等）

5. AI 控制

点击"AI 控制"进入 AI 控制页面
输入自然语言指令（如"打开微信"）
AI 会自动执行操作

技术特性

视频流模式

协议: scrcpy-server v3.3.3 + Socket.IO
编码: H.264 硬件编码
解码: WebCodecs API (WebGL 渲染)
延迟: 30-100ms
帧率: 20-30 FPS
硬件加速: 是

控制功能

点击屏幕
滑动
长按
虚拟按键（Home、返回、菜单、电源等）
音量控制
滚动
文本输入
系统操作（通知栏、快捷设置等）

常见问题

1. 视频流显示黑屏

原因: 浏览器不支持 WebCodecs API

解决方案: 使用 Chrome 94+ 或 Edge 94+

2. 点击控制按钮后视频流卡顿

原因: 已修复（使用非阻塞 ADB 命令）

解决方案: 确保使用最新版本的代码

3. 视频流连接后立即断开

原因: 组件重新渲染导致重连（已修复）

解决方案: 确保使用最新版本的代码

4. 设备未找到

原因: ADB 未正确配置或设备未连接

解决方案:

# 检查 ADB 是否安装
adb version

# 检查设备连接
adb devices

# 如果设备显示 "unauthorized"，在设备上允许 USB 调试

性能优化

调整视频质量

在"实时屏幕显示"页面调整"视频质量"滑块（1-5 Mbps）
默认 4 Mbps，适合大多数场景

调整分辨率

在"实时屏幕显示"页面调整"分辨率"滑块（480p-4K）
默认 1080p，适合大多数场景

使用 USB 连接

USB 连接比 WiFi 更稳定，延迟更低
推荐使用 USB 连接

项目结构

ai-auto-touch/
├── backend/              # 后端服务
│   ├── app/
│   │   ├── api/         # API 路由
│   │   ├── services/    # 业务逻辑
│   │   └── utils/       # 工具函数
│   └── start_backend.sh # 启动脚本
├── frontend/            # 前端应用
│   ├── src/
│   │   ├── components/  # React 组件
│   │   ├── pages/       # 页面
│   │   ├── hooks/       # 自定义 Hooks
│   │   └── api/         # API 调用
│   └── package.json
├── AutoGLM-GUI/         # 参考项目（保留）
└── scrcpy-server-v3.3.3 # scrcpy 服务器

核心组件

ScrcpyPlayer

视频流播放器组件，使用 WebCodecs API 解码 H.264 视频流

位置: frontend/src/components/ScrcpyPlayer.tsx

特性:

WebGL 渲染（优先）或 Bitmap 渲染（降级）
自动管理 canvas 尺寸
硬件加速
低延迟

ScrcpyStreamer

后端视频流服务，管理 scrcpy-server 进程

位置: backend/app/services/scrcpy_video_stream.py

特性:

自动启动和管理 scrcpy-server
解析 scrcpy 协议
通过 Socket.IO 推送视频帧
设备锁机制（防止多个流同时启动）

开发指南

添加新的控制功能

在 backend/app/services/phone_control_service.py 添加方法
在 backend/app/api/phone_control_api.py 添加 API 端点
在 frontend/src/api/phoneControlApi.ts 添加 API 调用
在 frontend/src/pages/ScreenDisplay.tsx 添加 UI 按钮

调试视频流

打开浏览器开发者工具
查看 Console 日志
查看 Network → WS 标签，检查 Socket.IO 连接
查看后端日志：tail -f backend/logs/app.log

参考文档

技术博客

详见：技术博客_AI自动化控制Android设备.md

故障排查

详见：TROUBLESHOOTING.md

贡献指南

详见：CONTRIBUTING.md

更新日志

详见：CHANGELOG.md

许可证

MIT License

FilesExpand file tree

快速启动指南.md

Latest commit

History