Android Guru Agent

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

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

一个开源的 Android 端自主智能体应用：OpenAI 兼容流式 LLM 接入、6 种执行模式、 109 个内置工具（v3 新增超时/重试/限流/熔断/追踪/批量/组合动作八层执行硬化；P83 环境闭环补全）、PRoot 沙箱化 Ubuntu 终端、仿生认知记忆系统（差分摄取 → 轨迹蒸馏 → FSM 旁路回放 → 梦境巩固）、Root/Shizuku/无障碍三级权限链、插件化 SDK —— 全部跑在一台手机上，无需任何服务器。

CI · 质量门禁 · 贡献

技术栈

仓库动态

项目事实

快速跳转

分享与交流

---

🔭 一眼看懂

🧠 仿生认知记忆 屏幕感知 → 语义降维 → FSM 宏技能 指纹命中即 0 token 旁路回放	🖥️ 真 Linux 终端 设备上 PRoot 沙箱跑 Ubuntu 24.04 原生 PTY + 自研 VT100，apt install 可用	🔀 双引擎工作流 流式 ReAct 循环 + 任务编排器 状态机 · 恢复规划 · 用户交互门
🗜️ 上下文工程 三级压缩：工具输出截断 → 滑动窗口 → LLM 摘要，长任务不爆窗口	🛰️ BYO-LLM 任意 OpenAI 兼容端点 / 局域网 Ollama 多模型角色路由 + 原生思维链透传	⚡ 三级权限链 Root → Shizuku → 沙箱 Shell 自动降级 无 Root 也能执行特权命令

⬆️ 返回顶部

---

📖 目录

核心能力 🔭 一眼看懂 ✨ 项目亮点 🆚 与其他方案对比 🏗️ 架构总览 🧠 认知记忆系统 cs-mem 🔄 Agent 引擎与六种工作模式 🗜️ 上下文工程（P7 三级压缩） 🖥️ 终端运行时（Ubuntu + PRoot） 🌐 浏览器智能体 🔧 工具全景（109 个） ⚡ 权限执行链

使用与工程 🧩 技能系统与市场 💬 斜杠命令 🔌 插件 SDK 🎨 ComposeFoundry（伴侣工程） 💎 Liquid Glass 玻璃组件系统 📱 应用界面 🚀 快速开始 🧪 测试与质量保障 📊 CI/CD 流水线 📁 仓库结构与代码规模 🗺️ 路线图 · 📄 文档索引 ❓ FAQ · 🧭 术语速查 · 🤝 贡献指南 📊 开发者统计 · ⭐ Star History · 👥 贡献者

---

✨ 项目亮点

	亮点	说明
🧠	仿生认知记忆	UI 感知 → 语义降维（体积压缩 90%+）→ 差分摄取（再压缩 95%+）→ ReAct 轨迹蒸馏为有限状态机 → 0 token 的"肌肉记忆"旁路回放，App 升级后经拓扑同胚迁移保鲜
🛡️	记忆免疫系统	悬浮窗钓鱼 / 无障碍劫持 / 记忆中毒防御：敏感词分级 + 结构完整性校验 + 可疑指纹隔离（Quarantine）
🌙	梦境渲染	息屏 + 充电 + WiFi 时后台巩固记忆：低能宏保鲜验证、能量衰减、跨版本拓扑迁移（借鉴人类睡眠记忆巩固）
🔥	能量遗忘与晶化	每条记忆带能量值：使用增能、时间衰减、低能坍缩删除；能量≥8 且成功率≥90% 的高频宏晶化为 ROM 级永久技能，免疫衰减与剪枝
🖥️	真·Linux 终端	设备上供给 Ubuntu 24.04 官方 rootfs，PRoot 用户态沙箱执行 + 原生 C++ PTY（forkpty/JNI）+ 自研 VT100/ANSI 模拟器，apt install、跑 bash 脚本皆可
🔀	双引擎工作流	直连 ReAct 引擎 + 任务编排器（状态机/恢复规划/用户交互门/多模型路由）两条执行路径，复杂任务自动上编排
🗜️	上下文工程	三级压缩（工具输出智能截断 → 滑动窗口 → LLM 摘要），双引擎统一水位检查，长任务不爆上下文窗口
🛰️	BYO-LLM	OpenAI 兼容协议 + DeepSeek / OpenRouter / Ollama / 自定义端点预设；多模型运行时按角色路由（含图片自动走 VISION）；原生支持 reasoning_content 思维链（R1 / Qwen3-thinking / o 系列）
⚡	三级权限链	Root → Shizuku → 普通沙箱 shell 自动降级选择，无 Root 设备也能执行特权命令
🧩	全插件化	AIDL 跨进程插件 SDK + 技能市场（工具/技能/MCP/插件/连接器五个货架）+ 40+ 可安装技能模板
💭	七档思考系统（Coding 页专属）	NONE→ULTRACODE→APEXCODE 七深度档 + AUTO 预检自适应（发送前选档 + 深水区升级）；档位驱动提示词 / 模型参数 / 迭代倍率 / 压缩阈值 / 输出预算全执行画像，档位效能用历史数据说话（Agent 聊天页为独立六档体系）
🕓	长任务中心（v1.2）	超阈值运行自动留档；检查点时间线回看（轮次 / 相对时间 / todo 完成度）+ 续跑不从头、复制带上下文重跑、同目标运行对比、8 模板一键启动

Important

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

⬆️ 返回顶部

---

🆚 与其他方案对比

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

Note

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

⬆️ 返回顶部

---

🏗️ 架构总览

flowchart TB
    subgraph APP["📱 :app — Compose UI + Hilt 装配"]
        direction LR
        CHAT["AgentChat 主聊天<br/>流式气泡 · 思维链 · 工具卡片<br/>计划确认卡 · 附件多模态"]
        SCREENS["Terminal · Skill · Market<br/>Memory · Permissions · Log · Settings"]
    end

    subgraph CORE["⚙️ core:* — 纯 JVM · 零 Android 依赖"]
        direction LR
        ENGINE["agent-engine<br/>六模式 ReAct 循环<br/>TaskOrchestrator<br/>P7 三级压缩"]
        TOOLS["tool-registry<br/>内置工具 · schema 即校验<br/>SkillRegistry · MCP 客户端 · Hub 源"]
        LLM["llm-adapter<br/>OpenAI 兼容 SSE<br/>多模型运行时 · 角色路由"]
        LOGC["logging<br/>结构化日志"]
        CODEENG["code-engine<br/>编码工位引擎<br/>长任务韧性 · 子代理 · 胶囊流"]
    end

    subgraph PLAT["🧱 platform:* — Android 平台层"]
        direction LR
        PRIV["privilege<br/>Root / Shizuku / Shell<br/>三级权限链"]
        PERSIST["persistence<br/>前台服务 + 看门狗"]
        TERM["terminal<br/>Ubuntu rootfs · PRoot<br/>原生 PTY · 25 工具"]
        CSMEM["cs-mem 认知记忆<br/>蒸馏 · 旁路回放 · 梦境<br/>Room 图数据库"]
        MCPH["mcp-host<br/>逆向 MCP Host<br/>:8765 · Bearer · 白名单"]
    end

    VTE["🖥️ terminal-emulator<br/>自研 VT100 / ANSI 模拟器"]
    VTN["🚀 terminal-native<br/>apex-vt-native C++17 引擎<br/>（JNI 零分配热路径）"]
    TVW["🪟 terminal-view<br/>Compose 画布渲染 · 手势 · IME"]

    subgraph PLUG["🧩 plugin-sdk — AIDL 跨进程"]
        PAPI["plugin-api · IApexPlugin"]
        PHOST["plugin-host<br/>发现 · 绑定 · 工具桥接"]
        PLUGINS["plugins:* 插件 APK"]
    end

    CHAT --> ENGINE
    SCREENS --> ENGINE
    ENGINE -->|工具调用| TOOLS
    ENGINE -->|LLM 请求| LLM
    TOOLS -->|LLM 请求| LLM
    TOOLS --> PRIV
    TOOLS --> TERM
    CSMEM -->|记忆召回工具| TOOLS
    ENGINE -->|会话记忆观察| CSMEM
    TERM --> VTE
    VTE -.native 加速.-> VTN
    TERM --> TVW
    MCPH -->|工具暴露·同一门控链| TOOLS
    PHOST -->|插件工具注册| TOOLS
    PERSIST -.前台保活.-> APP
    PAPI -.契约.-> PHOST
    PLUGINS -.实现.-> PAPI

