# AI-Super-Agent

**Repository Path**: git_mystore/ai-super-agent

## Basic Information

- **Project Name**: AI-Super-Agent
- **Description**: AI超级智能体项目
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-11
- **Last Updated**: 2026-05-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI Super Agent

## 项目简介

这是一个已经完成开发的 AI 智能体项目，采用前后端分离架构，包含两个面向用户的核心场景：

- `AI 恋爱大师`：面向情感咨询、恋爱沟通、关系分析等场景，支持会话记忆、流式回复、敏感词拦截，以及基于阿里云百炼知识库的 RAG 问答。
- `AI 超级智能体`：面向通用任务处理场景，基于自定义 ReAct Agent + Tool Calling 机制，可调用本地工具、数据库工具和 MCP 服务完成多步骤任务。

项目后端使用 `Spring Boot 3 + Spring AI + DashScope + MyBatis-Plus`，前端使用 `Vue 3 + Vite`，同时额外包含一个独立的 `image-search-mcp-server` 子服务，用于为智能体提供图片搜索能力。

这个仓库更适合作为以下几类项目的参考实现：

- Spring AI 智能体项目实战模板
- 带流式 SSE 对话界面的 AI Web 应用
- 集成 RAG、工具调用、MCP、数据库操作、PDF 生成、邮件发送的综合示例
- Java 技术栈下的 Agent 系统学习项目

---

## 运行截图

![](run_images/首页.png)

![](run_images/AI恋爱大师.png)

![](run_images/AI超级智能体.png)

## 功能概览

### 1. AI 恋爱大师

- 前端为独立聊天页面，进入页面自动生成 `chatId`
- 后端基于 `LoveApp` 提供恋爱咨询问答能力
- 支持 `SSE` 流式输出
- 支持会话记忆，连续对话时可带上下文
- 支持敏感词检测与拦截
- 当前对外接口使用阿里云百炼知识库进行云端 RAG 检索
- 代码中同时保留了本地 Markdown 向量库方案，便于后续切换或扩展

### 2. AI 超级智能体

- 前端将“思考过程”和“最终回答”分开展示
- 后端基于自定义 `SuperAgent -> ToolCallBackAgent -> ReActAgent -> BaseAgent` 体系执行
- 支持多轮“思考 -> 调用工具 -> 继续思考 -> 输出最终答案”
- 支持显式终止工具 `doTerminate`
- 支持本地工具与 MCP 工具统一注册
- 当前页面更偏向单轮复杂任务处理，不依赖前端传入 `chatId`

### 3. 已集成工具能力

- 文件读写
- 联网搜索
- 网页正文抓取
- 终端命令执行
- 资源下载
- 当前时间获取
- 数据库用户信息查询与更新
- PDF 生成并上传阿里云 OSS
- QQ 邮箱发送文本/HTML 邮件
- MCP 地图服务
- MCP 图片搜索服务

---

## 技术栈

### 后端

- Java 21
- Spring Boot 3.5.8
- Spring AI 1.1.2
- Spring AI Alibaba 1.1.2.2
- DashScope / 通义千问
- Ollama
- MyBatis-Plus
- MySQL
- Hutool
- Jsoup
- iText PDF
- Jakarta Mail
- 阿里云 OSS SDK
- Spring AI MCP Client

### 前端

- Vue 3
- Vue Router 4
- Vite 8
- Axios

### 附属服务

- 独立 MCP Server：`backend/image-search-mcp-server`
- AMap 地图 MCP 服务
- Pexels 图片搜索 API

---

## 系统架构

```mermaid
flowchart LR
    A[Vue 3 Frontend] --> B[Spring Boot Backend]
    B --> C[DashScope Chat Model]
    B --> D[阿里云百炼知识库 RAG]
    B --> E[MySQL]
    B --> F[阿里云 OSS]
    B --> G[本地工具集]
    B --> H[MCP Client]
    H --> I[AMap MCP Server]
    H --> J[Image Search MCP Server]
```

