第一章：架构概览

01 - 架构概览

一、整体分层

Dodo-Agent 采用经典的分层架构，从上到下依次为：

┌────────────────────────────────────────────────────────────────────────────┐
│                          应用层 (Application Layer)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────────────┐  │
│  │ 智能问答 Agent │ │ 文件问答 Agent │ │ PPT 生成 Agent│ │    深度研究 Agent   │  │
│  │ WebSearch   │  │  File RAG   │  │  PPT Builder│  │  Plan-Execute     │  │
│  │   ReAct     │  │   ReAct     │  │  StateMachine│  │  Multi-Round      │  │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └─────────┬─────────┘  │
│         └─────────────────┴─────────────────┴─────────────────┘            │
│                                    │                                       │
│                              BaseAgent (抽象基类)                          │
│                    ┌───────────────┼───────────────┐                       │
│                    │   ChatMemory  │  TaskManager  │   SessionService      │
│                    └───────────────┴───────────────┘                       │
├────────────────────────────────────────────────────────────────────────────┤
│                            服务层 (Service Layer)                           │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐  │
│  │ Embedding服务 │ │ 文件管理服务 │ │ 会话管理服务 │ │   PPT 渲染服务    │  │
│  │  (RAG核心)   │ │ (Minio+解析) │ │ (MySQL持久化)│ │ (Python+PptxGenJS)│ │
│  └──────────────┘ └──────────────┘ └──────────────┘ └──────────────────┘  │
├────────────────────────────────────────────────────────────────────────────┤
│                              工具层 (Tool Layer)                            │
│  ┌─────────────────┐  ┌─────────────────┐  ┌───────────────────────────┐   │
│  │  MCP 工具回调    │  │  文件内容检索     │  │    图片生成服务            │   │
│  │ (Tavily 搜索)   │  │ (Vector Search) │  │  (AI Image Generation)    │   │
│  └─────────────────┘  └─────────────────┘  └───────────────────────────┘   │
├────────────────────────────────────────────────────────────────────────────┤
│                          基础设施层 (Infrastructure)                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────────┐  ┌──────────┐  ┌──────────┐  │
│  │  大模型   │  │ PgVector │  │    MySQL    │  │  Minio   │  │  Tavily  │  │
│  │OpenAI/   │  │ 向量数据库 │  │  关系数据库   │  │ 对象存储  │  │ 搜索引擎  │  │
│  │通义千问   │  │          │  │              │  │          │  │          │  │
│  └──────────┘  └──────────┘  └──────────────┘  └──────────┘  └──────────┘  │
└────────────────────────────────────────────────────────────────────────────┘

二、技术栈

2.1 核心技术框架

层级	技术选型	版本 / 说明
基础框架	Spring Boot + Spring AI	3.2.x / 1.x
响应式编程	Project Reactor	3.6.x
大模型接入	OpenAI API / 通义千问	Compatible Mode
向量嵌入	Spring AI Embedding	text-embedding-v4（1024 维）
工具协议	Model Context Protocol (MCP)	1.0
Agent 框架	spring-ai-alibaba-agent-framework	1.1.0.0
ORM	MyBatis-Plus	3.5.5

2.2 数据存储

类型	技术	用途
关系数据库	MySQL 8.0	会话历史、文件元数据、PPT 实例
向量数据库	PostgreSQL + pgvector	文档向量存储与检索
对象存储	MinIO	原始文件、生成 PPT、图片素材
缓存/Pub-Sub	Redis + Redisson	会话记忆、任务注册、跨实例广播

2.3 关键依赖

组件	用途
spring-ai-starter-model-openai	接入 OpenAI 兼容的大模型
spring-ai-starter-mcp-client	MCP 协议客户端（用于 Tavily 搜索）
spring-ai-starter-vector-store-pgvector	PgVector 向量库
spring-ai-alibaba-agent-framework	Agent 编排框架
redisson-spring-boot-starter	Redis 高级客户端
pdfbox / poi-ooxml	PDF / Word 文档解析
jsoup	HTML 解析
playwright	浏览器自动化
fastjson2	JSON 处理

三、核心智能体矩阵

Agent 类型	核心模式	工具	适用场景	入口
WebSearchReactAgent	ReAct	Tavily MCP	实时信息查询、新闻分析	/agent/chat/stream
FileReactAgent	RAG + ReAct	loadContent 工具	企业内部文档问答	/agent/file/stream
PPTBuilderAgent	状态机	搜索 + 渲染	智能演示文稿生成	/agent/pptx/stream
PlanExecuteAgent	Plan-Execute-Critique	搜索 + RAG	深度研究、复杂任务	/agent/deep/stream
SkillsReactAgent	Skills + ReAct	搜索 + 文件 + Skills + Bash	通用型智能体	/agent/skills/stream

