Skip to content

Module Map

Jump to bottom
AceGuru-mjh edited this page Sep 25, 2026 · 4 revisions

模块地图

13 个 Gradle 模块，全部登记在根 settings.gradle.kts（rootProject.name = "apex-agent"）。 本页给出每个模块的职责、关键类、依赖与被依赖方向，以及"我该改哪里"的反查表。

1. 一张表看懂 13 个模块

模块 类型 职责一句话 关键入口
:app Android App Compose UI（抽屉导航）+ Hilt 装配 + 浏览器/GitHub 工具 + 悬浮球 ApexApp.kt · MainActivity.kt · ui/ApexRoot.kt
:core:agent-engine 纯 JVM 六模式 ReAct 引擎、任务编排器、上下文压缩、会话记忆 AgentEngine · ApexAgentEngine · DefaultTaskOrchestrator · HybridCompressor
:core:tool-registry 纯 JVM 64 个内置工具 + schema 校验 + v3 执行硬化 + 技能注册 + MCP 客户端 ToolRegistry · ToolSchema · EnhancedToolExecutor · ToolBatchRunner
:core:llm-adapter 纯 JVM OpenAI 兼容流式客户端（自研 SSE）+ 多模型运行时 LlmClient · StreamingOpenAiClient · ModelRuntimeRegistry · ModelRoleRouter
:core:logging 纯 JVM 结构化日志（分类/级别/记录） AppLogger · LogCategory · LogLevel
:platform:privilege Android Lib Root / Shizuku / 沙箱三级权限链 + 无障碍服务 + 进程流工厂 PrivilegeDetector · PrivilegeManager · ProcessStreamFactory
:platform:persistence Android Lib 前台服务 + WorkManager 看门狗 PersistenceEngine.kt
:platform:terminal Android Lib 终端运行时：rootfs 供给、PRoot 后端、原生 PTY、apt、18 个工具 LinuxPRootBackend · UbuntuLifecycleCoordinator · PtyOutputPump
:platform:cs-mem Android Lib 认知记忆（本仓库差异化核心） CsMemSessionManager · TraceDistiller · BypassExecutionEngine · DreamRenderer
:terminal-emulator Android Lib 自研 VT100/ANSI 终端模拟器（零依赖） 转义序列解析、滚动区、24 位色
:plugin-sdk:plugin-api Android Lib AIDL 契约 IApexPlugin + PluginContract 常量 IApexPlugin.aidl · ApexPluginService
:plugin-sdk:plugin-host Android Lib 插件发现 / 绑定 / 工具桥接 PluginManager.kt
:plugins:plugin-workflow Android App 参考插件 APK（3 个工具） WorkflowPluginService.kt

Note

ComposeFoundry/ 目录里是另一个独立 Gradle 工程（有自己的 settings.gradle.kts， 只包含 :app），不参与主构建。见 ComposeFoundry。

2. 依赖方向（谁可以依赖谁）

flowchart LR
    APP[":app"] --> AE[":core:agent-engine"]
    APP --> TR[":core:tool-registry"]
    APP --> LLM[":core:llm-adapter"]
    APP --> LOG[":core:logging"]
    APP --> PRIV[":platform:privilege"]
    APP --> TERM[":platform:terminal"]
    APP --> CSMEM[":platform:cs-mem"]
    APP --> PERSIST[":platform:persistence"]
    APP --> VTE[":terminal-emulator"]
    APP --> PHOST[":plugin-sdk:plugin-host"]

    AE --> TR
    AE --> LLM
    AE --> LOG
    TR --> LLM
    TERM --> VTE
    TERM --> TR
    CSMEM --> TR
    CSMEM --> PRIV
    CSMEM --> LOG
    PERSIST --> PRIV
    PHOST --> PAPI[":plugin-sdk:plugin-api"]
    PHOST --> TR
    PLUGIN[":plugins:plugin-workflow"] --> PAPI
Loading

