第二次软工作业

这个作业属于哪个课程	https://edu.cnblogs.com/campus/gdgy/SoftwareEngineering24
这个作业要求在哪里	https://edu.cnblogs.com/campus/gdgy/SoftwareEngineering24/homework/15646
这个作业的目标	构建一个能通过自然语言交互理解用户意图，并自动调用工具或执行操作来完成实际任务的AI智能体。
学号	3224004346 3224004575 3224004537 3224004455

一、项目简介

本项目为“天气出行智能助手”，调用Open-Meteo天气API与智谱AI大模型API，实现精准气象查询与个性化出行规划。系统采用AI+规则双引擎架构，支持多轮对话记忆与偏好持久化，服务异常时自动降级。配套Streamlit网页端提供流畅交互，整体注重模块化与高可用性，致力于提供稳定、智能的出行决策支持。

项目仓库地址：https://github.com/caogaobener/rg4_homework

项目运行成果：天气出行智能体（命令行端 + 网页端 http://localhost:8501/ ）

二、团队成员分工

成员1 谢惠敏
负责智能体核心架构与调度开发，完成 agent_core.py、main.py 开发；制定接口规范，搭建项目框架，实现模块间整体调度。

成员2 饶梦雯
负责天气数据接口开发，实现 Open-Meteo 天气 API 调用(weather_api.py) ，完成城市天气查询与数据解析，保证数据稳定可靠。

成员3 严小颖
负责多轮记忆管理、出行规划与前端界面开发，实现多轮对话记忆功能（memory.py)，对接智谱 AI API生成建议(planner.py)；基于 Streamlit 完成前端页面 (app.py)，实现可视化交互。

成员4 阿丽热·阿布来克木
负责项目代码集成、全流程联调测试与问题排查；统一文件结构，解决环境与模块冲突，确保双端稳定运行；完成项目收尾与博客撰写。

三、需求描述

1. 支持多城市实时天气与多天预报查询
2. 基于天气数据+用户偏好，生成穿衣/活动/提醒等出行建议
3. 记住用户偏好（如"不喜欢下雨"）和最近查询城市，支持多轮连贯对话
4. AI服务异常时自动降级至规则引擎，保障基础功能可用
5. 提供命令行 + 网页双端交互界面

四、业务流描述

核心业务场景流

（1）场景1：查询天气并自动生成建议
步骤1：用户输入"北京天气怎么样"
步骤2：意图识别模块分析输入，识别为 query_weather 意图，提取实体 city="北京"
步骤3：调用 weather_api.get_weather("北京")，内部执行：
调用 Open-Meteo 地理编码API获取经纬度
调用天气预报API获取实时数据
标准化返回字典（包含city、text、temp、humidity等字段）
步骤4：格式化天气信息，生成"北京当前：晴，25°C..."文本
步骤5：自动调用 planner.generate_plan(weather, preferences)，生成穿衣、活动、提醒建议
步骤6：更新 memory.json，设置 last_city="北京"
步骤7：返回完整回复（天气数据 + 出行建议 + 偏好提示）

(2) 场景2：设置用户偏好
步骤1：用户输入"我不喜欢下雨天"
步骤2：意图识别模块识别为 set_preference 意图，提取 preference="avoid_rain"
步骤3：调用 memory.update_preference("avoid_rain")，将偏好追加到列表
步骤4：调用 memory.save_memory()，持久化保存到 memory.json
步骤5：返回"已记住：您不喜欢下雨天。下次出行建议会考虑这个偏好！"
步骤6：后续查询天气时，planner模块读取 preferences 列表，根据 avoid_rain 偏好优先推荐室内活动

(3) 场景3：多轮对话记忆（继承上下文）
步骤1：用户首次输入"上海天气"，系统识别并更新 last_city="上海"
步骤2：用户再次输入"明天呢？"，未指定城市
步骤3：意图识别模块从 memory.json 读取 last_city="上海"，作为默认城市
步骤4：调用天气API查询上海明日预报
步骤5：返回"上海明天：多云，20~28°C"及相关建议

(4) 场景4：AI服务异常自动降级
步骤1：用户输入"去广州穿什么"，识别为 ask_advice 意图
步骤2：调用 weather_api.get_weather("广州") 成功获取天气数据
步骤3：调用 planner.generate_plan(..., use_ai=True) 尝试AI模式
步骤4：智谱AI API超时或返回错误
步骤5：planner.py 中的 try-except 捕获异常，打印日志" AI调用失败，已自动降级使用规则引擎"
步骤6：自动调用 _generate_with_rules(weather, preferences) 执行本地规则逻辑
步骤7：返回规则引擎生成的建议（基于温度区间、天气类型、偏好关键词判断）
步骤8：程序正常运行，用户无感知

前端交互流程（Streamlit网页端）

步骤1：用户访问 http://localhost:8501 ，浏览器加载 app.py
步骤2：执行 st.set_page_config 设置页面标题和布局
步骤3：渲染侧边栏
步骤4：初始化聊天历史
步骤5：用户输入
步骤6：调用后端
步骤7：显示回复
步骤8：状态同步

五，实现说明

1. 核心调度模块（agent_core.py）
   负责意图识别、模块调度、对话流程控制，串联 API 调用与记忆功能。

def agent_dispatch(user_input, memory):
    city = memory.get_last_city()
    weather = weather_api.get_weather(city)
    advice = planner.get_advice(weather, memory)
    memory.update_history(user_input, advice)
    return weather, advice

