Android Agent-Runtime Implementation
基于 OHOS
ascf-agent架构 + Kai Android 参考实现的 Android agent-runtime 模块。
1. 概述
flexui-engine/modules/android/agent-runtime/ — 与 OHOS ascf-agent/agent-runtime/ 功能对齐的 Android 库模块。
- 包名:
org.flexui.agent - Demo 包名:
org.flexui.agentdemo - 插件:
com.android.library+org.jetbrains.kotlin.android - 编译:
compileSdkVersion 34,minSdkVersion 21, Java 1.8
2. 架构
org.flexui.agent
├── AgentRuntime — 公共门面
├── AgentRuntimeConfig — 配置 + 公共类型
├── core/
│ ├── AgentLoop — think → tool-call → execute → repeat
│ ├── AgentTypes — 枚举、事件、类型定义
│ └── SystemPromptBuilder — 系统提示词构建（skills/memories/context）
├── llm/
│ ├── LlmClient — Ktor SSE 流式客户端
│ ├── LlmTypes — StreamCallbacks、ToolCall、ChatRequestBody
│ └── ToolCallAccumulator — SSE delta 增量工具调用累积器
├── tools/
│ ├── Tool — Tool 接口（schema + timeout + execute）
│ ├── ToolRegistry — 注册/注销/查询
│ ├── ToolExecutor — 三源路由（builtin/mcp/skill）
│ ├── BuiltinTools — activate_skill、fetch_url、web_search
│ ├── FetchUrlTool — HTTP 安全抓取（从 Kai 移植）
│ ├── WebSearchTool — DuckDuckGo 搜索（从 Kai 移植）
│ ├── MemoryTools — memory_store/forget/learn/reinforce
│ ├── EmailTools — 6 个邮件工具
│ ├── SmsTools — 5 个短信工具
│ ├── SchedulingTools — schedule_task/list_tasks/cancel_task
│ └── HeartbeatTools — promote_learning
├── mcp/
│ ├── McpClient — JSON-RPC 2.0 协议客户端
│ ├── McpTool — MCP → Tool 适配器
│ ├── McpServerManager — MCP 服务器生命周期管理
│ ├── McpConfigLoader — mcp.json 解析 + 工具/卡片注册
│ ├── McpValidator — API 列表文本构建
│ └── McpTypes — 协议类型定义
├── cards/
│ ├── CardRegistry — componentPath → FlexView 映射
│ └── CardRenderer — 工具结果 → CardRenderData 解析
├── modelcontext/
│ ├── AscfAIModule — Hippy NativeModule 桥接
│ ├── SkillDiscovery — 技能扫描（assets + filesystem）
│ ├── SkillActivator — activate_skill 处理器
│ ├── SkillApiBridge — JS↔Native 技能 API 桥接
│ ├── InstanceManager — 卡片实例生命周期
│ ├── SkillPackageInstaller — 下载→解压→安装流程
│ └── VersionManager — 语义版本解析/比较
├── data/
│ ├── DataRepository — 中央编排器
│ ├── AppSettings — SharedPreferences 封装
│ ├── Conversation + Storage — 会话模型 + JSON 持久化
│ ├── MemoryStore — 分类记忆 CRUD
│ ├── TaskScheduler/TaskStore — 定时任务调度
│ ├── HeartbeatManager — 心跳自检配置
│ ├── EmailModels/Store — 邮件模型 + 存储
│ ├── SmsModels/Store — 短信模型 + 存储
│ ├── ModelCatalog — 静态模型目录
│ └── PendingQueue — 有界 FIFO 队列
├── email/
│ ├── EmailConnection — TLS/TCP Socket 接口
│ ├── ImapClient — IMAP 协议实现
│ ├── SmtpClient — SMTP 协议实现
│ ├── EmailPoller — 邮件轮询器
│ └── ServerAutoDetect — 已知服务商配置
├── sms/
│ ├── SmsReader — ContentProvider 短信读取
│ ├── SmsSender — SmsManager 短信发送
│ └── SmsPoller — 短信轮询器
├── network/
│ ├── RemoteConfigLoader — 远程配置获取
│ └── Requests — Ktor HttpClient 工厂
├── platform/
│ ├── DaemonService — Android 前台服务
│ ├── DaemonController — 守护进程启停
│ └── HeartbeatNotifier — 心跳通知
├── ui/
│ ├── AgentChatView — 顶层 Compose 组件
│ ├── ChatViewModel — StateFlow 状态管理
│ ├── ChatScreen/ChatMessageList/ChatInputBar/MessageBubble
│ ├── Markdown (11 文件) — GFM markdown 解析/渲染
│ ├── Math (4 文件) — LaTeX 数学渲染
│ ├── FlexCardView — FlexUIView AndroidView 互操作
│ ├── ChainOfThought/ToolCallCard/TypingIndicator/Banners
│ └── markdown/ — 从 Kai 移植的 markdown 子系统
└── utils/
└── Logger — 统一 TAG="FlexUIAgent" 日志
3. 核心数据流
3.1 对话流
User Input → ChatViewModel.sendMessage()
→ AgentRuntime.run(userMessage, history, callbacks)
→ buildSystemPrompt() → SystemPromptBuilder
→ AgentLoop.run(messages, systemPrompt, tools, onEvent)
→ [loop] LlmClient.streamChat() — Ktor SSE
→ text/reasoning delta → Compose recompose
→ tool_calls → ToolExecutor.executeAll()
├── builtin → local
├── mcp__ → McpTool → SkillApiBridge
└── __ → skill stub
→ _componentPath → CardRenderer.resolve()
→ CardRenderData → FlexCardView (AndroidView + FlexUIView)
→ onComplete → ChatMessage → Compose recompose
3.2 心跳自主流
DaemonService (foreground) → TaskScheduler.poll(60s)
→ HeartbeatManager.shouldRun()
→ EmailPoller.poll() + SmsPoller.poll()
→ HeartbeatPromptBuilder.build()
→ DataRepository.ask(heartbeatPrompt) → AgentLoop
→ HeartbeatNotifier.show(result)
3.3 启动自测流
MainActivity.onCreate()
→ AgentRuntime.initialize() → tools registered
→ AgentChatView(startupMessage="帮我推荐饮品...")
→ LaunchedEffect → ChatViewModel.sendMessage(startupMessage)
→ AgentRuntime.run() → AgentLoop → LLM call
3.4 卡片回传流
Card click → sendFollowUpMessage (JS bridge)
→ AscfAIModule.handleCall("sendFollowUpMessage", ...)
→ AgentRuntime.handleFollowUpMessage(userText, apiResults)
→ onFollowUp callback → ChatViewModel.sendMessage(text, results)
→ AgentRuntime.run() with preExecutedToolResults
4. 技术决策
| 决策 | 选择 | 原因 |
|---|---|---|
| UI 框架 | Jetpack Compose | 复用 Kai 的 markdown 渲染 + 聊天 UI |
| 网络库 | Ktor Client (Android) | 复用 Kai Requests.kt |
| 异步 | Kotlin Coroutines + Flow | 流式 SSE + UI 状态 |
| JSON 解析 | org.json (Android SDK) | 无需 kotlinx.serialization 编译器插件 |
| 持久化 | SharedPreferences + File | 简单、无需 Room |
| 日志 | android.util.Log, TAG=FlexUIAgent | 统一过滤 |
| 模块结构 | 单 :agent-runtime library |
匹配 OHOS 单体 agent-runtime |
| compileSdk | 34 (从 33 升级) | Compose 传递依赖需要 |
5. 实现阶段
| 阶段 | 文件数 | 关键交付 |
|---|---|---|
| Phase 1: Foundation | 12 source + 3 test | AgentLoop、LlmClient、ToolRegistry、ToolExecutor |
| Phase 2: Skills & Cards | 16 source + 2 test | MCP 子系统、SkillDiscovery、AscfAIModule、InstanceManager |
| Phase 3: Data Layer | 8 source + 2 test | AppSettings、Conversation、MemoryStore、DataRepository |
| Phase 4: Enrichment | 4 source | FetchUrl、WebSearch、Memory tools、SystemPromptBuilder |
| Phase 5: Scheduler | 12 source + 1 test | TaskScheduler、Heartbeat、Cron、DaemonService |
| Phase 6: Email & SMS | 15 source | IMAP/SMTP 客户端、SMS 读写、Poller |
| Phase 7: Chat UI | 26 source | Markdown(11)、Math(4)、Chat composables |
| Phase 8: Integration | 1 source | SkillPackageInstaller、demo 接入 |
总计: 94 source + 8 test 文件，~18,000 行代码
6. 快速开发命令
# 一键构建+安装+启动
./build.sh dev --platform android
# 构建
./build.sh build-apk --platform android
# 查看日志
./build.sh logs --platform android
# 或
adb logcat -s FlexUIAgent