内容
# 🧠 AI 超级智能体 — AI Agent
> 基于 **Spring AI** + **ReAct 模式** 的自主规划 AI 智能体平台，集成 RAG 知识库、MCP 协议、工具调用等核心 AI 技术。
<p align="center">
<img src="https://img.shields.io/badge/Java-21-orange?logo=openjdk" alt="Java 21">
<img src="https://img.shields.io/badge/Spring_Boot-3.4.4-brightgreen?logo=springboot" alt="Spring Boot">
<img src="https://img.shields.io/badge/Spring_AI-1.0.0-blue" alt="Spring AI">
<img src="https://img.shields.io/badge/Vue-3.x-4FC08D?logo=vue.js" alt="Vue 3">
<img src="https://img.shields.io/badge/License-MIT-yellow" alt="License">
</p>
---
## 📖 项目介绍
本项目是一套以 **AI 开发实战** 为核心的全栈项目，包含两大核心应用：
### 💕 AI 恋爱大师
基于大模型的智能情感顾问，支持多轮对话、RAG 知识库检索、工具调用和 MCP 服务集成，能够解决用户的恋爱难题、制定约会计划等。
### 🤖 Manus 超级智能体
基于 **ReAct (Reasoning + Acting)** 模式自主规划智能体，能够自主推理、调用工具（联网搜索、网页抓取、文件操作、资源下载、PDF 生成），完成用户指定的任意复杂任务。
## 🎯 核心特性
- **大模型接入**：支持 DashScope (阿里云百炼)、Ollama 本地部署、HTTP API 直接调用等多种方式
- **ReAct 智能体**：从零实现的自主规划 Agent，支持 Think → Act → Observe 循环，最大 20 步任务执行
- **RAG 知识库**：基于 PgVector / SimpleVectorStore 的向量检索，集成文档加载、关键词增强、查询重写、上下文查询增强等完整链路
- **工具调用 (Tool Calling)**：7 个内置工具（联网搜索、网页抓取、文件读写、资源下载、终端操作、PDF 生成、任务终止）
- **MCP 模型上下文协议**：支持 STDIO 和 SSE 两种传输方式，内置图片搜索 MCP 服务
- **流式对话 (SSE)**：基于 Server-Sent Events 的实时流式对话
- **对话记忆**：支持内存和基于 Kryo 序列化的文件持久化两种记忆模式
- **结构化输出**：将 AI 回复解析为结构化 JSON 对象
- **接口文档**：Knife4j + Swagger UI 自动生成 API 文档
## 🏗️ 技术栈
### 后端
| 技术 | 版本 | 说明 |
|------|------|------|
| Java | 21 | 开发语言 |
| Spring Boot | 3.4.4 | 主框架 |
| Spring AI | 1.0.0 | AI 开发框架 |
| Spring AI Alibaba | 1.0.0.2 | 阿里云百炼集成 |
| DashScope SDK | 2.19.1 | 通义千问大模型 |
| LangChain4j | 1.0.0-beta2 | 补充 AI 框架 |
| PgVector | — | PostgreSQL 向量数据库 |
| Ollama | — | 本地大模型部署 |
| MCP Client | — | 模型上下文协议客户端 |
| Knife4j | 4.4.0 | API 文档 |
| iText | 9.1.0 | PDF 生成 |
| Jsoup | 1.19.1 | HTML 解析 / 网页抓取 |
| Kryo | 5.6.2 | 高性能序列化 |
| Hutool | 5.8.37 | 通用工具库 |
### 前端
| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.x | 前端框架 (Composition API) |
| Vue Router | 4.x | 路由管理 |
| Axios | 1.x | HTTP 客户端 |
| Vite | 4.x | 构建工具 |
| EventSource | — | SSE 流式通信 |
### 基础设施
| 技术 | 说明 |
|------|------|
| PostgreSQL + PgVector | 向量数据库 |
| Docker | 容器化部署 |
| SearchAPI.io | 百度搜索引擎 API |
| Pexels API | 图片搜索服务 |
## 📐 架构设计
### 系统架构图
```mermaid
graph TB
subgraph Frontend["🖥️ 前端 (Vue 3 + Vite)"]
Home[首页]
LoveMaster[AI 恋爱大师页面]
SuperAgent[AI 超级智能体页面]
ChatRoom[共享聊天组件]
SSE_Client[SSE Client]
end
subgraph Backend["⚙️ 后端 (Spring Boot :8123)"]
AiController[AI Controller<br/>REST API]
LoveApp[LoveApp<br/>恋爱大师服务]
Manus[Manus Agent<br/>ReAct 智能体]
subgraph AgentCore["智能体核心"]
BaseAgent[BaseAgent<br/>基础 Agent 抽象类]
ReActAgent[ReActAgent<br/>思考-行动 循环]
ToolCallAgent[ToolCallAgent<br/>手动工具调度]
end
subgraph Advisors["Advisor 链"]
ChatMemory[ChatMemory<br/>对话记忆]
RAG_Advisor[RAG Advisor<br/>知识检索增强]
Logger[MyLogger<br/>日志记录]
end
subgraph Tools["🔧 工具集 (7 Tools)"]
WebSearch[联网搜索]
WebScrape[网页抓取]
FileOps[文件操作]
Download[资源下载]
Terminal[终端操作]
PDF[PDF 生成]
Terminate[任务终止]
end
RAG_Engine[RAG 引擎<br/>文档加载 → 向量化 → 检索]
end
subgraph MCP_Server["📡 MCP 服务 (:8127)"]
ImageSearch[图片搜索 MCP<br/>Pexels API]
end
subgraph External["🌐 外部服务"]
DashScope[阿里云百炼<br/>qwen-plus]
PgVector[(PgVector<br/>向量数据库)]
SearchAPI[SearchAPI.io<br/>百度搜索]
Pexels[Pexels<br/>图片搜索]
Ollama[Ollama<br/>本地模型]
end
Home --> LoveMaster
Home --> SuperAgent
LoveMaster --> ChatRoom
SuperAgent --> ChatRoom
ChatRoom --> SSE_Client
SSE_Client -->|"SSE Stream"| AiController
AiController -->|"聊天"| LoveApp
AiController -->|"智能体"| Manus
LoveApp --> Advisors
LoveApp --> Tools
LoveApp --> RAG_Engine
LoveApp --> MCP_Server
Manus --> AgentCore
AgentCore --> Tools
LoveApp --> DashScope
Manus --> DashScope
RAG_Engine --> PgVector
Tools --> SearchAPI
Tools --> Pexels
LoveApp --> Ollama
MCP_Server --> Pexels
style Frontend fill:#42b883,color:#fff
style Backend fill:#6db33f,color:#fff
style AgentCore fill:#ff9800,color:#fff
style Tools fill:#9c27b0,color:#fff
style MCP_Server fill:#00bcd4,color:#fff
style External fill:#607d8b,color:#fff
```
### Agent 执行流程
```mermaid
sequenceDiagram
participant User as 👤 用户
participant Ctrl as AiController
participant Agent as Manus
participant LLM as 🤖 大模型
participant Tools as 🔧 工具
User->>Ctrl: 发送任务
Ctrl->>Agent: 创建 Agent 实例
activate Agent
loop ReAct 循环 (最多20步)
Agent->>LLM: think() — 发送消息历史 + 工具列表
LLM-->>Agent: 返回 ToolCall 列表
alt 有工具调用
Agent->>Tools: act() — 执行工具
Tools-->>Agent: 工具执行结果
Agent->>LLM: 将结果反馈给 LLM
LLM-->>Agent: 继续推理 / 调用更多工具
else 无工具调用 (Terminate)
Agent->>Agent: 设置状态 = FINISHED
end
end
deactivate Agent
Agent-->>Ctrl: SSE 流式返回结果
Ctrl-->>User: 展示最终结果
```
### 项目目录结构
```
ai-agent/
├── src/main/java/com/pi/aiagent/
│ ├── AiAgentApplication.java # 应用入口
│ ├── controller/
│ │ ├── AiController.java # AI 核心接口
│ │ ├── HealthController.java # 健康检查
│ │ └── TestController.java # API Key 测试
│ ├── agent/ # 🧠 Agent 智能体
│ │ ├── BaseAgent.java # 基类：状态管理、消息上下文、执行循环
│ │ ├── ReActAgent.java # ReAct 模式：think() + act()
│ │ ├── ToolCallAgent.java # 工具调度：手动管理工具调用
│ │ └── Manus.java # 终极智能体实现
│ ├── app/
│ │ └── LoveApp.java # 💕 AI 恋爱大师 (Advisor 链)
│ ├── advisor/
│ │ ├── MyLoggerAdvisor.java # 请求/响应日志拦截器
│ │ └── ReReadingAdvisor.java # Re2 重读增强
│ ├── chatmemory/
│ │ └── FileBasedChatMemory.java # Kryo 文件持久化记忆
│ ├── config/
│ │ └── CorsConfig.java # 跨域配置
│ ├── rag/ # 📚 RAG 知识库
│ │ ├── LoveAppDocumentLoader.java # 文档加载
│ │ ├── LoveAppVectorStoreConfig.java # 向量存储配置
│ │ ├── LoveAppRagCustomAdvisorFactory.java # 自定义 RAG Advisor
│ │ ├── LoveAppContextualQueryAugmenterFactory.java # 上下文增强
│ │ ├── LoveAppRagCloudAdvisorConfig.java # 云知识库配置
│ │ ├── PgVectorVectorStoreConfig.java # PGVector 配置
│ │ ├── MyKeywordEnricher.java # 关键词增强
│ │ ├── MyTokenTextSplitter.java # 文档分割
│ │ └── QueryRewriter.java # 查询重写
│ ├── tools/ # 🔧 工具集
│ │ ├── ToolRegistration.java # 工具注册中心
│ │ ├── WebSearchTool.java # 联网搜索
│ │ ├── WebScrapingTool.java # 网页抓取
│ │ ├── FileOperationTool.java # 文件操作
│ │ ├── ResourceDownloadTool.java # 资源下载
│ │ ├── TerminalOperationTool.java # 终端操作
│ │ ├── PDFGenerationTool.java # PDF 生成
│ │ └── TerminateTool.java # 任务终止
│ ├── demo/ # 📖 示例代码
│ │ ├── invoke/ # 4 种大模型接入方式
│ │ └── rag/ # RAG 高级特性 Demo
│ └── constant/
│ └── FileConstant.java # 文件路径常量
├── src/main/resources/
│ ├── application.yml # 主配置（已脱敏）
│ ├── application-prod.yml # 生产配置
│ ├── application-local.yml.example # 本地配置模板
│ ├── document/ # RAG 知识库文档
│ │ ├── 恋爱常见问题和回答 - 单身篇.md
│ │ ├── 恋爱常见问题和回答 - 恋爱篇.md
│ │ └── 恋爱常见问题和回答 - 已婚篇.md
│ └── mcp-servers.json # MCP 服务配置
├── ai-agent-frontend/ # 🎨 Vue 3 前端
│ ├── src/
│ │ ├── views/
│ │ │ ├── Home.vue # 首页
│ │ │ ├── LoveMaster.vue # 恋爱大师界面
│ │ │ └── SuperAgent.vue # 超级智能体界面
│ │ ├── components/
│ │ │ ├── ChatRoom.vue # 核心聊天组件
│ │ │ ├── AiAvatarFallback.vue # AI 头像
│ │ │ └── AppFooter.vue # 页脚
│ │ ├── api/index.js # API & SSE 封装
│ │ └── router/index.js # 路由配置
│ ├── Dockerfile # 前端 Docker 构建
│ ├── nginx.conf # Nginx 配置
│ └── package.json
├── image-search-mcp-server/ # 📡 图片搜索 MCP 服务
│ ├── src/main/java/.../
│ │ ├── ImageSearchMcpServerApplication.java
│ │ └── tools/ImageSearchTool.java # Pexels 图片搜索
│ └── src/main/resources/
│ ├── application-sse.yml # SSE 模式配置
│ └── application-stdio.yml # STDIO 模式配置
├── Dockerfile # 后端 Docker 构建
├── pom.xml # Maven 依赖管理
└── README.md
```
## 🚀 快速开始
### 环境要求
- **JDK 21+**
- **Maven 3.9+**
- **Node.js 18+** (前端开发)
- **PostgreSQL + PgVector 插件** (向量检索，可选)
- **Ollama** (本地模型部署，可选)
### 1. 克隆项目
```bash
git clone https://github.com/SXX176/ai-agent-master.git
cd ai-agent-master
```
### 2. 配置 API Key
```bash
# 复制配置模板
cp src/main/resources/application-local.yml.example src/main/resources/application-local.yml
```
编辑 `src/main/resources/application-local.yml`，填入你的配置：
```yaml
spring:
datasource:
url: jdbc:postgresql://<your-host>:5432/<your-db>
username: <your-username>
password: <your-password>
ai:
dashscope:
api-key: <your-dashscope-api-key>
search-api:
api-key: <your-searchapi-key>
```
> ⚠️ **注意**：`application-local.yml` 已在 `.gitignore` 中，不会被提交到 Git。
**API Key 获取地址：**
- 阿里云百炼 DashScope：[https://dashscope.console.aliyun.com/apiKey](https://dashscope.console.aliyun.com/apiKey)
- SearchAPI：[https://www.searchapi.io/](https://www.searchapi.io/)
### 3. 启动后端
```bash
# 使用 Maven Wrapper（无需安装 Maven）
./mvnw spring-boot:run
# 或使用系统 Maven
mvn spring-boot:run
```
后端启动后访问：
- API 服务：http://localhost:8123/api
- Swagger 文档：http://localhost:8123/api/swagger-ui.html
- 健康检查：http://localhost:8123/api/health
### 4. 启动前端（开发模式）
```bash
cd ai-agent-frontend
npm install
npm run dev
```
访问：http://localhost:3000
### 5. 启动图片搜索 MCP 服务（可选）
```bash
cd image-search-mcp-server
../mvnw spring-boot:run -f pom.xml
```
MCP 服务启动在 http://localhost:8127
## 🐳 Docker 部署
### 后端部署
```bash
# 构建镜像
docker build -t ai-agent .
# 运行容器
docker run -d \
-p 8123:8123 \
-v /path/to/application-local.yml:/app/src/main/resources/application-local.yml \
--name ai-agent \
ai-agent
```
### 前端部署
```bash
cd ai-agent-frontend
# 构建静态文件
npm run build
# 使用 Nginx 部署 dist/ 目录
# 参考 ai-agent-frontend/nginx.conf
```
### 使用 Docker Compose（推荐）
创建 `docker-compose.yml`：
```yaml
version: '3.8'
services:
backend:
build: .
ports:
- "8123:8123"
volumes:
- ./src/main/resources/application-local.yml:/app/src/main/resources/application-local.yml
environment:
- SPRING_PROFILES_ACTIVE=local
frontend:
build: ./ai-agent-frontend
ports:
- "80:80"
depends_on:
- backend
postgres:
image: pgvector/pgvector:pg16
environment:
POSTGRES_DB: ai_agent
POSTGRES_USER: my_user
POSTGRES_PASSWORD: my_password
ports:
- "5432:5432"
volumes:
- pgdata:/var/lib/postgresql/data
mcp-server:
build: ./image-search-mcp-server
ports:
- "8127:8127"
volumes:
pgdata:
```
## 🔌 API 接口
### 核心接口
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/ai/love_app/chat/sse` | AI 恋爱大师 — SSE 流式对话 |
| GET | `/api/ai/love_app/chat/sync` | AI 恋爱大师 — 同步对话 |
| GET | `/api/ai/manus/chat` | Manus 智能体 — SSE 流式对话 |
| GET | `/api/health` | 健康检查 |
| GET | `/api/test/api-key` | 测试 API Key 有效性 |
### 使用示例
```bash
# 与 AI 恋爱大师对话（SSE 流式）
curl -N "http://localhost:8123/api/ai/love_app/chat/sse?message=你好&chatId=my_session"
# 调用 Manus 智能体
curl -N "http://localhost:8123/api/ai/manus/chat?message=帮我搜索上海约会地点并生成PDF"
```
## 🧪 内置工具一览
| 工具 | 类名 | 功能 |
|------|------|------|
| 🌐 联网搜索 | `WebSearchTool` | 通过 SearchAPI 调用百度搜索，返回 Top 5 结果 |
| 📄 网页抓取 | `WebScrapingTool` | 使用 Jsoup 抓取网页完整 HTML |
| 📁 文件操作 | `FileOperationTool` | 读写本地文件 |
| ⬇️ 资源下载 | `ResourceDownloadTool` | 从 URL 下载文件到本地 |
| 💻 终端操作 | `TerminalOperationTool` | 执行系统命令并返回输出 |
| 📝 PDF 生成 | `PDFGenerationTool` | 使用 iText 生成含中文内容的 PDF |
| 🛑 任务终止 | `TerminateTool` | 标记 Agent 任务完成 |
## 🔗 MCP 服务
项目实现了 **Model Context Protocol (MCP)** 的完整支持：
### 内置 MCP 服务：图片搜索
- **功能**：通过 Pexels API 搜索图片
- **传输方式**：支持 STDIO 和 SSE 两种模式
- **独立部署**：可作为独立 MCP 服务运行在 8127 端口
### MCP 配置 (`mcp-servers.json`)
```json
{
"mcpServers": {
"amap-maps": {
"command": "npx",
"args": ["-y", "@amap/amap-maps-mcp-server"]
},
"image-search-mcp-server": {
"command": "java",
"args": ["-jar", "image-search-mcp-server/target/image-search-mcp-server-0.0.1-SNAPSHOT.jar"]
}
}
}
```
## 📚 RAG 知识库
知识库文档位于 `src/main/resources/document/`，包含三篇恋爱话题的中文知识文档：
- 单身篇：如何认识异性、搭讪技巧等
- 恋爱篇：约会建议、矛盾解决等
- 已婚篇：婚姻经营、家庭关系等
### RAG 全链路特性
```mermaid
graph LR
A[📄 Markdown 文档] -->|MarkdownDocumentReader| B[📝 文档加载]
B -->|TokenTextSplitter| C[✂️ 文档切割]
C -->|KeywordMetadataEnricher| D[🏷️ 关键词增强]
D -->|Embedding Model| E[🔢 向量化]
E -->|PgVector / Simple| F[💾 向量存储]
G[❓ 用户问题] -->|QueryRewriter| H[🔍 查询重写]
H --> F
F -->|相似度检索| I[📋 检索结果]
I -->|ContextualQueryAugmenter| J[✨ 上下文增强]
J --> K[🤖 LLM 生成回答]
style A fill:#4caf50,color:#fff
style K fill:#ff9800,color:#fff
```
## 🏛️ 设计模式
### ReAct Agent 模式
智能体遵循 **Reasoning + Acting** 循环：
1. **Think（思考）**：分析当前任务状态，决定是否需要调用工具
2. **Act（行动）**：执行 LLM 选择的工具调用
3. **Observe（观察）**：将工具执行结果反馈给 LLM
4. 循环直到任务完成或达到最大步数限制
### Advisor 链模式
AI 恋爱大师使用 Spring AI 的 Advisor 链实现横切关注点：
- `MessageChatMemoryAdvisor` → 对话记忆
- `QuestionAnswerAdvisor` → RAG 知识检索
- `MyLoggerAdvisor` → 日志拦截
### 策略模式
支持多种向量存储后端（Simple / PgVector / Alibaba Cloud），通过配置切换。
## 🛠️ 开发指南
### 项目构建
```bash
# 编译打包
./mvnw clean package -DskipTests
# 运行测试
./mvnw test
```
### 本地大模型部署 (Ollama)
```bash
# 安装 Ollama 后拉取模型
ollama pull gemma3:1b
# 配置 application-local.yml
# spring.ai.ollama.base-url: http://localhost:11434
# spring.ai.ollama.chat.model: gemma3:1b
```
### 切换大模型接入方式
项目支持 4 种大模型接入方式（见 `src/main/java/com/pi/aiagent/demo/invoke/`）：
1. **HTTP 直接调用** — `HttpAiInvoke.java`
2. **SDK 调用** — `SdkAiInvoke.java`
3. **Spring AI 调用** — `SpringAiAiInvoke.java`
4. **LangChain4j 调用** — `LangChainAiInvoke.java`
## 📄 License
MIT License. 详见 [LICENSE](./LICENSE) 文件。
---
## 🙏 致谢
- [Spring AI](https://spring.io/projects/spring-ai) — Java AI 开发框架
- [LangChain4j](https://docs.langchain4j.dev/) — Java LangChain 实现
- [阿里云百炼](https://bailian.console.aliyun.com/) — 大模型服务平台
- [OpenManus](https://github.com/mannaandpoem/OpenManus) — ReAct Agent 参考实现
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器