规则速记：

  • core:* 只向下依赖 core:*（除 logging）—— 永远不碰 Android；
  • platform:* 可以依赖 core:* 与其它 platform:*；
  • terminal-emulator 零依赖（连 platform:terminal 都不许依赖）；
  • :app 是全汇聚点，因此所有 wiring（di/）都在 :app。

3. 各模块细节

3.1 :core:agent-engine —— 智能体的脑子

com.apex.agent.core.engine
├── AgentEngine / ApexAgentEngine      流式 ReAct 主循环（大文件，受 ≤1200 行预算约束）
├── AgentConfig / AgentEvent           配置与事件（TextChunk / ThinkingChunk / ToolCall* / ResponseComplete…）
├── CommandPermissionGate / UserInput / UserQuestion
├── ConversationMemory / EnginePrompts
├── compression/                       ContextCompressor · HybridCompressor · ToolOutputTruncator
│                                      SlidingWindowCompressor · LlmSummaryCompressor · TokenEstimator
├── orchestrator/                      TaskOrchestrator · DefaultTaskOrchestrator · TaskStateMachine
│                                      BatchExecutionEngine · LoopDetector · FailureClassifier
│                                      RecoveryPlanner · RetryPolicy · ToolCallGraph · UserInteractionGate
└── task/                              TaskRuntime · TaskModels · TaskStore/FileTaskStore
                                       TaskStatusMachine · RecoveryPolicy · DanglingToolCallRepair

详见 Agent 引擎 · 任务编排器 · 上下文压缩。

3.2 :core:tool-registry —— 能力的唯一出口

ToolRegistry · ToolResult · ToolSchema/ToolMetadata/ToolArguments/ToolAnnotations · EnhancedToolExecutor · SafeAgentTool · StreamingTool · ToolExecutionGate · ToolRunPolicy · ToolEnvironmentState · ToolBatchRunner · ToolCircuitBreaker · ToolUsageTracker · ToolTraceRecorder · ToolSuggester · Shortcut。

v2 定义"工具是什么"，v3 定义"工具在真实循环里怎么不死"，见 工具系统。

3.3 :core:llm-adapter —— 只说 OpenAI 方言

自研 SSE 解析（不依赖官方 SDK）：LlmClient / LlmClientFactory / LlmConfig / ModelProfile / ModelsCatalog / StreamingOpenAiClient， 运行时包 runtime/：ModelRuntime / ModelRuntimeRegistry / ModelRoleRouter / CapabilityResolver / ModelProfileValidator / ModelRuntimeDiagnostics。

LlmConfig 关键默认值：contextWindow 128k、readTimeout 120s、connectTimeout 15s、retryCount 2。 详见 LLM 适配层。

3.4 :platform:terminal —— 一台 Ubuntu 住进手机

api/          TerminalApi · TerminalSdk · ApiHardening       对外契约（面向 app）
runtime/      ExecutionContext · LinuxExecutionContext       运行时抽象
pty/          NativePty · JniNativePty                       JNI 桥 → C++ forkpty
proot/        LinuxPRootBackend · ProotExecutor · SystemBindProfile · NativeLibraryPRootBinaryProvider
ubuntu/       BundledRootfsSource · RootfsDownloader/Extractor/Configurator
              RootfsProvisionerImpl · RootfsHealthCheck · UbuntuSourcesList
              lifecycle/UbuntuLifecycleCoordinator
pkg/          UbuntuAptPackageManager · PackageOperationLock
tools/v2/     22 个 terminal 工具 + tools/legacy/ 7 个
observation/state/  ObservationEngine2 · SemanticStateReducer · InputWaitingDetector

JNI：src/main/cpp/{pty_engine,pty_session,jni_bridge}.cpp + headers，CMake 产出 apex_terminal。 详见 终端运行时。

3.5 :platform:cs-mem —— 差异化核心

包 com.apex.agent.platform.csmem：

