AI 智能体 (AI Intelligent Agent)

本项目是一个基于 Spring AI 构建的企业级多智能体系统，集成了检索增强生成 (RAG)、函数调用、MCP、长期记忆和流式响应等先进 AI 能力。系统不仅仅是聊天机器人，更是一个可扩展的智能代理平台，支持多种专业领域的智能体协同工作。

🏗️ 核心架构

系统采用分层式多智能体架构，通过 AgentManagerService 实现智能体的统一管理、路由分发和生命周期控制。每个智能体都具备独立的工具调用能力和专业领域知识。

graph TD
    subgraph "前端层 (Frontend Layer)"
        A[Vue 3 + TypeScript 聊天界面]
        A1[Markdown 渲染引擎]
        A2[SSE 流式响应处理]
        A3[Tailwind CSS 样式系统]
    end

    subgraph "API 网关层 (API Gateway)"
        B[AiController - REST API]
        B1[参数校验 & 异常处理]
        B2[SSE 流式响应]
        B3[Knife4j API 文档]
    end

    subgraph "智能体管理层 (Agent Management)"
        C[AgentManagerService]
        C1[智能体缓存 - Caffeine]
        C2[会话管理 & 路由]
        C3[生命周期控制]
    end

    subgraph "智能体与应用层 (Agent & App Layer)"
        D[MyManus Agent<br/>通用超级智能体]
        E[LoveApp RAG<br/>知识问答应用]
        F[Bangumi Agent<br/>动漫专家]
        G[ToolCallAgent<br/>工具调用基类]
    end

    subgraph "工具层 (Tool Layer)"
        H[WebSearchTool - 阿里云搜索]
        I[BangumiTool - 动漫数据API]
        J[FileTool - 文件操作/OSS上传]
        K[PDFGenerationTool - PDF生成]
        L[EmailSendingTool - 邮件发送]
        M[TerminalTool - 命令执行]
        N[MCP Tools - 外部工具协议]
    end

    subgraph "AI 核心层 (AI Core)"
        O[Spring AI Framework]
        P[Alibaba DashScope - 通义千问]
        Q[Chat Memory - 对话记忆]
        R[Vector Store - 向量数据库]
        S[RAG Pipeline - 检索增强]
    end

    subgraph "存储层 (Storage Layer)"
        T[Redis - 对话记忆存储]
        U[File System - 本地文件存储]
        V[Aliyun OSS - 对象存储]
        W[SimpleVectorStore - 内存向量存储]
        X[Elasticsearch - 可选向量存储]
    end

    A --> B
    B --> C
    B --> E
    C --> D & F
    D --> G
    F --> G
    E --> O
    E --> S
    G --> H & I & J & K & L & M & N
    G --> O
    O --> P & Q & R
    S --> R
    Q --> T & U
    R --> W
    J --> U & V
    K --> U

🎯 核心技术亮点

分层式多智能体架构

本项目采用 分层式多智能体架构，通过统一的 AgentManagerService 实现智能体的生命周期管理：

智能体缓存机制

// 30 分钟过期的智能体实例缓存
private final Cache<String, BaseAgent> agentCache = Caffeine.newBuilder()
        .expireAfterAccess(30, TimeUnit.MINUTES)
        .maximumSize(1000)
        .build();

public MyManus getOrCreateManus(String conversationId) {
    String cacheKey = "manus:" + conversationId;
    return (MyManus) agentCache.get(cacheKey, key -> {
        MyManus manus = new MyManus(allTools, dashscopeChatModel);
        manus.setConversationInfo(conversationId, chatMemory);
        return manus;
    });
}

混合存储记忆系统

// 支持 Redis、文件、混合三种存储模式
@Component
public class HybridChatMemory implements ChatMemory {
    // 双写模式：同时写入 Redis 和文件
    // Redis 失败时自动降级到文件存储
    // 混合模式下优先读取 Redis，失败时读取文件
}