四、统一流式响应协议（SSE）

所有智能体的流式输出都使用统一的 SSE 协议，事件类型如下：

type	含义	字段	示例
thinking	思考过程	content	{"type":"thinking","content":"正在分析问题..."}
text	最终回答片段	content	{"type":"text","content":"这是回答内容"}
reference	参考链接	content（JSON 数组）、count	{"type":"reference","content":"[{\"title\":\"来源1\"}]","count":1}
recommend	推荐问题	content（JSON 数组）、count	{"type":"recommend","content":"[\"问题1\"]","count":1}
error	错误信息	content	{"type":"error","content":"..."}

AgentResponse 类是上述 JSON 的构造工厂（common/AgentResponse.java），提供了 text/thinking/reference/recommend/error/json 一系列工厂方法。

五、关键设计模式

5.1 模板方法模式（Template Method）

BaseAgent 定义了所有智能体的执行骨架：

• 加载历史记忆 → 注入系统提示词 → 保存用户问题 → 多轮 ReAct 循环 → 保存会话结果
• 各子类只需实现具体的 execute() 流式输出逻辑

5.2 策略模式（Strategy）

PPTBuilderAgent 采用状态机 + 策略模式：

• PptStateStrategy 接口
• 每个状态对应一个具体策略类（RequirementStrategy / TemplateStrategy / OutlineStrategy / SchemaStrategy / RenderStrategy / SuccessStrategy / FailedStrategy 等）
• PptStateStrategyFactory 单例管理所有策略
• PptStateStrategyContext 跨策略共享依赖

5.3 工厂模式（Factory）

• ToolCallbacks.from() 将 POJO 转为 Spring AI 的 ToolCallback[]
• DynamicPgVectorStoreFactory 动态创建 PgVectorStore

5.4 建造者模式（Builder）

几乎所有 Agent 都提供 Builder：

• WebSearchReactAgent.builder()...build()
• FileReactAgent.builder()...build()
• PlanExecuteAgent.builder()...build()

5.5 中介者模式（Mediator）

AgentTaskManager 是所有 Agent 的中介者：

• 统一的任务注册、停止、TTL 刷新
• 通过 Redis Pub/Sub 实现跨实例协调

六、与外部系统的集成

┌────────────┐    HTTP/SSE     ┌────────────┐    JSON     ┌──────────────┐
│  前端 / 客户端 │ ──────────────→ │  Dodo-Agent │ ──────────→ │ LLM (通义千问) │
└────────────┘                  │  Spring Boot │             └──────────────┘
                                │             │
                                │             │ ──JDBC───→  MySQL
                                │             │
                                │             │ ──HTTP───→  Tavily MCP
                                │             │
                                │             │ ──MinIO──→  对象存储
                                │             │
                                │             │ ──PgVec──→  向量库
                                │             │
                                │             │ ──Redis──→  Redisson
                                │             │
                                │             │ ──HTTP───→  grsai (图片生成)
                                │             │
                                │             │ ──Python──→  PPT 渲染服务
                                └────────────┘

七、可观测性

• 结构化日志：所有 Agent 使用 SLF4J 记录执行过程
• 首字延迟：通过 firstResponseTime 字段记录
• 总响应时长：通过 totalResponseTime 字段记录
• 工具调用统计：usedTools 字段保存本次会话使用的工具列表
• 执行链可追溯：通过 ai_session 表的 question / answer / thinking / tools 字段

八、扩展性

• 新增 Agent：继承 BaseAgent 并实现 execute() 即可
• 新增工具：使用 @Tool 注解标注方法，或继承 MCP 协议
• 新增策略：实现 PptStateStrategy 并在 PptStateStrategyFactory 中注册
• 多模型切换：通过 application.yml 修改 spring.ai.openai.base-url / api-key
• 技能扩展：在 skills.directory 目录下添加 SKILL.md 文件即可被自动加载

九、安全与权限

• 路径安全：FileSystemTools 阻止目录穿越（.. 校验）
• 文件大小限制：默认 10MB，避免 OOM
• 会话级并发控制：基于 conversationId 防止重复请求
• TTL 机制：任务在 Redis 中默认 30 分钟过期
• 任务停止：通过 Disposable.dispose() 中断底层 Reactor 流