Mobile Agent

English | 简体中文

让 AI 真正"握住"你的手机 —— 一个运行在本机、能看屏幕、能点屏幕的开源 Android 智能体。

项目处于早期开发阶段，接口与交互仍可能调整。请先在测试设备上使用，不要让它执行支付或账号安全操作。

桌面端 Agent 的天花板是浏览器；这个项目的天花板是你手机上装的每一个 App。

它不靠 API、不靠网页版——AI 像人一样看屏幕、点屏幕：微信、美团、设置、相册，只要人能在界面上操作，Agent 就能操作。

• 不挑 App：无障碍语义节点 + 视觉坐标双路感知——标准控件走语义，Flutter/自绘界面走像素。
• 安全先于执行：外部副作用动作先过语义安全闸（放行/确认/拦截），宁可多问，绝不静默放行。
• 前台后台都能跑：无障碍服务免 Root 直控前台；Root 虚拟屏在后台屏幕干活，悬浮窗实时围观。
• 电脑也能控制手机：内置 loopback 鉴权桥 + adb forward + 零依赖 MCP 服务，桌面 Agent 直接读屏点屏。
• 跑一遍就能沉淀：流程固化成 Recipe 模板秒级回放；定时/通知触发任务带工具范围隔离，无人值守也安全。
• 数据全留在本机：对话、产物、裁决记录本地存储可整库导出；外发只有你显式配置的模型/语音服务。

交互式架构图（下载后用浏览器打开，支持缩放 / 路径追踪 / 暗色模式）

全部来自真机截图，没有渲染图。部分画面上悬浮的深色小条是 Agent 悬浮窗（展开 / 产物 / 设置 / 关闭），任务执行时会实时同步 Agent 正在做什么。

提需求。输入框里就有模型切换和单次发送的思考强度。	问清楚。需求有关键歧义时停下来让你点选，而不是瞎猜。	过你手。设为"每次询问"的工具会等你裁决：不允许 / 仅此次 / 始终允许。	去执行。工具调用流式渲染成卡片：只读调用并行跑，写操作保持顺序。

Markdown 排版回答；输入区集成语音、附件、思考开关和模型选择。	置顶/最近会话可搜索，全部只存在本机。	每组工具独立开关，各有权限档位（始终允许 / 使用时 / 每次询问）。	不可用的工具直接说明缺什么——比如手机操作要 Root，通知要先授权。	"询问用户"与"定时任务"工具组——歧义时反问，触发任务按授权范围无人值守执行。

主题、语言、步数上限、操作安全闸、专用决策后端入口。	决策后端选择、模型故障切换、结果语音播报、广告守卫、定时任务。	设备操作位置（自动/主屏/后台）、详细日志、常驻悬浮助手、Root 状态。	个性化提示词——长期记住你的偏好、习惯和回复风格。
能力总览：所有系统授权与高级通道一目了然，可一键跳转授权页。	每个工具组如实报告状态——可用 / 受限 / 不支持，并写清卡点。	模型配置：服务地址、模型 ID、上下文窗口，最多存 20 套。	自动压缩阈值 + 思考强度档位，官方推荐值一键填充。	视觉模型开关——截图随界面识别结果一起发给模型，按像素坐标操作图标和图片界面。

语音转写走 OpenAI 兼容或讯飞接口，配完可先测连接。	分模型 token 用量、缓存清理与产物保留策略。	整库 JSON 导出/导入，按记录主键合并不重复。	版本信息与从 GitHub Releases 直接检查更新。

决斗场实战录屏：敌方替身"推测已恢复"、我方疑似替身 7.0s 读秒——全程本机像素推断，不走模型、不联网。

开关、进 App 自动启动、冷却与采样参数，会话状态内联展示。	豆槽校准把双方查克拉豆框画在真实捕获帧上，滑块微调。	对局中倒计时胶囊浮在游戏上——敌我替身状态，本地推断。

开启"视觉模型"开关后（GLM-4.5V、GPT-4o 等），device_observe 的截图会作为图片内容块直接发给模型，模型按截图像素输出 x/y 即可完成点击、滑动、输入。

每次有外部副作用的工具调用（发消息、改设置、删数据……）在执行前先过一道语义裁决：

• allow：普通操作直接执行，不打扰你；
• confirm：并入现有审批弹窗，附上裁决理由；
• block：高风险不可逆操作直接拒绝，原因结构化回传给模型让它换路子。

裁决超时或失败自动降级为"需人工确认"——宁可多问一次，绝不静默放行。可在设置中关闭；只读操作永远不进闸。

可选专用决策后端（Laya/Jev）：安全闸裁决可外接独立小模型服务（自托管 Laya 或 TypeSafe Jev，deploy/laya/ 有部署说明）——默认不接入，出站需显式同意且只发最小判定上下文，本地策略仍是权威（服务只能选候选，不能发明动作），SHADOW/ENFORCE 双模式，裁决记录可回看。

