第四次软件工程作业

这个作业属于哪个课程	软件工程
这个作业要求在哪里	https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS/homework/16760
这个作业的目标	构建一个能理解用户需求、调用工具获取外部信息并执行任务、再用自然语言反馈结果的智能体。
学号	A：严翊郗（3224004119）；B：曾盈洁（3224004120）；C：许艺琳（3224004083）；D：李蔓淇（3224004080）；E：邓炜娟（3224004116）
GitHub链接	https://github.com/Ajie8021/weather-travel-assistant

天气出行助手：会查询天气、生成并修改行程的 AI Agent

一、项目简介

我们小组实现了一个天气与出行规划 Web 应用，并在原有天气查询和计划生成能力上集成了聊天式 AI Agent。用户可以在聊天页面用自然语言查询天气、生成单日计划，也可以在后续对话中修改计划中的某个时段。Agent 会调用天气和行程工具执行操作，再以中文回复，并展示工具实际返回的天气或计划信息。

项目代码：weather-travel-assistant 公共仓库
在线体验：天气出行助手 Agent

项目使用 Java 21、Spring Boot 和 Thymeleaf。天气数据来自 Open-Meteo；聊天模型通过 DashScope 的 OpenAI 兼容 Chat Completions 接口调用，默认模型配置为 qwen3.7-plus。后端通过 Spring AI MCP Server 暴露天气工具，也可以通过 MCP Client 连接配置的 MCP 服务。项目保留了传统的天气查询和表单生成计划页面，同时提供 /chat 聊天入口。

二、需求描述

出行规划需要综合目的地、日期、天气和活动偏好。只返回天气数据不能直接解决“这一天适不适合户外活动”“下雨时要带什么”以及“我只想把下午改成室内活动”等实际问题。因此，本项目实现一个能对话并能调用工具的天气出行 Agent，完成从需求理解到计划执行的主要流程。

项目主要需求如下：

1. 用户可用自然语言询问指定城市和日期的天气，或提出出行计划需求。
2. Agent 能够调用工具搜索城市、查询真实天气并生成出行计划，而不是仅凭模型生成天气信息。
3. 计划结合天气情况和用户偏好，给出上午、下午、晚间活动建议，以及天气摘要、穿衣建议、携带物品和注意事项。
4. 用户在多轮对话中可以修改目的地、日期、偏好或某个时段；没有要求修改的计划条件应尽量保留。
5. 城市有多个候选时，Agent 展示候选并等待用户确认；天气字段缺失或工具出错时，明确说明情况，不编造数据。

三、业务流程

用户在 /chat 输入自然语言
             ↓
聊天接口将消息和会话历史交给 Agent
             ↓
DashScope 兼容模型理解意图并选择工具
             ↓
┌─────────────────────────────────┐
│ 搜索城市 → 用户确认地点          │
│ 查询天气 → Open-Meteo             │
│ 生成计划 → 天气规则与计划服务      │
│ 修改计划 → 保留其他会话条件        │
└─────────────────────────────────┘
             ↓
Agent 根据工具的真实返回组织中文回复
             ↓
页面展示回复、天气卡片或结构化行程

四、实现说明

1. 自然语言交互与模型调用

用户通过 /chat 页面输入消息，前端调用 POST /api/chat。请求可携带 sessionId 和必填的 message。后端将当前对话历史和工具定义发送给支持 OpenAI Chat Completions 工具调用格式的模型。模型可以返回普通文本，也可以请求调用天气或行程工具；后端执行工具后将结果交回模型，形成“理解需求—调用工具—根据结果回复”的闭环。

聊天模型默认从运行环境读取 DASHSCOPE_API_KEY，模型地址及名称可通过 DASHSCOPE_BASE_URL、DASHSCOPE_MODEL 配置。密钥不写入代码仓库。未配置密钥时，聊天接口会返回配置提示，传统表单功能仍可使用。Agent 对工具调用轮数设有上限，避免单轮请求无限调用工具。

2. 天气查询工具

天气服务通过 Open-Meteo 地理编码接口搜索城市，再通过天气预报接口查询天气，并把结果转换成项目内部统一的天气数据结构。天气数据包括地点、日期、天气代码、最高/最低温、降水概率、降水量、风速和数据来源等字段。

天气工具包括：

• search_city：根据城市名返回地点候选及其行政区、国家、坐标和时区。
• get_weather：查询已确认地点在指定日期的天气。

当城市候选不唯一时，Agent 会等待用户按序号或完整地点名称确认，再使用确认后的地点查询天气。日期按目的地当地日期处理；天气字段为空时保留为空值，不当作 0 或晴天。

3. 出行规则和计划生成

TravelRuleService 根据标准化天气数据分析天气状况和风险；TravelPlanService 综合出行请求、活动偏好和规则分析结果，生成结构化的单日计划。业务规则包括：

