267 lines
15 KiB
Markdown
267 lines
15 KiB
Markdown
# Android 客户端开发计划书
|
||
|
||
> 目标功能：屏幕浏览 + 操作控制（触控/键盘输入注入）
|
||
> 参考实现：`linux/` 与 `macos/`，两者已验证的共用策略同样适用于 Android
|
||
|
||
---
|
||
|
||
## 一、代码复用分析
|
||
|
||
### 1.1 可 100% 直接复用（NDK 无改动）
|
||
|
||
| 文件 | 用途 | 依赖 |
|
||
|------|------|------|
|
||
| `common/ikcp.c/.h` | KCP 可靠 UDP 传输 | 纯 C，无 OS 依赖 |
|
||
| `common/aes.c/.h` | AES 加密 | 纯 C |
|
||
| `common/commands.h` | 协议定义（全平台共享） | 无 |
|
||
| `common/client_auth_state.h` | 认证状态机 | 无 |
|
||
| `common/posix_net_helpers.h` | POSIX socket 辅助函数 | POSIX（Android NDK 支持） |
|
||
| `common/sub_conn_thread.h` | 子连接线程 | POSIX |
|
||
| `common/rtt_estimator.h` | RTT 估计器 | 无 |
|
||
| `common/logger.h` | 日志 | 无 |
|
||
| `common/locker.h` | 互斥锁 | `std::mutex` |
|
||
| `common/FileTransferV2.h` | V2 文件传输协议 | 无 |
|
||
| `common/xxhash.h` | xxHash 校验 | 纯头文件 |
|
||
| `client/IOCPClient.cpp/.h` | TCP/KCP 连接管理（Linux 已复用） | POSIX socket |
|
||
| `client/Buffer.cpp/.h` | 数据缓冲区 | 无 |
|
||
| `client/sign_shim_unix.cpp` | 签名垫片（Linux/macOS 已复用） | `libsign.a` |
|
||
|
||
### 1.2 可参考逻辑、重新实现 Android 版本
|
||
|
||
| 现有文件 | Android 对应实现 | 原因 |
|
||
|----------|-----------------|------|
|
||
| `linux/ScreenHandler.h` | `android/cpp/ScreenHandler.h` | 捕获 API 不同（MediaProjection vs X11） |
|
||
| `macos/InputHandler.mm` | `ControlService.kt` + `main.cpp::DispatchControlEvent` | 注入方式不同（AccessibilityService vs CGEvent） |
|
||
| `linux/SystemManager.h` | `android/cpp/SystemManager.cpp`（Phase 4） | 系统 API 不同 |
|
||
| `macos/H264Encoder.mm` | Android MediaCodec 路径（Java 侧） | 硬件编码器 API 不同 |
|
||
| `linux/main.cpp` | `android/cpp/main.cpp` | 参考连接逻辑，逐段移植 |
|
||
|
||
### 1.3 不复用（Windows 专属）
|
||
|
||
- `client/ScreenCapturerDXGI.h`、`client/IOCPBase.h`、`client/ScreenSpy.cpp`（Windows GDI/DXGI）
|
||
- `client/KeyboardManager.cpp`（SendInput API）
|
||
- `client/KernelManager.cpp`、`client/ServicesManager.cpp`
|
||
|
||
---
|
||
|
||
## 二、技术选型
|
||
|
||
### 2.1 屏幕捕获
|
||
|
||
**方案**：`MediaProjection` API（Android 5.0+）
|
||
|
||
```
|
||
MediaProjection
|
||
└── VirtualDisplay (Surface)
|
||
└── MediaCodec (Surface input，零拷贝)
|
||
└── H.264 NALU → JNI → C++ ScreenHandler → 网络发送
|
||
```
|
||
|
||
- 无需 root，官方公开 API
|
||
- 通过 `ForegroundService` + `FOREGROUND_SERVICE_MEDIA_PROJECTION` 维持后台运行
|
||
- **实际采用零拷贝路径（Path A）**：VirtualDisplay 的 Surface 直接绑定 `MediaCodec` 输入 Surface，无 ImageReader 中间环节
|
||
|
||
### 2.2 视频编码
|
||
|
||
**已采用**：Android `MediaCodec`（硬件 H.264 加速）✅
|
||
|
||
- VirtualDisplay Surface → MediaCodec Surface input → H.264 NALU，零拷贝
|
||
- 关键帧前自动拼接 SPS+PPS，确保解码器可初始化
|
||
- 每 2 秒强制触发一次 IDR（兼容忽略 `KEY_I_FRAME_INTERVAL` 的软编码器）
|
||
- 编码分辨率：长边限制 1080，保持宽高比，宽高各自 2 对齐（H.264 要求）
|
||
|
||
**编码流水线**：
|
||
```
|
||
VirtualDisplay → MediaCodec(Surface input) → CODEC_CONFIG(SPS/PPS) + IDR+P 帧
|
||
→ onOutputBufferAvailable → JNI nativeOnH264Frame → C++ g_screenHandlers (broadcast) → TCP
|
||
```
|
||
|
||
### 2.3 输入控制
|
||
|
||
**已采用**：`AccessibilityService`（`ControlService.kt`）✅
|
||
|
||
| 事件 | 映射 |
|
||
| --- | --- |
|
||
| `WM_LBUTTONDOWN/MOVE/UP` | 累积路径，UP 时判断：位移 < 10px → 单击（dispatchTap），否则 → 拖拽（dispatchTouchGesture） |
|
||
| `WM_LBUTTONDBLCLK` | 双击：两次 80ms 手势，间隔 200ms |
|
||
| `WM_RBUTTONDOWN` | 长按 600ms |
|
||
| `WM_MOUSEWHEEL` | delta > 0（滚轮上）→ 手指下划 +400px；delta < 0 → 手指上划 -400px |
|
||
| `WM_KEYDOWN` Backspace/ESC | `GLOBAL_ACTION_BACK` |
|
||
| `WM_KEYDOWN` VK_HOME (0x24) | `GLOBAL_ACTION_HOME` |
|
||
| `WM_KEYDOWN` VK_APPS (0x5D) | `GLOBAL_ACTION_RECENTS` |
|
||
| `WM_KEYDOWN` PrtSc (0x2C) | `GLOBAL_ACTION_TAKE_SCREENSHOT` |
|
||
|
||
**关键实现细节**：
|
||
|
||
- 协议：`COMMAND_SCREEN_CONTROL` + MSG64（固定 48 字节），**坐标从 lParam（offset 24）读取**，与 Windows/Linux/macOS 客户端完全一致；不读 pt.x/pt.y（64-bit MSG 与 MSG64 的 pt 偏移不同，直接读会得到错误 Y 坐标）
|
||
- 坐标映射：`phys = enc * physSize / encSize`（编码空间 → 物理屏幕空间）
|
||
- 单击路径非退化：`moveTo(x,y); lineTo(x+1,y)`，避免 Android 静默拒绝零长度手势路径
|
||
- C++ → Kotlin 回调：`DispatchControlEvent()` 全局函数通过 JNI AttachCurrentThread → `ControlService.onControlEvent(@JvmStatic)` → post 到主线程 Handler
|
||
|
||
### 2.4 网络传输
|
||
|
||
与 Linux 完全相同的 POSIX socket 路径：
|
||
- TCP 控制通道（`IOCPClient.cpp` 已在 Linux 验证）
|
||
- KCP over UDP 视频流（`ikcp.c` 纯 C，NDK 直接编译，当前未启用）
|
||
- TLS/AES 加密复用 `common/aes.c`
|
||
|
||
---
|
||
|
||
## 三、目录结构（实际）
|
||
|
||
```
|
||
android/
|
||
├── PLAN.md # 本文件
|
||
├── README.md # 编译与安装说明
|
||
├── build_apk.sh # 编译脚本（release/debug/clean）
|
||
├── yama-release.jks # 签名密钥库（密码通过 YAMA_PWD 环境变量传入）
|
||
├── app/
|
||
│ ├── build.gradle
|
||
│ ├── proguard-rules.pro # 保留 JNI 方法名
|
||
│ └── src/main/
|
||
│ ├── AndroidManifest.xml
|
||
│ ├── java/com/yama/client/
|
||
│ │ ├── MainActivity.kt # 权限申请 + 启动 Service
|
||
│ │ ├── CaptureService.kt # ForegroundService：MediaProjection + MediaCodec
|
||
│ │ ├── ControlService.kt # AccessibilityService：手势注入 + 全局键 + 活动窗口上报
|
||
│ │ └── YamaBridge.kt # JNI 声明（nativeInit/Stop/SetScreenSize/OnH264Frame）
|
||
│ ├── cpp/
|
||
│ │ ├── CMakeLists.txt
|
||
│ │ ├── main.cpp # NDK 入口：连接/心跳/DataProcess/DispatchControlEvent
|
||
│ │ ├── ScreenHandler.h # 子连接管理：发送 BitmapInfo/H264 帧，接收 SCREEN_CONTROL
|
||
│ │ ├── android_compat.h # 平台兼容头（强制注入替代修改共用源文件）
|
||
│ │ ├── common/ → ../../common/ # 符号链接（commands.h 等）
|
||
│ │ ├── client/ → ../../client/ # 符号链接（IOCPClient 等）
|
||
│ │ └── lib/
|
||
│ │ ├── arm64-v8a/libsign.a
|
||
│ │ ├── arm64-v8a/libzstd.a
|
||
│ │ ├── armeabi-v7a/libsign.a
|
||
│ │ └── armeabi-v7a/libzstd.a
|
||
│ └── res/
|
||
│ ├── mipmap-*/ic_launcher.png # 传统图标（各密度）
|
||
│ ├── mipmap-*/ic_launcher_foreground.png # Adaptive Icon 前景层
|
||
│ ├── mipmap-anydpi-v26/ic_launcher.xml # Adaptive Icon 定义
|
||
│ ├── values/colors.xml # ic_launcher_background (#F2F2F2)
|
||
│ ├── values/strings.xml
|
||
│ └── xml/accessibility_service_config.xml
|
||
├── build.gradle (project-level)
|
||
└── settings.gradle
|
||
```
|
||
|
||
> **注**：原计划中的 `InputHandler.cpp` 已合并至 `main.cpp`（`DispatchControlEvent` 全局函数）和 `ControlService.kt`；`SystemManager.cpp` 留待 Phase 4。
|
||
|
||
---
|
||
|
||
## 四、开发阶段
|
||
|
||
### Phase 0：工程初始化 ✅ 已完成
|
||
|
||
- 创建 Android Studio 项目，配置 NDK + CMake
|
||
- `CMakeLists.txt` 引入 `common/`、`client/` 源文件（与 `linux/CMakeLists.txt` 同构）
|
||
- 编译验证 `IOCPClient.cpp + Buffer.cpp + sign_shim_unix.cpp + ikcp.c` 在 NDK 下无错误
|
||
- `SimplePlugins/sign_lib/` 新增 `sha256_portable.h`（纯 C，零外部依赖）和 `build_android.sh`，在 WSL + NDK r27c 下成功交叉编译，产物已复制至 `android/app/src/main/cpp/lib/{arm64-v8a,armeabi-v7a}/libsign.a`
|
||
|
||
### Phase 1：连接与协议 ✅ 已完成
|
||
|
||
- 移植 `linux/main.cpp` 的连接逻辑到 `android/cpp/main.cpp`
|
||
- `CaptureService.kt` 通过 `YamaBridge.nativeInit()` 启动 C++ 网络线程
|
||
- 实现登录握手（`LOGIN_INFOR`）、心跳（`TOKEN_HEARTBEAT` + `CMD_HEARTBEAT_ACK` RTT 估算）、认证状态机（`client_auth_state.h`）
|
||
- 设备信息上报：ANDROID_ID（XXH64 作为 ClientID）、型号、OS 版本、分辨率
|
||
- 心跳日志限流：60 秒最多打印一次，避免 logcat 刷屏
|
||
|
||
### Phase 2：屏幕捕获与编码 ✅ 已完成
|
||
|
||
- `CaptureService.kt`：申请 `MediaProjection`，建立 `VirtualDisplay`，Surface 直连 `MediaCodec`
|
||
- SPS/PPS 缓存，IDR 帧发送前自动拼接，子连接 `COMMAND_NEXT` 后开始推流
|
||
- `ScreenHandler.h`：发送 `TOKEN_BITMAPINFO`（含 `ScreenSettings.QualityLevel=H264`），`SendH264` 封装帧头
|
||
- 服务端 H264 解码器正常显示 Android 屏幕 ✅
|
||
- 服务端适配：`ScreenSpyDlg.cpp` 新增 `ComputeAdaptiveLayout()` 自适应缩放和信箱黑边，`m_offsetX/Y` 修正坐标映射（已合入 `main` 分支）
|
||
|
||
### Phase 3：操作控制 ✅ 已完成（branch: feature/android-remote-control）
|
||
|
||
- `ControlService.kt`（`AccessibilityService`）：手势注入、全局键、双击/长按/滚轮
|
||
- `main.cpp::DispatchControlEvent()`：JNI 反向调用，将 `COMMAND_SCREEN_CONTROL` 路由到 Kotlin
|
||
- `ScreenHandler.h::OnReceive`：子连接也可接收 `COMMAND_SCREEN_CONTROL`，统一调用 `DispatchControlEvent`
|
||
- 坐标 Bug 修复：64-bit MSG 与 MSG64 的 `pt.x/pt.y` 偏移不同（MSG: offset 36，MSG64: offset 40）；改为从 lParam（两者均在 offset 24）提取坐标，与其他所有客户端保持一致
|
||
- 单击无效 Bug 修复：零长度手势路径被 Android 静默拒绝；tap 改用 `lineTo(x+1, y)` 非退化路径
|
||
- 代码审查修复：JNI `ExceptionClear()`
|
||
|
||
### Phase 3 后期修复 ✅ 已完成
|
||
|
||
发现并修复的生产问题：
|
||
|
||
| 问题 | 根因 | 修复文件 |
|
||
|------|------|---------- |
|
||
| 静止屏幕首帧黑屏 10-60 秒 | SurfaceFlinger 空闲优化：无脏区时不向 VirtualDisplay 推帧，`REQUEST_SYNC_FRAME` 永远排队等不到输入帧 | `CaptureService.forceFirstFrame()`：VirtualDisplay 临时 resize +2px 触发强制合成；`main.cpp` 在 `SendBitmapInfo` 后调用 `ForceFirstFrameFromJava()` |
|
||
| 部分硬件编码器 IDR 帧未被识别 | 高通等 SoC 对强制 IDR 不设置 `BUFFER_FLAG_KEY_FRAME`，`SendLoop` 将其当作 P 帧丢弃，首帧永远发不出 | `CaptureService.isNaluKeyframe()`：扫描 Annex-B NALU type 5/7/8 补充判断 |
|
||
| H.264 推流在 `SendBitmapInfo` 前卡住 | 推送模式下服务端 `COMMAND_NEXT` 到达时 `setManagerCallBack` 尚未注册消息被丢弃，`m_started` 永远为 `false` | `ScreenHandler.h::SendBitmapInfo()` 末尾直接 `m_started=true; m_cond.notify_all()` |
|
||
| 多用户不能同时观看/控制 | `g_screenHandler` 单指针 + `g_screenSpyRunning` 互斥锁，只允许一条子连接 | `main.cpp`：改为 `std::set<AndroidScreenHandler*> g_screenHandlers`，`nativeOnH264Frame` 广播给全部 handler；每个 `COMMAND_SCREEN_SPY` 独立建立子连接，对齐 Windows/Linux/macOS 客户端行为 |
|
||
|
||
### Phase 4：系统信息与稳定性（进行中）
|
||
|
||
**已完成：**
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| 活动窗口上报 | `ControlService` 监听 `TYPE_WINDOW_STATE_CHANGED`，通过 JNI `getActiveWindow()` 上报当前前台包名；锁屏时上报 `"Locked"` |
|
||
| 心跳间隔下限 | Android 侧将服务端下发的 `ReportInterval` 强制限制为 `max(收到值, 30)`，防止 5s 高频心跳耗电 |
|
||
| 服务端心跳超时延长 | `CheckHeartbeat()` 超时阈值从 `max(60, interval*3)` 改为 `max(120, interval*3)`，与 30s 心跳间隔留出 4 倍余量 |
|
||
| CPU 频率上报 | `GetCpuMHz()` 优先读 `/sys/devices/system/cpu/*/cpufreq/cpuinfo_max_freq`，虚拟机无此节点时回退读 `/proc/cpuinfo` 的 `BogoMIPS` |
|
||
| 后台保活 | `ForegroundService` + 持久通知（Phase 2 已完成），豁免 Doze 模式网络限制 |
|
||
| 应用图标 | 自定义眼睛图标，支持 Android 8+ Adaptive Icon（前景层 + 浅灰背景），兼容各厂商形状裁切 |
|
||
| Release 签名 | `yama-release.jks` 随仓库分发，密码通过 `YAMA_PWD` 环境变量或交互输入，保证多机一致签名 |
|
||
|
||
**待完成：**
|
||
|
||
- 处理 `MediaProjection` 被用户撤销的情况（弹出通知，引导重授权）
|
||
- 连接断线自动重连后子连接同步重建（目前 `ScreenSpyThread` 有 20 次重试，但主连接重连后子连接未同步恢复）
|
||
- `WM_MBUTTONDOWN`（中键）手势映射（目前静默丢弃）
|
||
- `SystemManager` 封装：将 Java 层已上报的设备信息（型号、版本、IP）统一封装为独立模块
|
||
|
||
---
|
||
|
||
## 五、关键约束与风险
|
||
|
||
| 风险 | 影响 | 状态 |
|
||
|------|------|------|
|
||
| ~~`libsign.a` 无 ARM 构建~~ | ~~Phase 0 阻塞~~ | ✅ 已解决：`sha256_portable.h` + `build_android.sh` |
|
||
| Android 12+ `MediaProjection` 需每次重新申请 | 后台录屏被中断 | `ForegroundService` 保活 + 通知引导重授权 |
|
||
| `AccessibilityService` 用户需手动开启 | 操作控制功能受限 | UI 引导流程，说明开启步骤 |
|
||
| 某些厂商 ROM 限制后台 Service | 连接断开 | 电池优化白名单申请 |
|
||
| H.264 Baseline Level 对齐 | 服务端解码兼容性 | `MediaCodec` 输出指定 `profile=Baseline`，与 x264 现有配置一致 |
|
||
| `AccessibilityService` 无法向系统设置页面注入手势 | 设置界面无法远程操作 | Android 安全限制，无解，提示用户 |
|
||
|
||
---
|
||
|
||
## 六、代码审查注意事项
|
||
|
||
### 最高原则：既有功能无破坏
|
||
|
||
增加 Android 客户端支持时，Windows/Linux/macOS 客户端的全部既有功能必须保持正常。每次改动上线前须验证：
|
||
|
||
| 检查项 | 说明 |
|
||
| --- | --- |
|
||
| `isAndroidRemote` 初始值为 `false` | 非 Android 客户端走原有代码路径，不受影响 |
|
||
| `updateUIForOrientation()` Android 分支有 `isAndroidRemote &&` 守卫 | 非 Android 客户端不会进入沉浸模式分支 |
|
||
| `NotifyResolutionChange` 新参数有默认值 `= ""` | 现有调用点即便漏传也能正常编译和运行 |
|
||
| `FindHostByClientID` 与 `FindHostByIP` 一致的指针返回约定 | ScreenSpyDlg 在 UI 线程（OnInitDialog）调用，OnReceiveComplete 在 IO 线程调用，后者读 `additonalInfo[]` 为只读操作，低概率竞争 |
|
||
| Web 端坐标映射 `getTouchPos` 使用 `getBoundingClientRect()` | 动态取 canvas 实际显示尺寸，CSS 拉伸不影响坐标精度 |
|
||
| Android 边缘手势检测有时间和距离双重门槛 | 普通慢速拖拽不会被误识别为系统手势 |
|
||
|
||
### 审查流程
|
||
|
||
1. `git diff HEAD` 逐文件审查，重点关注非 Android 代码路径的改动
|
||
2. 确认所有新增条件分支均以 `isAndroidRemote`、`client_type === 'APK'` 等 Android 专有标志守卫
|
||
3. 共享协议结构体（`commands.h`、`LOGIN_INFOR`、`szReserved`）改动需确认向前/向后兼容
|
||
4. 服务端 C++ 改动在 Windows 下编译，前端 `index.html` 在桌面和移动浏览器两端验证
|
||
|
||
---
|
||
|
||
## 七、不在本期范围
|
||
|
||
- 音频监听（`AudioRecord` + Opus 编码）
|
||
- 文件管理（已有 `FileTransferV2`，后期可直接接入）
|
||
- 摄像头（前/后摄）
|
||
- Shell 终端（`/system/bin/sh` + PTY，可参考 `PTYHandler.h`）
|
||
- Root 特权功能（uinput、内核注入）
|