Quick Start

快速开始

🚀 入门 · 🏠 首页 › Quick-Start

---

📑 本页目录

• 1. 环境要求
• 2. 路线 A：直接安装 APK（推荐先走这条）
• 3. 路线 B：从源码构建
• 4. 配置 LLM（BYO-LLM）
• 5. 解锁更多能力（全部可选，无 Root 也能玩）
• 6. 第一句话该说什么
• 7. 接下来读什么

目标：5 分钟跑起来并让智能体替你干第一件活。三种路线任选其一 —— 装 APK（最省事）、 自己构建（要改代码）、先了解后再装。

1. 环境要求

依赖	版本	说明
设备	Android 8.0+（API 26）	arm64-v8a / armeabi-v7a / x86_64 三种 ABI 都随包提供 PRoot 二进制
JDK	17（Temurin 推荐）	仅源码构建需要
Android SDK	compileSdk 35 + NDK 27.0.12077973	仅源码构建需要（terminal 原生层）
Gradle	8.10	仓库未锁定 wrapper，首次需现场生成
LLM	任意 OpenAI 兼容端点	OpenAI / DeepSeek / OpenRouter / 中转 / 局域网 Ollama

2. 路线 A：直接安装 APK（推荐先走这条）

1. 打开 发布仓库 下载最新 APK（v1.4.4.x，arm64 设备选 arm64-v8a 变体，内置 Ubuntu rootfs，见 Ubuntu rootfs 供给）；或 Actions → ci.yml 最新版 → 下载工件 app-debug-apk（保留 14 天）。
2. adb install -r app-debug.apk（或直接在手机上点击安装包）。
3. 桌面会出现 赛博霓虹悬浮球（EasyFloat），点它可从任意界面唤起应用。

Note

如果系统提示"应用针对旧版 Android 开发"，这是预期的：项目必须 targetSdk = 28， 原因见 终端运行时。

3. 路线 B：从源码构建

git clone https://github.com/AceGuru-mjh/Android-Guru-Agent.git
cd Android-Guru-Agent

# 仓库未锁定 wrapper——用本机 Gradle 8.10 现场生成（仅首次）
gradle wrapper --gradle-version 8.10
chmod +x gradlew

./gradlew :app:assembleDebug --stacktrace

产物：app/build/outputs/apk/debug/app-debug.apk。 完整排错见 从源码构建。

4. 配置 LLM（BYO-LLM）

1. 安装启动 → 抽屉 设置；
2. 选择预设：OpenAI / DeepSeek / OpenRouter / Ollama / 自定义；
3. 填 Base URL + API Key + 模型名；局域网 Ollama 填 http://<pc-ip>:11434；
4. 点 测试连接（会发送 Say 'OK' in one word. 验证）→ 保存。

Tip

未配置任何端点时，应用注入 NoOpLlmClient：界面友好提示，不会崩溃。 Key 只写进应用私有目录 + EncryptedSharedPreferences，详见 安全与隐私。

5. 解锁更多能力（全部可选，无 Root 也能玩）

能力	怎么做	解锁后可做
Shizuku	安装 shizuku.rikka.app 并在权限屏授权	ADB 级（uid=2000）：pm install / settings put / am start / input / dumpsys / screencap
无障碍服务	权限屏里开启 ApexAccessibilityService	UI 自动化（ui_tap / ui_swipe / ui_dump / input_text）与 cs-mem 屏幕感知
Root	已 Root 设备自动探测到 su	全系统：/system、mount、SELinux、iptables、ptrace
终端 / Ubuntu	首次进终端屏按引导供给 rootfs（内置包则跳过下载）	apt install、跑 bash 脚本、编译小工具
悬浮窗	权限屏授权	悬浮球快速唤起 + UI 感知防钓鱼所需上下文

什么都不开也能用：权限链会降级到应用沙箱 shell（/sdcard 基本文件操作）。 详见 权限执行链。

6. 第一句话该说什么

① 信息型：  "帮我看看这台设备还剩多少存储，按目录大小排个前 5"
② 操作型：  "打开设置，看看当前连的 Wi-Fi 名"              ← UI 自动化工具链
③ 终端型：  "在终端里装 figlet，然后打印 HELLO"
④ 记忆型：  多做几次 ③，之后说"再打印一次 HELLO"           ← FSM 宏旁路，0 token 秒回
⑤ 谨慎型：  切到 Plan 模式后说"帮我清理下载目录里大于 50MB 的文件"

推荐初始配置：

• 模式：日常用 Build；涉及删除/安装/多步改动切 Plan（先给计划再执行）；
• 思考深度：普通模型 ThinkingLevel=STANDARD + ReasoningEffort=NONE； 推理模型（DeepSeek-R1 / Qwen3-thinking / o 系列）反过来：NONE + MEDIUM/HIGH；
• 怀疑它在乱猜：切 Assist 模式，遇到多选会强制弹菜单让你决策。

模式语义见 Agent 引擎。

7. 接下来读什么

你想做	去这里
理解分层与数据流	架构总览
知道每个模块负责什么	模块地图
挑 gradle 模块改	模块地图 + 贡献指南
写自己的工具 / 技能 / 插件	工具系统 · 技能与斜杠命令 · 插件 SDK
让它帮你逛网页	浏览器智能体
让它记住操作并 0 token 复现	cs-mem 认知记忆
出问题了	故障排查 · FAQ

---

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

_{Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room}