判断项	项目采用的规则
高温	最高温度 ≥ 35℃ 时给出防暑等提醒
低温	最低温度 ≤ 5℃ 时给出保暖提醒
大风	风速 ≥ 30 km/h 时提示关注风力并调整相关户外安排
降水风险	降水概率 ≥ 50% 时提醒携带雨具并评估户外活动

活动偏好包括 OUTDOOR（户外）、INDOOR（室内）和 FOOD（美食）。计划包含天气摘要、上午/下午/晚间活动、穿衣建议、携带物品及风险提示。未知天气代码或缺失的天气字段不会被当成天气良好；活动建议以通用活动类型为主，不虚构具体景点开放时间、票价或精确路线。

Agent 可调用 generate_travel_plan 生成计划。用户提出“下午改成室内活动”一类要求时，Agent 使用当前会话的城市、日期及现有计划，只修改指定时段，并保留其他未修改内容。

4. MCP 接入

项目以 Spring AI MCP Server 暴露天气能力，默认 MCP 端点为 POST /mcp，服务使用无状态 Streamable HTTP 模式。天气 MCP Server 注册 search_city 和 get_weather 两个只读工具；计划能力通过 generate_travel_plan 工具封装，复用已有天气服务和计划生成服务，不在工具层重复实现业务规则。

聊天 Agent 默认可直接使用仓库内的天气与计划服务。配置 MCP_ENDPOINT 后，MCP Client 会发现并调用远端 MCP 服务中的天气/计划工具，并只向模型提供约定的工具白名单。Agent 使用 JSON-RPC 与 MCP 服务交互；仓库说明包含对无状态协议及旧版初始化握手的兼容处理。

5. 多轮会话与前端

会话由 sessionId 区分。系统在内存中保存消息历史、待确认地点、已确认地点、最近天气和最近计划；会话 30 分钟无活动后清理。服务重启后会话记录不会保留。

前端采用 Spring Boot + Thymeleaf 服务端渲染，聊天页提供自然语言输入和回复展示，并可渲染 Agent 回复中的 Markdown、天气信息及计划结果。原有 /weather 天气查询页面和 /plan/generate 表单计划流程也保留。

五、使用示例

示例一：查询天气

用户： 查一下明天广州的天气。

Agent 执行： 搜索广州地点；若只有唯一候选，则查询该地点明天的天气；若有多个候选，则先请用户确认。

Agent 回复： 根据天气工具返回的真实数据说明天气情况，并在页面展示天气信息。具体数值以实际查询结果为准。

示例二：生成美食主题行程

用户： 帮我安排明天广州一日游，偏好美食。

Agent 执行： 调用天气查询和单日计划生成能力，结合天气与 FOOD 偏好生成计划。

页面结果： 天气摘要、上午/下午/晚间活动建议、穿衣建议、建议携带物品和注意事项。

示例三：多轮修改

用户： 下午改成室内活动。

Agent 执行： 根据当前会话中的已有计划，仅调整下午活动安排，并保留目的地、日期及其他时段计划。

Agent 回复： 说明修改后的下午安排；工具调用结果会由后端实际执行后记录，不由页面伪造成功状态。

六、测试与验证

仓库包含天气服务、天气 MCP 工具、天气规则、计划生成、聊天控制器、会话存储及 Agent 服务等测试。测试重点覆盖输入校验、天气数据转换、工具参数、计划生成、天气风险和多轮会话相关行为。

仓库中的 Agent 端到端验收记录（2026-10-21）记载：DashScope qwen3.7-plus 真实对话成功；Agent 实际调用 search_city 与 get_weather 查询广州天气；随后调用 generate_travel_plan 生成美食偏好计划；在同一会话中调用 modify_travel_plan 将下午活动改为室内活动，并保留其他安排。记录中的天气来源为 Open-Meteo。该记录是仓库提交的验收材料，演示时的实时天气会随日期变化。

本地运行方式及环境变量配置可参照仓库的 Agent 聊天使用说明。运行聊天 Agent 需要 Java 21 和 DashScope API Key；Open-Meteo 天气服务还需要运行环境能够访问其接口。

七、小组分工

成员	分工
成员 A（严翊郗，3224004119）	负责项目前期需求梳理和需求文档等资料编写，整理项目文档，并撰写博客随笔。
成员 B（曾盈洁，3224004120）	负责主要业务代码，包括天气规则、出行计划生成及计划工具等；参与项目协作、测试与部署。
成员 C（许艺琳，3224004083）	负责主要 Agent/后端代码，包括天气接口与 MCP 工具、自然语言对话、模型配置、工具调用编排和会话状态等。
成员 D（李蔓淇，3224004080）	完成前端页面与交互界面，包括聊天及天气/计划结果展示。
成员 E（邓炜娟，3224004116）	负责测试与功能验收，覆盖天气、行程及 Agent 多轮工具调用等流程。

