这个作业属于哪个课程 https://edu.cnblogs.com/campus/gdgy/Class78-Grade2024-CS
这个作业要求在哪里 https://edu.cnblogs.com/campus/gdgy/Class78-Grade2024-CS/homework/16761
这个作业的目标 理解 AI 智能体（Agent）的基础原理，基于 MCP（Model Context Protocol）协议开发一款出行规划智能助手；实现 “能说（自然语言多轮对话）、会做（调用外部工具 API 完成实际任务）” 的核心能力，完成前后端协同开发、测试排错，掌握智能体项目的工程化实现思路，积累大模型应用开发经验，为课程后续综合性大项目做好技术储备
学号 袁炜轩：3124004449；王安亮：3124004439；王俊霖：3124004441；张帅：3124004451

基于 MCP 的出行计划智能助手 Agent

一、需求描述

本小组实现一款出行计划智能助手 Agent，项目命名为行迹 TRAVEL ATELIER，满足作业 “能说会做” 的智能体要求：
✅ 能说：支持自然语言多轮对话，理解用户口语化出行相关提问，结合上下文给出通顺自然的中文回答；
✅ 会做：基于 MCP（Model Context Protocol）协议调用独立工具服务，自动执行天气查询、地点检索、地理编码、路线规划；支持单工具调用，也支持多个工具串联组合完成复杂出行任务。

功能清单：

  1. 实时天气查询、未来多日天气预报；
  2. 地名转经纬度（地理编码）；
  3. 指定位置周边 POI 搜索（餐厅、商铺等）；
  4. 起止点之间地铁路线规划；
  5. 复合场景自动链式调用工具（同时查天气 + 规划路线）；
  6. 异常输入容错，识别无效地点并返回友好提示，服务不崩溃；
  7. Web 对话界面，账号登录使用，对话记录持久化保存。

非功能需求：

  1. 使用 MCP 协议，工具服务与 Agent 调度逻辑解耦，后续新增工具不需要大量修改 Agent 核心代码；
  2. 后端 FastAPI 端口 8000，前端服务端口 8080，两个服务独立运行；
  3. 使用 SQLite 本地数据库存储用户账号、会话和对话消息；
  4. 配置文件 .env 单独管理密钥，敏感信息不提交到代码仓库；
  5. 代码统一托管在小组公共 GitHub 仓库。

二、业务流描述

整体遵循 ReAct 智能体循环流程：

  1. 用户打开前端页面 http://localhost:8080，登录后在对话框输入自然语言提问；
  2. 前端把对话消息发送给 FastAPI 后端 Agent；
  3. Agent 读取历史对话上下文，将用户问题 + MCP 可用工具列表一起提交给大模型；
  4. LLM 自主判断是否需要调用工具、选择哪个工具、生成对应的参数；
  5. 需要调用工具时，Agent 通过 MCP 协议请求对应的工具服务，拿到工具返回结果；
  6. 将工具返回的数据再次交给大模型，整理成通顺自然语言回答；
  7. 回答回传到前端展示，本次对话自动写入 SQLite 数据库持久保存；
  8. 等待用户下一轮提问，循环执行。

复合场景示例（用户输入：我明天下午从广工番禺校区去广州南站坐高铁，帮我看看明天广州天气，顺便给我规划合适的地铁路线）：

  1. LLM 判断需要同时调用天气工具和路线工具；
  2. 调用 weather_forecast 获取广州明日天气预报；
  3. 调用两次 geo_geocode，分别解析【广东工业大学番禺校区】、【广州南站】坐标；
  4. 调用 route_plan，传入两点坐标，生成地铁路线方案；
  5. LLM 汇总天气信息、换乘站点、耗时、票价，综合给出出行建议（是否带雨具、建议提前出发时间）；
  6. 整合后的完整回答返回前端展示。

系统分层架构：

  1. Agent 调度层（FastAPI :8000）：会话管理、JWT 鉴权、MCP 服务管理、工具调用编排、数据库读写；
  2. MCP 工具服务层（独立服务）
    weather MCP：weather_now（实时天气）、weather_forecast（多日预报）
    place MCP：geo_geocode（地理编码）、place_search（POI 检索）、route_plan（路线规划）
  3. 前端交互层（行迹 TRAVEL ATELIER）：登录页面、聊天对话界面，展示模型回答和工具执行结果。

三、实现说明

3.1 技术选型

开发语言：Python 3.11
智能体协议：MCP（Model Context Protocol）
后端框架：FastAPI + uvicorn
前端：自研页面「行迹 TRAVEL ATELIER」
数据库：SQLite（轻量本地数据库，无需单独部署）
LLM：支持 function call 的大模型接口
依赖管理：pip

3.2 项目目录结构

raungong/
├── backend/
│ ├── main.py # FastAPI 入口，Agent 调度、MCP 管理
│ └── config.py # 环境变量校验（JWT 密钥长度校验）
├── frontend/
│ └── main.py # 行迹前端页面代码
├── scripts/
│ └── init_db.py # 数据库初始化脚本，建表 + 创建 root 管理员账号
├── data/ # 自动生成，存放 sqlite 数据库 app.db
└── .env # 环境配置文件（不上传 git）

3.3 关键配置说明

.env 配置内容：
TPA_JWT_SECRET=abc123456789abc123456789abc123456
TPA_ROOT_PASSWORD=root123456
TPA_LLM_API_KEY=sk-dummy
TPA_AMAP_KEY=dummy