智能记忆摘要系统

// 装饰器模式实现记忆摘要功能
@Component
public class SummarizingChatMemoryDecorator implements ChatMemory {
    private final ChatMemory delegate;           // 被装饰的底层存储
    private final ChatModel chatModel;           // 用于生成摘要的AI模型
    private final int summarizationThreshold;    // 触发摘要的阈值(15条)
    private final int messagesToSummarize;       // 每次摘要的消息数(6条)

    @Override
    public void add(String conversationId, List<Message> messages) {
        delegate.add(conversationId, messages);

        // 异步执行摘要，避免阻塞用户请求
        CompletableFuture.runAsync(() -> summarize(conversationId));
    }

    private void summarize(String conversationId) {
        List<Message> history = delegate.get(conversationId);
        if (history.size() <= summarizationThreshold) return;

        // 1. 提取旧消息进行摘要
        List<Message> oldMessages = history.subList(0, messagesToSummarize);
        List<Message> recentMessages = history.subList(messagesToSummarize, history.size());

        // 2. 使用AI生成摘要
        String summaryText = chatModel.call(createSummaryPrompt(oldMessages));
        Message summaryMessage = new SystemMessage("【历史对话摘要】: " + summaryText);

        // 3. 构建新的压缩历史：摘要 + 近期消息
        List<Message> newHistory = new ArrayList<>();
        newHistory.add(summaryMessage);
        newHistory.addAll(recentMessages);

        // 4. 原子性替换历史记录
        synchronized (this) {
            delegate.clear(conversationId);
            delegate.add(conversationId, newHistory);
        }
    }
}

记忆摘要配置

ai-agent:
  memory:
    summary:
      threshold: 15      # 超过15条消息触发摘要
      chunk-size: 6      # 每次摘要最旧的6条消息

技术优势

• 高性能缓存: Caffeine 本地缓存，支持 1000 个智能体实例
• 故障恢复: 混合存储模式，Redis 失败自动降级
• 内存向量存储: SimpleVectorStore 提供毫秒级检索响应
• 工具生态: 7 种专业工具，支持 MCP 协议扩展

✨ 核心功能特性

🤖 多智能体系统

• MyManus Agent: 通用超级智能体，具备强大的工具调用能力，可执行文件操作、网络搜索、PDF 生成等复杂任务
• LoveApp RAG: 基于 RAG 的知识问答应用，提供专业领域问答服务
• Bangumi Agent: 动漫领域专家智能体，集成 Bangumi API，提供动漫作品查询、评分、时间表等服务
  • 智能体缓存: 基于 Caffeine 的智能体实例缓存，30 分钟过期机制，支持高并发访问

🛠️ 丰富的工具生态

• WebSearchTool: 集成阿里云开放搜索，支持实时网络信息检索
• BangumiTool: 动漫数据 API 工具，支持作品搜索、详情查询、用户评价等
• FileTool: 文件系统操作工具，支持文件读写、目录管理
• PDFGenerationTool: 高质量 PDF 生成工具，支持完整 Markdown 格式
• EmailSendingTool: 邮件发送工具，支持 HTML 格式和附件
• TerminalTool: 系统命令执行工具，支持跨平台命令行操作
• MCP 工具集: 支持 Model Context Protocol，可集成外部工具服务

🧠 智能记忆系统

• 混合存储架构: 支持 Redis、文件、混合三种存储模式，可配置切换
• 对话记忆: 基于会话 ID 的长期对话记忆，支持上下文理解和自动过期
• 智能摘要机制: SummarizingChatMemoryDecorator装饰器模式实现记忆摘要
  • 当对话超过15条时自动触发异步摘要
  • 使用AI模型生成摘要，压缩历史对话为背景知识
  • 保留最近6条消息 + 1条摘要，优化记忆效率
  • 异步执行避免阻塞用户请求，保证响应速度
