# YAMA Android 客户端

YAMA 的 Android 客户端，允许服务端将 Android 设备作为受控主机进行远程查看和操控。功能包括：

- 屏幕实时截图并推流给服务端
- 接收服务端的触控/按键指令并注入到系统
- 后台保持心跳连接，支持长期驻留

---

## 编译前：配置服务端地址

服务端 IP 和端口在源码中硬编码，编译前必须修改：

文件：`app/src/main/java/com/yama/client/MainActivity.kt`

```kotlin
private val serverIp   = "91.99.165.207"   // 改为你的服务端 IP
private val serverPort = 443                // 改为你的服务端端口
```

改完再执行编译，否则客户端连不上服务端。

---

## 编译环境

在 **WSL（Ubuntu）或原生 Linux** 上编译，Windows 原生环境不支持。

| 依赖 | 版本要求 | 安装命令 |
|---|---|---|
| Java | 17+ | `sudo apt install openjdk-17-jdk` |
| CMake | 3.22+ | `sudo apt install cmake` |
| Ninja | 任意 | `sudo apt install ninja-build` |
| Android SDK | 含 build-tools | 见下方说明 |
| Android NDK | 30.x（Linux 版） | 见下方说明 |

### Android SDK

推荐通过 Android Studio 安装，安装后 SDK 默认在：

- Windows：`%USERPROFILE%\AppData\Local\Android\Sdk`
- Linux：`~/Android/Sdk`

WSL 环境下脚本会自动检测 Windows 侧的 SDK，也可以手动指定：

```bash
export ANDROID_HOME=/mnt/c/Users/<用户名>/AppData/Local/Android/Sdk
```

### Android NDK（Linux 版）

> **重要**：必须使用 **Linux 版 NDK**，Windows NDK 的 `.exe` 工具无法在 WSL 内执行。

```bash
# 下载 Linux NDK（约 600 MB）
wget https://dl.google.com/android/repository/android-ndk-r30b-linux.zip
unzip android-ndk-r30b-linux.zip -d $HOME

# 解压目录名可能带字母后缀（r30、r30b 等），统一重命名
mv $HOME/android-ndk-r30* $HOME/android-ndk
```

脚本会自动检测 `~/android-ndk`，也可以通过环境变量指定：

```bash
export ANDROID_NDK_HOME=$HOME/android-ndk
```

---

## 签名密钥（一次性准备）

Release APK 需要签名密钥。密钥库文件 `yama-release.jks` 已在仓库中，**密码需向仓库维护者获取**，或通过以下方式传入：

```bash
# 方式一：环境变量（推荐，避免每次输入）
export YAMA_PWD=密钥库密码

# 方式二：编译时脚本会交互提示输入
```

如需重新生成密钥库（密码遗失等情况）：

```bash
cd android/
keytool -genkeypair -keystore yama-release.jks \
  -alias yama -keyalg RSA -keysize 2048 -validity 10000 \
  -dname 'CN=YAMA,O=Internal,C=CN'
```

> 密钥库文件本身不含私密信息，可以提交到 git；密码不要提交。
> 重新生成密钥库后，已安装旧版本的设备需要先卸载再安装。

---

## 编译

在 WSL 或 Linux 终端中，进入 `android/` 目录：

```bash
cd android/

# 编译 Release（默认，约 1.7 MB，推荐部署用）
./build_apk.sh

# 编译 Debug（约 4 MB，含调试符号，开发排查用）
./build_apk.sh debug

# 清理所有编译产物（切换配置或遇到奇怪错误时使用）
./build_apk.sh clean
```

编译成功后产物：

| 类型 | 路径 |
|---|---|
| Release | `ghost.apk` |
| Debug | `ghost-debug.apk` |

---

## 安装到设备

### 1. 传输 APK

将 `ghost.apk` 拷贝到手机（USB 传输、微信文件传输等均可）。

### 2. 安装

在手机上用文件管理器找到 APK，点击安装。

如提示"禁止安装未知来源应用"，需先开启允许：

- **Android 8+**：设置 → 应用 → 找到你使用的文件管理器 → 允许安装未知应用
- **MIUI/ColorOS 等**：设置 → 隐私/安全 → 安装未知应用

### 3. 解除受限设置（Android 13+ 必须）

Android 13 及以上系统对手动安装的 APK 有额外限制，若不解除，无法授权 Accessibility Service：

1. 打开 **设置 → 应用 → YAMA**
2. 点击右上角 **三点菜单**
3. 选择 **"允许受限设置"**（Allow restricted settings）
4. 使用 PIN 或指纹确认

> 此步骤每次重新安装 APK 后都需要重复执行一次。

### 4. 授权必要权限

**Accessibility Service**（必须，用于注入触控/按键）

设置 → 无障碍 → 已安装的应用 → YAMA → 开启

> 重装 APK 后此权限会被重置，需重新授权。

### 5. 启动

点击桌面 YAMA 图标启动，系统会弹出屏幕录制确认框，点击 **"立即开始"** 授权。

授权后应用进入后台运行，通知栏会显示一条持久通知表示服务正在运行。此后服务端即可在主机列表中看到该设备。

> 屏幕录制确认在每次应用重启后都会弹出，这是 Android 系统的强制要求，无法跳过。

---

## 注意事项

- 建议在电池优化设置中将 YAMA 设为 **"不限制"**（或"不优化"），防止系统在后台将其杀掉
  - 路径：设置 → 应用 → YAMA → 电池 → 不限制
- 心跳间隔最小 30 秒，长期后台运行耗电量与微信后台相当
- 服务端可在设置中调大上报间隔（建议不超过 60 秒）以进一步降低耗电