Files
AndroidDeviceStreaming/android_agent

Android 手机直接联网设备端

独立 Android Gradle 项目,Kotlin 传统 View(无 Compose)+ Rust JNI。手机无需连接现场电脑,通过本机 adbd 接入现有控制中心、P2P 与中继,远端继续使用 ads-client、ADB、scrcpy 和可选 ads-usb。

目录

目录 用途 语言/格式
app/ Android APK 模块 Kotlin、XML、Gradle Kotlin DSL
app/src/main/java/com/ttstd/ads/ Activity、前台服务、开机恢复、配置加密、日志和 JNI 声明 Kotlin
app/src/main/jniLibs/ 构建脚本生成的多 ABI JNI 运行库,Git 忽略 SO,无业务源码
native/ 独立 Cargo 工作区,JNI、生命周期、状态及输入校验 Rust、TOML、Cargo.lock
native/src/ Rust 网关入口与单元测试 Rust
scripts/ Windows NDK 多 ABI 构建脚本 PowerShell

build/、.gradle/、native/target/ 为自动生成产物或缓存,不纳入源码。当前直接通过源码路径复用 ../agent/src/gateway.rs 和 ../crates/ads-core,所以本目录需要与整个仓库一起检出,不能只复制此目录构建。

当前实现

  • 支持最低 Android 6 / API 23,compile/target API 35;API 26+ 通知渠道与 startForegroundService;API 34+ specialUse 类型;不使用受新版限时约束的 dataSync 类型冒充长期连接。
  • Kotlin Activity 提供控制中心、设备 ID、内置 Agent 令牌、本机 adbd 端口、启动/停止和实时日志。
  • Service 工作线程调用 JNI,Tokio 双线程执行网络;UI 不阻塞等待网络。控制连接断线时终止旧会话,按现有网关 1–30 秒退避重连。
  • 原样复用现有网关 v1/v2:设备注册、独占租约、WebRTC P2P、独立中继回退、32 路并发限制、流控和超时。
  • 当前测试包从 Git 忽略的 agent.local.properties 读取 agentToken 并编入 BuildConfig;界面无需输入,不回显、不传 Intent、不写入日志。内置令牌可从 APK 提取,此包仅用于受控测试,不应公开分发。
  • Rust 日志有界队列 300 条;服务每秒转入 Logcat(ADS-Agent)及应用内 300 条环形日志。记录启动、ABI、adbd 探测、注册、连接失败、重试、转发失败和退出,不记录票据、SDP、ADB 内容。
  • BOOT_COMPLETED 仅在用户已启用时尝试恢复;不支持解锁前启动。停止按钮关闭下次开机恢复,关闭界面不停止服务。

系统前置条件与边界

按需求不实现运行时权限申请、通知权限弹窗、忽略电池优化申请、Shizuku、root、setprop 或隐藏 API 提权。Manifest 中正常声明网络、开机及前台服务权限。

ROM 必须预先提供可被本应用访问的原始 adbd TCP 端点(固定连接 127.0.0.1,默认 5555),并配置必要的 SELinux、系统预授权和后台策略。此处连接的是手机 adbd,不是电脑 ADB server 的 5037,也不是 Android 无线调试的配对/TLS 端口。程序不会自动开启 adbd,不会关闭 ADB 认证。电脑首次调试密钥授权仍由 adbd/ROM 管理。

注册成功仅代表手机已连中继,不代表 adbd 可调试。ADBD_PROBE_OK 仅代表端口可连接;探测失败仍允许注册,实际数据通道会明确报无法连接 adbd。

当前是 APK 内的 Rust JNI 服务,不是 init 托管 native 守护。START_STICKY 和开机广播不能保证 OEM 强杀、强制停止、Doze、未解锁或系统禁止前台启动时仍永久在线;系统签名也不能替代 ROM 的策略配置。未实现独立 init 服务和 SELinux 策略,不能宣称已完成所有 ROM 常驻适配。

支持 ABI:arm64-v8a、armeabi-v7a、x86_64;不包含 x86。设置 16 KB ELF 对齐,仍需在真实 16 KB 系统验收。Android 6–15 是代码适配范围,不是实机兼容认证;更高版本需要按目标 ROM 验证。

只构建,不安装

