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。