• 故障恢复: 混合模式下 Redis 失败自动降级到文件存储，保证可用性
• 序列化优化: 使用 Kryo 高性能序列化，避免序列化问题

🔍 检索增强生成 (RAG)

• 多源知识库: 支持 SimpleVectorStore 内存存储、Elasticsearch、阿里云知识库等
• 智能文档处理: Markdown 文档自动解析、分块和向量化，支持关键词元信息增强
• 查询优化: 智能查询重写和腾讯翻译，提升检索准确性
• 向量存储: 默认使用内存向量存储，支持 Elasticsearch 扩展
• 文档加载: 自动加载 classpath 下的 Markdown 文档，支持水平分割

🌊 流式响应体验

• SSE 流式传输: 基于 Server-Sent Events 的实时流式响应
• 打字机效果: 前端实现逐字显示效果，提升用户体验
• 异步处理: 非阻塞式请求处理，支持高并发场景
• 错误恢复: 流式传输中断自动重连机制

🔒 企业级特性

• 参数校验: 完善的输入参数校验和异常处理机制
• 日志记录: 结构化日志记录，支持链路追踪
• API 文档: Knife4j 自动生成的交互式 API 文档
• 配置管理: 多环境配置支持，敏感信息加密存储

🚀 快速开始

环境要求

• Java: OpenJDK 21 或更高版本
• Node.js: 16.8 或更高版本
• Redis: 6.0 或更高版本 (可选，支持文件存储模式)
• Maven: 3.6 或更高版本

后端启动

1. 克隆项目

   git clone <repository-url>
   cd my-ai-agent
   

2. 配置环境

   复制并编辑配置文件：

   cp src/main/resources/application-local.yml.example src/main/resources/application-local.yml
   

   配置必要的 API Keys：

   spring:
     ai:
       dashscope:
         api-key: <your-dashscope-api-key>  # 阿里云通义千问 API Key
   
   # 阿里云搜索服务配置
   aliyun:
     webSearch:
       apiKey: <your-aliyun-search-api-key>
       host: <your-aliyun-search-host>
   
   # Bangumi API 配置
   bangumi:
     api:
       access-token: <your-bangumi-access-token>
   

3. 安装依赖并启动

   mvn clean install
   mvn spring-boot:run
   

   或者使用 IDE 直接运行 MyAiAgentApplication.main() 方法。

4. 验证启动

   • 后端服务: http://localhost:8123/api
   • API 文档: http://localhost:8123/api/doc.html#/home

前端启动

1. 进入前端目录

   cd my-ai-agent-frontend
   

2. 安装依赖

   npm install
   

3. 启动开发服务器

   npm run dev
   

4. 访问应用

   • 前端应用: http://localhost:3000

MCP 工具配置 (可选)

项目支持 MCP 外部工具集成：

1. 配置 MCP 服务器

   编辑 src/main/resources/mcp-servers.json：

   {
     "mcpServers": {
       "amap-maps": {
         "command": "npx.cmd",
         "args": ["-y", "@amap/amap-maps-mcp-server"],
         "env": {
           "AMAP_MAPS_API_KEY": "<your-amap-api-key>"
         }
       }
     }
   }
   

2. 启用 MCP 客户端

   在 application.yml 中配置：

   spring:
     ai:
       mcp:
         client:
           request-timeout: 30s
           stdio:
             servers-configuration: classpath:mcp-servers.json
   

📖 使用指南

API 接口

1. 通用智能体对话

# SSE 流式对话
curl -N "http://localhost:8123/api/ai/manus/chat?message=你好&conversationId=test-001"

# 同步对话
curl "http://localhost:8123/api/ai/manus/chat/sync?message=帮我搜索最新的AI技术发展&conversationId=test-001"

2. RAG 知识问答 (恋爱顾问)

# 流式对话
curl -N "http://localhost:8123/api/ai/love_app/chat/sse?message=如何提升沟通技巧&chatId=love-001"

3. 动漫专家智能体

