# ai-player

**Repository Path**: nachao/ai-player

## Basic Information

- **Project Name**: ai-player
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-04
- **Last Updated**: 2025-11-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI App Agent - 强化学习移动应用自动化训练系统

使用强化学习（PPO算法）训练AI自动操作移动应用的项目。

## 项目简介

本项目使用 Stable-Baselines3 和 PPO 算法，通过强化学习训练AI自动操作Android/iOS应用。AI可以学习点击、滑动、输入等操作，完成指定的任务。

## 系统要求

### 必需软件

- **Python 3.8+** （推荐 3.9 或 3.10）
- **Node.js 16+** （用于运行 Appium，推荐 v20.10.0）
- **npm 7+** （推荐 10.2.3）
- **ADB** （Android Debug Bridge）
- **Appium 2.x** （移动应用自动化框架，推荐 2.19.0）
- **uiautomator2 驱动** （Android 驱动，推荐 2.14.0）

### 硬件要求

- **内存**: 至少 8GB RAM（推荐 16GB）
- **存储**: 至少 10GB 可用空间（用于模型和日志）
- **GPU**: 可选，但推荐使用 NVIDIA GPU 加速训练

### 移动设备

- **Android 模拟器**（推荐雷电模拟器）或真实设备
- **iOS 模拟器**或真实设备（仅限 macOS）

## 安装步骤

### 1. 克隆项目

```bash
git clone <repository-url>
cd ai2
```

### 2. 安装 Python 依赖

```bash
# 创建虚拟环境（推荐）
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/Mac
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt
```

### 3. 安装 Appium

**已测试版本**（推荐使用相同版本以避免兼容性问题）：
- **Node.js**: v20.10.0（要求 16+）
- **npm**: 10.2.3
- **Appium**: 2.19.0
- **uiautomator2 驱动**: 2.14.0

```bash
# 安装 Appium（全局安装）
npm install -g appium@2.19.0

# 安装 Appium 驱动（Android）
appium driver install uiautomator2@2.14.0

# 安装 Appium 驱动（iOS，仅限 macOS）
appium driver install xcuitest
```

**版本兼容性说明**：
- Appium 2.x 需要 Node.js 16+ 和 npm 7+
- 如果遇到安装错误，请确保 Node.js 和 npm 版本符合要求
- 可以使用 `node --version` 和 `npm --version` 检查当前版本

### 4. 安装 ADB

#### Windows（使用雷电模拟器）

1. 下载并安装雷电模拟器
2. ADB 通常位于模拟器安装目录（如 `D:\leidian\LDPlayer9\adb.exe`）
3. 将 ADB 添加到系统 PATH，或修改 `setup_android_env.py` 中的路径

#### Linux/Mac

```bash
# Ubuntu/Debian
sudo apt-get install android-tools-adb

# macOS
brew install android-platform-tools
```

### 5. 安装 UIAutomator2 Server（Android）

```bash
python install_uiautomator2_server.py
```

## 配置说明

### 必须修改的配置

#### 1. Android SDK 路径（Windows + 雷电模拟器）

编辑 `setup_android_env.py`，修改第 9 行：

```python
android_home = r"D:\leidian\LDPlayer9"  # 改为你的雷电模拟器安装路径
```

**常见路径**：
- 雷电模拟器：`D:\leidian\LDPlayer9` 或 `C:\LDPlayer\LDPlayer9`
- Android Studio：`C:\Users\<用户名>\AppData\Local\Android\Sdk`

#### 2. 设备连接配置

编辑 `auto_train.py`，修改以下配置（第 11-17 行）：

```python
# 游戏配置
GAME_PACKAGE = "com.ltg.rxjh.ld"  # 你的应用包名
GAME_ACTIVITY = "com.joypiegame.rxjh.MainActivity"  # 你的应用主Activity
DEVICE = "127.0.0.1:5555"  # 设备地址（模拟器通常为 127.0.0.1:5555）
PLATFORM = "android"
TASK = "游戏"  # 任务描述
TIMESTEPS = 100000  # 训练步数
```

#### 3. 设备名称配置

编辑 `train.py` 或使用命令行参数：

```bash
python train.py --device 127.0.0.1:5555 --package com.example.app --activity .MainActivity
```

#### 4. 应用包名和Activity

**查找应用包名和Activity的方法**：

```bash
# 方法1：使用工具脚本
python tools/find_app_activity.py

# 方法2：使用 ADB
adb shell pm list packages | grep <关键词>
adb shell dumpsys window | grep mCurrentFocus
```

#### 5. Appium 服务器地址（可选）

默认情况下，代码使用 `http://127.0.0.1:4723` 连接 Appium 服务器。如果遇到连接问题，可以：

**方法1：使用环境变量**
```bash
# Windows
set APPIUM_URL=http://127.0.0.1:4723

# Linux/Mac
export APPIUM_URL=http://127.0.0.1:4723
```