Loading

20 个 Gradle 模块（单一仓库 settings.gradle.kts）：

模块	类型	职责
:app	Android App	Compose UI（抽屉导航 8 屏）、Hilt 装配、浏览器/GitHub 工具、悬浮球
:core:agent-engine	纯 JVM	ReAct 引擎（Plan/Build 等六模式）、任务编排器、上下文压缩、会话记忆
:core:tool-registry	纯 JVM	内置工具（schema 即校验 + 风险门 + 使用统计）+ 工具执行器 + SkillRegistry + MCP 客户端 + Hub 源
:core:llm-adapter	纯 JVM	OpenAI 兼容流式客户端 + 多模型运行时（角色路由/能力校验/错误分类）
:core:logging	纯 JVM	结构化日志（LogCategory/LogLevel/LogRecord）
:core:code-tools	纯 JVM	编码工具包：文件编辑 / git / 诊断 / TODO
:core:code-engine	纯 JVM	编码工位专用引擎：长任务韧性 / 子代理 / 胶囊流式 / 思考档位
:platform:privilege	Android Lib	Root/Shizuku/普通三级权限链 + 无障碍服务 + 进程流工厂
:platform:persistence	Android Lib	前台服务 + WorkManager 看门狗（被杀自动拉起）
:platform:terminal	Android Lib	终端运行时 2.0：rootfs 供给、PRoot 后端、原生 PTY、Ubuntu 生命周期编排、25 个工具
:platform:cs-mem	Android Lib	认知记忆系统（本仓库的差异化核心，见下节）
:platform:code-workspace	Android Lib	编码工作区：安全根目录与生命周期
:platform:mcp-host	纯 JVM	逆向 MCP Host：把手机工具暴露给 PC 客户端（零第三方依赖）
:terminal-emulator	纯 Kotlin	自研 VT100/ANSI 终端模拟器（零依赖）+ TerminalEngine 引擎抽象
:terminal-native	Android Lib	apex-vt-native C++17 零分配 VT 引擎（vendored + JNI，运行时回退 Kotlin）
:terminal-view	Android Lib	Compose 终端视图层：画布渲染 / 手势 / 选区 / IME 连接
:plugin-sdk:plugin-api	Android Lib	AIDL IApexPlugin + PluginContract 常量
:plugin-sdk:plugin-host	Android Lib	插件发现/绑定/工具桥接
:plugins:plugin-workflow	Android App	参考插件 APK（工作流三工具）
:plugins:plugin-web-automation	Android App	参考插件 APK：浏览器自动化工具目录

Note

📌 ComposeFoundry/ 是独立的 Gradle 工程（有自己的 settings.gradle.kts）， 不参与主构建 —— 详见 ComposeFoundry 章节。 上图为控制/数据流示意（非严格 Gradle 依赖图）。

⬆️ 返回顶部

---

🧠 认知记忆系统 cs-mem

platform/cs-mem 是本项目的差异化核心：它不只是"给 LLM 塞一段历史"， 而是一套把 屏幕感知转化为可复用程序性记忆 的完整管线。

管线全景

flowchart TB
    subgraph INGEST["🔵 摄取侧 —— 每次动作后自动触发"]
        direction LR
        A["👁 感知<br/>getUiTree()<br/>Root / Shizuku / Shell"]
        B["✂️ 语义降维<br/>UiTreePruner<br/>剔除不可见与装饰节点<br/>体积 -90%+ · 指纹 SHA-256"]
        C["Δ 差分摄取<br/>DifferentialIngestor<br/>只存状态跃迁<br/>压缩 95%+"]
        D["✉️ 串行写入<br/>MemoryWriterActor<br/>有界邮箱 256 · 背压"]
        A --> B --> C --> D
    end

    E[("🗄 MemoryGraphDatabase<br/>Room · schema v3<br/>nodes · edges · episodes<br/>fsm_macros · migration_map")]
    D --> E

    subgraph CONSUME["🟢 消费侧"]
        direction LR
        R1["召回工具 ×3<br/>search_nodes<br/>recent_episodes<br/>recall_macro"]
        R2["轨迹蒸馏<br/>TraceDistiller<br/>锚点提取 → 动作压缩<br/>→ FSM 编译"]
        R2 --> M["FSMMacro 宏技能"]
        M --> BY["⚡ 旁路回放<br/>BypassExecutionEngine<br/>指纹命中 → 绕过 LLM<br/>微秒级 · 0 token"]
    end

    E --> R1
    E --> R2

    IMM["🛡️ MemoryImmuneSystem<br/>摄取前免疫检查<br/>悬浮窗 / 敏感词 / 完整性 / 隔离"] -.检查.-> INGEST
    DR["🌙 DreamRenderer（WorkManager）<br/>息屏+充电+WiFi 时巩固<br/>能量衰减 · 晶化 · 拓扑迁移"] -.维护.-> E

Loading

记忆的两种形态

形态	模型	产生	消费
陈述性记忆	SemanticNode 语义图 + Episode 情景 + GraphEdge（SPATIAL/CAUSAL/SEMANTIC 三类边）	每次动作后 CsMemSessionManager.afterAction() 捕获差分	memory_search_nodes / memory_recent_episodes 召回工具；记忆屏可视化
程序性记忆	FSMMacro 有限状态机宏技能	任务成功后 TraceDistiller.distill()：锚点提取 → 动作压缩 → FSM 编译	BypassExecutionEngine.tryBypass()：指纹命中即绕过 LLM 直接回放（微秒级 / 0 token）

生命周期管理（四个仿生机制）

机制	组件	触发	效果
🔥 能量熵增	EntropyManager	每次梦境周期	成功检索/执行 → 能量增加；时间推移 → 指数衰减（艾宾浩斯遗忘曲线）
💎 晶化	EntropyManager.shouldCrystallize → crystallizeMacro	能量≥8 且成功≥10 次且成功率≥90%	ROM 级固化：免疫衰减/剪枝/删除
🌙 梦境渲染	DreamRenderer（WorkManager）	息屏 + 充电 + WiFi + 电量≥50%	低能宏随机保鲜验证、全局熵衰减、拓扑同胚迁移
🛡️ 免疫	MemoryImmuneSystem	每次摄取前	悬浮窗检测 / 敏感词分级 / 结构完整性 / 包名可信分级 / 可疑指纹隔离

