# leimu-agent

**Repository Path**: elfbobo_admin_admin/leimu-agent

## Basic Information

- **Project Name**: leimu-agent
- **Description**: 雷姆智能体（leimu-agent） 是一个基于大语言模型（LLM） 和模型上下文协议（MCP） 的智能助手系统。该项目通过标准化的协议设计，实现了多模态内容生成、工具调用和智能对话等核心功能，为开发者提供了一套完整的AI智能体开发框架。
- **Primary Language**: Java
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-09-10
- **Last Updated**: 2025-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# leimu-agent

leimu-agent 是一个基于大语言模型（LLM）和模型上下文协议（MCP）的智能助手系统，旨在为开发者提供一套完整的AI智能体开发框架。该项目以动漫角色"蕾姆"为主题，构建了一个具有独特个性和交互体验的AI助手。

## 项目特色

蕾姆是一个拥有蓝发蓝瞳、小女仆裙的可爱AI助手，具有温柔体贴的性格，能够与用户进行自然语言对话，同时具备多种实用功能：

- 🎨 **AI绘画功能** - 根据用户描述生成精美图像
- 🎵 **音乐搜索播放** - 搜索并播放用户想听的歌曲
- 💬 **智能对话** - 基于上下文的自然语言交流
- 📝 **会话记录导出** - 支持HTML/Markdown格式导出对话记录
- 🖼️ **多模态交互** - 支持文本和图像输入
- 🧠 **工具调用能力** - 可根据需求调用不同工具完成复杂任务

## 系统功能

### 核心功能模块

1. **智能对话系统**
   - 基于ReAct模式的智能体实现
   - 上下文记忆和状态管理
   - 工具调用决策机制

2. **多模态内容生成**
   - 文本生成与对话
   - AI图像生成（绘画功能）
   - 音频内容处理（音乐搜索）

3. **会话管理系统**
   - 用户会话创建、选择、删除
   - 消息历史记录存储与管理
   - 会话内容导出功能

4. **工具调用系统**
   - 绘画工具：根据描述生成图像
   - 导出工具：将对话记录导出为HTML/Markdown
   - 音乐工具：搜索并播放音乐

## 技术架构

### 后端技术栈
- **核心框架**：Spring Boot 3.2.4、Spring WebFlux
- **AI框架**：Spring AI（集成OpenAI和MCP客户端）
- **数据存储**：MongoDB（会话和消息存储）、Redis（缓存和权限管理）
- **安全框架**：Sa-Token（权限认证、JWT、Redis缓存）
- **文件存储**：MinIO（用户上传文件存储）
- **工具库**：Lombok、Hutool、Jsoup、Flexmark等

### 前端技术栈
- **核心框架**：Vue.js 3、Vite
- **UI框架**：Element Plus
- **样式设计**：Tailwind CSS
- **状态管理**：Pinia
- **构建工具**：Vite

### 系统架构图
```mermaid
graph TD
    A[前端界面] --> B{Nginx网关}
    B --> C[后端API服务]
    C --> D[(MongoDB数据库)]
    C --> E[(Redis缓存)]
    C --> F[AI模型服务]
    F --> G[绘图模型]
    F --> H[语言模型]
    C --> I[MinIO存储]
```

## 简化部署优势

本项目采用容器化部署方式，通过Docker网络实现服务间通信，大大简化了部署配置：

1. **服务间通信**：各服务通过Docker容器名称进行通信，无需配置具体IP地址
2. **配置一致性**：开发环境和生产环境使用相同的容器名称配置
3. **部署便捷性**：仅需修改密钥等敏感配置，无需修改服务主机配置
4. **迁移便利性**：项目可整体迁移至不同环境，只需调整密钥配置

生产环境部署时，仅需修改`application-pro.yml`中的密钥配置：
```yaml
spring:
  ai:
    openai:
      api-key: your_siliconflow_api_key   # 硅基流动API密钥

resend:
  api-key: your_resend_api_key           # Resend邮件服务API密钥
  from:    Leimu-Agent@leimu.com         # 已在控制台验证的域名
```

## 界面展示

以下是我们系统的主要界面截图：

### 主界面
![主界面](images/index.png)

### 对话交互界面
![对话界面](images/chatArea.png)

### AI绘画结果展示
![绘画结果](images/image.png)

### 音乐播放界面
![音乐播放](images/music.gif)

## 角色设定

系统中的AI助手名为"蕾姆"，源自动漫《Re:从零开始的异世界生活》中的角色，具有以下特征：
- **外观**：蓝发蓝瞳、小女仆裙、永远带着温柔微笑
- **性格**：温柔、体贴，偶尔小声傲傲娇
- **语气**：轻软、简短，每句不超过30字，常用"～""呀""呢"等语气词

