Feat: Android client Phase 0-3 full implementation

android/README.md

@@ -0,0 +1,172 @@
+# 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 秒）以进一步降低耗电