### 前后端职责划分

#### 前端

- 提供首页、恋爱大师页、超级智能体页
- 封装统一聊天工作台 `ChatWorkspace`
- 通过 `EventSource` 接收 SSE 实时输出
- 对超级智能体场景额外做“思考过程 / 最终回答”分段展示
- 负责页面视觉呈现、状态反馈、会话切换、输入交互

#### 后端

- 提供聊天接口和 SSE 接口
- 管理模型调用、对话记忆、敏感词拦截、RAG 检索增强
- 实现 Agent 执行框架与工具调用流程
- 接入数据库、对象存储、邮件、搜索、抓取、MCP 服务等能力

---

## 目录结构

```text
super_agent_project
├─ backend                         # Spring Boot 主后端
│  ├─ src/main/java/com/lk/super_agent
│  │  ├─ agent                     # 自定义 Agent 框架
│  │  ├─ advisor                   # 自定义 Advisor（敏感词、请求增强等）
│  │  ├─ app                       # 业务应用层，如 LoveApp
│  │  ├─ config                    # 全局配置，如 CORS
│  │  ├─ controller                # 对外接口
│  │  ├─ mapper                    # MyBatis-Plus Mapper
│  │  ├─ model                     # 实体与返回对象
│  │  ├─ properties                # 配置属性类
│  │  ├─ rag                       # RAG、向量库、检索增强相关
│  │  ├─ service                   # 服务层
│  │  └─ tools                     # Spring AI 工具实现
│  ├─ src/main/resources
│  │  ├─ application*.yml          # 环境配置
│  │  ├─ document                  # 恋爱领域 Markdown 知识文档
│  │  ├─ mapper                    # MyBatis XML
│  │  ├─ prompts                   # 系统提示词模板
│  │  ├─ security                  # 敏感词词库
│  │  └─ mcp-servers.json          # MCP 客户端配置
│  └─ image-search-mcp-server      # 独立图片搜索 MCP 子服务
├─ frontend                        # Vue 3 前端
│  ├─ src/components               # 通用组件，核心为 ChatWorkspace
│  ├─ src/views                    # 首页 / 恋爱大师 / 超级智能体页面
│  ├─ src/router                   # 前端路由
│  ├─ src/utils                    # API 与 chatId 工具
│  ├─ Dockerfile                   # 前端镜像构建
│  └─ nginx.conf                   # 生产环境反向代理配置
├─ README.md
├─ README.en.md
└─ AI超级智能体项目-笔记.md          # 项目过程笔记/学习记录
```

---

## 核心模块说明

### 1. LoveApp：面向业务场景的 AI 应用封装

`LoveApp` 是恋爱大师场景的核心入口，主要整合了：

- `DashScopeChatModel`
- 会话记忆 `MessageWindowChatMemory`
- `CustomAdvisor`
- `SensitiveWordAdvisor`
- 阿里云百炼云知识库 Advisor
- 可选本地向量库检索能力
- 工具调用能力
- MCP 能力

从代码实现看，当前前台实际使用的是下面两个能力：

- 同步问答：`/syncCall/loveApp`
- 流式问答：`/streamWay1/loveApp`、`/streamWay2/loveApp`

其中前端默认接的是 `streamWay2`。

### 2. 自定义 Agent 框架

项目的超级智能体不是直接使用一个“黑盒 Agent”，而是自己实现了一套可理解的轻量 Agent 执行框架：

- `BaseAgent`
  - 定义智能体运行状态、消息列表、步骤数、系统提示词、最终结果等基础能力
  - 使用 `SseEmitter` 异步向前端持续推送内容
- `ReActAgent`
  - 定义 `think()` 与 `action()` 的执行范式
  - 每一步先判断要不要行动，再决定是否调用工具
- `ToolCallBackAgent`
  - 对接 Spring AI `ToolCallback`
  - 统一本地工具与 MCP 工具
  - 手动维护工具调用上下文
  - 在调用 `doTerminate` 后，再补一次最终回答生成
