KYRIE66nb / mobile-agent

# Mobile Agent
English | 简体中文
**让 AI 真正"握住"你的手机** —— 一个运行在本机、能看屏幕、能点屏幕的开源 Android 智能体。
> 项目处于早期开发阶段，接口与交互仍可能调整。请先在测试设备上使用，不要让它执行支付或账号安全操作。
## 为什么它和别的 Agent 不一样
桌面端 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 直接检查更新。 
### 火影替身计时——真机对局实拍
https://github.com/user-attachments/assets/2d88800f-3ffe-45b2-bfee-56f474d6c136
决斗场实战录屏：敌方替身"推测已恢复"、我方疑似替身 7.0s 读秒——全程本机像素推断，不走模型、不联网。
 开关、进 App 自动启动、冷却与采样参数，会话状态内联展示。 
 豆槽校准把双方查克拉豆框画在真实捕获帧上，滑块微调。 
 对局中倒计时胶囊浮在游戏上——敌我替身状态，本地推断。 
## 核心能力
### 双路径界面感知
| 路径 | 原理 | 适用 |
|---|---|---|
| **无障碍节点树** | 读取界面语义节点（文本、坐标、可点性），按语义点击 | 标准控件界面，精确且省 token |
| **视觉坐标** | 截图直喂视觉模型，返回像素坐标注入触控 | 图标、图片墙、Flutter/自绘界面 |
开启"视觉模型"开关后（GLM-4.5V、GPT-4o 等），`device_observe` 的截图会作为图片内容块直接发给模型，模型按截图像素输出 `x/y` 即可完成点击、滑动、输入。
### 操作安全闸（DecisionGate）
每次**有外部副作用**的工具调用（发消息、改设置、删数据……）在执行前先过一道语义裁决：
- `allow`：普通操作直接执行，不打扰你；
- `confirm`：并入现有审批弹窗，附上裁决理由；
- `block`：高风险不可逆操作直接拒绝，原因结构化回传给模型让它换路子。
裁决超时或失败自动降级为"需人工确认"——**宁可多问一次，绝不静默放行**。可在设置中关闭；只读操作永远不进闸。
**可选专用决策后端（Laya/Jev）**：安全闸裁决可外接独立小模型服务（自托管 Laya 或 TypeSafe Jev，`deploy/laya/` 有部署说明）——默认不接入，出站需显式同意且只发最小判定上下文，本地策略仍是权威（服务只能选候选，不能发明动作），SHADOW/ENFORCE 双模式，裁决记录可回看。
### 设备控制双引擎
- **无障碍服务**（免 Root）：读节点树、点击、输入、滑动、监听前台应用切换；
- **Root 虚拟屏**（可选）：独立的 `RootDeviceService` 进程在 VirtualDisplay 上干活，截屏 + 触控注入在**后台虚拟屏**执行，你主屏该干嘛干嘛；悬浮窗可实时围观 Agent 操作。
**执行位置偏好**（设置 → 通用 → 设备操作位置）：
| 档位 | 行为 |
|---|---|
| **自动**（默认） | Agent 按任务性质选主屏/后台；虚拟屏不可用时**自动降级主屏**继续执行，降级在审批文案和工具结果中如实披露 |
| **仅主屏** | 固定前台操作，无 Root 设备省掉注定失败的虚拟屏尝试 |
| **仅后台** | 只用虚拟屏，失败即失败，**绝不静默触碰主屏** |
**Shizuku 降级通道**：非 Root 设备安装并授权 Shizuku 后，`system_shell` 工具可以 shell(uid 2000) 身份执行白名单管理命令（am/pm/dumpsys/settings/input/content 等，拒绝管道与拼接），用于查应用信息、清缓存、发按键事