• 无障碍服务（免 Root）：读节点树、点击、输入、滑动、监听前台应用切换；
• Root 虚拟屏（可选）：独立的 RootDeviceService 进程在 VirtualDisplay 上干活，截屏 + 触控注入在后台虚拟屏执行，你主屏该干嘛干嘛；悬浮窗可实时围观 Agent 操作。

执行位置偏好（设置 → 通用 → 设备操作位置）：

Shizuku 降级通道：非 Root 设备安装并授权 Shizuku 后，system_shell 工具可以 shell(uid 2000) 身份执行白名单管理命令（am/pm/dumpsys/settings/input/content 等，拒绝管道与拼接），用于查应用信息、清缓存、发按键事件——无需抢主屏。

手机上的 Agent 可以自己动手，也可以把双手借给电脑上的 Agent：App 内置一个只绑 127.0.0.1:17325 的鉴权 HTTP 桥，经 adb forward 暴露给桌面端零依赖 Python MCP 服务——Claude Code、Devin 或任何 MCP 客户端像操作一台远程设备一样读屏、点屏、输文字。

交互式链路图（下载后用浏览器打开，支持缩放 / 路径追踪 / 暗色模式）

• 安全边界是硬设计：HTTP 只绑 loopback，Bearer token 配对且只能经 adb shell 取到；服务不可导出，开关在 App 设置页显式掌控；桥会话排他，桌面端对可能已执行的动作绝不盲重放——断线只会报"不确定成没成"，不会重复点两次。
• 19 个 aua_* 工具：observe（节点树 + 截图）、find / tap / long_press / swipe / type_text / press_button / launch_app，以及 batch、scroll_find、collect_list、apps、screen（MJPEG 实时预览）与 setup / ready / doctor / metrics 装配诊断全套。
• 与 App 内 Agent 同一条网关：选择器按文本/描述/id/类型/正则命中无障碍节点，命中不了回退截图像素坐标；Unicode 文本按字素分段续传，滚动与批量动作都带执行校验。

真机接通路径（红米 Android 16 实测）：

python3 desktop/server/android_use.py   # 作为 MCP stdio 服务注册进客户端
# aua_setup: discover → configure → enable_accessibility → pair → forward → ready
# 开启桥：设置 → 通用 → 电脑控制（USB）（release 包不可 run-as，开关是唯一权威入口）

手机侧：设置 → 通用 → 电脑控制（USB），一键开关，状态文案显示监听端口与配对方式。	桌面侧：`aua_screen` 打开浏览器 MJPEG 预览页，操作前先眼看手机画面；需要登录/解锁时 `aua_screen pause` 立刻断流。

对 Agent 说"清理一下手机""释放点内存"即可触发，三条路径按权限自动选择：system_storage_stats 查占用明细/Top N（需用量访问权限，缺失自动引导授权）、system_clear_cache 清应用缓存（Root 直清 cache/code_cache 并返回释放字节，无 Root 降级走界面操作）、system_free_memory 结束后台进程。清理类属外部副作用，过安全闸 + 审批确认。

真机实测——对它说一句"清理手机"的完整过程：

清缓存触发安全闸审批——操作范围、风险说明、将执行的参数全部摆明再动手。	中途主动反问：要不要结束后台进程释放内存？选项结构化，点一下即答。	收尾汇报：各应用缓存占用排名、已清结果、下一步怎么批量清（甚至主动提醒别误点"清除数据"）。

弹窗和摇一摇广告只闪现几秒，模型来不及反应——拦截交给无障碍事件流上的确定性规则引擎（毫秒级，不走模型），模型退居二线按需配规则：开屏"跳过"自动点、"广告"弹窗自动关、auto_back 撤销甩到落地页的跳转（包内广告页按特征类名同样拦截）。对它说"XX 老弹红包广告"，它现场写规则下次秒拦。每规则独立冷却 + 全局熔断，拦截记录可回放；设置页一键开关，默认关闭。

真机实测——对它说"帮我拦抖音的开屏广告"：

悬浮窗里就能看到它构造规则的全过程：跳过文案候选、上下文条件逐项取舍，新增规则过审批才落库——中间它自己发现匹配词有个错字，主动删了重建。	完工汇报：守卫开关顺手打开、无障碍已连接、3 条规则（2 内置 + 新加的"抖音开屏跳过"）；包名无法本机核实也如实披露，并主动提出补一条弹窗类规则。

交互式守卫回路图（下载后用浏览器打开，支持缩放 / 路径追踪 / 暗色模式）

高频流程不该每次让模型重新探索界面——操作模板把验证过的流程固化为确定性步骤序列，执行全程不进模型。内置 wechat_send_message 开箱即用；Agent 走通一遍后可 recipe_save 存成参数化模板（{contact}、{message} 占位符）秒级复现；某步超时返回失败步骤序号，模型从断点改用通用操作兜底，不卡死重来。模板在主屏前台执行，需无障碍服务在线。

把"每天早上""收到通知时"这类自动化交给触发器——任务在后台无人值守执行，结果以本地通知交付：