跨版本记忆保鲜（拓扑同胚迁移）

App 升级会改变 UI（resourceId / 布局 / 文案）→ 旧指纹失效 → 宏集体失配。 解法是别名桥而不是改写历史：

flowchart TB
    D["🌙 梦境周期<br/>TopologyMigrator"] --> CMP["对比旧/新版本节点集<br/>同 role + resourceId 归一化<br/>+ textHint 相似度打分 ≥ 0.7"]
    CMP --> MAP["migration_map<br/>old_fp → new_fp<br/>（score · from_version → to_version）"]
    MAP --> LOOKUP["召回侧：精确匹配失败时<br/>findMacrosViaMigration 反查旧别名"]
    LOOKUP --> RES["resolveMigration 正向校验闭环<br/>resolve(旧指纹) == 探测指纹"]

Loading

存储演化（schema v3）

• 边 ID 从帧内自增计数器改为内容哈希（SHA-256(源指纹|目标指纹|关系) 前 16 位）—— 同一条拓扑边在任意两帧同 ID，差分语义与跨 Episode 删除才正确；
• v2→v3 Room 迁移：清理历史重复边 + 建 (episode_id, edge_label) 唯一索引 + 删除增加 episode 作用域；

Warning

升级必须显式提供 Room Migration，仅降级允许 destructive 重建 —— 这是保护长期记忆不被静默清空的硬约束。

Tip

深入阅读：docs/memory-and-workflow-research.md —— 对标 MemGPT/Letta、Mem0、A-MEM、Zep/Graphiti、Voyager¹ 的完整调研与差距分析。

⬆️ 返回顶部

---

🔄 Agent 引擎与六种工作模式

core:agent-engine 提供两条执行路径，UI 自动选择：

1. 直连路径 ApexAgentEngine —— 流式 ReAct 循环（Think → Act → Observe → …）， 全事件流输出，适合绝大多数对话式任务；
2. 编排路径 DefaultTaskOrchestrator —— 复杂长任务：任务状态机、 批量工具执行引擎、失败分类 + 恢复规划器、重试策略、循环检测（LoopDetector）、 用户交互门（ask_user 挂起等待人工决策）、生命周期事件（SharedFlow）。

编排器任务状态机（真实转移）

stateDiagram-v2
    direction LR
    [*] --> Idle
    Idle --> Planning : execute(mode)
    Planning --> AwaitingPlanConfirmation : PlanGenerated
    AwaitingPlanConfirmation --> Planning : 确认 / 重规划
    Planning --> AwaitingSpecConfirmation : SpecGenerated
    AwaitingSpecConfirmation --> Planning : 确认 / 重规划
    Planning --> Acting : ToolCallScheduled
    Acting --> Observing : ToolCallFinished
    Observing --> Planning : 下一轮迭代
    Observing --> Responding : 无更多工具调用
    Acting --> AwaitingUserInput : ask_user / 权限门
    AwaitingUserInput --> Acting : 用户答复
    Responding --> Completed : ResponseComplete
    Planning --> Failed : 异常 / 重试耗尽
    Acting --> Failed : 批量执行失败
    Observing --> Failed : 恢复规划失败
    Responding --> Failed : LLM 错误
    Planning --> Aborted : cancel
    Acting --> Aborted : cancel
    Responding --> Aborted : cancel
    Completed --> [*]
    Failed --> [*]
    Aborted --> [*]

Loading

Note

图为 TaskStateMachine + DefaultTaskOrchestrator / BatchExecutionEngine 中全部 transitionTo(...) 调用的合并视图；Finished 是 sealed 终态 （Completed / Failed / Aborted），终态不可逆。

六种模式（AgentMode）

模式	行为	适用
Build	边想边做，实时执行	简单任务、快速响应
Plan	先产出完整计划，用户确认后逐步执行	复杂多步操作
Spec	先产出需求规格（目标/需求/约束/验收标准/交付物），确认后逐项执行	"做什么、做成什么样才算完成"
Reflect	生成 → 评审 → 修正 自我循环	代码生成、内容创作等高质量场景
Assist	遇到多选（方案/目标/偏好）强制弹出选项菜单人工决策	不擅自猜测的谨慎场景
Custom	附加用户自定义指令（输出格式/语言/行为约束），持久化保存	个性化定制

双层思考深度（v1.2：7 档 + AUTO）

层	控制点	档位	效果
提示词思考	Agent 六档 ThinkingLevel / Coding 七档 CodeThinkingLevel	两套独立阶梯：聊天页 NONE/LIGHT/STANDARD/DEEP/MAXIMUM+AUTO；Coding 页另有 ULTRACODE/APEXCODE 深水两档	系统提示注入推理指令强度；档位同时驱动执行画像（迭代倍率 / 压缩阈值 / 输出预算，Coding 深水两档经旋钮补偿反补）
原生思考	ReasoningEffort	NONE / LOW / MEDIUM / HIGH / MAX	直接写 reasoning_effort 请求参数（o 系列 / R1 / Qwen3-thinking），MAX 档同时抬高 max_completion_tokens 给思维链留空间

七档思考阶梯（Coding 页专属；Agent 聊天页为独立六档体系，两页面互不干扰。Code 屏另有「思考档位指南」弹层摊开全部画像 + 档位效能统计）：

档位	定位	budget	迭代倍率	输出预算
NONE	直接执行不推理	0	×0.8	6000
LIGHT	1-2 句简思	256	×0.9	7000
STANDARD	CoT 三步	1024	×1.0	8000
DEEP	多路径 5 步 + 工具失败自检	4096	×1.2	9000
MAXIMUM	ToT 7 步 + 终检三问清单	16384	×1.5	10000
ULTRACODE	编码闭环 7 步（不变量→候选改法→风险排序→最小修改→即时验证）	32768	×2.0	12000
APEXCODE	架构级穷举 + 对抗性自审 + 全量验证矩阵 + 证据链汇报	65536	×3.0	16000
AUTO	元档：发送前预检选档 + 深水区升级（可升至 ULTRACODE，永不自动选 APEXCODE）	—	—	—

Coding 模式在通用画像之上还有一层编码特化指令（CodeThinkingPrompts： 一读一改 / 标准编码循环 / 改动集思维 / 不变量守护 / 依赖地图→回归扫描 / 影响半径测绘→证据链汇报）——「怎么想」与「编码时具体怎么想」三层分工， 互不重复注入。

两层正交：可以 NONE+MAX（纯模型原生思考）也可以 DEEP+NONE（纯提示引导）。 原生思维链通过 LlmStreamChunk.reasoningContent 透传为 ThinkingChunk 事件， UI 实时显示推理过程（正文与思维链严格分流，双引擎同语义）。

多模型运行时（T72）

• ModelRoleRouter：按角色（默认/VISION）路由到不同模型；
• 会话含图片时自动要求 vision + imageInput 能力，全链无视觉模型则抛 ModelCapabilityMismatch（能力校验 + 诚实降级）；
• ModelProfileValidator 校验档案，ErrorClassifier 分类运行时错误供重试决策。

🧑‍💻 Coding 模式（Code 屏 —— 与 Agent 模式同级别的对等入口）