# 流式对话
curl -N "http://localhost:8123/api/ai/bangumi/chat?message=推荐几部2024年的优秀动画&conversationId=bangumi-001"

4. 会话管理

# 清理会话
curl "http://localhost:8123/api/conversation/clear?conversationId=test-001"

# 获取会话信息
curl "http://localhost:8123/api/conversation/info?conversationId=test-001"

工具调用示例

智能体支持多种工具调用，以下是一些使用示例：

文件操作

用户: 帮我创建一个名为 "meeting-notes.txt" 的文件，内容是今天的会议记录
智能体: [调用 FileTool.writeFile()]

网络搜索

用户: 搜索一下最新的 Spring AI 发展动态
智能体: [调用 WebSearchTool.searchWeb()]

PDF 生成

用户: 把刚才的搜索结果生成一份 PDF 报告
智能体: [调用 PDFGenerationTool.generatePDF()]

动漫查询

用户: 查询《进击的巨人》的详细信息和评分
智能体: [调用 BangumiTool.searchWorks() 和 BangumiTool.getWorkDetail()]

🏗️ 项目结构

my-ai-agent/
├── src/main/java/com/zyb/myaiagent/
│   ├── agent/                          # 智能体实现
│   │   ├── BaseAgent.java              # 智能体基类
│   │   ├── MyManus.java                # 通用超级智能体
│   │   ├── BangumiAgent.java           # 动漫专家智能体
│   │   ├── ToolCallAgent.java          # 工具调用智能体基类
│   │   └── service/
│   │       └── AgentManagerService.java # 智能体管理服务
│   ├── app/
│   │   └── LoveApp.java                # RAG 应用主类
│   ├── advisor/                        # Spring AI 顾问
│   │   ├── ForbiddenWordsAdvisor.java  # 敏感词过滤
│   │   └── MyLoggerAdvisor.java        # 日志记录
│   ├── chatmemory/                     # 对话记忆
│   │   └── FileBasedChatMemory.java    # 文件存储记忆
│   ├── controller/
│   │   └── AiController.java           # REST API 控制器
│   ├── rag/                            # 检索增强生成
│   │   ├── QueryRewriter.java          # 查询重写
│   │   ├── LoveAppVectorStoreConfig.java # 向量存储配置
│   │   └── translation/
│   │       └── TencentTranslationQueryTransformer.java
│   ├── tools/                          # 工具实现
│   │   ├── WebSearchTool.java          # 网络搜索工具
│   │   ├── BangumiTool.java            # 动漫 API 工具
│   │   ├── FileTool.java               # 文件操作工具
│   │   ├── PDFGenerationTool.java      # PDF 生成工具
│   │   ├── EmailSendingTool.java       # 邮件发送工具
│   │   ├── TerminalTool.java           # 终端命令工具
│   │   └── ToolRegistration.java       # 工具注册配置
│   └── MyAiAgentApplication.java       # 应用启动类
├── src/main/resources/
│   ├── application.yml                 # 主配置文件
│   ├── application-local.yml           # 本地环境配置
│   └── mcp-servers.json               # MCP 服务器配置
├── my-ai-agent-frontend/               # Vue 3 前端项目
│   ├── src/
│   │   ├── components/                 # Vue 组件
│   │   ├── stores/                     # Pinia 状态管理
│   │   ├── utils/                      # 工具函数
│   │   └── views/                      # 页面视图
│   ├── package.json
│   └── vite.config.ts
├── my-image-search-mcp/                # MCP 图片搜索服务
└── pom.xml                            # Maven 配置文件

🔒 安全考虑

输入验证

• 参数校验: 完善的输入参数验证机制
• 敏感词过滤: 内置敏感词检测和过滤

访问控制

• API 限流: 基于 Redis 的分布式限流
• 会话隔离: 基于会话 ID 的数据隔离
• 配置加密: 敏感配置信息加密存储

---

⭐ 如果这个项目对你有帮助，请给它一个 Star！