Module Map

模块地图

🏗️ 架构 · 🏠 首页 › Module-Map

Version Kotlin Modules Tools License

📑 本页目录

1. 一张表看懂 20 个模块
2. 依赖方向（谁可以依赖谁）
3. 各模块细节
4. 「我该改哪个模块」反查表
5. 构建要点

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

1. 一张表看懂 20 个模块

模块	类型	职责一句话	关键入口
`: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	内置工具 + schema 校验 + v3 执行硬化 + 技能注册 + MCP 客户端	`ToolRegistry` · `ToolSchema` · `EnhancedToolExecutor` · `ToolBatchRunner`
`:core:llm-adapter`	纯 JVM	OpenAI 兼容流式客户端（自研 SSE）+ 多模型运行时	`LlmClient` · `StreamingOpenAiClient` · `ModelRuntimeRegistry` · `ModelRoleRouter`
`:core:logging`	纯 JVM	结构化日志（分类/级别/记录）	`AppLogger` · `LogCategory` · `LogLevel`
`:core:code-tools`	纯 JVM	编码工具包：文件编辑 / git / 诊断 / TODO	`CodeTools` · `CodeWorkspaceRoots` · `git/GitTools` · `diagnostics/CodeDiagnostics`
`:core:code-engine`	纯 JVM	编码模式专用引擎：长任务 / 子代理 / 流式胶囊 / 思考档位	`CodeAgentEngine` · `longtask/` · `subagent/CodeTaskTool` · `stream/` · `thinking/`
`:platform:privilege`	Android Lib	Root / Shizuku / 沙箱三级权限链 + 无障碍服务 + 进程流工厂	`PrivilegeDetector` · `PrivilegeManager` · `ProcessStreamFactory`
`:platform:persistence`	Android Lib	前台服务 + WorkManager 看门狗	`PersistenceEngine.kt`
`:platform:terminal`	Android Lib	终端运行时：rootfs 供给、PRoot 后端、原生 PTY、apt、23 个工具	`LinuxPRootBackend` · `UbuntuLifecycleCoordinator` · `PtyOutputPump`
`:platform:cs-mem`	Android Lib	认知记忆（本仓库差异化核心）	`CsMemSessionManager` · `TraceDistiller` · `BypassExecutionEngine` · `DreamRenderer`
`:platform:code-workspace`	Android Lib	编码工作区：安全根目录与工作区生命周期	`CodeWorkspace` · `CodeWorkspaceManager`
`:platform:mcp-host`	纯 JVM	逆向 MCP Host：把手机工具暴露给 PC 客户端（零第三方依赖）	`McpHostServer` · `McpHostBridge` · `http/HttpCodec` · `rpc/JsonRpc`
`:terminal-emulator`	纯 Kotlin	自研 VT100/ANSI 终端模拟器（零依赖）：转义解析、滚动区、24 位色、双宽字符	`TerminalCore` · `VtParser` · `CsiOps` · `Reflow` · `UnicodeWidthTables`
`:terminal-native`	Android Lib	VT 引擎原生加速层（C++）：图膜簇 / 会话 / 重排版	`NativeVtCore` · `VtEngineFactory` · `cpp/vt-native/`
`:terminal-view`	Android Lib	Compose 终端视图层：画布渲染 / 手势 / 选区 / IME 连接	`TerminalView` · `TerminalCanvasRenderer` · `TerminalGestureModel` · `TerminalInputConnection`
`: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（工作流）	`WorkflowPluginService.kt`
`:plugins:plugin-web-automation`	Android App	参考插件 APK：浏览器自动化工具目录	`WebAutomationPluginService.kt` · `BrowserToolCatalog.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"]
    APP --> CE[":core:code-engine"]
    APP --> MCPH[":platform:mcp-host"]
    APP --> TVIEW[":terminal-view"]
    APP --> CWS[":platform:code-workspace"]

    AE --> TR
    AE --> LLM
    AE --> LOG
    TR --> LLM
    CE --> TR
    CE --> LLM
    CE --> LOG
    TERM --> VTE
    TERM --> TR
    TERM --> TVIEW
    CSMEM --> TR
    CSMEM --> PRIV
    CSMEM --> LOG
    PERSIST --> PRIV
    PHOST --> PAPI[":plugin-sdk:plugin-api"]
    PHOST --> TR
    MCPH --> TR
    CWS --> LOG
    PLUGIN[":plugins:plugin-workflow"] --> PAPI
    PLUGIN2[":plugins:plugin-web-automation"] --> PAPI

规则速记：

core:* 只向下依赖 core:*（除 logging）—— 永远不碰 Android；
platform:* 可以依赖 core:* 与其它 platform:*；
terminal-emulator 零依赖（连 platform:terminal 都不许依赖）；
terminal-view 只被 :app / platform:terminal 使用，不反向依赖任何业务模块；
platform:mcp-host 是纯 JVM（零第三方依赖），工具执行借道 ToolRegistry；
: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/     23 个 terminal 工具 + tools/legacy/ 6 个
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 `:core:code-engine` + `:core:code-tools` + `:platform:code-workspace` —— 编码工位三件套

v1.4.x 双工位重构（PR #198）把「Coding 工位」从 Agent 引擎里独立出来：

模块	包	关键类	职责
`:core:code-engine`	`core.code`	`CodeAgentEngine` · `CodePrompts` · `CodeConversationMemory`	编码模式专用引擎（与 `agent-engine` 平行的 ReAct 循环）
	`code.longtask/`	长任务韧性：重试 / 换路提示 / 退避预算	PR #249
	`code.subagent/`	`CodeTaskTool`	子代理任务拆分
	`code.stream/`	胶囊流式会话	CodeStream 归约机
	`code.thinking/`	思考档位（七档 + AUTO）
`:core:code-tools`	`core.codetools`	`CodeTools` · `git/GitTools` · `diagnostics/` · `edit/`	文件编辑 / git / 诊断 / TODO 工具包（纯 JVM）
`:platform:code-workspace`	`platform.code.ws`	`CodeWorkspace` · `CodeWorkspaceManager`	编码工作区安全根目录与生命周期（Android 侧）

3.7 `:platform:mcp-host` —— 逆向 MCP Host

纯 Kotlin JVM、零第三方依赖（ServerSocket + 协程 + kotlinx.serialization）：

platform/mcp-host/src/main/kotlin/com/apex/agent/platform/mcphost/
├── http/HttpCodec.kt       最小 HTTP/1.1 编解码（Bearer 提取 / 限体）
├── rpc/JsonRpc.kt          JSON-RPC 2.0 信封
├── McpHostConfig.kt        Token/白名单/黑名单/限速持久化接口
├── McpHostBridge.kt        工具暴露桥（白名单 + vault 硬拦截 + v3 管线）
└── McpHostServer.kt        ServerSocket（会话/审计/限速/鉴权）

详见 MCP 生态。

3.8 `:terminal-emulator` / `:terminal-native` / `:terminal-view` —— 终端三层

终端在 v1.4.x 拆成三层（见终端迁移）：

模块	形态	内容
`:terminal-emulator`	纯 Kotlin、零依赖	VT 解析器 `VtParser` + `TerminalCore`：CSI/SGR/OSC、滚动区、reflow、双宽字符表 `UnicodeWidthTables`、24 位色、超链接注册表、鼠标/焦点上报
`:terminal-native`	Android Lib + C++	VT 引擎原生加速层：`NativeVtCore` + `cpp/vt-native/`（`vt_engine/vt_session/vt_grapheme/vt_reflow`），`VtEngineFactory` 负责加载与回退
`:terminal-view`	Android Lib（Compose）	视图层：`TerminalView` + `TerminalCanvasRenderer`（画布渲染）+ 手势/选区/滚动模型 + `TerminalInputConnection`（IME）+ 31 套 `TerminalPalette`

3.9 `: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-*` 三层（渲染）	四层之间不许互相依赖
改 rootfs 打包方式	`scripts/fetch_rootfs.sh` + `platform/terminal/build.gradle.kts`	见 Ubuntu rootfs 供给
改记忆算法	`platform/cs-mem`	同步更新 `docs/memory-and-workflow-research.md`
改 MCP 接入/沙箱/门控	`core/tool-registry`（客户端）+ `app/marketplace`（UI）	见 MCP 生态
改逆向 Host / 安全门	`platform/mcp-host`	不碰 `McpModule/McpManager`（客户端侧）
改编码模式引擎	`core/code-engine` + `core/code-tools`	工作区根目录在 `platform/code-workspace`
改 CI 门禁	`.github/workflows/`、`scripts/`	见质量门禁
写独立插件	`plugins/`（新 application 模块，依赖 `plugin-api`）	见插件 SDK

5. 构建要点

主题	事实
仓库管理	`settings.gradle.kts` 声明 20 个 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 步骤

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

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

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

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

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

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

📖 Wiki 导航

🏠 首页 · 🚀 快速开始 · 📚 文档索引 · 🧭 术语速查

58 pages version

🚀 入门

🏗️ 架构

🧠 Agent 内核

🔧 能力

🛰️ MCP 生态

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

🖥️ 终端 & Linux

💡 记忆

🎨 UI & 扩展

🛠️ 工程化

🔒 参考

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

🐛 提 Issue · ⭐ Star 仓库

Module Map

模块地图

1. 一张表看懂 20 个模块

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

3. 各模块细节

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

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

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

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

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

3.6 :core:code-engine + :core:code-tools + :platform:code-workspace —— 编码工位三件套

3.7 :platform:mcp-host —— 逆向 MCP Host

3.8 :terminal-emulator / :terminal-native / :terminal-view —— 终端三层

3.9 :app 目录速查

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

5. 构建要点

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

🚀 入门

🏗️ 架构

🧠 Agent 内核

🔧 能力

🛰️ MCP 生态

🖥️ 终端 & Linux

💡 记忆

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

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

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

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

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

3.6 `:core:code-engine` + `:core:code-tools` + `:platform:code-workspace` —— 编码工位三件套

3.7 `:platform:mcp-host` —— 逆向 MCP Host

3.8 `:terminal-emulator` / `:terminal-native` / `:terminal-view` —— 终端三层

3.9 `:app` 目录速查