**方法2：在代码中指定**
```python
from app_agent.core.app_controller import AppController

# 创建控制器时指定 Appium URL
controller = AppController(
    platform='android',
    device_name='emulator-5554',
    appium_url='http://127.0.0.1:4723'  # 或使用其他地址，如 http://192.168.1.100:4723
)
```

**为什么使用 127.0.0.1 而不是 localhost？**
- 在某些网络环境下，`localhost` 可能解析不正确
- `127.0.0.1` 是更可靠的本地回环地址
- 如果 Appium 监听在局域网 IP（如 `0.0.0.0`），可以使用对应的局域网地址

### 可选配置

#### 1. 训练参数（config.yaml）

```yaml
training:
  algorithm: PPO
  total_timesteps: 100000
  learning_rate: 0.0003
  batch_size: 64
  n_steps: 2048
  n_epochs: 10
  gamma: 0.99
```

#### 2. 模型保存路径

```yaml
model:
  save_path: models/app_agent
  save_frequency: 10000
```

## 依赖列表

### Python 包（requirements.txt）

- **torch** (>=2.0.0) - PyTorch 深度学习框架
- **torchvision** (>=0.15.0) - 图像处理
- **opencv-python** (>=4.8.0) - 计算机视觉
- **pillow** (>=10.0.0) - 图像处理
- **numpy** (>=1.24.0) - 数值计算
- **appium-python-client** (>=3.0.0) - Appium Python 客户端
- **selenium** (>=4.15.0) - WebDriver 支持
- **stable-baselines3** (>=2.0.0) - 强化学习算法库
- **gymnasium** (>=0.29.0) - 强化学习环境
- **easyocr** (>=1.7.0) - OCR 文字识别
- **pytesseract** (>=0.3.10) - Tesseract OCR
- **matplotlib** (>=3.7.0) - 可视化
- **tensorboard** (>=2.14.0) - 训练可视化
- **flask** (>=2.3.0) - Web 服务器（用于标注工具）
- **werkzeug** (>=2.3.0) - WSGI 工具

### 系统依赖

- **Tesseract OCR**（用于文字识别）
  - Windows: 下载安装包并添加到 PATH
  - Linux: `sudo apt-get install tesseract-ocr tesseract-ocr-chi-sim`
  - macOS: `brew install tesseract tesseract-lang`

## 使用方法

### 快速开始

#### 1. 启动 Appium 服务器

```bash
# 方法1：手动启动（推荐用于调试）
appium

# 方法2：使用自动脚本（Windows）
python auto_train.py
# 脚本会自动设置环境变量并启动 Appium
```

#### 2. 设置 Android 环境变量（Windows + 雷电模拟器）

```bash
python setup_android_env.py
```

#### 3. 启动训练

```bash
# 方法1：使用自动训练脚本（推荐）
python auto_train.py

# 方法2：使用命令行参数
python train.py \
    --platform android \
    --device 127.0.0.1:5555 \
    --package com.example.app \
    --activity .MainActivity \
    --task "完成任务" \
    --timesteps 100000
```

### 查看训练进度

#### 启动 TensorBoard

```bash
tensorboard --logdir=./logs/
```

然后在浏览器打开：`http://localhost:6006`

**详细说明**：查看 `TENSORBOARD_GUIDE.md`

### 训练流程

1. **检查连接**：确保设备已连接
   ```bash
   adb devices
   ```

2. **启动 Appium**：确保 Appium 服务器运行
   ```bash
   appium
   ```

3. **运行训练**：执行训练脚本
   ```bash
   python auto_train.py
   ```

4. **监控进度**：使用 TensorBoard 查看训练曲线

5. **保存模型**：训练完成后模型会自动保存到 `models/` 目录

## 常见问题

### 1. ADB 未找到

**解决方案**：
- 检查 ADB 是否在 PATH 中：`adb version`
- 修改 `setup_android_env.py` 中的路径
- 或将 ADB 添加到系统 PATH

### 2. Appium 连接失败

**症状**：脚本显示"Appium服务器未运行"，但实际上 Appium 已经启动。

**诊断步骤**：

1. **使用诊断工具**（推荐）：
   ```bash
   python test_appium_url.py
   ```
   这个工具会自动测试多个可能的连接地址，并告诉你哪个可用。

2. **手动检查服务器状态**：
   ```bash
   # 检查服务器状态（使用 127.0.0.1 而不是 localhost）
   curl http://127.0.0.1:4723/status
   # 或使用 Python
   python -c "import requests; print(requests.get('http://127.0.0.1:4723/status').json())"
   ```

3. **检查 Appium 窗口**：
   - 查看 Appium 启动窗口是否显示：`Appium REST http interface listener started on http://0.0.0.0:4723`
   - 查看日志中显示的可用连接地址（通常是 `127.0.0.1:4723` 或局域网 IP）