注意：JWT 密钥强制要求长度 ≥32 字符，长度不足会直接校验失败，无法启动后端。
日志中会提示 RAG 模块缺少 Embedding Key，RAG 知识库功能禁用，但天气、地点、路线 MCP 工具调用不受影响。

3.4 部署步骤

  1. 拉取仓库代码，安装全部依赖；
  2. 编写 .env 配置文件；
  3. 初始化数据库：
    py -3.11 scripts/init_db.py
  4. 新开终端，启动后端服务：
    py -3.11 -m uvicorn backend.main:app --reload --port 8000
    成功标识日志：
    MCP Server weather 已连接，发现 2 个工具：weather_forecast, weather_now
    MCP Server place 已连接，发现 3 个工具：geo_geocode, place_search, route_plan
    后端就绪: http://127.0.0.1:8000/api/v1
    Application startup complete.
  5. 再新开终端，启动前端服务；
  6. 浏览器访问 http://localhost:8080，账号 root，密码 root123456 登录使用。

⚠️ 后端、前端两个终端窗口必须同时保持运行。

3.5 开发过程遇到的问题与解决

  1. 直接输入 uvicorn 提示不是内部命令：使用 py -3.11 -m uvicorn 以模块方式启动；
  2. JWT 密钥过短启动失败：增加密钥长度至 32 位以上；
  3. MCP 服务连接失败：核对.env 配置里 MCP 服务地址；
  4. 模型生成偶发失败：在测试过程中复现，属于大模型调用链路不稳定问题，记录在排错日志中。

四、使用示例（功能演示，附截图说明）

图 1：后端控制台截图，MCP weather、place 连接成功日志
16372ba84107bcf854bcb45d41f97ad1

图 2：行迹 TRAVEL ATELIER 对话主界面
9ffe877d063633ed76acfe4a2e561bae

图 3：TC001：查询广州现在的天气，对话结果
d087c8f4ade595b8b0997fc12930ce43

测试用例表格：
编号，用户输入提示词，预期效果
TC001，查询广州现在的天气，自动调用 weather_now，返回广州实时温度、湿度、风向、天气情况
TC002，帮我查广州接下来 3 天的天气预报，调用 weather_forecast，返回连续三天最高最低气温、天气、降水概率
TC003，帮我找广州南站附近的粤式茶餐厅，调用 place_search，以广州南站为中心，返回周边茶餐厅 POI 信息
TC004，获取广东工业大学番禺校区的坐标，调用 geo_geocode，返回该校区经纬度
TC005，规划从广工番禺校区到广州南站的地铁路线，先解析两点坐标，再调用 route_plan，返回地铁换乘方案、耗时、预估票价
TC006，我明天下午从广工番禺校区去广州南站坐高铁，帮我看看明天广州天气，顺便给我规划合适的地铁路线，自动串联调用天气 + 地理编码 + 路线规划多个工具，综合天气给出出行提醒和路线方案
TC007，查询火星的天气，识别为无效地点，返回友好提示，程序正常运行不崩溃

五、GitHub 仓库链接

https://github.com/zs666700/raungong

六、小组分工

袁炜轩（3124004449）：后端文件编写，完成 Agent 调度逻辑、MCP 服务对接、数据库相关代码开发；
王安亮（3124004439）：博客文档撰写，整理整套实验文档、校对全文、输出博客园发布文稿；
王俊霖（3124004441）：测试人员，设计全部测试用例，执行功能测试、记录排错日志，反馈系统 bug；
张帅（3124004451）：前端文件编写，完成「行迹 TRAVEL ATELIER」网页对话界面，对接后端接口、调试交互展示。

七、组员心得

袁炜轩：本次作业我主要负责后端代码的编写与 MCP 对接。在开发之前，我只是对 MCP 协议和 Agent 工具调用有理论层面的了解，真正动手写调度逻辑之后，才理解 MCP 把工具独立成服务的解耦优势。开发过程中遇到了参数传递、工具返回值解析、JWT 校验等不少问题，反复调试后才打通完整调用链路。这次实践让我对 ReAct 智能体的运行循环有了直观认识，也熟悉了 FastAPI 的开发方式，为后续大项目积累了后端开发经验。

王安亮：我负责本次作业的博客文档撰写。整理文档的时候，需要把需求、流程、部署、测试、分工全部梳理清楚，让整个项目逻辑连贯。在和组员对接素材、整合后端、前端、测试资料的过程中，我完整复盘了整个智能体的工作流程，也意识到工程文档在小组协作里的重要性。同时我也体会到，一个能演示的 AI 项目，除了代码能跑，清晰的文档和规范的测试记录同样必不可少。

王俊霖：我在小组里担任测试人员，负责设计测试用例、跑通全部场景、记录 bug 和排错日志。从单工具调用、多工具串联调用，再到异常边界场景，我一轮一轮进行验证。测试的时候我发现复合链式场景最容易出问题，模型偶尔会选错工具或者参数出错，同时还会遇到截图里这样生成失败的情况，我们和后端同学一起定位、调整 prompt。测试的经历让我知道智能体和普通程序不一样，它的输出存在不确定性，测试思路不能完全照搬传统软件的测试方案，收获很大。

张帅：本次任务我负责前端页面「行迹 TRAVEL ATELIER」的开发。这个界面包含对话窗口、侧边行程管理栏、知识库 RAG 模块，还有管理员登录体系。开发过程中我主要处理前后端消息收发、对话内容渲染、界面样式调整，对齐后端接口格式，保障消息正常传递。通过这次开发，我看懂了前端、Agent 后端、MCP 工具三者的数据流转链路，对大模型应用的整体交互流程有了更深的理解。