推荐订阅源

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扩展IMafAgent IMafAgentLifecycle独立生命周期
依赖倒置 (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架构团队