**解决方案**：
- **如果使用 `localhost` 连接失败**，这是常见问题！代码已默认使用 `127.0.0.1`，但如果你仍遇到问题，可以：
  ```bash
  # Windows
  set APPIUM_URL=http://127.0.0.1:4723
  # Linux/Mac
  export APPIUM_URL=http://127.0.0.1:4723
  ```
- 检查设备连接：`adb devices`
- 如果服务器监听在局域网 IP（如 `192.168.x.x`），使用对应的地址：
  ```bash
  set APPIUM_URL=http://192.168.x.x:4723
  ```
- 查看 `SESSION_RECONNECTION_GUIDE.md` 了解会话重连机制

**代码改进**：
- 代码已自动尝试多个地址（`127.0.0.1`、`localhost`）
- 增加了超时时间和重试次数
- 改进了错误提示信息

**验证 Appium 服务器启动成功**：

启动 Appium 后，应该看到类似以下日志：

```
[Appium] Welcome to Appium v2.19.0
[Appium] The autodetected Appium home path: C:\Users\<用户名>\.appium
[Appium] Attempting to load driver uiautomator2...
[Appium] AndroidUiautomator2Driver has been successfully loaded in X.XXXs
[Appium] Appium REST http interface listener started on http://0.0.0.0:4723
```

**可用的连接地址**：
- `http://127.0.0.1:4723/` - 本地连接（仅本机可访问）
- `http://192.168.x.x:4723/` - 局域网连接（其他设备可访问）

**检查驱动状态**：
启动日志应显示：
```
[Appium] Available drivers:
[Appium] - uiautomator2@2.14.0 (automationName 'UiAutomator2')
```

如果看到这些信息，说明 Appium 服务器已成功启动并准备好接受连接。

### 3. ANDROID_HOME 错误

**解决方案**：
- Windows + 雷电模拟器：运行 `python setup_android_env.py`
- 或在启动 Appium 前设置环境变量：
  ```bash
  set ANDROID_HOME=D:\leidian\LDPlayer9
  set ANDROID_SDK_ROOT=D:\leidian\LDPlayer9
  ```

### 4. 会话丢失错误

**解决方案**：
- 代码已包含自动重连机制
- 如果频繁出现，检查 Appium 服务器和设备连接稳定性
- 查看 `SESSION_RECONNECTION_GUIDE.md`

### 5. 找不到应用包名或Activity

**解决方案**：
```bash
# 使用工具脚本查找
python tools/find_app_activity.py

# 或使用 ADB
adb shell pm list packages
adb shell dumpsys window windows | grep -E 'mCurrentFocus'
```

## 项目结构

```
ai2/
├── app_agent/              # 核心代码
│   ├── core/               # 核心功能（屏幕分析、应用控制）
│   └── rl/                 # 强化学习相关
├── examples/               # 示例代码
├── tools/                  # 工具脚本
├── models/                 # 训练好的模型（gitignore）
├── logs/                   # TensorBoard 日志（gitignore）
├── screenshots/            # 截图文件（gitignore）
├── auto_train.py          # 自动训练脚本
├── train.py               # 训练主脚本
├── requirements.txt       # Python 依赖
└── config.yaml            # 配置文件
```

## 文档

- **TRAINING_GUIDE.md** - 详细训练指南
- **MOBILE_SETUP_GUIDE.md** - 移动设备设置指南
- **TENSORBOARD_GUIDE.md** - TensorBoard 使用指南
- **SESSION_RECONNECTION_GUIDE.md** - 会话重连机制说明
- **AI_ARCHITECTURE.md** - AI 架构说明

## 配置检查清单

在新电脑上运行前，请检查：

- [ ] Python 3.8+ 已安装（推荐 3.9 或 3.10）
- [ ] 已安装所有 Python 依赖（`pip install -r requirements.txt`）
- [ ] Node.js 16+ 已安装（推荐 v20.10.0，使用 `node --version` 检查）
- [ ] npm 7+ 已安装（推荐 10.2.3，使用 `npm --version` 检查）
- [ ] Appium 已安装（推荐 2.19.0，使用 `appium --version` 检查）
- [ ] Appium UIAutomator2 驱动已安装（推荐 2.14.0，使用 `appium driver list` 检查）
- [ ] ADB 已安装并可访问（`adb version`）
- [ ] 已修改 `setup_android_env.py` 中的 Android SDK 路径
- [ ] 已修改 `auto_train.py` 中的设备和应用配置
- [ ] 设备已连接（`adb devices` 显示设备）
- [ ] Appium 服务器已启动（`http://127.0.0.1:4723/status`）
- [ ] UIAutomator2 Server 已安装到设备（运行 `python install_uiautomator2_server.py`）

## 许可证

[根据项目实际情况填写]

## 贡献

欢迎提交 Issue 和 Pull Request！

## 联系方式

[根据项目实际情况填写]