Home

📖 Android Guru Agent · Wiki

🤖 原生于 Android 的自主智能体 —— 设备上的大脑、终端、与肌肉记忆

An autonomous AI agent that lives entirely on your Android device.

一个开源 Android 端自治智能体：OpenAI 兼容流式 LLM · 6 种执行模式 · 109 个内置工具 · PRoot 沙箱化 Ubuntu 24.04 终端 · 仿生认知记忆 cs-mem · 三级权限链 · AIDL 插件 SDK —— 全部跑在一台手机上，无需任何服务器。

仓库 · CI · 质量门禁

技术栈

项目事实

快速跳转

---

🆚 与其他方案对比

维度	Android Guru Agent	PC 端编码智能体（Claude Code / OpenHands 等）	传统自动化工具（Tasker 类）	手机 AI 聊天 App
运行位置	📱 全程在设备上	💻 PC / 服务器	📱 设备上	☁️ 云端
需要服务器/PC	❌ 不需要	✅ 需要	❌ 不需要	✅（厂商云）
LLM 可换性	✅ 任意 OpenAI 兼容端点 / 局域网 Ollama	固定模型或自配	无 LLM	❌ 固定
执行能力	109 工具：shell / 文件 / 结构化查询 / UI 自动化 / 浏览器 / 终端	文件 + shell + web	规则触发，无推理	仅对话
Linux 环境	✅ PRoot Ubuntu 24.04 沙箱	✅ 宿主 OS	❌	❌
跨会话记忆	✅ 陈述性语义图 + 程序性 FSM 宏旁路回放	仓库内 markdown	❌	云端会话
离线记忆	✅ Room 本地图数据库	—	—	❌
特权操作	Root / Shizuku / 沙箱三级降级	宿主用户权限	需 Root 的居多	❌
可扩展	插件 APK（AIDL）+ 技能 + MCP	MCP 等	插件市场	❌

Note

对比基于各方案公开形态的定性归纳；PC 端智能体在代码工程深度上依然更强， 本项目的差异化在于把完整的智能体闭环装进口袋。

---

✨ 十个差异化亮点

亮点 一句话 🧠 仿生认知记忆 UI 感知 → 语义降维（−90%）→ 差分摄取（−95%）→ 轨迹蒸馏成 FSM → 0 token 的"肌肉记忆"旁路回放 🛡️ 记忆免疫系统 悬浮窗钓鱼 / 无障碍劫持 / 记忆中毒防御：敏感词分级 + 结构完整性 + 可疑指纹隔离 🌙 梦境渲染 息屏 + 充电 + WiFi 时后台巩固：保鲜验证、能量衰减、跨版本拓扑迁移 💎 晶化 能量 ≥8 且成功率 ≥90% 的高频宏固化为 ROM 级技能，免疫衰减与剪枝 🛰️ MCP 双向生态 客户端：npm 生态沙箱接入 + 官方 Hub 仓库直装；服务器：逆向 Host 让 PC 的 AI 调用手机工具

亮点 一句话 🖥️ 真 Linux 终端 官方 Ubuntu 24.04 rootfs + PRoot 用户态沙箱 + 原生 C++ PTY + 自研 VT100 模拟器（纯 Kotlin 零依赖） 🔀 双引擎双工位 Agent 引擎 + 编码引擎（CodeAgentEngine）双工位拆分：长任务韧性 / 子代理 / 胶囊流式 🗜️ 上下文工程 P7 三级压缩：工具输出截断 → 滑动窗口 → LLM 摘要，双引擎统一水位检查 🛰️ BYO-LLM OpenAI 兼容协议 + 多模型角色路由 + 原生 reasoning_content 思维链透传 ⚡ 三级权限链 Root → Shizuku → 沙箱 shell 自动降级，无 Root 也能执行特权命令

Important

这一切跑在一台普通 Android 手机上。 不需要服务器，不需要 PC 伴侣， 配置任意 OpenAI 兼容 API（或局域网 Ollama）即获得完整的智能体能力。

---

🧭 阅读路线

🚀 入门 快速开始 —— 5 分钟跑起来 架构总览 —— 三层隔离 模块地图 —— 20 个模块 界面导航地图 —— 功能在哪一屏 设置项参考 · FAQ · 术语速查 🧠 Agent 内核 Agent 引擎 · 六种模式详解 任务编排器 · 任务运行时与持久化 工具系统 · 工具总目录 · 工具幂等与恢复 LLM 适配层 · 上下文压缩 🛰️ MCP 生态 MCP 生态总览 —— 沙箱接入 / 官方 Hub / 逆向 Host / 门控语义

