phongent 教程：用 iPhone 或安卓协同控制多台手机 Agent

phongent 是什么

phongent 是一个多设备 Agent 协同控制项目。它允许你使用自然语言向全部设备、某个设备组或指定设备分配任务，并在一个界面中查看执行进度、结果、通知消息和安卓设备的实时画面。

iOS 和 Android 都可以作为主控端，负责连接和管理安卓执行端。两者均支持任务分配、结果查看、消息管理、实时小窗和接管操作；只有 Android 可以直接执行本机 App 操作任务。

注意：iOS 当前只作为主控连接安卓执行端，不能执行 iPhone 本机 App 操作任务。

核心功能

• 多设备任务分配：长按设备并描述任务，也可以让主控的任务代理自行决定如何向设备下发任务。
• 设备分组协作：选择整组设备批量执行任务，也能为不同组或组内某一台设备指定不同任务。
• 内容创作与分发：主控模型可以生成多份文案和文字图卡，再将不同内容交给对应设备处理，并支持附带图片。
• 安卓实时小窗：查看安卓虚拟屏画面，并通过点击、滑动和输入接管设备操作。该功能默认开启，可在设置中关闭。
• 消息集中处理：按照设备、应用和消息来源整理通知，并让目标安卓设备的 Agent 回复消息。
• 集中配置：管理记忆、技能、定时任务和操作路线，可选择单台设备或批量操作。
• 连接管理：支持局域网发现、首次授权、一键连接、断线重连、设备重命名和设备网格。

安装前的准备

设备和系统要求

• 至少准备一台作为执行端的安卓设备。
• 主控端可以是 iPhone，也可以是安卓设备。
• 主控和执行端需要连接到同一个局域网。
• 安卓最低安装版本为 Android 11，具体操作能力还会受到系统版本和权限设置影响。
• iOS 最低部署版本为 iOS 17，目前需要通过 Xcode 构建、签名并安装。

选择正确的安装包

安卓用户可以从项目发布页下载 phongent.apk。请使用 phongent 项目提供的构建，不要使用上游项目的 APK 替代，因为上游版本可能缺少多设备群控所需的接口。

快速配置与连接

1. 安装应用。在安卓设备上安装 phongent APK。iOS 主控需要在 macOS 上使用 Xcode 构建并签名安装。
2. 设置安卓执行端。在应用内配置所需模型和手机操作能力，并根据实际功能授予无障碍、通知读取等权限。底层手机操作设置可参考项目的 设置指南。
3. 保持执行端服务运行。确认安卓端服务已经启动，并让主控设备与安卓执行端接入同一局域网。
4. 连接设备。在主控的“设备”页面选择发现到的安卓设备，或使用“一键连接”。首次连接时，需要在安卓端确认授权。
5. 配置主控模型。进入主控设置，配置负责理解和下发任务的模型。相关应用账号需要在对应执行设备上登录。
6. 开始协作。进入“agent”页面，选择全部设备、一个设备组或单台设备，然后输入自然语言任务。

设备完成首次授权后可以断线重连。如果设备没有被发现，应先检查局域网连接和安卓端服务状态，而不是立即重复安装应用。

认识四个主要入口

• 设备：发现、连接、重命名和分组安卓设备。
• agent：分配任务，查看执行进度、结果和实时小窗。
• 消息：按照设备、应用和来源查看通知，并发起回复任务。
• 设置：配置主控模型、执行端能力以及相关同步选项。

基础用法：向设备下发任务

给不同设备分配不同任务

假设设备名称分别为 A 和 B，可以直接在任务中说明每台设备要做什么：

A 打开小红书主页并截图，B 打开浏览器查看今天的天气。

提交后，可以按设备查看执行进度和结果。如果需要观察或纠正安卓端操作，可以打开对应设备的实时小窗，通过点击、滑动或输入进行接管。

按设备组批量协作

对于内容生产、检查或运营等重复工作，可以先建立设备组，再使用组名分配任务：

内容组分别生成一份产品介绍草稿，检查组查看各设备的任务状态。
内容组里的 A 改为整理已有素材，其余设备继续生成草稿。

这类描述既可以为整个组指定统一目标，也可以覆盖组内某一台设备的任务。

生成并分发不同内容

需要让每台设备处理不同素材时，可以要求主控模型分别生成内容，然后逐台下发：