- `SuperAgent`
  - 具体落地的智能体实现
  - 设定系统提示词、步骤提示词、最大步数、聊天客户端

### 3. Advisor 体系

项目中有两个比较关键的自定义 Advisor：

- `CustomAdvisor`
  - 在模型调用前重写/增强用户问题
  - 在流式响应完成后汇总完整回答日志
- `SensitiveWordAdvisor`
  - 对用户输入做敏感词检测
  - 一旦命中，直接返回固定拦截消息，不再继续下游调用

### 4. RAG 体系

项目中实际上保留了两套 RAG 思路：

#### 云端 RAG

- 使用 `DashScopeDocumentRetrievalAdvisor`
- 读取阿里云百炼知识库
- 当前对外接口实际走的是这一套
- 代码中配置的知识库名称为：`恋爱大师`

#### 本地向量库 RAG

- 读取 `backend/src/main/resources/document/*.md`
- 通过 `MarkdownDocumentReader` 切分文档
- 使用 DashScope Embedding 写入 `SimpleVectorStore`
- 保留了本地向量检索增强能力，便于后续本地化部署

### 5. MCP 体系

后端在 `application-local.yaml` 中开启了 Spring AI MCP Client，并通过 `mcp-servers.json` 注册了两个 MCP 服务：

- `amap-maps`
- `image-search-mcp-server`

其中图片搜索服务是仓库内置的独立子项目，支持返回网络图片地址列表。

---

## 前端页面说明

### 首页 `/`

- 展示项目简介
- 提供两个应用入口
- 说明使用流程
- 展示联系方式与站点说明

### 恋爱大师页 `/love`

- 基于统一聊天工作台组件
- 页面进入时自动生成一个新的 `chatId`
- 所有请求自动带 `chatId`
- 使用 SSE 实时显示 AI 输出
- 用户消息与 AI 回复左右分栏展示

### 超级智能体页 `/agent`

- 同样基于统一聊天工作台组件
- 接入 `superAgent` SSE 接口
- 可单独展示“思考中”内容
- 在智能体完成任务后自动折叠思考过程，单独展示最终答案
- 当前页面提示中明确说明：不支持对话记忆，适合一次性完整描述任务

---

## 后端接口说明

后端默认端口为 `8123`，上下文路径为 `/api`。

完整访问前缀：

```text
http://localhost:8123/api
```

### 对外接口

| 接口 | 方法 | 说明 |
|---|---|---|
| `/syncCall/loveApp` | GET | 恋爱大师同步调用 |
| `/streamWay1/loveApp` | GET | 恋爱大师流式调用，返回 `text/event-stream` |
| `/streamWay2/loveApp` | GET | 恋爱大师流式调用，使用 `SseEmitter` |
| `/stream/superAgent` | GET | 超级智能体流式调用 |

### 请求参数

#### 恋爱大师

- `message`：用户输入内容
- `chatId`：会话 ID

示例：

```text
GET /api/streamWay2/loveApp?message=她最近总是回复很慢怎么办&chatId=test-chat-001
```

#### 超级智能体

- `message`：用户输入内容

示例：

```text
GET /api/stream/superAgent?message=帮我查询用户名里包含张的用户，并整理结果
```

### 接口文档

项目集成了 `knife4j`，启动后可访问：

```text
http://localhost:8123/api/doc.html
```

---

## 已集成工具清单

| 工具类 | 主要能力 |
|---|---|
| `FileOperationTool` | 读取/写入本地文件 |
| `WebSearchTool` | 调用 SearchAPI 进行联网搜索 |
| `WebScrapingTool` | 抓取网页正文摘要 |
| `TerminalOperationTool` | 执行终端命令 |
| `ResourceDownloadTool` | 下载资源到本地 |
| `LatestTimeTool` | 获取当前实际时间 |
| `QueryDataBaseTool` | 查询和更新系统中的用户信息 |
| `PDFGenerationTool` | 生成 PDF 并上传到阿里云 OSS |
| `QQEmailSendTool` | 发送文本/HTML 邮件 |
| `TerminateTool` | 结束 Agent 工作流 |