## 快速开始

### 环境要求
- JDK 17
- Maven 3.8+
- Docker 20.10+
- Docker Compose 1.29+
- Node.js 16+ (仅前端开发需要)

### 本地开发启动

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd leimu-agent
   ```

2. **后端服务启动**
   ```bash
   # 使用Maven启动后端服务
   mvn spring-boot:run
   ```

3. **前端服务启动**
   ```bash
   # 进入前端目录
   cd src/main/resources/web/front
   
   # 安装依赖
   npm install
   
   # 启动前端开发服务器
   npm run dev
   ```

4. **访问应用**
   - 前端界面：http://localhost:5173
   - 后端API：http://localhost:8090

### 生产环境部署

详细部署说明请参考 [DEPLOYMENT.md](DEPLOYMENT.md) 文件。

使用项目提供的部署脚本可以快速完成生产环境部署：

#### Linux系统:
```bash
# 给脚本添加执行权限
chmod +x start.sh

# 构建并启动所有服务
./start.sh --build --start
```

#### Windows系统:
```cmd
# 构建并启动所有服务
start.bat --build --start
```

## 项目结构

```
leimu-agent/
├── config/                 # 配置文件目录
│   └── redis/              # Redis配置文件
├── src/                    # 源代码目录
│   ├── main/
│   │   ├── java/           # 后端Java代码
│   │   │   └── com.gzist.leimuagent/
│   │   │       ├── agent/     # AI智能体核心实现
│   │   │       ├── controller/ # Web控制器
│   │   │       ├── service/    # 业务逻辑层
│   │   │       ├── repository/ # 数据访问层
│   │   │       ├── tools/      # 工具实现
│   │   │       └── ...         # 其他组件
│   │   └── resources/      # 配置文件和前端代码
│   │       └── web/front/      # 前端Vue项目
│   └── test/               # 测试代码
├── dist/                   # 构建产物目录
├── leimu-agent-data/       # 外部数据存储目录（自动生成）
├── Dockerfile             # 后端Docker运行时文件
├── docker-compose.yml     # Docker服务编排文件
├── nginx.conf             # Nginx配置文件
├── start.sh               # Linux部署脚本
└── start.bat              # Windows部署脚本
```

## 核心组件介绍

### AI智能体系统
- `BaseAgent`：抽象基础代理类，定义了代理的基本结构和状态管理
- `ReActAgent`：实现ReAct模式的代理类，支持思考和行动循环
- `ToolCallAgent`：工具调用代理类，处理工具选择和执行
- `LeiMuManus`：具体实现的蕾姆智能体，具有特定的角色设定和行为模式

### 工具系统
- `PaintingTool`：AI绘画工具，可根据描述生成图像
- `ChatMessagesExportTool`：聊天记录导出工具，支持多种格式导出
- `MusicSearchTool`：音乐搜索工具，可搜索并播放音乐

### 服务层
- `PaintingService`：AI绘画服务，处理图像生成逻辑
- `ChatExportService`：聊天记录导出服务，支持HTML和Markdown格式
- `MessageService`：消息管理服务，处理消息存储和检索
- `SessionService`：会话管理服务，管理用户会话

## 开发指南

### 添加新工具

1. 在 [tools](file:///D:/program%20files/gitee-project/leimu-agent/src/main/java/com/gzist/leimuagent/tools) 目录下创建新的工具类
2. 使用 `@Component` 注解标记工具类
3. 使用 `@Tool` 注解标记工具方法
4. 在 [ToolRegistration](file:///D:/program%20files/gitee-project/leimu-agent/src/main/java/com/gzist/leimuagent/tools/ToolRegistration.java#L1-L24) 中注册新工具

### 扩展智能体功能

1. 继承 [BaseAgent](file:///D:/program%20files/gitee-project/leimu-agent/src/main/java/com/gzist/leimuagent/agent/BaseAgent.java#L22-L120) 或其子类创建新的智能体
2. 实现具体的 [step](file:///D:/program%20files/gitee-project/leimu-agent/src/main/java/com/gzist/leimuagent/agent/BaseAgent.java#L71-L71) 方法
3. 在 [LeiMuManusFactory](file:///D:/program%20files/gitee-project/leimu-agent/src/main/java/com/gzist/leimuagent/agent/LeiMuManusFactory.java#L16-L27) 中注册新的智能体

## 贡献指南

欢迎提交Issue和Pull Request来帮助改进项目。

## 许可证

本项目采用 [MIT](LICENSE) 许可证。