WeaTrip天气感知型旅游规划Agent说明文档
🌟项目概述
1.系统背景
WeaTrip是一个基于MCP协议的智能天气旅行助手系统，它通过自然语言交互为用户提供精准的天气查询和个性化的旅行建议。整个系统采用分层架构设计，从前端用户界面到后端服务处理形成了完整的业务闭环。
2.系统目标
- 根据用户输入的城市和旅行需求提供个性化天气建议
- 采用DeepSeek大语言模型进行自然语言理解和意图识别
- 实现基于MCP协议的可扩展架构
- 提供直观的聊天式用户交互界面
3.开发模式：敏捷开发实践🚀
本项目采用敏捷开发模型进行迭代开发，旨在快速响应需求变化，持续交付可用的软件增量。我们的实践体现在以下几个方面：
- 迭代式开发：我们将项目划分为多个短周期（Sprint），每个Sprint都包含计划、设计、编码、测试和评审环节，确保产品功能持续完善。本文所展示的即为我们当前Sprint周期内交付的可工作软件成果。
- 用户故事驱动：在需求分析阶段，我们基于“用户角色与画像”创建了详细的用户故事（User Stories），例如“作为一个自由行爱好者，我希望查询目的地的天气报告，以便我能够准备合适的衣物和规划户外活动”。这些故事明确了功能的验收标准，指导我们的开发与测试。
- 持续集成与交付：我们建立了持续集成流程，通过频繁的代码集成与构建，快速发现并修复缺陷，保证了基础代码库的稳定。
- 定期站会与评审：团队每个小周期（2~3天）进行站会，同步进度、识别障碍。
📋 需求描述
1.问题陈述
用户在为旅行做规划时，面临以下痛点：
- 信息割裂：需要分别在旅游网站、天气APP等多个平台获取信息，并进行人工整合，过程繁琐
- 计划僵化：静态计划无法应对天气突变，可能导致户外活动因恶劣天气而取消，影响行程
- 决策困难：在众多景点和活动中，难以根据实时环境条件（如温度、降水、紫外线）做出最优选择
2.解决方案
开发一款智能Agent，用户只需输入目标旅游城市/地点，Agent将：
- 自动获取该地点的近期（例如，未来1-3天）精准天气预报
- 基于天气数据，智能推荐最适合的景点、活动和安排
- 生成一份结构清晰、考虑天气因素的个性化旅游计划
3.核心价值主张
- 对用户：一站式、智能化规划，获得更舒适、更安全的旅行体验
- 对团队：打造一款具有市场差异化的AI产品，展示团队在AI应用层的能力
4.用户画像
| 用户类型 | 特征 | 核心需求 |
|---|---|---|
| 自由行爱好者 | 25-40岁，喜欢自主规划，追求深度体验 | 获得独特、本地化推荐，避免天气"踩雷" |
| 家庭出游规划者 | 30-45岁，带老人孩子出行 | 室内备选方案，天气预警，舒适度优先 |
| 商务出差兼游览者 | 28-50岁，行程紧张 | 快速生成基于当时天气的高效游览建议 |
5.原型界面设计
基于用户研究和使用场景分析，我们设计了简洁直观的聊天式界面，确保用户能够轻松获取天气信息和旅行建议。
🔄 业务流描述
1.用户界面交互流程
用户交互始于简介直观的聊天界面。应用启动后，用户首先看到WeaTrip智能助手的主界面。顶部是应用名称"WeaTrip"，中间区域展示智能助手"小W"的头像和欢迎语："请输入目的地，我将根据当地天气为你生成专属出行计划"。
界面底部是用户输入区域，包含文本输入框和功能按钮。用户可以通过文本输入框直接输入城市名称或旅行需求。点击Agent名称还可以查看功能简介。
视觉设计上采用绿色系配色方案，用户消息使用绿色气泡，AI回复使用灰色气泡，确保良好的视觉层次和阅读体验。
2.智能意图识别与工具选择
当用户输入查询后，系统启动智能处理流程。MCP客户端首先将用户输入与系统提示词组合，发送给DeepSeek大语言模型进行意图分析。同时，客户端向MCP服务器查询可用工具列表，为模型决策提供支持。
工具选择逻辑：
- 简单查询 → get_weather工具（当前天气）
- 多日规划 → get_forecast工具（5天预报）
- 旅行建议 → weather_report工具（详细报告）
DeepSeek模型基于用户查询的内容进行意图分析。如果用户简单询问"北京天气"，模型可能选择get_weather工具；如果用户询问"北京未来几天天气"，则可能选择get_forecast；如果用户表达"想去北京旅游，需要天气建议"，模型更可能选择weather_report工具，因为它能生成包含穿衣建议和活动推荐的详细报告。这个决策过程完全由大语言模型自主完成，体现了系统的智能化特性。
3.天气数据获取与处理流程
一旦工具被选定，MCP客户端会调用相应的工具函数。服务器接收请求后，构建符合OpenWeatherMap API规范的查询参数，包括地理位置、API密钥、测量单位和语言设置。
4.智能报告生成与旅游建议
对于更复杂的需求，当用户请求旅游建议时，系统会调用weather_report工具。这个工具不仅返回原始天气数据，还包含提示模板功能。工具内部首先获取基础天气信息，然后使用正则表达式解析关键数据点，最后返回一个结构化数据，包含原始数据、提示模板名称和模板参数。
MCP客户端识别到这个结构后，会自动调用对应的weather_prompt提示模板。DeepSeek模型基于这个模板和具体天气数据，生成自然、专业且贴近生活的最终回复，真正实现从"天气数据"到"旅行建议"的智能转换。
5.完整的业务闭环与价值交付
最终，生成的天气报告或旅行建议通过MCP客户端返回前端界面，以对话气泡的形式展示给用户。整个业务流程从用户输入开始，经过意图识别、工具选择、数据获取、智能分析和内容生成，最终以有价值的旅行建议结束，形成了完整的业务闭环。
系统最大的价值在于将技术性的天气数据转化为用户真正需要的决策支持信息。用户不需要理解温度、湿度、风速等数据的具体含义，而是直接获得"适合穿什么衣服"、"可以进行什么活动"等实用的旅行建议，真正体现了智能助手的技术价值和应用价值。
⚙️ 实现说明
整体架构设计
MCP服务器端 - 数据服务层：
- 角色定位：天气信息工具模块的提供者，扮演"数据提供者"角色
- 核心功能：
- 通过OpenWeatherMap API获取实时天气与未来预报数据
- 通过MCP协议以标准化工具形式暴露功能给客户端
- 处理模型工具调用请求，访问外部天气数据源，格式化结果并返回标准化响应
MCP客户端 - 智能决策层：
- 角色定位：基于DeepSeek V3大语言模型的智能决策中枢，充当"智能中间人"角色
- 核心功能：
- 通过MCP协议与后端工具通信，通过DeepSeek API与大模型交互
- 理解用户自然语言问题，自动决定是否调用MCP工具
- 根据工具返回结果生成最终的自然语言回答
前端用户界面 - 交互展示层：
- 角色定位：基于现代Web技术栈的可视化交互平台，扮演"用户友好门户"角色
- 核心功能：
- 通过多模态输入方式（文字、语音、文件、快捷模板）收集用户出行需求
- 将MCP客户端返回的天气数据转化为直观的出行建议展示
- 提供流畅的对话体验和完整的对话历史管理
核心工作流程
MCP_SERVER实现说明
一、服务器端结构设计
整个服务器端系统主要由以下几个核心模块组成：
| 模块名称 | 主要功能 |
|---|---|
| FastMCP 服务实例 | 定义并运行一个名为"weather"的 MCP 服务端，负责注册所有天气工具和提示模板 |
| OpenWeatherMap 接口封装 | 实现与外部天气 API 的通信，包括异步请求与响应解析 |
| 数据格式化模块 | 将 JSON 天气数据转换为可读文本格式，便于模型理解和展示 |
| MCP 工具函数（@mcp.tool） | 提供可被模型直接调用的功能接口，如获取当前天气、获取五日天气预报等 |
| 提示模板模块（@mcp.prompt） | 定义天气报告生成模板，引导模型输出自然语言播报内容 |
| 综合报告生成器 | 结合工具数据与模板，返回结构化的报告输入，供模型自动生成天气说明 |
系统整体运行逻辑如下：
二、主要功能流程
1. 服务初始化与注册
在程序启动时，首先通过以下代码创建一个 MCP 服务实例：
mcp = FastMCP("weather")
2. API 配置与请求封装
程序中定义了与 OpenWeatherMap 的通信参数，同时实现了核心请求函数 make_weather_request(url)，用于发送异步 HTTP 请求。
3. 数据格式化逻辑
函数 format_weather_data(data, units) 负责将API返回的原始 JSON 格式数据转换为可读的多行文本输出，提取并格式化城市名、国家代码、天气描述、温度、湿度、风速等核心信息。
4. 工具函数注册与调用
本项目定义了三个主要 MCP 工具：
get_weather()：获取指定城市的实时天气信息get_forecast()：获取未来五天（以三小时为间隔）的天气预报数据weather_report()：结合天气信息与提示模板，生成结构化报告输入
5. 天气报告提示模板
程序还定义了一个提示模板函数 weather_prompt()，通过 @mcp.prompt() 装饰器注册。该模板用于指导大语言模型如何根据结构化天气数据生成自然语言报告。
6. 综合报告生成与模板绑定
weather_report() 是系统的综合性工具函数，它结合了前述两个模块的功能。最终返回结果为一个包含三部分内容的 JSON 对象。
7. 服务运行与通信机制
程序通过标准输入输出（stdio）与客户端进行通信，从而确保跨语言、跨进程的兼容性。
三、运行流程总结
MCP Server 的工作流程可以概括为以下步骤：
- 启动服务端进程并注册天气工具与模板
- 等待客户端发起工具调用请求
- 根据请求参数访问 OpenWeatherMap API
- 获取并格式化天气数据
- 将结果返回客户端，或与模板绑定生成结构化报告
- 客户端或模型据此生成自然语言回答
MCP_CLIENT实现说明
一、系统结构设计
整个系统分为以下几个核心模块：
| 模块名称 | 主要功能 |
|---|---|
| DeepSeekMCPClient | 客户端核心类，负责与 MCP 服务连接、调用工具、与模型通信 |
| MCP Server（外部服务） | 提供可调用的工具函数，如天气查询、计算器等 |
| DeepSeek API | 负责理解用户请求，决定是否使用工具，并生成自然语言回答 |
| AsyncExitStack | 异步资源管理器，用于在程序结束时自动关闭连接、释放资源 |
二、主要功能流程
1. 程序启动与参数解析
在 main() 函数中，程序首先解析命令行参数，要求输入 MCP 服务端脚本路径（.py 或 .js 文件）。
2. 创建并初始化客户端
def_init_() 函数负责创建一个DeepSeekMCPClient() 类的客户端，并进行初始化，从环境变量中读取KEY和URL。
3. 与 MCP 服务器建立连接
connect_to_server() 函数负责与 MCP 服务端建立通信连接，根据文件后缀判断使用 python 或 node 选择启动命令。
4. 处理用户请求
主循环函数 chat_loop() 提供简单的命令行交互界面，用户输入问题，程序调用 process_query() 处理，输出模型回答或工具的响应。
5. 调用模型处理请求
process_query() 是系统的核心函数，构造包含系统提示和用户输入的 messages 列表，向 MCP 服务端请求可用工具，将MCP工具信息转换为模型可理解的格式。
6. 工具调用与结果处理
若模型请求调用工具，解析工具名称与参数，调用 session.call_tool() 执行工具，获取工具执行结果并打印，将结果加入到对话历史。
7. 资源清理
当程序结束时（无论正常退出还是异常中断），cleanup() 函数会自动关闭会话和通信通道，释放资源。
前端用户界面实现说明
一、应用结构设计
1.系统架构
整个前端设计分为以下几个板块：
| 层级 | 功能模块 | 主要职责 |
|---|---|---|
| 用户界面层 | 侧边栏导航，主聊天区域，输入控制区 | 界面布局和交互设计 |
| 业务逻辑层 | 对话管理，消息处理，语音识别 | 核心业务逻辑处理 |
| 数据层 | 本地存储，状态管理 | 数据持久化和状态维护 |
| 工具层 | 文件处理，动画效果，JSON解析 | 辅助功能实现 |
2.核心功能模块
- JSON数据预处理：专门处理MCP客户端返回的JSON结构，提取纯文本内容
- 视觉系统配置：采用青绿色品牌主色，现代Inter字体，确保视觉一致性
二、主要功能流程
1.应用初始化与界面构建
在页面加载时，通过DOMContentLoaded事件初始化前端应用，确保在DOM完全加载后执行初始化。
2.数据通信与处理
前端通过HTTP API与后端Web服务器通信，专门处理MCP客户端返回的复杂JSON结构，提取出纯净的文本内容用于界面显示。
3.多模态输入处理逻辑
用户输入支持四种方式，前端负责统一处理和格式化：
- 文本输入：通过智能
textarea元素接收，支持自适应高度调整 - 语音输入：集成 Web Speech API，实现实时语音转文字功能
- 文件上传：支持图片和文档文件，提供预览和大小验证（≤5MB）
- 快捷模板：预设常用出行问题，一键填充输入框
4.对话状态管理与数据持久化
定义了完整的对话管理机制：
createNewChat()：创建新对话会话，重置界面状态loadChat(chatId)：加载指定对话历史，恢复消息记录saveChatData()：将对话数据保存到本地存储deleteChat(chatId)：删除指定对话，包括标题和消息记录
5.消息渲染与界面更新
函数 addMessage(content, isUser, skipSave) 负责将消息内容转换为可视化的聊天气泡，支持消息复制功能。
6.响应式布局与交互机制
- 桌面端（≥1024px）：固定侧边栏布局，主内容添加内边距
- 移动端：侧滑导航设计，触摸友好的交互
- 自适应：输入框高度自动调整，动画效果适配
🎯 使用示例（功能演示）
1. 智能体简介
2. 整体界面
3. 询问天气功能
(1) 北京的天气
(2) 北京未来三天的天气
(3) 北京天气报告
4. 对话管理功能
建立新对话
删除对话
5. 智能交互功能
灵活回答
语音识别输入
复制功能
搜索功能
修改对话名
修改成功
👥 小组分工
| 角色类型 | 姓名 | 担任角色 | 主要职责 |
|---|---|---|---|
| 项目管理 | 余琪丽 | 项目经理兼前后端联调 | • 制定项目计划和里程碑 • 协调开发资源和进度 • 主持前后端接口联调 • 跟踪项目风险和问题 |
| 需求设计 | 蒋伊妍 | 需求文档、原型设计 | • 收集和分析用户需求 • 编写产品需求文档(PRD) • 设计产品原型和交互流程 • 维护需求变更记录 |
| 后端开发 | 郑乐妍 | MCP架构主开发 | • 负责MCP核心架构设计 • 实现关键业务逻辑模块 • 性能优化和代码审查 • 技术难点攻关 |
| 后端开发 | 钟媛 | MCP_server开发 | • 服务端业务功能开发 • 数据库设计和优化 • 业务流程图绘制 • 接口文档编写 |
| 客户端开发 | 钟扬 | MCP_client开发 | • MCP客户端架构设计 • 核心功能模块实现 • 编写架构实现文档 • 客户端性能优化 |
| 前端开发 | 洪蓉玫 | 前端网页设计 | • 用户界面视觉设计 • 页面布局和样式实现 • 设计规范制定 • 用户体验优化 |
| 前端开发 | 黄依萍 | 前端网页设计 | • 前端页面组件开发 • 交互效果实现 • 响应式设计适配 • 浏览器兼容性处理 |
| 前端开发 | 姜品伊 | 前端设计实现 | • 编写设计实现文档 • 代码规范制定 • 前端架构优化 |
| 前端开发 | 徐紫嫣 | 前端设计实现 | • 编写组件使用文档 • 前端测试用例编写 • 技术方案验证 |
| 测试文档 | 方怡玥 | 软件测试 | • 编写测试计划和用例 • 缺陷跟踪和管理 |
| 测试文档 | 陈芳玲 | 博客撰写、前后端联调 | • 编写项目技术博客 • 协助前后端联调测试 • 用户文档编写 |
🔗 GitHub 链接
[请在此处添加GitHub仓库链接]
WeaTrip - 智能天气旅行助手，让每一次出行都遇见好天气！