• 三种触发：定时（一次性 / 每天 / 工作日 / 每周）、通知匹配（包名+标题+正文正则 AND）、周期巡检（≥15 分钟）；RTC_WAKEUP 排期，开机自动重排；
• 安全边界是硬约束：每任务独立 tool_scope 白名单——scope 外调用直接拒绝，默认只读；无人值守任务免审批但受冷却、每日上限、连续失败熔断约束，敏感通知永不触发；通知正文以低信任数据注入；
• 历史隔离 + 快捷回复：每任务独立会话与日常聊天分离；notifications_reply 经通知 RemoteInput 免打开 App 直接回消息（需在 scope 显式授权）。

对它说"每天早上 8 点读一下今天日程"即可创建；省电策略可能延迟触发，通知匹配需"通知使用权"。可选开启任务完成的离线 TTS 播报。

决斗场「替身术」冷却的纯本地推断计时：不开聊天、不调用模型、不联网——打开 App 授权录屏后进入游戏自动识别，双方豆槽变化即出倒计时悬浮窗：

• 无需 Root：MediaProjection + mediaProjection 前台服务采集主屏，ImageReader 只留最新帧（慢设备丢帧不排队）；
• 间接推断，如实标注：对左右豆槽 ROI 网格采样做 HSV 分类，连续 3 帧确认计数，仅稳定 n→n−1 判为疑似替身启动单调钟倒计时；主动扣豆、多豆跳变、爆闪遮挡不误报，候选一律带"疑似"标记；
• 自动启动语义清晰：打开 App 幂等进入授权→待机→识别流程，拒绝不循环弹窗；暂停本次与永久关闭分开，离开游戏自动隐藏；
• 校准驱动：设置页"豆槽校准"用游戏帧框选双方豆位（仅内存帧不落盘），坐标/冷却/阈值全部可持久化调整；
• 安全边界：不注入输入、不读游戏内存、不绕过检测——只观察像素并显示推测倒计时，是否封号由游戏规则决定（文档页见 docs/substitution-timer.md）。

• OpenAI 兼容网关：自建 OkHttp + SSE 流式解析，GLM / OpenAI / DeepSeek / 任意兼容端点即插即用，多配置切换 + reasoning_effort 透传；
• 调用与执行韧性：瞬时故障指数退避重试、主配置失败自动切备用模型、已产出内容绝不重发；上下文超限自动三段压缩后原轮重试，不把任务打死；
• 多轮 Agent 循环：步数上限、随时取消、调用全程落库可回放；只读工具并行执行，界面识别结果紧凑序列化压低每轮 token；
• 50+ 内置工具：设备操作、文件/文档读写编辑、网页抓取、通知、剪贴板、应用启动、语音转写、系统维护、广告守卫、操作模板、定时任务、联系人/日历——细节见上文各节。

纯 Kotlin 六模块，零框架依赖（无 Hilt / Koin / MVVM 框架），核心运行时不碰 Android SDK：

技术栈：Kotlin 2.0 + Jetpack Compose（Material3）+ Room + DataStore + Coil + libsu，Gradle Kotlin DSL 版本目录，minSdk 24 / targetSdk 36。

从 Releases 下载 APK，或在 App 内 设置 → 关于 → 检查更新 直接升级。

git clone https://github.com/KYRIE66nb/mobile-agent.git
cd mobile-agent
./gradlew :app:assembleDebug    # 产物在 app/build/outputs/apk/debug/

设置 → 模型 → 新建配置：

• 地址：https://open.bigmodel.cn/api/paas/v4
• 模型：glm-5.3-flash（视觉能力用 glm-4.5v 并开启"视觉模型"开关）
• Key：智谱开放平台 API Key
• 思考强度：参数名保持 reasoning_effort，等级可在编辑器一键填入官方档位（GLM-5.3：low/high/max；GLM-5.2：minimal–max 全档）；聊天输入框左侧可随时切换
• 自动压缩阈值：同一编辑页可调（30%–95%，默认 80%），大窗口模型可调晚压缩；上下文长度按模型真实窗口填写（如 GLM-5.3 的 1M）

已交付：视觉截图操作、语义安全闸、App 内一键升级、虚拟屏后台执行（自动降级）、系统清理、广告守卫、操作模板、触发器、Shizuku 降级通道、Office 文档读写与手术编辑、通知快捷回复、能力总览、独立决策后端、火影替身计时、桌面 USB 控制桥。

进行中

• 更多内置操作模板（支付宝、美团等高频场景的版本适配）

应用可能申请麦克风、通知、悬浮窗、开机启动、应用列表以及无障碍权限。Root、无障碍、截图和外部模型调用都是高权限能力，只有在你主动开启或确认后才使用。

模型请求、语音转写和网页访问会把相关内容发送给你配置的第三方服务。安装前请阅读 隐私说明。

• 产品定义 · 设计规范 · 技术架构 · 实施计划
• 更新记录 · 第三方声明 · 安全策略

本项目源码以 Apache License 2.0 开源，第三方组件遵循各自许可证。