与六种 AgentMode（会话行为开关）不同，Coding 模式是一个独立的顶层工作面： 抽屉里的 Code 屏拥有自己的引擎实例、按工作区隔离的会话记忆、以及 opencode 契约的编码工具集 —— 但与 Agent 模式共享全部能力基础设施（工具注册表 + v3 执行硬化 + v4 目录 / 技能注入 / MCP 一等工具 / 插件 / 多模型路由）。

┌─ Code 屏（app/ui/screen/code）──────────────────────────────────┐
│ 工作区条（切换/新建/删除 + 环境探测摘要）                          │
│ Todo 面板（code_todo 实时快照 → checklist 渲染）                  │
│ 消息流（用户 / 助手 Markdown / 工具卡 diff 着色 +/-）              │
│ 输入栏（发送 / 停止 / ask_user 应答）                             │
└──────────────────────────────────────────────────────────────────┘
        │ @Named("code") 独立引擎实例（CodeAgentEngine）
        ▼
┌─ core/code-engine ──────────┐   ┌─ core/code-tools（6 工具）────┐
│ CodePrompts（编码行为注入）   │   │ code_read   行号契约+目录+纠错  │
│ CodeConversationMemory      │   │ code_edit   7级模糊替换链+护栏   │
│ （per-workspace 会话记忆）    │   │ code_write  全量写+diff 回显    │
│ JIT 上下文（环境/统计注入）    │   │ code_grep   ripgrep 语义搜索    │
└─────────────────────────────┘   │ code_glob   递归模式匹配        │
        │ 共享单例                 │ code_todo   任务清单状态机      │
        ▼                         └────────────────────────────────┘
┌─ platform/code-workspace ───┐   ┌─ MCP（BUILTIN 进程内服务器）────┐
│ 工作区生命周期 + 环境探测      │   │ search：web_search/web_fetch    │
│ 默认工作区=Agent 沙箱同源目录  │   │ （Agent/Code 两模式互用）       │
│ host↔guest(/workspace) 同一文件│  └────────────────────────────────┘
└─────────────────────────────┘

关键设计：

• 不重写 Agent Loop —— CodeAgentEngine 是 ApexAgentEngine 的薄包装， 编码行为经 additionalSystemContext 通道注入（BUILD 循环 + opencode 风格 编码行为段落），Agent 模式零影响；
• code_edit 的成功率就是编码循环的效率 —— 精确匹配失败后依次尝试 行 trim / 块锚点+Levenshtein / 空白归一 / 缩进平移 / 边界 trim / replaceAll 七级回退；失衡护栏（模糊命中 span 远大于 old_string 时拒绝）防止"吞代码"；
• 工作区即沙箱 —— code_* 工具的根经 CodeWorkspaceRoots 动态解析， 切换工作区即时生效；默认工作区与 Agent 文件工具、Ubuntu 终端会话三方 看同一份文件（linux/workspaces/default ↔ guest /workspace）；
• 网络搜索 MCP 本地运行 —— BuiltinSearchMcpTransport 把成熟搜索栈 （DuckDuckGo/Bing 三级回退 + 智能正文提取）包装为进程内 MCP 服务器， Agent 与 Coding 两模式共享 mcp__search__web_search 一等工具。

🕓 长任务中心（v1.2）

跑完即散是深度任务的死穴：几十轮迭代的重构 / 修 Bug / 评审一旦会话清理 就全部蒸发，想「再来一遍」只能从头描述。Code 屏工作区条的「长任务」入口 把达到规模阈值（迭代 ≥8 / 工具 ≥12 / 时长 ≥120s / 文件 ≥3，四维任一达标， LongTaskDetector）的运行自动留档，并在其上提供六类顶级操作：

能力	说明
🕓 检查点时间线	运行中每 5 轮 / 60s 拍一张廉价快照（≤10 个，超限丢最旧）；展开记录卡即是时间线渲染——轮次徽标 + 相对时间（+45s）+ 累计计数（工具 / 文件）+ monospace 对话摘要 + todo 完成度（☑3 ☐2），上次卡在哪、绕了哪些弯一眼可见
📋 复制任务	携带上次的结论再跑：上下文 / todo 快照 / 文件清单三开关 + 档位覆盖（用 ULTRACODE 重跑 DEEP 任务做对比）+ 跨工作区复制 + 复制链谱系（parentTaskId 溯源整条重跑历史）
⏯️ 检查点续跑	不从头重跑——从指定检查点（或最后检查点）接着干，上次的弯路不重走；无检查点时诚实回退为带上下文重跑
🔄 运行对比	同 parent 的兄弟记录天然是「同一目标的不同尝试」，LongTaskDiff 产出迭代 / 工具 / 时长 / 文件集的结构化对比报告
🗂️ 8 内置模板	重构 / 修 Bug / 新功能 / 评审 / 测试 / 文档 / 性能 / 迁移——应用推荐思考档位 + 预置 todo 骨架，一键启动
📊 档位效能	工作区 × 思考档位的长任务聚合统计（runs / 成功率 / 平均迭代 / 工具 / 时长）——用自己的历史数据选档，而非凭感觉

⬆️ 返回顶部

---

🗜️ 上下文工程（P7 三级压缩）

长任务的死穴是上下文窗口。双引擎共享同一套 HybridCompressor，在 TokenEstimator 估计超阈值（默认 128k×80%）时逐级触发：

flowchart TD
    IN["新工具输出 / 新一轮迭代"] --> W{"水位检查<br/>TokenEstimator > 128k × 80% ?"}
    W -- 否 --> KEEP["保持原样"]
    W -- 是 --> C1["Layer 1 · ToolOutputTruncator（零成本 · 永远在跑）<br/>JSON → 保头 + 尾 200 字符（闭合结构）<br/>列表多于 20 短行 → 保首 15 + 尾 10 行<br/>read_file 类 → 只保头<br/>默认 → 头 1200 + 尾 600 字符 + 省略标注"]
    C1 --> W2{"仍超阈值？"}
    W2 -- 否 --> DONE1["✅ 完成"]
    W2 -- 是 --> C2["Layer 2 · SlidingWindowCompressor（零成本）<br/>保系统提示 + 最近 N 轮<br/>中段折叠为单条规则摘要"]
    C2 --> W3{"仍超阈值？"}
    W3 -- 否 --> DONE2["✅ 完成"]
    W3 -- 是 --> C3["Layer 3 · LlmSummaryCompressor（一次额外 LLM 调用）<br/>中段结构化摘要（Task / Progress / State / Key Data ≤400 词）<br/>失败自动回退规则摘要"]

Loading

Note

永不压缩：系统提示 / 最新用户任务 / 最近 5 轮 / 执行中工具调用。 压缩后发射 AgentEvent.ContextCompressed(before, after, strategy, ...)， UI 渲染为系统消息，压缩结果同步回持久化记忆（重启后加载已压缩状态）。

⬆️ 返回顶部

---

🖥️ 终端运行时（Ubuntu + PRoot）

platform:terminal 在设备上供给并运行一个真实的 Ubuntu 24.04 用户态 Linux：