准备 JDK 17、Android SDK 35、Gradle 8.11.1+(当前插件 8.9.2)、NDK r28+、Rust Android targets。仓库不包含平台签名私钥,不自动签系统应用,不执行安装、刷机或更改设备配置。

# 仓库根目录;仅编译现有工具链,不安装任何目标或软件
.\android_agent\scripts\build-native.ps1 -Ndk F:\AndroidSDK\ndk\28.2.13676358
cd android_agent
# ANDROID_HOME 指向已安装 SDK;或在 Git 忽略的 local.properties 配置 sdk.dir
gradle :app:assembleDebug

APK 构建会检查三种 ABI 的 SO 是否存在,不允许静默输出缺少 native 核心的 APK。当前默认使用本机提供的 Crosshatch 证书签名;系统预装、权限白名单和 SELinux 集成仍由设备厂商 ROM 流程完成。

cargo test --manifest-path android_agent/native/Cargo.toml --locked --lib
# 如需纯 Kotlin/Manifest 编译检查(不能将其产物视为可用 APK)
gradle :app:compileDebugKotlin -x verifyNative

日志查看(将来安装验证时):adb logcat -s ADS-Agent。启动失败按 CONFIG_INVALID、JNI_LOAD_FAILED、FGS_DENIED、ADBD_PROBE_FAILED、START_FAILED 排查。不要把令牌/配置 JSON 添加到诊断输出。

参考:前台服务类型、启动前台服务。

本次验证

  • Rust 主机侧 3 项测试通过;ARM64、ARMv7、x86_64 的 Release SO 均编译完成。
  • Gradle Release 编译、Manifest/资源处理、Lint Vital 和 APK 打包通过;使用 SDK 35 本地 aapt2 解决离线工具依赖缺失。
  • apksigner verify 通过,v1/v2 签名有效;证书 SHA-256 与指定 keystore 别名导出的证书一致:c8a2e9bccf597c2fb6dc66bee293fc13f2fc47ec77bc6b2b0d52c11f51192ab8。
  • APK 包含三个 ABI 的 JNI 库与 classes.dex;minSdk 23、targetSdk 35。ARM64 ELF LOAD 对齐检查为 0x4000。
  • 已签名 APK:../bin/apk/ads-android-agent-0.1.0-crosshatch.apk(12,846,591 字节)。
  • 未安装、刷机或进行真机多版本、休眠保活及公网远程调试验收。

默认签名

app/build.gradle.kts 默认对 debug 和 release 使用 crosshatch 签名。当前机器的密钥位置、别名和口令存放在 Git 忽略的 signing.local.properties,不把口令写入可提交构建脚本。复制项目到其他机器时需提供该文件(storeFile、storePassword、keyAlias、keyPassword),或对应 ADS_SIGNING_STOREFILE、ADS_SIGNING_STOREPASSWORD、ADS_SIGNING_KEYALIAS、ADS_SIGNING_KEYPASSWORD 环境变量。

gradle :app:assembleRelease

Gradle 中间输出为 app/build/outputs/apk/release/app-release.apk;成功后自动交付到 ../bin/apk/,debug 文件增加 -debug 后缀。签名不会自动获得系统应用身份、ROM 白名单或 SELinux 权限;需要与目标 ROM 平台证书及系统预装配置匹配。

本机打包时可使用现有 SDK 的 aapt2(PowerShell 参数需保留引号):

gradle :app:assembleRelease '-Pandroid.aapt2FromMavenOverride=F:/AndroidSDK/build-tools/35.0.0/aapt2.exe'

固定 Agent 测试包(0.1.1)

按当前要求,构建时将现有 config/private/agent.env 中的 ADS_AGENT_TOKEN 写入 Git 忽略的 agent.local.properties,通过 BuildConfig.AGENT_TOKEN 固定在 APK 内。界面已移除令牌输入框,保存配置只保存服务器、设备 ID 和 adbd 端口;旧版加密令牌字段在保存时清理,运行时始终使用内置值。

重新构建仍需本机 agent.local.properties;该文件和签名配置都不得提交。没有新增自动启动或自动开启 adbd 行为,仍需用户点击保存并启动。产物为 ../bin/apk/ads-android-agent-0.1.1-crosshatch.apk,versionCode=2,默认 Crosshatch 签名。

后续 APK 统一交付到仓库 bin/apk/,该目录只保存自动生成的 APK,无业务源码且不纳入 Git。