🖥️ 终端 & Linux 终端运行时 · 终端 API 契约 SDK 边界 · Termux 能力矩阵 Ubuntu rootfs 供给 · Ubuntu 生命周期 PRoot 二进制溯源 · VT100 模拟器 终端性能 · 终端迁移 · 原生层 C++/JNI 🧠 记忆 cs-mem 认知记忆 · 记忆生命周期 · 记忆系统调研 🎨 UI / 扩展 Liquid Glass · 流水线输出 UI · UI 审计 浏览器智能体 · 浏览器设计裁决 技能与斜杠命令 · 插件 SDK · ComposeFoundry 🛠️ 工程化 从源码构建 · CI 流水线 · 质量门禁 测试体系 · 仓库脚本 · 可观测性 版本与发布 · 架构决策 ADR 混沌工程与崩溃审计 · 持久化与保活 无障碍与 UI 自动化 · 深度文档索引 🔒 参考 数据模型速查 · 安全与隐私 故障排查 · 路线图 · 贡献指南

---

📊 关键事实（自动核对过主干）

指标	数值	指标	数值
Gradle 模块	20	Kotlin 主源码	802 文件 / 183,615 行
Kotlin 测试源码	252 文件 / 64,116 行（≈4,008 个 @Test 用例）	C++（PTY / JNI / VT 原生层）	37 文件 / 10,650 行
内置工具	109（审计实测注册 ≈80，见口径说明）	Agent 模式	6
支持 ABI	arm64-v8a · armeabi-v7a · x86_64	minSdk / targetSdk / compileSdk	26 / 28 / 35
Kotlin · AGP · Gradle	2.0.21 · 8.7.3 · 8.10	Compose BOM · Hilt · Room · OkHttp	2024.12.01 · 2.53.1 · 2.6.1 · 4.12.0

Warning

targetSdk = 28 是硬红线，不是笔误。 Android 10（API 29）起系统禁止应用从可写私有目录 执行二进制（SELinux untrusted_app 域不得 exec app_data_file），而 Ubuntu rootfs 依赖 execve + ptrace。升到 29+ 会让 PRoot/guest 进程直接失败。 详见 终端运行时 · 为什么必须 targetSdk 28。

---

⚖️ 项目三条纪律（读 Wiki 前先知道）

1️⃣ 诚实声明 本地验证的写本地验证，无法验证的明确标 NOT VERIFIED，绝不写假 PASS （T81 / T82 / MIGRATION / 混沌审计四处同源）。

2️⃣ 未实现即声明 例如 Liquid Glass 的 Refraction 明确标注 NOT IMPLEMENTED， 拒绝"alpha + blur 冒充玻璃"。

3️⃣ 死层不接线、不删除 约 5000 行的平行规格层（process2 / observation2 / reliability2 …）保持原样， 能力由生产路径实现 —— 见 架构决策。

---

🚀 三分钟体验路线

① 对话：  "帮我看看设备还剩多少存储"                    ← 工具调用闭环
② 感知：  "打开设置，看看当前 Wi-Fi 名"                 ← ui_tap / ui_dump（无障碍）
③ 终端：  终端屏引导装 Ubuntu，然后"装 figlet 并打印 HELLO"
④ 记忆：  多做几次 ③，之后说"再打印一次 HELLO"           ← FSM 宏旁路，0 token 秒回

🎞️ 动效预览

_{仓库内置动效资源（GIF）· 更多 UI 细节见 Liquid Glass 与 流水线输出 UI}

📄 文档约定

• Wiki 讲 "怎么用、怎么改、为什么这样设计"；仓库 docs/ 存 原始设计稿与交付报告，索引见 深度文档索引。
• 凡出现 模块:路径 的写法，均可在仓库中按路径定位源码。
• 所有数字均以当前主干 main 为准（冲突时以审计文为准）。发现漂移请提 Issue。

---

如果这个项目对你有帮助，请点一个 ⭐ Star —— 这是持续开发的动力。

Made with ❤️ and a lot of ☕ · Kotlin · Compose · PRoot · Room

Android Guru Agent · 官网 · 仓库 · 下载 APK · 报告问题 · 发起 PR · 回到顶部