Architecture

架构总览

🏗️ 架构 · 🏠 首页 › Architecture

---

📑 本页目录

• 1. 分层全景
• 2. 三条设计红线
• 3. 一次对话的完整数据流
• 4. 两条执行路径的关系
• 5. 进程模型与保活
• 6. 从"改一行 UI"到"加一个能力"的最短路径

一句话：三层干净隔离 —— core:* 是零 Android 依赖的纯 JVM 智能体内核， platform:* 是把内核落到 Android 上的平台实现，:app 只做 Compose UI 与 Hilt 装配。 内核不知道 Android 存在，平台不知道 UI 存在。

1. 分层全景

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

    subgraph CORE["⚙️ core:* — 纯 JVM · 零 Android 依赖"]
        direction LR
        ENGINE["agent-engine<br/>六模式 ReAct 循环<br/>TaskOrchestrator<br/>P7 三级压缩"]
        TOOLS["tool-registry<br/>64 内置工具 · schema 即校验<br/>v3 执行硬化八层"]
        LLM["llm-adapter<br/>OpenAI 兼容 SSE<br/>多模型运行时 · 角色路由"]
        LOGC["logging<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 · 18 工具"]
        CSMEM["cs-mem 认知记忆<br/>蒸馏 · 旁路 · 梦境<br/>Room 图数据库"]
    end

    VTE["🖥️ terminal-emulator<br/>自研 VT100 / ANSI 模拟器"]

    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
    PHOST -->|插件工具注册| TOOLS
    PERSIST -.前台保活.-> APP
    PAPI -.契约.-> PHOST
    PLUGINS -.实现.-> PAPI

Loading

Note

上图是控制/数据流示意，不是严格 Gradle 依赖图；精确依赖关系见 模块地图。 ComposeFoundry/ 是独立 Gradle 工程，不参与主构建，见 ComposeFoundry。

2. 三条设计红线

#	红线	为什么	违反后果
1	core:* 不得依赖 Android SDK	纯 JVM 才能用 kotlinc 秒级类型校验、跑 JVM 单测；CI 静态分析 job 就是靠它做到无 Android SDK 也能验证四个 core 模块	CI 静态分析失效、单测需模拟器
2	terminal-emulator 不得依赖 platform:terminal	模拟器是通用视图组件，被" vendored"进仓库（ATR Phase 2），反向依赖会让可移植性崩塌	模拟器无法独立复用/测试
3	targetSdk = 28	API 29+ 的 SELinux untrusted_app 域禁止 exec app_data_file，Ubuntu rootfs 依赖 execve + ptrace	PRoot / guest 进程全部无法执行

其余派生约定：

• 单 Activity + 全 Compose：:app 的 res/ 只有资源，没有 View 布局文件；
• 依赖注入统一 Hilt：跨模块的接线集中在 app/.../di/（ToolModule / TerminalModule / AgentModule 等）；
• 依赖版本集中管理：全部走 gradle/libs.versions.toml + RepositoriesMode.FAIL_ON_PROJECT_REPOS（禁止模块私开仓库）；
• 工具是唯一能力出口：LLM 只能通过 ToolRegistry 触达系统能力，便于统一风险门 / 追踪 / 限流。

3. 一次对话的完整数据流

sequenceDiagram
    participant U as 用户
    participant VM as AgentChatViewModel
    participant EN as ApexAgentEngine / TaskOrchestrator
    participant LLM as StreamingOpenAiClient
    participant EX as EnhancedToolExecutor
    participant T as 工具实现（app / platform）
    participant M as cs-mem

    U->>VM: 输入文本 + 附件（图片多模态）
    VM->>EN: execute(input, mode, thinkingLevel)
    loop ReAct 迭代
        EN->>LLM: chat(messages, tools) — SSE
        LLM-->>EN: Δ text / Δ reasoning_content / tool_calls
        EN-->>VM: AgentEvent.TextChunk / ThinkingChunk
        alt 无工具调用
            EN-->>VM: AgentEvent.ResponseComplete
        else 有工具调用
            EN->>EX: execute(toolId, args, policy)
            EX->>EX: 建议→环境门→风险门→schema→限流→熔断→超时重试
            EX->>T: 实际执行
            T-->>EX: ToolResult（含流式 Progress / Error）
            EX-->>EN: 结果 + ToolTraceSpan
            EN->>EN: 水位检查 → 触发 P7 压缩
            EN-->>VM: AgentEvent.ToolCallStarted / Output / Finished
        end
    end
    EN->>M: 会话结束写 Episode / 蒸馏 FSM 宏
    EN-->>VM: AgentEvent.ContextCompressed（如发生压缩）

Loading

4. 两条执行路径的关系

路径	实现	何时使用	关键能力
直连	ApexAgentEngine（流式 ReAct）	对话式、绝大多数任务	全事件流输出、压缩、多模附件
编排	DefaultTaskOrchestrator	复杂长任务（多步计划、需重试/恢复/人工确认）	任务状态机、批量执行引擎、失败分类 → 恢复规划、循环检测、用户交互门

两者共享同一套 HybridCompressor、ToolRegistry、LlmClient， 因此统一种水位语义：UI 不需要区分消息来自哪条路上的 major (+) minors (+) patches 路径，同一套 AgentEvent 即可渲染。

详见 Agent 引擎 与 任务编排器。

5. 进程模型与保活

组件	位置	作用
ApexApp	app/.../ApexApp.kt	@HiltAndroidApp + Configuration.Provider，启动时注入记忆写入 actor、梦境渲染器、Ubuntu 生命周期、桥接服务、环境状态更新器
MainActivity	app/.../MainActivity.kt	单 Activity；首次启动走 OnboardingScreen；进程内幂等拉起 ApexCoreService
ApexCoreService	app/.../service/	前台 service，承载长任务与终端会话
PersistenceEngine	platform/persistence	前台服务 + WorkManager 看门狗，被杀后自动拉起
BootReceiver	app/.../receiver/	开机 / 包替换事件后恢复后台链路
DreamRenderer	platform/cs-mem	WorkManager 周期任务：息屏 + 充电 + WiFi 时巩固记忆

Important

Android 上"永久后台"不可达。保活能力受厂商策略与系统省电策略限制， 项目的姿态是 诚实降级：梦境渲染只在约束满足时跑，前台必要时拉通知，不做欺骗式保活。

6. 从"改一行 UI"到"加一个能力"的最短路径

我想……	落点
加一个工具	core/tool-registry 注册 ToolSchema + 实现；若需要 Android 能力，在 app 或 platform 实现并由 ToolModule 注入 —— 见 工具系统
加一种模式	core/agent-engine 的 AgentMode + EnginePrompts 对应分支 —— 见 Agent 引擎
加一屏 UI	app/.../ui/screen/<name>/ + 在 ApexRoot.kt 抽屉目的地注册 —— 见 界面导航地图
加一块记忆	platform/cs-mem 的 entity + DAO + 写入 actor —— 见 cs-mem 认知记忆
加一条 CI 门禁	.github/workflows/quality-gate.yml 或 scripts/ —— 见 质量门禁

---

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

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