MAF框架架构设计概览
MAF框架架构设计概览
文档版本: v1.0
创建日期: 2026-03-12
设计原则: 抽象接口与实现完全分离
目标: 构建通用、可扩展、易测试的多Agent框架
📋 文档说明
本文档是MAF框架的架构设计概览，提供核心架构、设计原则和技术选型的快速了解。
详细专题文档：
- 📐 接口设计规范 - 所有接口定义
- 💻 实现指南 - 代码实现细节
- 📊 任务调度系统 - 优先级、依赖、调度
- 🎨 UI设计规范 - 前端架构设计
- 🚀 部署指南 - 部署与运维
- 📈 架构图表集 - 可视化图表
一、核心设计原则
1.1 SOLID原则
MAF框架严格遵循SOLID原则：
| 原则 | 说明 | MAF中的应用 |
|---|---|---|
| 单一职责 (SRP) | 每个类只负责一件事 | IMafAgent只负责执行任务ITaskDecomposer只负责任务分解 |
| 开闭原则 (OCP) | 对扩展开放，对修改关闭 | 新增Agent无需修改框架 新功能通过接口扩展 |
| 里氏替换 (LSP) | 子类可替换父类 | MafAgentBase可被任何Agent替换 |
| 接口隔离 (ISP) | 接口精简，按需实现 | IMafMainAgent扩展IMafAgentIMafAgentLifecycle独立生命周期 |
| 依赖倒置 (DIP) | 依赖抽象而非具体 | 实现层依赖抽象接口 高层不依赖低层 |
1.2 分层架构
┌─────────────────────────────────────┐
│ 应用层 │ 智能家居、设备控制、客服 │
├─────────────────────────────────────┤
│ 实现层 │ Agent实现、服务实现 │
├─────────────────────────────────────┤
│ 抽象层 │ 接口定义、模型定义 │
├─────────────────────────────────────┤
│ 基础设施层 │ LLM、数据库、消息队列 │
└─────────────────────────────────────┘
依赖方向: 应用层 → 实现层 → 抽象层 → 基础设施层
二、核心架构
2.1 Main-Agent + Sub-Agent 模式
graph TB
User[用户输入] --> MainAgent[MainAgent<br/>主控代理]
MainAgent --> Intent[意图识别]
MainAgent --> Decompose[任务分解]
MainAgent --> Match[Agent匹配]
MainAgent --> Orchestrate[任务编排]
MainAgent --> Aggregate[结果聚合]
MainAgent --> Sub1[LightingAgent]
MainAgent --> Sub2[ClimateAgent]
MainAgent --> Sub3[MusicAgent]
Sub1 --> Device1[智能设备]
Sub2 --> Device2[智能设备]
Sub3 --> Device3[智能设备]
style MainAgent fill:#fff4e1
style Sub1 fill:#e1f5ff
style Sub2 fill:#e1f5ff
style Sub3 fill:#e1f5ff
职责划分：
- MainAgent: 意图识别、任务分解、Agent编排、结果聚合
- SubAgent: 执行特定领域的具体任务
2.2 三层存储架构
| 层级 | 存储 | TTL | 延迟 | 用途 |
|---|---|---|---|---|
| L1 | 内存缓存 | 会话期间 | <1ms | 热数据、高频访问 |
| L2 | Redis | 1小时 | ~0.3ms | 会话数据、共享缓存 |
| L3 | PostgreSQL | 永久(30天归档) | ~10ms | 审计日志、历史数据 |
2.3 技术栈
后端技术栈
框架:
- .NET 10
- ABP Framework
LLM:
首选: 智谱AI (GLM-4/4-Plus)
备选: 通义千问、文心一言
数据库:
关系型: PostgreSQL 16
缓存: Redis 7
向量: Milvus
消息队列:
- RabbitMQ / Redis Streams
测试:
- xUnit
- Moq
- FluentAssertions
前端技术栈
框架:
首选: Blazor Server
备选: Blazor WebAssembly
UI库:
- MudBlazor (Material Design)
实时通信:
- SignalR (内置)
图表:
- Plotly.Blazor
三、核心概念
3.1 核心实体
classDiagram
class Conversation {
+string ConversationId
+string UserId
+List~MainTask~ MainTasks
+ConversationStatus Status
}
class MainTask {
+string TaskId
+string UserInput
+MainTaskStatus Status
+List~SubTask~ SubTasks
}
class SubTask {
+string SubTaskId
+string Intent
+SubTaskStatus Status
+string AgentId
}
class AgentSession {
+string SessionId
+string AgentId
+List~MessageContext~ Context
}
Conversation "1" --> "*" MainTask
MainTask "1" --> "*" SubTask
AgentSession --> SubTask
3.2 状态机
MainTask状态机
Submitted → Decomposing → Dispatching → Aggregating → Completed/Failed
SubTask状态机
Pending → Ready → Running → Completed/Failed/Timeout
↓ ↓
Cancelled InputRequired → Waiting
3.3 任务优先级
多维评分系统 (0-100分)：
- 基础优先级: 0-40分
- 用户交互: 0-30分
- 时间因素: 0-15分
- 资源利用率: 0-10分
- 依赖传播: 0-5分
优先级等级：
- Critical (50分): 安全关键、用户强制操作
- High (35-50分): 用户明确要求
- Normal (20-35分): 常规任务
- Low (10-20分): 后台任务
- Background (0-10分): 日志、统计
四、Demo场景
4.1 智能家居场景
场景1：晨间例程
用户输入: "我起床了"
↓
任务分解:
1. 打开客厅灯 (High, 45分)
2. 设置空调26度 (Normal, 25分)
3. 播放轻音乐 (Normal, 20分, 依赖任务1)
4. 打开窗帘 (Low, 10分)
↓
执行计划:
第一组(并行): 任务1
第二组(并行): 任务2, 任务3
第三组(并行): 任务4
场景2：紧急停止
用户输入: "紧急停止"
↓
关键任务 (Critical, 50分):
- 立即中断所有任务
- 独占资源
- 5秒超时
4.2 场景复杂度对比
| 场景 | Agent数 | 任务数 | 依赖关系 | 执行策略 |
|---|---|---|---|---|
| 简单控制 | 1 | 1-2 | 无 | 串行 |
| 场景模式 | 4-6 | 4-8 | 简单 | 混合 |
| 长对话 | 多个 | 10+ | 复杂 | 混合 |
五、关键技术特性
5.1 智能任务调度
- ✅ 自动依赖识别（隐式依赖检测）
- ✅ 循环依赖检测（DFS算法）
- ✅ 拓扑排序（Kahn算法）
- ✅ 并行组识别（按依赖深度）
- ✅ 资源约束优化（独占资源、任务数限制）
5.2 多轮对话支持
- ✅ 对话上下文管理（AgentSession）
- ✅ 指代消解（"它"、"那个"）
- ✅ 意图漂移处理
- ✅ 记忆管理（短期、长期、语义）
5.3 生产级特性
- ✅ 错误处理: 重试、断路器、降级
- ✅ 性能优化: 三层缓存、连接池、批量操作
- ✅ 监控告警: Prometheus指标、分布式追踪
- ✅ 安全加固: 认证授权、速率限制、数据加密
- ✅ 容器化: Docker、Kubernetes支持
六、快速开始
6.1 环境准备
# 1. 克隆仓库
git clone https://github.com/your-org/maf-framework.git
# 2. 启动基础服务
docker-compose up -d redis postgres milvus
# 3. 配置环境变量
cp appsettings.Development.json.example appsettings.Development.json
# 4. 运行应用
dotnet run --project src/MafApplication
6.5 核心接口使用示例
// 1. 创建MainAgent
var mainAgent = serviceProvider.GetRequiredService<IMafMainAgent>();
// 2. 处理用户输入
var request = new MafTaskRequest
{
TaskId = Guid.NewGuid().ToString(),
UserInput = "我起床了",
ConversationId = conversationId
};
var response = await mainAgent.ExecuteAsync(request);
// 3. 检查结果
if (response.Success)
{
Console.WriteLine($"成功: {response.Result}");
}
else
{
Console.WriteLine($"失败: {response.Error}");
}
七、文档导航
7.1 按角色阅读
| 角色 | 推荐阅读路径 |
|---|---|
| 架构师 | 本文档 → 接口设计规范 → 任务调度系统 → 架构图表集 |
| 后端开发 | 本文档 → 接口设计规范 → 实现指南 → 部署指南 |
| 前端开发 | 本文档 → UI设计规范 → 架构图表集 |
| 测试工程师 | 本文档 → 实现指南 → 测试指南 |
| 运维工程师 | 本文档 → 部署指南 → 架构图表集 |
7.2 学习路径
第1周: 理解核心架构
- 阅读本文档（架构概览）
- 查看架构图表集
第2周: 深入接口设计
- 研究接口设计规范
- 理解任务调度系统
第3周: 实践编码
- 跟随实现指南
- 运行Demo场景
第4周: 部署上线
- 参考部署指南
- 配置监控告警
八、常见问题
Q1: MAF与LangGraph、AutoGen的区别？
| 特性 | MAF | LangGraph | AutoGen |
|---|---|---|---|
| 命名空间 | MAF前缀，无冲突 | 可能冲突 | 可能冲突 |
| 语言 | C#/.NET | Python | Python/多语言 |
| 执行策略 | 弹性（自动选择） | 图状态机 | 对话式 |
| 存储架构 | 三层存储 | 单层 | 单层 |
| 多轮对话 | 完整支持 | 有限 | 有限 |
| 生产就绪 | 是 | 部分是 | 部分是 |
Q2: 如何扩展新的Agent？
// 1. 继承MafAgentBase
public class MyCustomAgent : MafAgentBase
{
public override string AgentId => "mydomain:custom:agent";
public override string Name => "我的自定义Agent";
public override IReadOnlyList<string> Capabilities =>
new List<string> { "MyDomain:Custom:Action" };
protected override async Task<ExecutionResult> ExecuteBusinessLogicAsync(
MafTaskRequest request,
CancellationToken ct)
{
// 实现业务逻辑
return new ExecutionResult { Success = true };
}
}
// 2. 注册到DI
services.AddSingleton<IMafAgent, MyCustomAgent>();
Q3: 如何处理长对话？
MAF自动管理长对话上下文：
- 短期记忆: L1内存缓存（会话期间）
- 长期记忆: L3数据库持久化
- 语义记忆: L2向量数据库检索
九、附录
9.1 术语表
| 术语 | 定义 |
|---|---|
| MAF | Multi-Agent Framework（多代理框架） |
| MainAgent | 主控Agent，负责意图识别、任务分解、Agent编排 |
| SubAgent | 子Agent，负责特定领域的具体任务 |
| Conversation | 用户与系统的完整对话上下文 |
| MainTask | 用户单次请求的完整处理过程 |
| SubTask | 委托给SubAgent的独立执行单元 |
| AgentSession | SubAgent的LLM上下文，会话期间维护 |
9.2 参考资料
文档版本: v1.0
最后更新: 2026-03-12
维护团队: MAF架构团队
浙公网安备 33010602011771号