# Liuhaizhu Agent > "刘海柱" AI 智能助手全栈项目，融合大模型对话、联网搜索、知识库检索（RAG）、MCP 工具调用等核心 AI 能力，提供赛博朋克风格的现代交互体验。供Java大模型应用开发项目学习使用。 - **Type:** MCP server - **Install:** `agentstack add mcp-acefelix-liuhaizhu-agent` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [aceFelix](https://agentstack.voostack.com/s/acefelix) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [aceFelix](https://github.com/aceFelix) - **Source:** https://github.com/aceFelix/liuhaizhu-agent - **Website:** https://ailhz.top ## Install ```sh agentstack add mcp-acefelix-liuhaizhu-agent ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About ██╗ ██╗ ██╗███████╗ █████╗ ██████╗ ███████╗███╗ ██╗████████╗ ██║ ██║ ██║╚══███╔╝██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝ ██║ ███████║ ███╔╝ ███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║ ██║ ██╔══██║ ███╔╝ ██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║ ███████╗██║ ██║███████╗██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║ ╚══════╝╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝ **刘海柱Agent——Java大模型应用开发项目学习使用** # LHZ 个人智能助手 代号"刘海柱"的 AI 智能助手全栈项目，融合大模型对话、联网搜索、知识库检索（RAG）、MCP 工具调用等核心 AI 能力，提供赛博朋克风格的现代交互体验。 🌐 在线体验：[https://ailhz.top](https://ailhz.top) ## 项目组成 | 子项目 | 技术栈 | 说明 | |--------|--------|------| | [liuhaizhu-backend](./liuhaizhu-backend) | Spring Boot 3 + Spring AI + MyBatis Plus | AI 对话后端服务 | | [liuhaizhu-frontend](./liuhaizhu-frontend) | Vue 3 + Vite + Element Plus | 前端交互界面 | ## 系统架构 ``` ┌──────────────────────────────────────────────────────────────────┐ │ Nginx (HTTPS + 反向代理) │ │ :80 / :443 │ └────────────┬─────────────────────────────────┬───────────────────┘ │ │ ▼ ▼ ┌────────────────────────┐ ┌───────────────────────────────────┐ │ Vue 3 Frontend │ │ Spring Boot Backend (:8000) │ │ 赛博朋克 UI │────▶│ ┌──────────┐ ┌─────────────┐ │ │ SSE 流式对话 │ SSE │ │ Chat │ │ RAG │ │ │ GSAP 动效 │◀────│ │ Service │ │ Service │ │ │ Pinia 状态管理 │ │ └────┬─────┘ └──────┬──────┘ │ └────────────────────────┘ │ │ │ │ │ ▼ ▼ │ │ ┌──────────────────────────┐ │ │ │ Spring AI 1.0.3 │ │ │ │ (DashScope / Qwen3-Max) │ │ │ └──────────┬───────────────┘ │ │ │ │ │ ┌──────────┴───────────┐ │ │ │ MCP Tools │ │ │ │ Date/Email/Product │ │ │ └──────────────────────┘ │ └───────────┬───────────────────────┘ │ ┌──────────────────────┼──────────────────────┐ │ │ │ ▼ ▼ ▼ ┌──────────┐ ┌──────────────┐ ┌──────────┐ │ MySQL │ │ Redis Stack │ │ SearXNG │ │ 9.5+ │ │ (缓存+向量) │ │ 搜索引擎 │ └──────────┘ └──────────────┘ └──────────┘ ``` ## 核心功能 ### 后端 - **AI 智能对话**：基于 Qwen3-Max 模型 + Spring AI，SSE 流式响应，数据库持久化的 7 轮对话历史上下文记忆 - **联网搜索**：集成 SearXNG 搜索引擎，**Query 改写**优化搜索关键词，搜索结果注入 LLM 对话上下文 - **知识库检索（RAG）**：Tika 文档解析 → 递归文本分割 → **qwen-flash Query 改写** → Redis 向量存储 → 语义检索 → qwen3-rerank Cross-Encoder 重排序 - **MCP 工具调用**：内置 DateTool / EmailTool / ProductTool，支持外部 MCP Server（如高德地图） - **用户系统**：邮箱验证注册、JWT 双 Token 认证（Access 24h + Refresh 7d）、BCrypt 密码加密 - **权限控制**：Spring Security + 自定义注解（`@RequirePermission`）+ AOP 切面 - **高级特性**：请求限流（Redis Lua）| 分布式锁 | 慢请求告警 | 会话数量控制 | Actuator 健康监控 ### 前端 - **流式对话**：SSE 字符级实时流式输出，支持文本和文件两种输入方式 - **三种对话模式**：普通对话 / 联网搜索 / 知识库检索，互斥切换 - **会话管理**：多会话 CRUD，消息持久化，标题自定义编辑 - **用户系统**：用户名/邮箱注册、JWT 自动刷新、个人信息管理、数据加密存储 - **管理后台**：用户管理、知识库管理、Token 用量统计，路由守卫 + 权限指令双重保护 - **赛博朋克 UI**：科幻粒子背景、故障文字特效、HUD 装饰、暗黑/明亮双主题 - **交互动效**：GSAP 卡片抽出页面转场、Lenis 阻尼滚动、打字机效果 ## 技术栈总览 | 层级 | 技术 | |------|------| | 前端框架 | Vue 3 (Composition API) | | 构建工具 | Vite 7 | | 状态管理 | Pinia 3 | | UI 组件 | Element Plus 2 | | 动画 | GSAP 3 + Lenis 1 | | 后端框架 | Spring Boot 3.5.8 | | AI 框架 | Spring AI 1.0.3 + DashScope (Qwen3-Max) | | ORM | MyBatis Plus 3.5.12 | | 数据库 | MySQL 9.5+ | | 缓存/向量 | Redis Stack | | 搜索引擎 | SearXNG | | 安全 | Spring Security + JWT (auth0) | | 文件存储 | x-file-storage (MinIO / Aliyun OSS) | | MCP 协议 | Spring AI MCP 1.0.3 | | 容器化 | Docker + Docker Compose | | CI/CD | Jenkins | | Web 服务器 | Nginx (HTTPS + 反向代理) | | 测试框架 | JUnit 5 + Mockito（后端） / Vitest + @vue/test-utils（前端） | ## 目录结构 ``` liuhaizhu-agent/ ├── liuhaizhu-backend/ # Spring Boot 后端 │ ├── src/main/java/.../ # Java 源码 │ ├── src/main/resources/ # 配置 / SQL / 提示词 │ ├── Dockerfile # 后端镜像构建 │ ├── docker-compose.yml # 后端容器编排 │ ├── Jenkinsfile # 后端 CI/CD │ └── pom.xml # Maven 配置 ├── liuhaizhu-frontend/ # Vue 3 前端 │ ├── src/ # Vue 源码 │ ├── public/ # 静态资源 │ ├── Dockerfile # 前端镜像构建 │ ├── docker-compose.yml # 前端容器编排 │ ├── nginx.conf # Nginx 配置 │ └── Jenkinsfile # 前端 CI/CD ├── LICENSE # MIT License └── README.md # 本文件 ``` ## 快速开始 ### 环境要求 - **后端**：JDK 17+ / Maven 3.9+ / MySQL 9.5+ / Redis Stack / SearXNG - **前端**：Node.js ^22.14.0 / Yarn 1.22+ ### 后端启动 ```bash cd liuhaizhu-backend # 1. 配置环境变量 cp src/main/resources/.env-template .env # 编辑 .env 填入实际配置（数据库、Redis、DashScope API Key 等） # 2. 初始化数据库（执行 SQL 脚本） # src/main/resources/sql/liuhaizhu.sql # 3. 启动 ./mvnw spring-boot:run ``` 后端默认运行在 `http://localhost:8000`。 ### 前端启动 ```bash cd liuhaizhu-frontend # 安装依赖 yarn install # 启动开发服务器 yarn dev ``` 前端默认运行在 `http://localhost:5173`，已配置反向代理到后端 8000 端口。 ### Docker Compose 一键部署（生产环境） 前后端均有独立的 `docker-compose.yml`，可按需分别部署： ```bash # 部署后端 cd liuhaizhu-backend # 编辑 docker-compose.yml 中的环境变量 docker-compose up -d --build # 部署前端（含 Nginx HTTPS） cd liuhaizhu-frontend # 准备 SSL 证书到 ssl/ 目录，编辑 docker-compose.yml docker-compose up -d --build ``` ## 默认管理员 系统首次启动时会自动创建默认管理员账户（用户名 `admin`，角色 ADMIN），密码请查看 `DataInitializer.java` 中的初始化逻辑，**生产环境务必修改默认密码**。 ## 文档索引 - [后端 README](./liuhaizhu-backend/README.md) — API 接口、架构设计、MCP 工具、开发规范 - [前端 README](./liuhaizhu-frontend/README.md) — 路由表、组件说明、主题系统、权限控制 ## 测试覆盖 项目已完成全面的单元测试覆盖，共 **442 项测试**（229 后端 + 213 前端），0 失败。 | 模块 | 测试文件数 | 测试数 | 覆盖范围 | |------|----------|--------|---------| | 后端工具类 | 6 | 69 | JwtUtil, AceResult, RateLimiterUtil, DistributedLockUtil, SSEServerUtil, RecursiveTextSplitter | | 后端枚举/MCP | 4 | 37 | UserRoleEnum, DateTool, EmailTool, DocumentFormatConversion | | 后端 Service | 6 | 103 | AuthService, AdminUserService, ConversationService, UserProfileService, PermissionService, CustomUserDetailsService | | 后端安全 | 2 | 16 | CustomUserDetails, JwtAuthenticationFilter | | 后端 MCP 工具 | 1 | 12 | ProductTool（枚举转换 + CRUD） | | 前端 Utils | 3 | 74 | helpers, imageUtils, permission | | 前端 Stores | 4 | 79 | auth, chat, settings, transition | | 前端 Composable | 1 | 12 | useToast | | 前端 指令/API | 2 | 18 | v-permission, auth API | ### 运行测试 ```bash # 后端 cd liuhaizhu-backend ./mvnw test # 前端 cd liuhaizhu-frontend yarn test:unit ``` ## License [MIT](./LICENSE) Copyright (c) 2025 aceFelix 本项目基于 MIT 协议开源，任何人可免费学习、使用、修改和分发。 ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [aceFelix](https://github.com/aceFelix) - **Source:** [aceFelix/liuhaizhu-agent](https://github.com/aceFelix/liuhaizhu-agent) - **License:** MIT - **Homepage:** https://ailhz.top Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-acefelix-liuhaizhu-agent - Seller: https://agentstack.voostack.com/s/acefelix - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.