Skip to content

README.md

Latest commit

 

History

History
343 lines (250 loc) · 10.6 KB

README.md

File metadata and controls

343 lines (250 loc) · 10.6 KB

PhoneAgent Remote

让 AI 控制你的 Android 设备

PhoneAgent 的配套 Android 客户端 - 快速实现 AI 操作手机所需的配置

Main Project Author License

📖 项目简介

PhoneAgent Remote 是 PhoneAgent 的配套 Android 客户端，专为快速实现 AI 操作手机而设计。

安装后，它会在后台运行，通过 FRP 隧道和 WebSocket 与 PhoneAgent 服务端通信，让 AI 可以远程控制你的 Android 设备执行各种任务。

工作原理

PhoneAgent 服务端 (AI 大脑)
        ↓ 通过 FRP 隧道和 WebSocket
PhoneAgent Remote (手机客户端)
        ↓ 执行 ADB 指令
你的 Android 设备 (被 AI 控制)

核心功能

  • 🔗 FRP 隧道 - 自动建立内网穿透，让服务端可以访问你的设备
  • 💬 实时通信 - 通过 WebSocket 与服务端保持连接
  • 🛡️ 后台保活 - 前台服务 + WorkManager + 厂商优化，确保持续在线
  • 🎨 现代界面 - Material Design 3 设计，简洁美观
  • 🔧 增强工具 - 预装 yadb，支持中文输入和强制截图
  • 🔌 跨应用通信 - 提供 ContentProvider 接口，支持与其他应用集成
  • ⚡ 高性能 - 优化资源管理，减少日志开销

🚀 快速开始

系统要求

  • Android 版本：5.0 (API 21) 及以上
  • 架构支持：ARM64 / ARM32
  • 网络要求：能访问 PhoneAgent 服务器
  • 权限要求：通知权限、电池优化豁免（推荐）、ADB TCP/IP 访问

安装步骤

1. 下载 APK

方式一：下载预构建 APK（推荐）

前往 Releases 页面 下载最新版本：

  • 📦 文件名：PhoneAgent-Remote-v1.0.0.apk
  • 📏 大小：约 70 MB
  • 🏗️ 架构：ARM64 + ARMv7（通用版）
  • 📱 系统要求：Android 5.0+

方式二：从源码构建

如果你想自己构建 APK，请参考 🏗️ 从源码构建 章节。

2. 安装应用

通过 ADB 安装：

adb install PhoneAgent-Remote-v1.0.0.apk

或直接在手机上安装：

  • 将 APK 文件传输到手机
  • 打开文件管理器，点击 APK 文件
  • 按提示完成安装（可能需要允许"未知来源"）

3. 启用 ADB TCP/IP

重要：首次使用需要通过 USB 启用 ADB TCP/IP：

# 手机通过 USB 连接电脑
adb tcpip 5555

💡 提示：Android 11+ 可以在"开发者选项 > 无线调试"中直接启用，无需 USB。

4. 配置应用

打开应用，填写配置信息：

配置项 说明 填写示例
后端服务器 IP PhoneAgent 服务器的 IP 地址 192.168.1.100
FRP Token 与服务器配置保持一致 （填写你的服务器 token）
FRP 远程端口 FRP 分配的唯一端口 6100、6101 等
WebSocket 连接方式 选择连接模式 推荐选择"直连 IP 模式"
域名地址（可选） 仅域名代理模式需要 phoneagent.example.com
设备名称（可选） 给设备起个名字 留空自动生成

WebSocket 连接方式说明：

  • 直连 IP 模式（推荐）：直接连接服务器 9999 端口，适合内网环境、开发测试
    • 自动生成格式：ws://{服务器IP}:9999/ws/device/{远程端口}
  • 域名代理模式：通过域名 + Nginx 反向代理连接，适合生产环境、需要 SSL 加密
    • 自动生成格式：wss://{域名}/device-ws/device/{远程端口}
    • 注意：需要配置 Nginx 反向代理

点击"保存并启动"。

5. 验证连接

在 PhoneAgent 服务端查看设备是否在线：

  • 设备状态应显示为"在线"
  • FRP 连接状态应显示为"已连接"

❓ 常见问题

服务启动失败？

查看日志：

adb logcat | grep -E "PhoneAgent|FrpManager|WebSocketManager"

常见原因：

  • ADB TCP/IP 未启用（执行 adb tcpip 5555）
  • 配置信息错误（检查服务器地址、端口、token）
  • 网络不通（检查防火墙、网络连接）

设备显示离线？

检查清单：

  • 确认已执行 adb tcpip 5555
  • 检查服务器地址和端口配置
  • 确认防火墙没有阻止连接
  • 查看应用日志中的 FRP 错误信息
  • 确认服务器 FRP 服务正在运行

应用被系统杀死？

应用已集成多层保活策略，但部分厂商仍需手动配置：