层	实现	要点
rootfs 供给	RootfsDownloader/Extractor/Configurator + UbuntuBootstrapManager	官方 Ubuntu 24.04.4 归档（sha256 锁定）、断点续装、sources.list 配置、基础包档案
执行后端	LinuxPRootBackend + ProotExecutor	PRoot 用户态沙箱（无需 root！）、预编译 so 随包分发（指纹校验防篡改）、Fake 后端供测试
PTY	C++ forkpty（pty_engine.cpp / jni_bridge.cpp）	原生伪终端、argv 编组、进程组信号、会话隔离
终端模拟	terminal-emulator + terminal-native	自研 VT100/ANSI：转义序列解析、滚动区、24 位色、UTF-8 解码；热路径由 C++17 引擎（apex-vt-native，每字符零堆分配）加速，Kotlin 实现保留为语义基准与 JVM 回退
背压 IO	PtyOutputPump + BackpressureConfig	有界输出泵、EOF 语义、丢帧保护
观察引擎	ObservationEngine2 + SemanticStateReducer	把 ANSI 噪音降维成语义状态（等待输入/运行中/完成/错误），InputWaitingDetector 识别提示符
包管理	UbuntuAptPackageManager + PackageOperationLock	设备上 apt install，并发锁防交错
环境自适应	AdaptiveProvisionLoop + DiagnosticRules	执行观察 → 诊断规则 → 自动修复（ResolverCache）
会话持久化	SessionMetadataStore + RuntimeRecoveryService	重启恢复会话元数据

16 个 terminal.* 工具暴露给 LLM：terminal.create / run / write / observe / snapshot / wait / resize / signal / close / workspaces / backends / linux_bootstrap / linux_status / linux_packages / linux_network / ubuntu_install。

Tip

测试含真实 E2E：CI 下载真 Ubuntu rootfs + Debian proot 5.4 跑真实 guest 进程（bash / apt）；proot 不可用时诚实自跳过高级别场景。

⬆️ 返回顶部

---

🌐 浏览器智能体

对标 Operit 的 BrowserAgent：DOM 级网页操控而非截图盲点。

• 15 个 browser_* 工具：navigate / click / input / scroll / select / screenshot / snapshot / toggle / show / download_list / file_upload / date_input / context_summary / network_log / debug_dump；
• 语义哈希稳定 ref：元素引用基于语义哈希而非 DOM 序号，SPA 局部刷新后 ref 依然有效；
• BrowserTracer（容量 100 的操作轨迹）+ RetryPolicy 支撑断点续控。

⬆️ 返回顶部

---

🔧 工具全景（109 个）

📦 点击展开 / 折叠完整工具清单（按模块分组）

core:tool-registry —— 64 个内置工具

类别	工具
🖥️ Shell	shell_execute（三级权限链 + 流式输出）
📁 文件	read_file write_file edit_file list_files glob_files search_files copy_move_file delete_file
🌐 网络	web_fetch web_search http_request download_file（流式进度）
🧠 文件记忆	memorize recall forget
📱 应用	app_list app_launch app_install app_uninstall app_force_stop app_info
⚙️ 系统	get_device_info get_set_settings control_media clipboard get_time logcat
🖱️ UI 自动化	ui_tap ui_swipe ui_dump screenshot input_text
🧮 实用	calculate text_transform get_location notification_read
🧩 技能	skill_search skill_install skill_create skill_list skill_uninstall
🛰️ MCP	mcp_connect mcp_list mcp_call
🧱 结构化 v2（15）	regex_extract regex_replace text_diff json_path xml_extract csv_query base_convert unit_convert duration_convert string_distance random_generate uuid_generate file_hash datetime cron_next（全部纯 JVM / 离线 / 确定性）
⚡ 执行硬化 v3（7）	wait（≤300s 可取消等待）· json_transform（jq 风格七操作管线）· version_compare（SemVer 排序）· tool_batch_run（批量首错即停 + 步间引用）· shortcut_define / shortcut_list / shortcut_run（组合动作：定义→热注册、清单+挖掘建议、执行）——详见 docs/tool-system-v3.md

app 模块 —— 22 个

类别	工具
🌐 浏览器（15）	browser_navigate/click/input/scroll/select/screenshot/snapshot/toggle/show/download_list/file_upload/date_input/context_summary/network_log/debug_dump
🐙 GitHub（7）	github_get_user/list_repos/read_file/write_file/create_issue/list_issues/search_code（配置 PAT 后注册）

platform:terminal —— 18 个 terminal.*（见终端运行时；T82 新增 terminal.ubuntu.ensure / terminal.ubuntu.status 一键生命周期编排）

platform:cs-mem —— 3 个记忆召回

工具	用途
memory_search_nodes	按文本/角色搜索语义节点（支持迁移别名解析）
memory_recent_episodes	近期情景回顾
memory_recall_macro	宏技能召回

Note

动态安装的技能（Skill）会通过 SkillToolAdapter 注册为运行时工具 （如 web_scrape），上表为静态注册基线。CI 有工具 ID 唯一性门禁。

⬆️ 返回顶部

---

⚡ 权限执行链

┌──────────────────────────── 优先级递降 ────────────────────────────┐
│ ① Root      su -c                    全系统：/system /data mount    │
│                                          SELinux iptables ptrace    │
│ ② Shizuku   Shizuku.newProcess        ADB 级(uid=2000)：pm install  │
│             （uid=2000，无需 root）      am start/stop settings put   │
│                                          dumpsys input screencap     │
│ ③ Shell     sh -c                     应用沙箱：/sdcard 基本文件操作 │
└────────────────────────────────────────────────────────────────────┘

PrivilegeDetector 运行时探测（su 二进制扫描 + binder 活性 + 授权检查）， getPrivilegeLevel() 返回 ROOT/SHIZUKU/NORMAL_SHELL 并注入系统提示 （PrivilegeInfoProvider 纯 JVM 接口 + app 侧实现）—— 智能体知道自己能做什么、 缺什么权限时主动建议用户装 Shizuku。Shell 三层共享同一条流式读取管道 （ProcessStreamFactory），stderr 行前缀 [stderr] 与 stdout 交错实时上屏。

⬆️ 返回顶部

---

🧩 技能系统与市场

Skill = 可组合能力包（JSON manifest，schema apex-skill-v1，存于 filesDir/skills/<id>.json）：

类型	机制	示例
Composite	steps[] 链式编排既有工具，{{var}}/{{prev_output}} 模板替换	网页爬虫 = fetch → 解析 → 存档
Prompt	启用时注入系统提示片段	"回答带引用来源"
Script	内嵌 Python/Shell 脚本，shell_execute 执行	数据清洗脚本
Connector	连接外部服务（URL/SSH）	Google Drive 桥（孵化中）

技能可以从市场（Market 屏）发现安装，也可以让智能体自己安装： skill_search → skill_install（URL / 内置模板 / 内容）→ auto_setup 执行 → skill_list 确认，全程 LLM 自主闭环。市场货架含工具 / 技能 / MCP / 插件 / 连接器五类。

官方 Hub 仓库生态（技能 / MCP 分发）

APK 内置技能只保留 13 个核心（8 个 coding 强技能 + 3 个 agent 通用 + 2 个双工位文档技能），其余 62 个生活/通用技能全部迁往官方技能仓库 apex-skill-hub；MCP 同理 ——内置仅保留 5 台进程内必要服务器（github / search / fs / memory / thinking），沙箱与远端 MCP 目录迁往 apex-mcp-hub。市场里 「官方仓库」源直连 raw.githubusercontent.com 拉取 index.json 注册表 （学习 opencode 的远程注册表模式：元数据小体积索引 + 技能正文按需单文件 下载），一键安装，装完与本地技能同权管理。升级用户由 pruneStaleBundled 白名单反向迁移自动清理旧内置残留。

