yuanyuanxiang/SimpleRemoter
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity
Files
v1.3.7
SimpleRemoter/android/PLAN.md
yuanyuanxiang 45553ec5b6 Feat: Android client Phase 0-3 full implementation
2026-06-21 23:00:05 +02:00

15 KiB
Raw Permalink Blame History

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、内核注入）
Reference in New Issue View Git Blame Copy Permalink