Eta

AI Agent for Android

一个第三方 Android 系统级 AI Agent，能操作手机界面，也能像 Coding Agent 一样读文件、跑命令。

底层基于 libxposed API 102 的 Xposed 模块，面向 ColorOS 16。Hook 小布进程拦截对话请求，接入同一套 Agent Runtime，支持 BYOK 自定义模型；App 本体是主工作台。此外保留了 system_server、SystemUI、ColorDirectService、Google App 等进程中的早期 Hook 功能（电源键唤醒 Gemini、手势条/双指识屏触发一圈即搜），当前不是重点，后续仍会维护。

核心能力

Agent 不会问一句答一句就结束。它在一个 loop 里运转：模型发指令，系统执行，结果写回上下文，模型再决定下一步。如此往复，直到做完。

作为 Android AI Agent，Eta 同时具备 GUI 操作和终端执行能力，这和主流 Coding Agent 的逻辑一致——屏幕是表层，shell 才是完整计算环境。

GUI 操作

• 屏幕与控件：截图、读取带快照标识的无障碍节点、按节点或坐标点击，以及带位移验证的四向滚动
• 应用与系统：启动 App、把链接显式交给外部应用、模拟按键、下拉通知栏、搜索应用
• 文本与剪贴板：输入文字、设置剪贴板、粘贴、等待特定文本出现
• 运行可视化：前台操作时显示浮层与手势反馈，让你知道它正在点哪里、怎么滑

网页浏览

browser_use 是运行在 Eta 内的 Agent 浏览器，不是简单调用系统 ACTION_VIEW。它可以在不抢占前台的情况下加载 JavaScript 网页、提取保留标题/段落/列表/链接等结构的正文、查找并操作页面元素、滚动和截图；需要人工验证或用户想查看过程时，可在 App 中挂载同一个 WebView 直接接管。外部打开链接仍由独立的 open_uri 工具负责，两种能力不会混淆。

浏览器只接受 HTTPS，SSL 错误不会被忽略，并对主页面与子资源执行 URL、DNS、主机数量和 Service Worker 限制；这些检查属于纵深防护，WebView 本身并不是可绑定实际连接 IP 的独立网络沙箱，因此不能把它当作访问内网或承载高敏感凭据的安全边界。网页内容会作为不可信数据交给模型，正文按偏移分页并以 UTF-8 字节严格限长；Cookie 不会作为工具结果暴露给模型。网页工具可在设置中关闭。

终端与文件

在用户授权下执行 user 或 root shell 命令，读写文件、列目录、跑脚本、查日志、改配置。会话式 shell 保持 cwd 和环境变量，异步任务后台执行并分段读取输出。默认关闭，需手动开启。

终端按用途分为两个环境：

• android 是原生 Android Shell，负责系统、应用、日志、Magisk 和设备文件操作。Root 会话会自动发现 Magisk、KernelSU 或 APatch 提供的 BusyBox，并以 standalone ash 补齐不在系统 PATH 中的 applet。
• linux 是可选安装的 Alpine 工具环境，负责 Python、Git、Bash、jq、zip、OpenSSL、SQLite 等通用任务。Eta 下载固定版本的官方 minirootfs 并校验 SHA-256，在 App 私有目录中解压，通过独立 mount namespace + Root chroot 运行；它不是安全沙箱，也不会取代 Android 环境。

Skills

• AI 安装：直接要求 Agent 安装或更新 Skill，或显式使用 $skill-installer。Eta 可以浏览公开 GitHub 仓库、列出候选 Skill，并从 Codex 的公开 curated 目录安装用户明确选择的内容
• 本地 ZIP：在 Skills 页面选择只包含一个 Skill 的 ZIP 包导入；压缩包会先在 App 私有目录中完成路径、大小、结构和 SKILL.md 校验，再写入正式目录
• 冲突保护：同名用户 Skill 默认不覆盖，只有针对同一份 ZIP 内容或同一 GitHub 提交再次明确确认后才会替换；内置 Skill 永远不会被导入包覆盖
• 按需读取：模型先看到已启用 Skill 的索引，需要时再读取正文和引用资源。新安装的 Skill 从下一轮对话开始可用