斜杠门控：聊天输入框 / 菜单的 Skills 分组只出现已安装且已开启 的技能；MCP 分组只出现已安装且正在运行的服务器——未安装/未启动的 不可选用（市场 → MCP 里安装并启动）。MCP 在市场内有配置 / 启动 / 停止 完整闭环（含 BUILTIN 服务器的配置对话框：作用域 / 启停 / 连接 / GitHub Token）。

⬆️ 返回顶部

---

💬 斜杠命令

输入栏 / 按钮弹出四类命令（实时联想、追加不覆盖已输入文本）：

/<type>:<id> [key=value ...] [自由文本]

/skill:code_interpreter
/skill:web_search query=Android 18 news
/mcp:github repo=owner/name        ← 未连接时自动引导 GitHub 连接流程
/connector:google_drive
/plugin:pdf_reader

文法容错（空白容忍、畸形降级为 Unknown 原样转发），解析与路由在 纯 JVM 包 com.apex.agent.slash 中实现（独立可测，4 个测试类锁定行为）。

⬆️ 返回顶部

---

🔌 插件 SDK

跨进程插件体系：插件是独立 APK，声明 IApexPlugin AIDL 服务；宿主 PluginManager 经 PackageManager 发现 → 绑定 → 把插件声明的工具桥接进 ToolRegistry。参考实现 plugins:plugin-workflow 暴露三个工具： workflow/save、workflow/execute、workflow/list。

⬆️ 返回顶部

---

🎨 ComposeFoundry（伴侣工程）

ComposeFoundry/ 是独立 Gradle 工程（不参与主构建）：一个 UI DSL 预览器 —— 用 JSON 描述 Compose 界面（sample_preview.androidui.json）， 引擎（UiParser/UiValidator/UiRenderer/DiagnosticsEngine）即时渲染 + 诊断， 配合沙箱预览面（PreviewSurface）与主题系统。它是智能体未来"画 UI"能力的 实验场：LLM 产出 DSL → Foundry 预览 → 人确认后落码。

⬆️ 返回顶部

---

💎 Liquid Glass 玻璃组件系统

普通 Android UI + 精确使用的 Liquid Glass 组件，而非“整个 App 一坨透明塑料”：

• 两个诚实材质档：Backdrop 档经 Haze 以 GraphicsLayer 真实采样背后内容（API 32+ 走 GPU RenderEffect 模糊，低版本自动 scrim 降级）；Frosted 档仅主题色薄霜 + 边缘光 + 高光，不冒充 backdrop
• 七档材质：Subtle / Control / Card / Navigation / Floating / Dialog / Strong，tint、边缘、高光、噪声全部从 MaterialTheme 动态派生，Light / Dark / Dynamic Color 自适应
• 已玻璃化：抽屉导航项（悬浮于氛围背景之上）、聊天悬浮输入栏（采样消息流）、回到底部 FAB、工具卡 / 计划卡 / 任务状态卡、顶栏菜单钮、玻璃对话框（HazeDialog 跨窗口采样）
• 明确不玻璃化：终端渲染区（性能敏感）、页面背景、气泡正文
• 未实现即声明：Refraction（折射位移）明确标注 NOT IMPLEMENTED，拒绝“alpha + blur 冒充玻璃”

组件 API 与验收细则见 docs/liquid-glass-system.md，抽屉内“玻璃实验室”屏可真机验证 backdrop / blur / 边缘 / 交互。

⬆️ 返回顶部

---

📱 应用界面

单 Activity Compose 应用，ModalNavigationDrawer 抽屉导航 9 屏：

屏	内容
Agent	主聊天：流式气泡 / 思维链 / 工具卡片（实时输出 + 进度条）/ 计划确认卡 / 附件（图片多模态）/ 斜杠命令 / 原生思考档位 / 模式切换
终端	真 Ubuntu 终端：VT100 渲染、SDK 下载器、rootfs 引导进度
Skill	已装技能列表 + 启停（持久化）
市场	工具/技能/MCP/插件/连接器五货架
记忆	cs-mem 可视化：Episode 统计 / 宏技能数 / 近期情景 / 删除
权限	Root / Shizuku（三态卡片）/ 无障碍 / 悬浮窗 / 通知 / 存储
运行日志	结构化运行日志浏览
玻璃实验室	Liquid Glass 内部验收页：可拖动玻璃片 / 档位阶梯 / 工具卡状态 / 诚实验收清单
设置	LLM 预设（OpenAI/DeepSeek/OpenRouter/Ollama/自定义）+ Base URL/Key/模型 + 温度 + 连接测试 + 通用设置

另有赛博霓虹悬浮球（EasyFloat）快速唤起。

⬆️ 返回顶部

---

🚀 快速开始

环境要求

依赖	版本	说明
JDK	17	Temurin 推荐
Android SDK	35	AGP 8.7.3 默认需要 NDK 27.0.12077973（terminal 原生层）
设备	Android 8.0+ (API 26)	arm64 / x86_64 / armeabi-v7a 均带 PRoot 二进制

构建

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

Tip

不想自己构建？直接下载正式版：发布仓库 Releases （arm64 / universal 两个变体；PR 合并进 main 即自动构建发布，无需打 tag）。 已装用户可在 App「设置 → 关于 → 检查更新」直接升级 —— 支持增量补丁 （~14MB vs 全量 300MB+）与高速节点/镜像加速下载；补丁下载后应用内自动 合成新版本并拉起安装（纯 Kotlin VCDIFF 解码器，零命令行），跨任意多个 小版本自动按 patches.json 补丁链逐段升级。 也可以用 CI 的 app-debug-apk 工件（debug 构建，保留 14 天）；或参考 .github/workflows/ci.yml 的 Configure pre-installed Android SDK 步骤配置环境。

产物：app/build/outputs/apk/debug/app-debug.apk。

配置智能体

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

未配置时注入 NoOpLlmClient，界面友好提示而不崩溃。

解锁更多能力（可选）

• Shizuku（shizuku.rikka.app）：无 root 获得 ADB 级权限（pm install / settings / input / dumpsys）；
• 无障碍服务：UI 自动化（ui_tap / ui_dump）与 cs-mem 屏幕感知；
• 终端：Ubuntu 24.04 完整 CLI 环境随 APK 内置（gcc/python3/git/vim/man， rootfs 档案 300MB+，首次使用离线解包约 25 分钟；此后只有 apt 装新包才联网）。

三分钟体验路线

① 对话：  "帮我看看设备还剩多少存储，清理一下下载目录的大文件"
② 感知：  "打开设置，看看当前 Wi-Fi 名"          ← ui_tap/ui_dump 工具链
③ 终端：  终端屏引导装 Ubuntu，然后 "在终端里装 figlet 并打印 HELLO"
④ 记忆：  多做几次 ③，之后说"再打印一次 HELLO"  ← FSM 宏旁路，0 token 秒回

⬆️ 返回顶部

---

🧪 测试与质量保障

252 个测试文件（246 JVM 单测 + 6 真机仪器测试，≈4,008 个 @Test 用例）+ 三道静态门禁：

模块	单测	亮点
core:agent-engine	3 套件	编排器 6 大类（状态机/执行/失败传播/取消/超时/事件）+ 韧性套件 + 角色路由黄金用例 + 流式语义回归组
platform:terminal	45	全域覆盖，含真实 Ubuntu rootfs E2E（真 proot 进程）
core:llm-adapter	6	多模型运行时：档案校验/注册表/能力解析/错误分类/路由
core:tool-registry	4	流式透传回归（SafeAgentTool 包装器不吞流式）+ DOM 解析
platform:cs-mem	3	稳定边 ID / 蒸馏参数提纯 / 迁移回退闭环 / 回放偏离防护
app / privilege / terminal-emulator	6	斜杠文法路由 / 进程流 / VT100 核心