2. 天气接口模块（weather_api.py）
   使用 Open-Meteo 天气 API，通过 HTTP 请求获取实时气温、天气状况等数据。

def get_weather(city):
    url = f"https://api.open-meteo.com/v1/forecast?latitude=xx&longitude=xx&current_weather=true"
    res = requests.get(url)
    return res.json()

3. 记忆管理模块（memory.py）
   多轮对话记忆核心：基于 JSON 持久化存储，自动记录城市、偏好、对话历史，实现上下文继承。

class Memory:
    def update_city(self, city):
        self.data["last_city"] = city
    def add_preference(self, pref):
        if pref not in self.data["prefs"]:
            self.data["prefs"].append(pref)

4. 出行规划模块（planner.py）
   调用智谱 AI API，结合天气与用户偏好生成出行建议；网络异常时自动切换规则引擎。

def _generate_with_ai(weather: dict, preferences: list) -> str:
    """AI模式生成建议"""
    if not weather.get("success"):
        return "⚠️ 天气数据获取失败"
    
    # 构造Prompt
    city = weather.get("city", "该城市")
    text = weather.get("text", "未知")
    temp = weather.get("temp", 25)
    humidity = weather.get("humidity", 50)
    pref_text = "、".join(preferences) if preferences else "无特殊偏好"
    
    prompt = f"""你是一个旅行规划师。根据以下信息给出建议：

【天气】{city}，{text}，{temp}°C，湿度{humidity}%
【偏好】{pref_text}

请按格式回复：
穿衣建议：
推荐活动：（3个）
特别提醒：
"""

5. 双端交互模块
   命令行：轻量测试
   网页前端（Streamlit）：展示记忆状态、聊天历史，界面直观友好

六、使用实例

基础功能测试：

1. 输入需要查询天气状况的地点，可以输出当前或者未来多天天气信息并自动附带AI出行建议

2. 可以设置偏好，并且偏好会影响出行建议

3. 拥有多轮记忆功能，可以做到城市继承以及偏好累加

4. 实现系统指令：清空记忆，帮助，退出；以及异常处理测试

七、开发问题与解决方案

模块导入错误：统一文件路径
网页无法运行：使用 streamlit run app.py
记忆不同步：修正 JSON 读写逻辑
依赖缺失：安装 requests / streamlit / python-dotenv
API 调用失败：增加异常捕获
天气查询无建议：优化调度逻辑自动联动

八、项目总结与心得体会

成员一：本次我负责智能体核心调度模块。在搭建意图识别与工具路由时， 面对依赖冲突、模块命名覆盖及Git代理报错等问题，我掌握了快速定位与隔离排查的方法。 最大收获是认识到：可靠的Agent不仅靠大模型，更在于稳健架构与容错设计。 通过接口预定义与Mock降级，有效支撑了团队并行开发。此次实践让我真正理解了AI Agent“能说会做”背后的底层逻辑，受益匪浅。

成员二：通过本次天气查询模块的开发，我从零基础完成了Python后端工具模块的开发实践，收获了丰富的技术经验和团队协作认知：

1. 掌握了第三方API的调用方法，包括网络请求发送、请求参数构造、返回数据解析，以及针对API调用的异常处理技巧；
2. 理解了团队开发中接口规范的重要性，严格遵循约定的接口和数据格式，是模块间无缝对接、提升开发效率的核心；
3. 学会了排查开发中的常见问题，如接口404、环境配置失效、数据格式不匹配等，提升了问题定位和解决能力；
4. 体会到了工具模块开发的容错性要求，针对各种异常场景做全面的错误处理，才能保证模块在实际使用中的稳定性；
5. 积累了Python模块化开发的经验，学会了将功能拆分为独立函数、对外提供标准化接口，让模块具备高可用性和可集成性。
   本次开发也让我认识到，零基础开发后端模块并非难事，核心是理清业务逻辑、遵循开发规范、做好细节处理，同时团队间的沟通和约定能大幅降低开发和集成成本，为后续的全栈开发积累了宝贵的实战经验。

成员三：我主要负责记忆中枢、出行规划模块及前端界面的开发。开发过程中解决了API依赖配置、AI与规则双引擎逻辑调试、前后端模块导入等问题。通过打印调试和代码隔离，我进一步掌握了Python异常处理、作用域和字典操作。在前端部分，我使用Streamlit搭建聊天界面并对接后端，解决了状态管理和数据同步问题。同时我也认识到好的代码不仅要功能正确，更要考虑健壮性和用户体验——比如AI调用失败时自动降级到规则引擎，系统指令优先于意图识别等设计，都是为了让程序更稳定、更智能。

成员四：我处理项目代码集成、全流程联调测试与问题排查、统一文件结构、解决环境与模块冲突，以及项目收尾与博客撰写。在集成过程中，我遇到了模块导入路径不一致、虚拟环境依赖冲突、前后端数据格式不兼容等问题，通过逐一排查日志、调整目录结构、统一接口规范，最终实现了命令行与网页双端稳定运行。这次实践让我深刻认识到，代码集成不是简单的拼凑，而是需要理解每个模块的设计思路、接口约定和异常处理机制。特别是在解决 KeyError、ModuleNotFoundError 等具体问题时，我学会了如何通过打印调试、版本锁定、路径配置等手段定位根源。项目收尾阶段的博客撰写也让我意识到，文档不仅是功能说明，更是对开发过程的梳理与沉淀，对后续维护至关重要。