手动优化步骤：

  1. 电池优化 → 找到 PhoneAgent Remote → 选择"不限制"
  2. 后台运行 → 允许后台活动
  3. 自启动 → 允许开机自启
  4. 厂商特定设置：
    • 小米：安全中心 → 应用管理 → PhoneAgent Remote → 无限制
    • 华为：手机管家 → 应用启动管理 → PhoneAgent Remote → 手动管理
    • OPPO/vivo：设置 → 应用管理 → PhoneAgent Remote → 允许后台运行

FRP 无法连接？

诊断步骤：

  1. 检查本地 ADB TCP：

    adb shell netstat -tln | grep 5555

    应该看到端口 5555 在监听。

  2. 检查 FRP 配置：

    • 服务器地址是否正确
    • FRP 端口是否正确（默认 7000）
    • Token 是否匹配

  3. 检查服务器：

    # 服务器上检查 FRP 服务
netstat -tln | grep 7000
ps aux | grep frps

  4. 查看应用日志： 应用内置日志查看器，可以查看详细的 FRP 连接日志。

🏗️ 从源码构建

环境要求

  • Android Studio Hedgehog (2023.1.1) 或更高版本
  • JDK 17
  • Android SDK API 34
  • Gradle 8.2+

构建步骤

# 克隆项目
git clone https://github.com/tmwgsicp/PhoneAgent.git
cd PhoneAgent/android-remote-control

# 构建 Release APK
./gradlew clean assembleRelease

# APK 位置
# app/build/outputs/apk/release/app-release.apk

⚠️ 重要提示

targetSdk 必须设置为 28

如果你要修改代码，请注意：不要升级 targetSdk！

// app/build.gradle.kts
android {
    defaultConfig {
        minSdk = 21
        targetSdk = 28  // ⚠️ 必须是 28，不要升级！
    }
}

原因：

  • PhoneAgent Remote 使用 Termux JNI 来执行 FRP 二进制文件
  • Android 10+ (API 29+) 引入了严格的 W^X (Write XOR Execute) 限制
  • targetSdk >= 29 的应用无法执行 app_data_file SELinux 上下文的二进制文件
  • 即使集成了 Termux JNI，targetSdk >= 29 仍然会导致 Permission denied

如果升级 targetSdk 会发生什么：

❌ FRP 无法启动
❌ 日志显示：sh: /data/.../frpc: Permission denied
❌ 服务端显示：frp_connected: false
❌ AI 无法操作手机

项目结构

android-remote-control/
├── app/
│   ├── src/main/
│   │   ├── assets/              # 预装资源
│   │   │   ├── frp/             # FRP 客户端二进制文件
│   │   │   ├── termux/          # Termux bootstrap
│   │   │   └── yadb/            # yadb 工具
│   │   ├── java/com/phoneagent/remote/
│   │   │   ├── core/            # 核心功能（FRP、WebSocket）
│   │   │   ├── data/            # 数据层（配置、仓库）
│   │   │   ├── provider/        # ContentProvider（跨应用通信）
│   │   │   ├── service/         # 后台服务
│   │   │   ├── termux/          # Termux JNI 集成
│   │   │   ├── ui/              # UI 界面
│   │   │   └── utils/           # 工具类
│   │   ├── jniLibs/             # Native 库（libtermux.so）
│   │   └── res/                 # 资源文件
│   └── build.gradle.kts         # 应用构建配置
├── gradle/                      # Gradle wrapper
├── build.gradle.kts             # 项目构建配置
├── LICENSE                      # AGPL-3.0 许可证
└── README.md                    # 本文件

📜 开源协议

本项目采用 AGPL 3.0 协议开源。

使用范围

使用场景 是否允许
✅ 个人学习和研究 免费使用
✅ 企业内部使用 免费使用
✅ 修改代码内部使用 免费使用
⚠️ 修改后对外提供服务 需开源或商业授权
⚠️ 集成到产品中销售 需开源或商业授权

AGPL 3.0 核心：修改代码并通过网络提供服务时，必须公开源代码。

商业授权：如需闭源使用，请联系洽谈商业授权。

第三方开源组件

本项目使用了以下开源组件：

🤝 参与贡献

关于 Pull Request

由于个人精力有限，目前暂不接受 PR，但非常欢迎：

  • 🐛 提交 Issue - 报告 Bug、提出功能建议
  • 💡 Fork 项目 - 自由修改和定制
  • 📖 改进建议 - 通过 Issue 提出文档和功能改进
  • ⭐ Star 支持 - 给项目点 Star，让更多人看到

提交 Issue

如果你遇到问题，欢迎在 GitHub Issues 提交 Issue。

请包含以下信息：

  • 设备信息（型号、Android 版本）
  • 问题描述和复现步骤
  • 相关日志（使用 adb logcat 或应用内日志查看器）
  • 截图（如果适用）

联系方式

  • 主项目：PhoneAgent
  • 作者：@tmwgsicp
  • 微信：SZJishere（技术交流 · 商务合作）

🌟 如果觉得项目有用，请给个 Star 支持一下！🌟

Made with ❤️ by tmwgsicp