# 全量 JVM 测试（约 3–8 分钟）
./gradlew :core:agent-engine:test :core:tool-registry:test \
  :platform:terminal:testDebugUnitTest :platform:cs-mem:testDebugUnitTest \
  --no-daemon -Pkotlin.incremental=false

# 真机仪器测试（需连接设备）
./gradlew :platform:terminal:connectedDebugAndroidTest

Tip

📖 完整测试文档：docs/TESTING.md（理念 / 矩阵 / 替身规范 / FAQ / 文件清单 —— 清单撰写时 74 文件，主干现已 252，待同步）。

⬆️ 返回顶部

---

📊 CI/CD 流水线

工作流	内容
ci.yml	① 静态分析：kotlinc 编译 core 四模块 + 工具 ID 唯一性 + 括号平衡 + PRoot 二进制 sha256 校验；② app-compile：:app:compileDebugKotlin + 四模块单测（agent-engine / tool-registry / terminal / cs-mem）+ 仪器测试编译；③ build-apk：assembleDebug + PR 尺寸评论
quality-gate.yml	文件大小预算（main≤1200 / test≤1600 行，反 God 文件）、反模式（反射分发 / printStackTrace）、空 catch + TODO 普查
pr-labeler.yml	按改动路径自动打 area/risk 标签

⬆️ 返回顶部

---

📁 仓库结构与代码规模

Android-Guru-Agent/
├── app/                          # 主应用（Compose UI + Hilt 装配）
│   └── src/main/kotlin/com/apex/agent/
│       ├── ui/                   #   ApexRoot（抽屉导航）+ screen/（8 屏）
│       ├── browser/              #   浏览器智能体（15 工具）
│       ├── github/               #   GitHub 工具（7 个）
│       ├── slash/                #   斜杠命令（纯 JVM 可测）
│       └── di/                   #   Hilt 模块（工具/引擎接线）
├── core/
│   ├── agent-engine/             # 纯 JVM：引擎 + 编排器 + 压缩
│   ├── tool-registry/            # 纯 JVM：42 工具 + 技能注册 + MCP
│   ├── llm-adapter/              # 纯 JVM：流式客户端 + 多模型运行时
│   └── logging/                  # 纯 JVM：结构化日志
├── platform/
│   ├── privilege/                # Root/Shizuku/无障碍三级链
│   ├── persistence/              # 前台服务 + 看门狗
│   ├── terminal/                 # 终端运行时 2.0（rootfs/PRoot/PTY/工具）
│   │   ├── src/main/cpp/         #   C++ forkpty/JNI 桥
│   │   └── src/main/jniLibs/     #   预编译 PRoot 二进制（sha256 锁定）
│   └── cs-mem/                   # 认知记忆系统（本仓库差异化核心）
├── terminal-emulator/            # 自研 VT100/ANSI 模拟器（TerminalEngine 接口 + Kotlin 基准实现）
├── terminal-native/              # apex-vt-native C++17 VT 引擎（vendored，见 VENDOR.md）
│   ├── src/main/cpp/vt-native/   #   C++ 核心 + JNI 桥（上游 CI 跑 129 项奇偶校验）
│   └── src/main/kotlin/          #   NativeVtCore 包装器 + VtEngineFactory 回退工厂
├── plugin-sdk/                   # AIDL 插件 SDK（api + host）
├── plugins/plugin-workflow/      # 参考插件 APK
├── ComposeFoundry/               # 独立工程：UI DSL 预览器
├── docs/                         # 深度文档（见文档索引）
└── .github/workflows/            # ci / quality-gate / pr-labeler

代码规模（自动统计于当前主干）：

指标	数值
Kotlin 主源码	802 个文件 / 183,615 行
Kotlin 测试源码	252 个文件 / 64,116 行（≈4,008 个 @Test 用例）
C++（终端 PTY/JNI/VT 原生层）	37 个文件 / 10,650 行
Gradle 模块	20
内置工具	109
测试代码 / 主源码比例	≈ 35%

⬆️ 返回顶部

---

🗺️ 路线图

• 流式 ReAct 引擎 + Plan 模式 + 五档思考深度
• 三级权限链 + 无障碍 UI 自动化
• P7 三级上下文压缩（双引擎对齐）
• cs-mem 认知记忆全管线（蒸馏 / 旁路 / 能量 / 梦境 / 免疫 / 迁移闭环）
• 终端运行时 2.0（Ubuntu rootfs + PRoot + 原生 PTY + VT100）
• 多模型运行时（角色路由 + VISION）
• 浏览器智能体（DOM 级 + 稳定 ref）
• v1.2 七档思考系统（NONE→ULTRACODE→APEXCODE + AUTO 预检自适应，Coding 页专属 + 档位效能统计；Agent 聊天页保持六档独立体系）
• v1.2 长任务中心（自动留档 / 检查点时间线与续跑 / 复制对比 / 8 模板）
• 宏技能语义检索（嵌入索引，跨 App 近邻复用 —— Voyager 启发）
• 记忆软删除与双时间线（Zep/Graphiti 启发）
• 编排器并行子代理扇出（Claude Code 启发）
• 免疫系统 OCR 视觉比对（MLKit）→ 记忆块自编辑（Letta 启发）
• 技能市场社区化（远程注册表 + 签名校验）

⬆️ 返回顶部

---

📄 文档索引