组 组件
会话 CsMemSessionManager
摄取 UiTreePruner · NodeFingerprint · DifferentialIngestor · MemoryWriterActor（有界邮箱 256）
存储 MemoryGraphDatabase（Room schema v3）· MemoryGraphStore · 5 张表 DAO（nodes/edges/episodes/fsm_macros/migration_map）
蒸馏 TraceDistiller（锚点提取 → 动作压缩 → FSM 编译）
回放 BypassExecutionEngine（指纹命中绕过 LLM）
生命周期 EntropyManager（能量/晶化）· DreamRenderer · TopologyMigrator
安全 MemoryImmuneSystem
对外 CsMemRecallTools（3 个召回工具）· di/CsMemModule

详见 cs-mem 认知记忆 · 记忆生命周期。

3.6 :app 目录速查

app/src/main/kotlin/com/apex/agent/
├── ui/           ApexRoot（抽屉）+ theme/ glass/ component/ + screen/<8 屏>
├── browser/      浏览器智能体（15 工具）+ chrome/ 一整套 Chrome 风 UI 与 bridge
├── github/       GitHub 工具（7 个）
├── slash/        斜杠命令解析（纯 JVM 可测）
├── tools/        AskUser · RiskAwareToolGate · PrivilegedCommandSpawner …
├── di/           Hilt 模块（ToolModule / TerminalModule / AgentModule …）
├── attachment/ environment/ marketplace/ bridge/ platform/
├── receiver/     BootReceiver
└── service/      ApexCoreService

4. 「我该改哪个模块」反查表

诉求 首选模块 备选 / 注意
新增工具（纯计算） core:tool-registry CI 有工具 ID 唯一性门禁
新增工具（需要 Android API） platform:* 实现 + app/di/ToolModule 注入 不要试图在 core 里引 Android
新增工具（需要 UI/界面跳屏） app/tools/ 或 app/browser/ 走 ask_user / 风险门
改 LLM 协议细节 core:llm-adapter 保持 OpenAI 兼容方言，别引入厂商 SDK
改 UI 外壳/主题 app/ui/theme、app/ui/glass 见 Liquid Glass
改终端行为 platform/terminal（实现）+ :terminal-emulator（渲染） 两层不许互相依赖
改 rootfs 打包方式 scripts/fetch_rootfs.sh + platform/terminal/build.gradle.kts 见 Ubuntu rootfs 供给
改记忆算法 platform/cs-mem 同步更新 docs/memory-and-workflow-research.md
改 CI 门禁 .github/workflows/、scripts/ 见 质量门禁
写独立插件 plugins/（新 application 模块，依赖 plugin-api） 见 插件 SDK

5. 构建要点

主题 事实
仓库管理 settings.gradle.kts 声明 13 个 include；RepositoriesMode.FAIL_ON_PROJECT_REPOS，仅 JitPack（EasyFloat）例外，exclusiveContent 过滤
依赖锁定 :app 开了 dependencyLocking
单 ABI 瘦身 -PapexAbi=arm64-v8a
ABI 过滤 arm64-v8a / armeabi-v7a / x86_64
原生构建 NDK CMake 3.22.1，-std=c++17 -Wall -Wextra -O2，-DANDROID_STL=c++_shared
特殊打包 useLegacyPackaging = true（rootfs 必须解压到 nativeLibraryDir 才能 exec）+ keepDebugSymbols 跳过 llvm-strip
wrapper 仓库未锁定 gradlew，需本机 gradle wrapper --gradle-version 8.10 生成，或看 CI 步骤

Android Guru Agent · 仓库 · 官网 · 下载 APK · Issue · PR · CI

🏠 首页 · 📚 文档索引 · 🛰️ MCP 生态 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图

Wiki 随主干 main 演进 · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room · License TBD

发现与代码不一致？欢迎提 Issue 纠正。

🚀 入门

🏗️ 架构

🧠 Agent 内核

🔧 能力

🛰️ MCP 生态

  • MCP 生态总览 新
  • （沙箱 MCP · 官方 Hub · 逆向 Host · 门控语义）

🖥️ 终端 & Linux

💡 记忆

🎨 UI & 扩展

🛠️ 工程化

🔒 参考

共 58 页 · 4,600+ 行 · 随主干 main 演进

🐛 提 Issue · ⭐ Star 仓库

Clone this wiki locally