本地优先架构技术文档
本篇解析 AGI 的本地优先（local-first）架构：模型如何通过 llama.cpp 在设备端运行，Flutter 与 Kotlin 如何分工，消息、模型、控制台与技能四大模块如何组织与协同，以及异常与降级机制。
01架构总览
AGI 采用本地优先的分层架构，核心原则是「模型与数据在设备端，界面与操控在本地」。
技术栈分工
- llama.cpp负责在设备端加载与推理大语言模型，提供高性能本地推理能力。
- Flutter负责跨平台界面，提供本机会话、Web 控制台前端与一致的用户体验。
- Kotlin负责系统能力层，对接设备原生系统，实现深度操控与技能执行。
| 架构层 | 职责 | 主要技术 |
|---|---|---|
| 交互层 | 本机会话、Web 控制台、语音交互 | Flutter |
| 智能体层 | 消息路由、技能调用、对话编排 | Flutter / Kotlin |
| 推理层 | 本地模型加载与推理 | llama.cpp |
| 系统能力层 | 设备深度操控、技能后端 | Kotlin |
02核心设计原则
设计原则
- ①本地优先：模型推理与数据存储默认在设备端，不强制依赖云端。
- ②数据自持：对话、配置与凭据等数据由用户掌控，见数据自持机制。
- ③模块解耦：消息渠道、模型、控制台、技能四大模块职责清晰、可独立管理。
- ④最小权限：技能与渠道仅授予完成任务所需的最小权限。
03关键流程与数据流
一次完整的对话交互涉及多个模块协同，数据流如下。
- 消息到达消息从渠道进入交互层，由智能体层的路由模块解析。
- 意图与技能识别智能体分析消息，判断是否需要调用技能，以及调用哪个模型。
- 模型推理推理层通过 llama.cpp 在设备端加载模型并生成响应。
- 技能执行如需操控设备，由系统能力层（Kotlin）执行受控操作，结果回传智能体。
- 响应返回智能体将结果组织为响应，经渠道返回用户。
04异常与降级机制
本地运行难免遇到资源受限或异常，AGI 提供降级与容错机制保障可用。
降级策略
- ①模型降级：资源不足时自动切换到更轻量的模型，见多模型路由。
- ②上下文裁减：超长对话时自动裁剪历史，控制上下文长度。
- ③技能降级：技能不可用时返回明确提示，不阻塞对话。
- ④日志与恢复：异常写入日志，支持通过 Web 控制台排查与恢复。
📌 关联阅读
多模型的选择与切换策略详见多模型路由技术文档；数据如何做到本地自持见数据自持机制技术文档。