八、小组成员心得

成员 A：严翊郗（3224004119）

这次项目中，我主要负责前期需求梳理和需求文档等资料编写，也承担了项目文档整理和博客随笔撰写工作。前期整理需求时，我需要把“查询天气、生成出行计划”这样的想法进一步拆解成用户输入、系统处理流程和预期结果，并梳理天气、偏好、行程建议等功能之间的关系，为后续模块划分和开发提供依据。

这段经历让我认识到，需求文档不是项目开始时的形式工作。把需求和流程写清楚，有助于组员对齐功能边界、减少接口理解偏差，也让测试时有明确的检查依据。随着项目实现，我也更具体地理解了 Agent 如何通过工具获取天气、应用业务规则并根据多轮对话调整计划。通过这次作业，我提升了需求表达和技术文档整理能力，也体会到前期沟通与持续协作对项目顺利完成的重要性。

成员 B：曾盈洁（3224004120）

这次天气出行助手项目让我体验了从项目创建、协作开发到测试部署的完整流程，也让我对软件工程有了更深入的认识。

这是我第一次在 GitHub 上与他人合作开发项目，也是第一次使用 Spring Initializr 创建 Spring Boot 项目。从建立仓库、划分模块，到统一接口规范、处理代码合并冲突，我逐渐体会到团队协作不仅需要完成自己的任务，还需要重视沟通与配合。

在业务开发中，我第一次深入了解智能体的内部逻辑。天气出行助手并非简单地调用大语言模型生成回答，还需要结合天气数据、业务规则和用户偏好进行分析与决策。此外，项目中大量的单元测试也让我认识到，测试不仅是检查代码能否运行，更是保障系统可靠性的重要环节。

最后，这是我第一次使用 DigitalOcean App Platform 部署项目。实际部署过程中遇到的问题让我意识到，本地运行正常并不代表线上环境一定稳定，还需要考虑外部服务、网络连接等因素。

通过这次实践，我不仅积累了新的技术经验，也更加理解了规范设计、团队协作、测试验证和部署运维的重要性。这些收获将为今后的软件开发学习提供很大帮助。

成员 C：许艺琳（3224004083）

在本次“天气查询与智能出行规划助手”项目中，我主要负责天气查询与接口接入。具体完成了 Open-Meteo 地理编码和天气预报接口的调用，实现用户输入城市后查询指定日期的最高温、最低温、降水概率、风速等天气信息；同时处理了同名城市、中文城市名称与地区匹配等问题，补充了北京、东莞等常用城市的标准坐标，避免查询到不符合实际的地点。除此之外，我还编写了天气模块的单元测试、MCP 天气工具和与智能体模块的接口说明，协助完成前后端联调与部署配置。

通过这次实践，我体会到接口开发不仅是“调用 API”，更重要的是参数校验、异常处理、数据准确性和模块协作。尤其是在多人项目中，及时提交代码、写清使用文档、保证接口稳定非常重要。这次项目提升了我使用 Spring Boot、Git 和第三方接口进行实际开发的能力。

成员 D：李蔓淇（3224004080）

这次项目中，我参与了前端页面和 Agent 交互实现，体会到界面需要把天气查询、行程规划和智能对话组织成连贯流程，页面字段与接口约定也必须保持一致。Agent 开发让我认识到，智能体还需要连接业务工具，并处理地点歧义、信息缺失和多轮状态。

测试反馈也让我关注到结果的可读性：字体和 Markdown 展示会影响用户理解。通过联调和修正，我熟悉了前后端衔接、工具调用及体验优化，也认识到尽早确认接口并按完整用户流程验证的重要性。

成员 E：邓炜娟（3224004116）

通过本次天气旅游智能体的测试，我对软件测试流程和方法有了更深入的认识。我通过实际操作网页、设计不同类型的测试问题，从天气查询、上下文理解和地点识别等角度验证系统功能，并根据输出判断结果是否符合预期。

测试过程中，我也认识到除了基本功能，还要检查连续对话的上下文衔接、异常输入处理和用户需求是否得到完整响应。记录测试结果、分析问题提升了我发现和整理问题的能力，也让我体会到测试对系统可靠性和用户体验的重要作用。

九、总结

本项目展示了天气出行场景中的 Agent 工作方式：模型理解用户表达并决定调用工具，后端工具连接天气服务和业务规则，执行结果再返回模型组织成用户可读的回复。地点歧义确认、真实天气查询、结构化计划生成和多轮局部修改，让系统具备了自然语言交互与实际任务执行能力。

项目也让我们认识到，Agent 的可靠性不只取决于模型回答，还依赖工具边界、数据校验、会话状态和异常处理。后续可以继续改进持久化会话记忆、丰富语音交互，以及部署环境下 MCP 服务的认证与访问控制。