### 本地文件输出位置

若从 `backend` 目录启动服务，则工具生成的本地文件通常会写到当前启动目录下的 `temp/` 目录，例如：

- `temp/file`
- `temp/resource`
- `temp/pdf`

---

## 数据库设计

项目当前代码中使用的是 MySQL，核心表为 `user_info`。  
超级智能体中的数据库工具会依赖这张表执行查询和更新。

根据实体类可以整理出一个可参考的建表语句：

```sql
CREATE TABLE `user_info` (
  `id` BIGINT NOT NULL AUTO_INCREMENT,
  `username` VARCHAR(100) NOT NULL,
  `password` VARCHAR(255) DEFAULT NULL,
  `nick_name` VARCHAR(100) DEFAULT NULL,
  `age` INT DEFAULT NULL,
  `gender` VARCHAR(20) DEFAULT NULL,
  `email` VARCHAR(100) DEFAULT NULL,
  `head_img` VARCHAR(255) DEFAULT NULL,
  `status` INT DEFAULT 0,
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP,
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

说明：

- 这份 SQL 是根据实体字段和映射文件整理出的推荐结构
- 仓库内未提供数据库迁移脚本，需要你自行初始化
- 如果只体验“恋爱大师”，数据库不是必须项
- 如果要完整体验“超级智能体的数据库工具”，则必须准备该表和测试数据

---

## 环境要求

建议本地开发环境至少满足以下条件：

| 软件 | 建议版本 |
|---|---|
| JDK | 21 |
| Maven | 3.9+ |
| Node.js | 20+ |
| npm | 与 Node 配套 |
| MySQL | 8.x |
| 可选：Ollama | 本地模型调试时使用 |

如果你准备启用默认的 MCP 配置，还需要：

- 系统中可执行 `npx` / `npx.cmd`
- 能够正常访问外部网络
- 先打包 `image-search-mcp-server`

---

## 本地启动指南

### 一、启动前你需要准备什么

项目当前依赖以下外部能力：

- DashScope 大模型 Key
- 阿里云百炼知识库
- MySQL 数据库
- SearchAPI Key
- QQ 邮箱授权码
- 阿里云 OSS 配置
- AMap MCP 所需 Key
- 图片搜索 MCP 服务依赖的 Pexels Key

如果你只是想先把页面和基础对话跑起来，最少也需要：

- 前端依赖
- 后端 DashScope 配置
- 恋爱大师对应的百炼知识库

如果你想完整体验超级智能体所有工具能力，则上述配置基本都需要补齐。

### 二、先构建图片搜索 MCP 子服务

由于后端本地配置默认会尝试加载 `image-search-mcp-server`，建议先构建它：

```bash
cd backend/image-search-mcp-server
mvn clean package -DskipTests
```

Windows 也可以使用：

```powershell
cd backend\image-search-mcp-server
.\mvnw.cmd clean package -DskipTests
```

### 三、配置后端

后端默认读取：

- `backend/src/main/resources/application.yaml`
- `backend/src/main/resources/application-local.yaml`

其中：

- 默认激活环境：`local`
- 默认端口：`8123`
- 默认上下文：`/api`

建议你至少检查并替换以下配置：

| 配置项 | 用途 |
|---|---|
| `spring.ai.dashscope.api-key` | DashScope 大模型调用 |
| `spring.ai.dashscope.chat.options.model` | 当前使用的模型 |
| `spring.datasource.*` | MySQL 数据源 |
| `search-api.api-key` | 联网搜索工具 |
| `qq-email.*` | 邮件发送工具 |
| `aliyun.oss.*` | PDF 上传到 OSS |
| `spring.ai.mcp.client.*` | MCP 客户端 |

推荐将敏感信息迁移到环境变量或私有配置文件中，不要直接在仓库里保留真实密钥。

### 四、启动后端主服务

```bash
cd backend
mvn spring-boot:run
```

或者：

```powershell
cd backend
.\mvnw.cmd spring-boot:run
```

启动成功后默认访问：

```text
http://localhost:8123/api
```

### 五、启动前端

```bash
cd frontend
npm install
npm run dev
```

前端默认通过：

```text
VITE_API_BASE_URL=http://localhost:8123/api
```

与后端通信。项目里已写了默认值，所以本地联调通常不额外配置也能工作。

### 六、访问页面

前端启动后，打开 Vite 输出的地址即可。常见为：

```text
http://localhost:5173
```

页面入口：

- 首页：`/`
- 恋爱大师：`/love`
- 超级智能体：`/agent`

---

## 可选的精简启动方式

如果你只是想先跑通前端界面和最基础的后端模型对话，而不想一开始就处理所有外部依赖，可以考虑：

### 方案 A：只体验恋爱大师

- 保留 DashScope 配置
- 保留百炼知识库配置
- 数据库可暂时不初始化
- 邮件、OSS、搜索等工具可以先不使用

### 方案 B：暂时关闭 MCP

如果本地没有 `npx`，或者暂时没有打包图片搜索 MCP 服务，可以先调整 `application-local.yaml` / `mcp-servers.json`，避免后端在启动时加载对应 MCP 服务。

### 方案 C：暂时不使用数据库工具

- 先不初始化 `user_info` 表
- 不在超级智能体中触发数据库相关任务

---

## Docker 部署说明

项目已经提供了前后端 `Dockerfile`。

### 后端镜像

位置：

```text
backend/Dockerfile
```

特点：

- 基于 `maven:3.9-amazoncorretto-21`
- 容器内执行 `mvn clean package -DskipTests`
- 暴露端口 `8123`
- 默认使用 `prod` 环境启动

构建命令：

```bash
cd backend
docker build -t super-agent-backend .
```

### 前端镜像

位置：

```text
frontend/Dockerfile
```

特点：

- 第一阶段使用 `node:20-alpine` 构建前端
- 第二阶段使用 `nginx:alpine` 托管静态文件
- 暴露端口 `80`

构建命令：

```bash
cd frontend
docker build -t super-agent-frontend .
```

### 关于 `frontend/nginx.conf`

当前 `nginx.conf` 中已经写死了一个线上后端代理地址。  
如果你是自己部署，请务必把 `/api/` 的 `proxy_pass` 和相关 Host 配置改成你自己的后端地址。

否则会出现：

- 页面能打开
- 但 API 实际请求打到别的服务
- SSE 或跨域表现异常

---

## 配置文件说明

### `application.yaml`

负责项目公共配置：

- 端口
- 上下文路径
- `springdoc` / `knife4j`
- 默认启用的 profile
- 敏感词配置
- MyBatis-Plus 配置

### `application-local.yaml`

偏向本地开发环境：

- DashScope 模型
- Ollama 本地模型
- MySQL 本地连接
- MCP 客户端配置
- 搜索 / 邮件 / OSS 等外部能力配置

### `application-prod.yml`

偏向生产部署环境：

- 生产数据库地址
- 生产启动所需配置

---

## 流式通信说明

项目中大量使用 `SSE` 来实现边生成边显示：

- 恋爱大师页通过 `/streamWay2/loveApp` 接收连续消息
- 超级智能体页通过 `/stream/superAgent` 接收每一步思考和最终结果

前端核心逻辑：

- 使用 `EventSource` 建立 SSE 连接
- 第一段返回时触发接收反馈动画
- 恋爱大师模式：直接把文本追加到同一条 AI 消息中
- 超级智能体模式：先把中间推理内容写入“思考中”面板，结束后再单独展示“最终回答”

---

## 测试情况

仓库中已经包含多类测试文件，例如：

- `LoveAppTest`
- `SuperAgentTest`
- 多个工具类测试
- RAG 相关测试
- `UserInfoServiceImplTest`

需要注意：

- 部分测试依赖真实外部服务
- 部分测试可能需要可用的 API Key、数据库或网络环境
- 因此在新环境直接执行全部测试，未必能一次通过

如果你要在 CI 中稳定运行，建议先对这些测试做分层：

- 纯单元测试
- 依赖外部服务的集成测试
- 需要真实账号/真实 API 的端到端验证

---

## 已知事项与维护建议

### 1. 当前仓库含有较多外部依赖

这不是一个“开箱即跑的纯离线项目”，而是一个集成度很高的实战型项目。  
如果你接手维护，第一步建议先梳理哪些能力是“必须”的，哪些是“可选”的。

### 2. 默认配置对本地环境有一定要求

默认 `local` profile 会启用 MCP 客户端，因此：

- 没有 `npx` 可能启动失败
- 没有打包 `image-search-mcp-server` 可能启动失败
- 外网不可用时，部分工具和 MCP 服务不可用

### 3. 恋爱大师当前主流程走的是云知识库

虽然代码中保留了本地 Markdown 向量库实现，但前端实际调用的公开接口走的是阿里云百炼知识库。  
如果后续需要纯本地化部署，需要重新切回本地向量库问答链路。

### 4. 超级智能体暴露了较强的工具能力

比如：

- 执行终端命令
- 读写文件
- 联网搜索
- 数据库更新
- 发送邮件

如果要上线生产环境，必须补充更严格的安全策略：

- 工具白名单
- 参数校验
- 权限控制
- 审计日志
- 敏感操作确认机制

### 5. 配置中的敏感信息需要尽快治理

从当前代码结构看，多个 API Key、数据库密码、邮箱授权码、OSS 凭证等都通过配置文件直接加载。  
正式交付或开源前，建议至少做这几件事：

1. 立即轮换所有已使用过的密钥和密码。
2. 将敏感配置迁移到环境变量、密钥管理平台或私有配置中心。
3. 在仓库中保留 `example` 配置，而不是保留真实值。
4. 为不同环境拆分开发、测试、生产配置。

---

## 后续可优化方向

如果未来还要继续演进，这个项目比较值得继续完善的方向有：

1. 增加统一鉴权与用户系统。
2. 为超级智能体加入工具权限分级。
3. 为数据库工具增加更严格的字段更新限制。
4. 把配置改造成 `.env + 配置中心` 的方式。
5. 增加数据库初始化脚本与 Docker Compose。
6. 增加消息持久化与历史会话管理。
7. 为 LoveApp 和 SuperAgent 分离更加清晰的业务边界。
8. 为前端补充消息 Markdown 渲染、代码高亮和富文本展示。
9. 为 MCP 服务增加健康检查和可观测性。
10. 将测试体系改造成可在 CI 稳定运行的分层结构。

---

## 许可证

仓库根目录包含 `LICENSE` 文件，请根据该文件内容使用本项目。

---

## 总结

这是一个完成度较高、覆盖面很广的 Spring AI 实战项目。  
它不仅实现了一个可用的 AI Web 应用，还把 RAG、Agent、Tool Calling、MCP、数据库、PDF、邮件、SSE 前端交互等能力串到了一起，适合作为学习样板、课程项目、毕业设计延伸项目，或者后续业务原型的基础框架。

如果你准备接手这个项目，建议先按下面顺序理解：

1. 先跑通前端页面和恋爱大师接口。
2. 再理解 `LoveApp` 的记忆、Advisor、RAG 组合方式。
3. 然后阅读 `BaseAgent / ReActAgent / ToolCallBackAgent / SuperAgent`。
4. 最后再接入数据库、OSS、邮件、MCP 等外围能力。

这样会比一开始就把所有模块同时拉起来更容易维护。