安装 Skill 只会保存文件并建立索引，不会自动执行包内脚本，也不会替用户开启默认关闭的终端/文件工具。目前 AI 安装仅支持公开 GitHub 仓库，不接受私有仓库 Token。

通用

• 结果归档：外部入口触发的运行结果会归档到 App 会话，即使 App 进程被杀也会尝试恢复

使用场景

• 跨 App GUI 操作 — "帮我把微信未读消息都点了"，Agent 自己看屏幕、找按钮、执行
• 跨 App 比价 — 截图分析淘宝商品，自动打开京东搜索同款并返回结果
• 网页研究 — 在后台阅读 JavaScript 渲染的文档或资讯页面，保留同一浏览会话；遇到验证码时由用户直接接管
• 终端任务 — "清一下后台，查 LSPosed 日志看 Hook 有没有异常，再看看 Magisk 模块生效了没"——Agent 可以执行 shell 命令、读系统日志、查模块状态、改配置，把意图转化为终端操作
• 小布入口触发复杂任务 — 按电源键唤醒小布，用自然语言让 Agent 执行多步流程

边界说明

第三方 Xposed 模块永远做不到系统内置助手那种动画丝滑和入口一致性。但原厂做得烂的时候，Hack 就是用户唯一的选择。

• 这不是聊天机器人换皮。 普通 AI App 只能输出文字。本项目通过 Xposed Hook、无障碍服务、系统浮层和 ==root== 权限，让 Agent 同时掌握 GUI 和终端——前者操作屏幕，后者进入本机命令层。两个入口叠加，意味着 Agent 拥有接近完整手机环境的操作能力。
• 目标系统为 ColorOS 16。 Hook 点强依赖 OPPO / Google App 当前实现，系统或 App 大版本更新后可能需要重新适配。

与豆包手机助手的区别

豆包手机助手证明了手机 AI 的方向：从聊天框走向系统级操作。但它是超级 App，有平台资源，也有平台约束——跨 App 接管会撞上微信登录异常、淘宝人机验证、银行 App 风险提示。厂商要维护商业关系、支付安全和监管合规，天然被生态绑住手脚。

本项目走第三方开发者路线：不代表手机厂商，不需要维护预装合作。用户愿意解锁、==root==、启用 Xposed 和无障碍，就应该能把自己的手机入口接给自己选择的 Agent。风险边界由用户决定，工具必须透明可见，敏感操作必须能随时停止和接管。

更重要的是，我们把终端执行能力放进了 Agent Runtime。普通手机 AI 只会点屏幕，但 Agent 一旦能在用户授权下执行 shell 命令、读写文件、跑脚本、改配置，它就具备了和主流 Coding Agent 同类的"把意图转化为操作"的能力。GUI 是手机表层，终端才是完整计算环境。

系统入口接管

项目早期做了大量 ColorOS 系统入口的 Hook 工作，保留至今，当前不是重点：

• 小布接管：接管小布对话入口，解析图片上下文，交给同一套 Agent Runtime 处理。支持 BYOK，默认只在 /agent 前缀下触发
• Gemini 解锁：电源键长按唤起 Gemini、锁屏自动语音输入、息屏维持 Hey Google 检测
• 一圈即搜：手势条长按和双指识屏触发 Android contextual_search，不改系统文件

模型与 BYOK

Agent 的能力取决于你用什么模型。