为内容组的每台设备生成不同的标题、正文和文字图卡，
分别下发给对应设备，保存为草稿，暂不发布。

任务中明确加入“保存为草稿，暂不发布”之类的限制，有助于表达期望的操作边界。实际执行仍取决于模型配置、目标 App 状态、账号登录情况和已授予的系统权限。

创建和管理设备分组

1. 打开“设备”页面。下方网格会显示当前已连接的设备，以及每台设备的名称和所属组。
2. 点击“分组”，勾选需要管理的设备。
3. 选择已有组或创建新组。
4. 点击“移动 N 台”，完成批量移动。

每台设备只能属于一个组，移动后会离开原来的组。没有手动分组的设备会被归入“默认组”。

长按设备头像或卡片，可以重命名设备或移动分组。设备重命名会尝试同步到对应安卓 App，但需要执行端支持相应接口。

分组信息保存在当前主控端，不会自动同步到另一台主控设备。在多主控环境中，需要分别维护每个主控端的分组。

集中查看并回复通知

phongent 可以读取已获授权的安卓通知，并按设备、应用和消息来源进行整理。进入“消息”页面后，可以查看通知详情，并将回复任务交给对应安卓设备的 Agent。

1. 确保目标安卓设备已经授予通知读取权限。
2. 在主控端打开“消息”入口。
3. 按设备、应用或来源找到目标通知。
4. 进入通知详情并发起回复任务。
5. 由目标安卓设备上的 Agent 完成实际回复操作。

如果主控端看不到通知，应优先检查目标安卓设备的通知读取权限、执行端服务和连接状态。

高级使用技巧

让任务描述更容易执行

• 写清设备或组名：例如“内容组”“检查组”或“A 设备”。
• 拆分不同目标：明确说明每台设备的操作，不要把多个设备的要求混在一个含糊的句子中。
• 注明最终状态：例如“截图后返回结果”“保存为草稿”“暂不发布”。
• 覆盖组内任务：先给整个组分配目标，再单独说明某一台设备需要改做什么。
• 先检查账号：涉及第三方 App 时，提前在对应安卓设备上完成账号登录。

合理使用实时小窗

实时小窗适合观察 Agent 操作过程，或在自动操作遇到页面变化时手动接管。它默认开启；如果不需要实时画面，可以在设置中关闭。

批量维护执行端

记忆、技能、定时任务和操作路线等配置可以集中管理，并按功能选择单台或批量操作。批量修改前应确认选中的设备范围，避免把只适用于某台设备的设置应用到整组设备。

处理连接问题

• 确认主控和执行端处于同一局域网。
• 确认安卓执行端服务仍在运行。
• 首次连接时，在安卓设备上完成授权。
• 已授权设备断线后，可尝试重新连接或使用“一键连接”。
• 设备网格只显示已连接设备，未出现的设备不代表已经成功连接。

从源码构建 Android 版本

项目的 Android 应用、主控界面和执行端服务位于 app/，Agent 核心能力位于 core/。构建需要 JDK 17 和 Android SDK，当前使用 compileSdk 36。

./gradlew :app:assembleDebug

调试 APK 会生成在 app/build/outputs/apk/debug/。安装前，应确认构建产物已经使用自己的开发签名签署。

从源码构建 iOS 主控

iOS 构建需要 macOS，以及支持项目所用 SDK 的 Xcode。最低部署版本为 iOS 17。

1. 使用 Xcode 打开 ios/MikaRemote.xcodeproj。
2. 选择 MikaRemote scheme。
3. 在签名设置中选择自己的开发团队。
4. 连接目标 iPhone，然后构建并安装。

仓库中的 ios/ 目录包含 iOS 主控、组件和实时活动；tools/android-emulators/ 提供安卓模拟器联调工具；设置指南、协议和验证记录位于 docs/。

安全提示：模型密钥、账号凭证和本机签名材料不应写入源码或提交到版本库。

总结

phongent 将多台安卓设备组织成可集中管理的 Agent 执行环境，并允许使用 iPhone 或安卓设备作为主控。完成执行端权限、局域网连接和主控模型配置后，就可以按单台设备、设备组或全部设备分配任务，同时查看结果、实时画面和通知消息。项目基于 Mika 开发，并沿用 Apache License 2.0。