文档	内容
docs/tool-system-v3.md	工具系统 v3：执行硬化八层（超时/重试/限流/熔断/追踪/批量/组合动作/环境门控），MCP·LangGraph·Anthropic CU·Mobile-Agent-E 对标
docs/TESTING.md	测试总指南：理念/矩阵/替身规范/FAQ/文件清单（撰写时 74，现已 252，待同步）
docs/liquid-glass-system.md	Liquid Glass 玻璃组件系统：架构/七档材质/组件 API/真实性验收矩阵
docs/memory-and-workflow-research.md	记忆与工作流调研报告：对标 MemGPT/Mem0/A-MEM/Zep/Voyager/Claude Code/OpenHands/SWE-agent
docs/terminal-api.md	终端 API 契约
docs/terminal/TERMINAL_EXPERIENCE_OVERHAUL_T87.md	T87 终端体验大修：7 项用户实测反馈的根因对照与修复（输入失败/exec 失败捕获、滚动空白、黑字、21 套配色、apt 引导）
docs/terminal/AGENT_TERMINAL_CALLCHAIN.md	Agent↔终端调用链：全部 terminal.* 工具表 + exec 链路图 + terminal.diagnostics 自证
docs/terminal/TERMINAL_CONFIGURATION.md	终端配置系统：配色/扩展键宏语法/持久化键/新增方案指南
docs/ubuntu-rootfs-t72.md	T72 Ubuntu rootfs 供给设计
docs/cs-mem-gaps-spec.md	cs-mem 缺口补全规格（含缺口 #9 拓扑迁移）
docs/agent-modes.md	六种模式详解
docs/proot-binary-provenance.md	PRoot 预编译二进制来源与指纹
docs/pipeline-output-optimization.md	流水线输出优化记录
docs/PERF.md	性能笔记
docs/MIGRATION_REPORT.md	迁移报告
docs/operit-rikkahub-comparison.md	P9x 系列调研：operit vs rikkahub 全面对比（架构/执行循环/Key 管理/记忆/角色/分支/提示词/搜索/终端/生态/质量 11 域），产出 P90-P96 七项落地
docs/key-pool.md	P90 API Key 池：三态门控/四轮换模式/指数退避/请求层换 Key 重试环（对标 operit MultiApiKeyProvider + rikka LruKeyRoulette）
docs/prompt-variables.md	P91 提示词变量：19 内置变量/转义与默认值语法/递归环安全（对标 rikka PlaceholderTransformer）
docs/prompt-template-library.md	P92 提示词模板库：10 内置模板/四级变量合并/原子持久化/导入导出（对标 operit 提示词库）
docs/message-branching.md	P93 消息分支：MessageBranchNode 候选数组模型/九操作/树存储与迁移（对标 rikka MessageNode）
docs/search-providers.md	P94 搜索供应商框架：Tavily/Brave/Exa/SearXNG/DDG/Bing 六供应商/三阶段回退/缓存限流（对标 rikka 19 家搜索抽象）
docs/persona-cards.md	P95 角色卡：SillyTavern V1/V2/PNG tEXt 导入/Lorebook 触发（对标 operit 角色卡 + rikka AssistantImporter）
docs/provider-share.md	P96 供应商分享：四层洋葱 URI/Key 脱敏/GZIP/QR 版本估算（对标 rikka QR 分享）
docs/capsule-stream.md	胶囊流式输出系统：Coding 工作流时间轴 / 双通道架构 / 幂等与检查点 / 验收矩阵
docs/dual-logic-engines.md	双思考逻辑引擎：Coding 屏右上角「深潜/标准」切换 / DualLogicCodeEngine 门面路由 / 标准任务循环（五画像·权限三态门·task 子代理·上下文压缩·C++ 文本核）/ /logic 斜杠命令 / 现场隔离
docs/agent-life-skills-and-memory.md	全能 Agent：46 内置技能矩阵 × 渐进披露（目录+会话装备+自动装备）/ 聊天自动记忆管线（双速捕获+主动召回）/ 首轮问候极简 / 网页自动化 wait_for+页面类型推断

⬆️ 返回顶部

---

❓ FAQ

1️⃣ 需要 Root 吗？

不需要。 三级权限链会自动降级：无 Root 时优先用 Shizuku（ADB 级， 免 Root 装应用 / 改设置 / 模拟输入），再不行就用普通应用沙箱 shell。 Root 只是解锁全系统操作（/system、SELinux、ptrace 等）的上限增强。

2️⃣ 必须配置 API Key 吗？支持哪些模型？

需要一个任意 OpenAI 兼容端点的 Key（OpenAI / DeepSeek / OpenRouter / 中转 / 局域网 Ollama 均可）。未配置时应用以 NoOpLlmClient 优雅降级、界面提示而不 崩溃。DeepSeek-R1 / Qwen3-thinking / o 系列的原生思维链（reasoning_content） 会透传到 UI 实时显示。

3️⃣ 我的 API Key 和记忆数据存在哪？会隐私泄露吗？

• Key 与记忆全部只存应用私有目录（filesDir / SharedPreferences）， 不上传任何自有服务器——本项目没有服务器；
• GitHub PAT 经 EncryptedSharedPreferences（AES-256-GCM）加密存储；
• 会话内容会直连你配置的 LLM 端点（这是智能体工作的必要通道）， 用局域网 Ollama 即可做到全链不出内网。

4️⃣ 终端的 Ubuntu 会很费流量 / 存储吗？

Ubuntu 24.04 完整 CLI 环境随 APK 内置（rootfs 档案 ~300MB+、解压后 1GB， 构建期 SHA-256 锁定），首次使用离线解包约 25 分钟；此后完全离线， 只有 apt install 装新包时才联网。PRoot 是用户态沙箱， 不修改系统分区。

5️⃣ 为什么仓库里没有 gradlew？

仓库未锁定 wrapper。一条命令现场生成（见快速开始），或直接下载 CI 产出的 debug APK 工件（每次构建保留 14 天），零环境开箱体验。

6️⃣ "肌肉记忆"是什么意思？真的省 token 吗？

任务成功后，TraceDistiller 把 ReAct 轨迹蒸馏成 FSM 宏技能。之后再次遇到 相同界面指纹时，BypassExecutionEngine 直接回放动作序列——完全绕过 LLM， 0 token、微秒级返回。App 升级导致指纹漂移时，拓扑同胚迁移通过别名桥保鲜。

⬆️ 返回顶部

---

🧭 术语速查

术语	一句话解释
cs-mem	本项目的认知记忆系统（cognitive memory）：屏幕感知 → 语义图 + FSM 宏技能
差分摄取	只存 UI 状态之间的"跃迁"，而不是整帧快照，压缩 95%+
节点指纹	UI 节点的 SHA-256 内容哈希，是记忆索引与宏回放匹配的主键
FSM 宏	把成功任务轨迹编译成的有限状态机技能，可 0 token 旁路回放
晶化	高能量高成功率的宏固化为 ROM 级永久技能，免疫遗忘与剪枝
梦境渲染	息屏+充电+WiFi 时的后台记忆巩固周期（保鲜验证/衰减/迁移）
PRoot	用户态 ptrace 沙箱，免 Root 运行完整 Linux 发行版
PTY	伪终端（C++ forkpty 实现），交互式 shell 的底层通道
VT100/ANSI	终端转义序列标准，自研模拟器负责渲染与解析
Shizuku	通过 ADB 授权获得 uid=2000 权限的框架，免 Root 执行特权命令
MCP	Model Context Protocol——外部工具服务器的标准接入协议
BYO-LLM	Bring Your Own LLM：自带任意 OpenAI 兼容端点与 Key
AIDL	Android 接口定义语言，插件 APK 与宿主跨进程通信的契约
P7 三级压缩	工具输出截断 → 滑动窗口 → LLM 摘要的上下文预算防线

⬆️ 返回顶部

---

🤝 贡献指南

欢迎 Issue / PR！提交前请自查：

1. CI 全绿是硬门禁（含 cs-mem / agent-engine / tool-registry / terminal 测试）；
2. 遵循 type(scope): description 提交规范（feat / fix / docs / refactor / chore）；
3. 结构预算：单文件 main ≤1200 行 / test ≤1600 行，超了先拆再提；
4. 修缺陷必须带回归测试（先红后绿，KDoc 注明锁定的缺陷）；
5. 新工具必须过工具 ID 唯一性检查；core:tool-registry 测试步骤不允许通过 跳过来变绿；
6. 记忆系统改动请同步更新 docs/memory-and-workflow-research.md 的对应结论。

Caution

⚖️ 许可证尚未确定（TBD）。商业化使用前请先联系作者开 issue 对齐。

---

📊 开发者统计

---

⭐ Star History

---

👥 贡献者

---

🪪 仓库名片

---

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

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

Android Guru Agent · 报告问题 · 发起 PR · 回到顶部

Footnotes

1. 调研覆盖：MemGPT/Letta、Mem0、A-MEM、Zep/Graphiti、Voyager（记忆系统）；Claude Code、OpenHands、SWE-agent（工作流）。全文见 docs/memory-and-workflow-research.md。 ↩