• OpenAI-compatible 与 Anthropic 双协议，支持 SSE 流式传输、流式工具调用、图片输入、推理内容
• 内置提供商：OpenAI、Anthropic、阿里百炼、DeepSeek、Kimi、MiMo、MiniMax、StepFun、硅基流动、OpenRouter
• 厂商品牌图标：已知提供商在列表中显示本地品牌原色图标，未知或自定义接口保留通用图标；素材来源与许可见 第三方声明
• 自定义提供商：自定义 Base URL、API Key、请求头、body JSON
• 模型管理：内置官方目录、远程拉取列表、自定义模型、启停管理；新增项仅在确认保存后入库，远程同步只更新远程来源，不删除手工模型
• 会话历史：新会话先作为本地草稿存在，发送第一条消息后才进入历史列表

BYOK（Bring Your Own Key）意味着 Agent 能力跟随你选择的模型，而不是被内置供应限制。

安装

展开安装步骤

1. 在支持 libxposed API 102 的 LSPosed 环境中安装 APK
2. 作用域包含 system、SystemUI、Google App、小布识屏 和小布助手
3. 重启手机
4. 打开 App，配置模型提供商、API Key 和当前模型
5. 按需授予悬浮窗、无障碍、应用列表读取、位置、后台运行等权限；位置仅在 Agent 调用时间与位置工具时读取，小布等后台入口需要“始终允许”；终端/文件工具支持用户明确选择 user 或 root 身份。用户主动执行 GUI Agent 操作时，如果 Eta 无障碍服务尚未连接，Runtime 会通过 Root 在保留其他服务的前提下启用 Eta，等待服务真实连接后再执行工具；开机或升级广播仍只审计状态
6. 按需开启小布接管、终端/文件工具；需要 Python、Git 等通用命令时，再从设置中主动安装 Linux 工具环境

当前限制

• 第三方模块无法获得原厂系统组件的全部私有权限，交互 UI、动画衔接和系统级一致性会弱于厂商内置方案

项目结构

核心代码在 app/src/main/kotlin/：

ModuleMain.kt              Xposed 模块入口
Application 层             App 初始化

hook/system/               system_server Hook
hook/google/               Google App 进程 Hook
hook/colordirect/          ColorDirectService Hook
hook/breeno/               小布入口接管

agent/runtime/             Agent Runtime、跨进程协议、结果归档
agent/model/               模型提供商抽象、SSE 解析
agent/tool/                本机工具执行器
agent/browser/             共享离屏浏览器、网页读取与安全边界
agent/device/              root / 无障碍 / input 设备控制
agent/terminal/            Android/Alpine 会话式 shell、环境安装与文件工具
agent/overlay/             运行浮层与手势反馈
agent/skill/               Skills 解析、安装、安全读取与索引
agent/accessibility/       无障碍服务、节点快照与授权状态检查

data/db/                   Room：会话、模型提供商、运行归档
data/repository/           仓库层
data/provider/             内置模型提供商与官方模型目录

ui/app/                    App 根状态、导航
ui/screens/                各功能页面
ui.pages/providers/        模型提供商管理
ui/components/             通用组件
systemizer/                Google App 系统化安装器
config/Prefs.kt            RemotePreferences 配置

Agent Loop、工具批次、steering 与 transcript 语义见 docs/AGENT_RUNTIME.md。Gemini、一圈即搜和 RemotePreferences 链路见 docs/TECHNICAL.md。

参考与致谢

Eta 的开发过程中参考或关注过以下开源项目：

• Pi Coding Agent：Eta Agent Runtime 的核心参考，包括 Agent Loop、工具调用、steering 与 transcript 状态管理
• OpenOmniBot：Android 端 AI Agent 方向的参考项目
• Operit：Android Shell 与完整 Linux 工具环境分层的产品形态参考

Eta 结合自身的 Xposed 系统入口、Android Runtime、IPC 与模型协议边界进行了独立实现。

_{Community: LINUX DO}

设置 Java 环境

JAVA_HOME="D:/Environment/Java/java25"

Debug 版本（不混淆，便于调试）

./gradlew assembleDebug

Release 版本（混淆 + 资源压缩）

./gradlew assembleRelease

清理后重新构建

./gradlew clean assembleDebug