# heart-ai-agent-server **Repository Path**: it4/heart-ai-agent ## Basic Information - **Project Name**: heart-ai-agent-server - **Description**: 一个基于springai框架开发的应用，拥有rag，tool，以及自主规划的ai应用。可以参考学习，切勿用于载人航天。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-23 - **Last Updated**: 2026-05-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: Spring, AI ## README # Heart AI Agent 基于 Spring AI Alibaba 的智能恋爱顾问 Agent，融合 RAG 知识库检索增强、MCP 协议、工具调用与 ReAct 自主规划能力，为用户提供恋爱领域专业咨询与智能任务执行服务。 --- ## 核心特性 - **恋爱顾问对话** — 扮演深耕恋爱心理领域的专家，围绕单身、恋爱、已婚三种状态提供专属解决方案 - **RAG 知识库增强** — 支持本地内存向量库、PgVector 持久化向量库、阿里云 DashScope 云端知识库三种检索增强方式 - **Manus 智能体** — 基于 ReAct（思考-行动）范式的自主规划 Agent，可自主选择并调用工具完成复杂任务 - **丰富的工具集** — 内置文件读写、网页搜索与抓取、PDF 生成、资源下载、终端命令执行等 7 种工具 - **MCP 协议支持** — 集成 MCP Client，可对接高德地图等外部 MCP 服务 - **多模式对话** — 支持同步返回、SSE 流式返回、结构化报告输出 - **会话记忆** — 基于文件的会话记忆持久化，支持独立会话隔离 --- ## 技术栈 | 类别 | 技术 | 说明 | |------|------|------| | 基础环境 | Java 21 + Spring Boot 3.5.14 | 运行基础 | | AI 框架 | Spring AI Alibaba 1.1.2.0 | Agent 编排 + DashScope 模型接入 | | 大语言模型 | 通义千问 qwen3.7-max | 阿里云 DashScope 提供 | | 向量存储 | PgVector + SimpleVectorStore | RAG 检索增强 | | 文档加载 | Markdown Document Reader | 知识库文档加载 | | MCP 协议 | spring-ai-starter-mcp-client | 外部工具服务集成 | | 会话持久化 | Kryo | 文件序列化会话记忆 | | API 文档 | Knife4j + SpringDoc OpenAPI | 接口文档与调试 | | 工具库 | Hutool、Jsoup、iTextPDF | 通用工具与文档处理 | --- ## 系统架构 ``` ┌─────────────────────────────────────┐ │ HTTP / SSE 接口 │ │ AiController / HeathController │ └──────────┬──────────────────────────┘ │ ┌────────────────┼────────────────┐ │ │ │ ┌─────────▼──────┐ ┌─────▼──────┐ ┌──────▼───────┐ │ LoveApp │ │ Manus │ │ MCP Client │ │ 恋爱顾问对话 │ │ 智能体 │ │ 外部服务集成 │ │ RAG / 记忆 │ │ ReAct规划 │ │ 高德地图等 │ └─────────┬──────┘ └─────┬──────┘ └──────────────┘ │ │ ┌─────────▼──────┐ ┌─────▼──────────────────────────┐ │ RAG 知识库 │ │ 工具集 (Tools) │ │ - PgVector │ │ 文件读写 │ 网页搜索 │ 网页抓取 │ │ - 内存向量库 │ │ PDF生成 │ 资源下载 │ 终端操作 │ │ - 阿里云知识库 │ │ 终止工具 │ └────────────────┘ └──────────────────────────────────┘ ``` ### Agent 继承体系 ``` BaseAgent (基础代理：状态管理、执行循环、SSE输出) └── ReActAgent (ReAct范式：think → act 抽象步骤) └── ToolCallAgent (工具调用：LLM工具选择与执行) └── Manus (智能体：自主规划，最大20步) ``` --- ## 项目结构 ``` src/main/java/com/okcl/heartaiagent/ ├── advisor/ # 顾问增强 │ ├── MyLoggerAdvisor.java # 日志顾问 │ └── ReReadingAdvisor.java # 重读顾问 ├── agent/ # Agent 核心 │ ├── enums/ # 枚举 │ │ └── AgentState.java # 代理状态枚举 │ ├── BaseAgent.java # 基础代理（状态管理、执行循环、SSE） │ ├── ReActAgent.java # ReAct 代理（思考-行动范式） │ ├── ToolCallAgent.java # 工具调用代理 │ └── Manus.java # Manus 智能体 ├── app/ # 应用层 │ └── LoveApp.java # 恋爱顾问应用（对话、RAG、工具、MCP） ├── chatmemory/ # 会话记忆 │ └── FileBasedChatMemory.java # 基于文件的会话记忆 ├── config/ # 配置 │ ├── CorsConfig.java # 跨域配置 │ └── ToolRegistrationConfig.java # 工具注册配置 ├── constant/ # 常量 │ └── FileConstant.java # 文件路径常量 ├── controller/ # 控制器 │ ├── AiController.java # AI 对话接口 │ └── HeathController.java # 健康检查接口 ├── demo/ # 示例 │ └── MultiQueryExpanderDemo.java # 多查询扩展演示 ├── factory/ # 工厂类 │ ├── LoveAppContextualQueryAugmenterFactory.java # 上下文查询增强工厂 │ └── LoveAppRagCustomAdvisorFactory.java # 自定义RAG顾问工厂 ├── rag/ # RAG 检索增强 │ ├── LoveAppDocumentLoader.java # Markdown文档加载器 │ ├── LoveAppRagCloudAdvisorConfig.java # 阿里云知识库配置 │ ├── LoveAppVectorStoreConfig.java # 内存向量库配置 │ ├── MyKeywordEnricher.java # 关键词增强器 │ ├── MyTokenTextSplitter.java # 自定义分词器 │ ├── PgVectorVectorStorageConfig.java # PgVector配置 │ └── RewriteQuery.java # 查询重写 ├── tools/ # 工具集 │ ├── FileOperationTool.java # 文件读写 │ ├── PdfGenerationTool.java # PDF 生成 │ ├── ResourceDownloadTool.java # 资源下载 │ ├── TerminalOperationTool.java # 终端命令执行 │ ├── TerminateTool.java # 终止工具 │ ├── WebScrapingTool.java # 网页抓取 │ └── WebSearchTool.java # 网页搜索 └── HeartAiAgentApplication.java # 启动类 ``` --- ## 快速开始 ### 环境要求 - JDK 21+ - Maven 3.8+ - PostgreSQL（需安装 PgVector 扩展） - Node.js（MCP 服务依赖） ### 1. 配置数据库 确保 PostgreSQL 已安装 `pgvector` 扩展： ```sql CREATE EXTENSION IF NOT EXISTS vector; ``` ### 2. 配置应用 复制并编辑本地配置文件 `src/main/resources/application-local.yml`： ```yaml spring: ai: dashscope: api-key: ${DASHSCOPE_API_KEY} # 阿里云 DashScope API Key chat: options: model: qwen3.7-max temperature: 0.8 ``` 同时修改 `application.yml` 中的数据库连接信息： ```yaml spring: datasource: url: jdbc:postgresql://localhost:5432/postgres username: your_username password: your_password ``` ### 3. 配置 MCP 服务（可选） 编辑 `src/main/resources/mcp-servers.json`，填入对应 API Key： ```json { "mcpServers": { "amap-maps": { "command": "npx.cmd", "args": ["-y", "@amap/amap-maps-mcp-server"], "env": { "AMAP_MAPS_API_KEY": "your_amap_api_key_here" } } } } ``` ### 4. 启动应用 ```bash mvn spring-boot:run ``` 应用启动后默认监听 `http://localhost:8499/api` --- ## API 接口 ### 健康检查 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/heath/` | 服务健康检查 | ### AI 对话 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/ai/love_app/chat/sync?message=&chatId=` | 恋爱顾问同步对话 | | GET | `/api/ai/love_app/chat/sse?message=&chatId=` | 恋爱顾问 SSE 流式对话 | | GET | `/api/ai/manus/sse?message=` | Manus 智能体 SSE 流式对话 | ### 接口示例 **同步对话：** ``` GET /api/ai/love_app/chat/sync?message=我想追一个女生&chatId=123 ``` **SSE 流式对话：** ``` GET /api/ai/love_app/chat/sse?message=我想追一个女生&chatId=123 ``` **Manus 智能体：** ``` GET /api/ai/manus/sse?message=帮我制定一个泰州海陵区的约会计划并生成PDF ``` ### API 文档 启动应用后访问 Knife4j 文档：`http://localhost:8499/api/swagger-ui.html` --- ## 工具集说明 | 工具 | 类名 | 功能描述 | |------|------|----------| | 文件读写 | `FileOperationTool` | 读取和写入本地文件 | | PDF 生成 | `PdfGenerationTool` | 将 Markdown 内容生成为 PDF 文档（支持中文字体）| | 资源下载 | `ResourceDownloadTool` | 从 URL 下载资源到本地 | | 网页搜索 | `WebSearchTool` | 调用搜索引擎获取实时信息 | | 网页抓取 | `WebScrapingTool` | 抓取指定 URL 的网页内容 | | 终端操作 | `TerminalOperationTool` | 执行终端命令（Windows 环境）| | 终止工具 | `TerminateTool` | Agent 任务完成时终止交互 | --- ## RAG 知识库 项目提供三种 RAG 检索增强方式，可在 `LoveApp` 中按需切换： | 方式 | 配置类 | 说明 | |------|--------|------| | 内存向量库 | `LoveAppVectorStoreConfig` | 基于 SimpleVectorStore，启动时从 Markdown 文档加载，适合开发调试 | | PgVector | `PgVectorVectorStorageConfig` | 基于 PostgreSQL + PgVector 持久化存储，适合生产环境 | | 阿里云知识库 | `LoveAppRagCloudAdvisorConfig` | 基于 DashScope 云端知识库，免维护向量数据 | 知识库文档位于 `src/main/resources/document/`： - `恋爱常见问题和回答-单身篇.md` - `恋爱常见问题和回答-恋爱篇.md` - `恋爱常见问题和回答-已婚篇.md` --- ## 配置项说明 | 配置项 | 默认值 | 说明 | |--------|--------|------| | `server.port` | 8499 | 服务端口 | | `server.servlet.context-path` | /api | 上下文路径 | | `spring.ai.dashscope.chat.options.model` | qwen3.7-max | 大语言模型 | | `spring.ai.dashscope.chat.options.temperature` | 0.8 | 生成温度 | | `spring.ai.vectorstore.pgvector.dimensions` | 1024 | 向量维度 | | `spring.ai.vectorstore.pgvector.index-type` | HNSW | 索引类型 | | `spring.ai.vectorstore.pgvector.distance-type` | COSINE_DISTANCE | 距离计算方式 | | `knife4j.enable` | true | Knife4j 文档开关 | --- ## 许可证 本项目仅供学习交流使用。