# ai-guide-agent **Repository Path**: feixueck/ai-guide-agent ## Basic Information - **Project Name**: ai-guide-agent - **Description**: 基于 Spring AI + RAG + Tool Calling + MCP 的企业级 AI 城市向导官,为用户规划旅游攻略。支持多轮对话、记忆持久化、RAG 知识库检索等能力,并且基于 ReAct 模式,能够自主思考并调用工具来完成复杂任务,比如利用网页搜索、资源下载和 PDF 生成工具制定完整的旅游攻略并生成文档。 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2025-10-17 - **Last Updated**: 2025-10-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ai-guide-agent #### 介绍 基于 Spring AI + RAG + Tool Calling + MCP 的企业级 AI 城市向导官,为用户规划旅游攻略。支持多轮对话、记忆持久化、RAG 知识库检索等能力,并且基于 ReAct 模式,能够自主思考并调用工具来完成复杂任务,比如利用网页搜索、资源下载和 PDF 生成工具制定完整的旅游攻略并生成文档。 ![输入图片说明](https://foruda.gitee.com/images/1760442030972066054/9e79fbcc_15808613.png "SSURYFDN%C{LWF]BR0O[UIO.png") ## 🏗️ 技术架构 ### 后端技术栈 ``` Spring Boot 3.5.6 ├── Spring AI 1.0.0-M6 │ ├── 阿里云DashScope (通义千问) │ ├── 向量数据库 (PGVector) │ └── MCP客户端 (高德地图) │ └── RAG知识库 │ └── Tool Calling 工具调用 | └── ReAct Agent 智能体构建 ├── iText PDF 9.1.0 │ └── 中文字体支持 (font-asian) ├── SSE 异步推送 ├── Hutool 5.8.37 ├── Jsoup 1.19.1 ├── Knife4j 4.4.0 (API文档) └── Cursor AI 代码生成 ``` ### 前端技术栈 ``` Vue 3.4.21 ├── Vite 5.1.6 ├── Axios 1.6.7 └── SSE (Server-Sent Events) ``` ### AI模型 - **对话模型**:阿里云 DashScope - qwen-plus - **搜索引擎**:智谱AI Web Search ## ✨ 核心功能 ### 双模式智能对话 #### 🤖 普通对话模式 - **特点**:快速、简洁、直接 - **场景**:简单咨询、问答互动 - **技术**: - 流式SSE响应 - 多轮对话记忆 - RAG知识增强 **示例对话:** ![输入图片说明](https://foruda.gitee.com/images/1760441962531505514/e79abfd8_15808613.png "7~G_%53G8V3E1VT4GT1V0TE.png") #### 🦾 Manus超级智能体模式 - **特点**:自主、强大、可视化 - **场景**:复杂任务、多步骤执行 - **技术**: - ReAct推理循环 - 自主工具调用 - 分步骤展示 - 任务状态追踪 **执行流程可视化:** ![输入图片说明](https://foruda.gitee.com/images/1760442053278685638/ca9fb302_15808613.png "`1LC`U({4MZMF%`}~IZ8HYF.png") ![输入图片说明](https://foruda.gitee.com/images/1760442068897810243/3a0a2882_15808613.png "[3GXQ[WZ[FI$IMR5M[3}}WS.png") ![输入图片说明](https://foruda.gitee.com/images/1760442109759594881/3cec38d8_15808613.png ")]AHJC_LK@6G)@]N`XSNSI6.png") # 🚀 快速开始指南 ## 📋 前置要求 在开始之前,请确保您的系统已安装: - ✅ **Java 21+** - [下载地址](https://www.oracle.com/java/technologies/downloads/#java21) - ✅ **Maven 3.6+** - [安装指南](https://maven.apache.org/install.html) - ✅ **Node.js 16+** - [下载地址](https://nodejs.org/) - ✅ **Git** - [下载地址](https://git-scm.com/) ## 📥 第一步:获取项目 ### 克隆仓库 ```bash git clone https://gitee.com/axingo9/ai-guide-agent.git cd ai-guide-agent ``` ### 或者下载ZIP 1. 访问 GitHub 仓库 2. 点击 "Code" → "Download ZIP" 3. 解压到本地目录 --- ## 🔑 第二步:配置API密钥 ### 1. 创建本地配置文件 在 `src/main/resources/` 目录下创建 `application-local.yml`: ```yaml ai: dashscope: api-key: sk-your-dashscope-api-key-here spring: postgresql: username: your-username password: your-password search-api: api-key: your-search-api-key-here ``` 在 `ai-guide-agent-frontend` 目录下创建 `.env`: ```yaml # .env VUE_APP_WEATHER_API_KEY = your-seniverse-api-key ``` ### 2. 获取API密钥 #### 阿里云DashScope(必需) 1. 访问 [DashScope控制台](https://dashscope.console.aliyun.com/) 2. 注册/登录阿里云账号 3. 开通灵积模型服务 4. 创建API Key 5. 复制到 `ai.dashscope.api-key` **免费额度:** 新用户有一定的免费调用额度 #### 智谱AI搜索(必需) 1. 访问 [智谱AI开放平台](https://open.bigmodel.cn/) 2. 注册/登录账号 3. 创建API Key 4. 复制到 `search-api.api-key` #### 高德地图(必需) 1. 访问 [高德开放平台](https://console.amap.com/) 2. 注册/登录账号 3. 创建应用,申请Web服务API Key 4. 编辑 `src/main/resources/mcp-servers.json`: #### 心知天气(非必需) 1. 访问 [心知天气平台](https://www.seniverse.com/) 2. 注册/登录账号 3. 创建应用,申请心知天气服务API Key 4. 复制到 `your-seniverse-api-key`: ## 🛠️ 工具能力 ### 1. 文件操作工具 (FileOperationTool) ```java @Tool(description = "Read content from a file") public String readFile(String fileName) @Tool(description = "Write content to a file") public String writeFile(String filename, String content) ``` **用途:** 读写文本文件,保存用户数据 ### 2. 网页搜索工具 (ZhipuWebSearchTool) ```java @Tool(description = "Search web content using Zhipu AI") public String searchWeb(String query) ``` **用途:** 搜索最新的网络信息 ### 3. 网页抓取工具 (WebScrapingTool) ```java @Tool(description = "Scrape content from a web page") public String scrapeWebPage(String url) ``` **用途:** 获取指定网页的详细内容 ### 4. 资源下载工具 (ResourceDownloadTool) ```java @Tool(description = "Download a resource from a given URL") public String downloadResource(String url, String fileName) ``` **用途:** 下载图片、文档等资源 ### 5. PDF生成工具 (PDFGenerationTool) ```java @Tool(description = "Generate a PDF file with given content") public String generatePDF(String fileName, String content) ``` **特性:** - ✅ 支持中文内容 - ✅ 自动字符过滤 ### 6. 终端操作工具 (TerminalOperationTool) ```java @Tool(description = "Execute a command in the terminal") public String executeTerminalCommand(String command) ``` **用途:** 执行系统命令 ### 7. 任务终止工具 (TerminateTool) ```java @Tool(description = "Terminate the interaction") public String doTerminate() ``` **用途:** 标记任务完成 --- ## 🗺️ MCP工具集成(高德地图) 通过 Spring AI MCP 协议集成高德地图API: - 📍 **地理编码/逆地理编码** - 地址与坐标转换 - 🔍 **POI搜索** - 关键词搜索、周边搜索 - 🚗 **路线规划** - 驾车、步行、骑行、公交 - 📏 **距离测量** - 计算两点间距离 - ☁️ **天气查询** - 实时天气信息 - 🏠 **IP定位** - 根据IP获取位置 --- ## 🧠 智能体架构 ### Agent层次结构 ``` BaseAgent (基础智能体) ├── ReActAgent (推理-行动循环) │ └── ToolCallAgent (工具调用智能体) │ └── AxingManus (超级智能体) └── GuideApp (城市向导应用) ``` ### Manus工作流程 ``` 用户输入 ↓ [Manus思考] 分析任务,制定计划 ↓ [工具调用1] 网页搜索 ↓ [工具调用2] 网页抓取 ↓ [工具调用3] 生成PDF ↓ [任务终止] 返回结果 ``` ---