基于 MCP 协议与智谱 AI 的 12306 车次查询智能体

这个作业属于哪个课程	https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS
这个作业要求在哪里	https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS/homework/16760
这个作业的目标	使用现代 AI 工具构建一个具备“语言交互”和“行动执行”能力的智能体（Agent）。
学号	吴东鹏 3124004141、姚祥捷3124004147、杨梓南3124004145
GitHub 链接	https://github.com/south-symphony/train-query-agent

基于 MCP 协议与智谱 AI 的 12306 车次查询智能体设计与实现

一、需求描述

本项目基于 MCP 模型上下文协议与智谱 AI 大模型，开发一款具备自主决策、工具调用能力的 12306 火车票查询智能体。

项目核心目标是降低火车票查询的使用门槛：用户无需掌握特定查询指令，仅通过日常自然语言描述出行需求，智能体即可自主理解用户意图、提取关键参数、调用官方接口获取实时数据，并返回结构化的车次与余票结果，实现 “自然语言提问 - 智能决策 - 工具执行 - 结果反馈” 的完整交互闭环。

项目满足以下功能要求：

1. 基础交互能力：支持自然语言多轮对话，可友好回应用户提问、主动补全缺失的查询信息
2. 工具调用能力：遵循 MCP 协议标准封装查询工具，智能体可自主判断并调用 12306 接口执行查询操作
3. 上下文记忆能力：支持多轮对话记忆，可复用历史对话中的出发地、目的地等上下文信息，无需用户重复说明
4. 真实数据对接：对接 12306 官方公开接口，获取实时车次、出发到达时间、历时、各席别余票等真实数据
5. 可视化交互界面：提供网页端聊天界面，支持可视化对话交互，降低普通用户的使用门槛

二、业务流程设计

完整的用户交互与数据流转流程如下：

1. 用户在网页端输入自然语言问题，例如「帮我查北京到上海下周一的火车票」
2. 请求发送至后端智能体，智能体结合历史对话上下文理解用户意图
3. 大模型判断是否需要调用工具：信息不全时主动追问用户，信息完整则提取出发地、目的地、日期三个核心参数
4. 调用 MCP 协议封装的车次查询工具，向 12306 官方接口发起请求
5. 解析接口返回的原始数据，整理成结构化的车次列表
6. 将完整结果返回前端页面，格式化展示给用户
7. 保存本次对话到记忆系统，支撑后续多轮上下文交互

三、技术方案与实现

3.1 整体架构

项目采用三层分层架构，各模块职责清晰、低耦合：

• 工具层（MCP 服务端）：遵循 MCP 模型上下文协议标准，封装 12306 车次查询工具，提供标准化的工具调用接口
• 决策层（智能体核心）：对接智谱大模型，负责意图识别、工具调用决策、多轮对话记忆管理
• 表现层（Web 前端）：基于 Flask 搭建后端服务，原生 HTML/CSS/JS 实现聊天界面，负责用户交互与结果展示

3.2 技术选型

类别	技术选型
大语言模型	智谱 AI GLM-4-Flash
智能体协议	MCP (Model Context Protocol)
开发语言	Python 3.10+
Web 框架	Flask
前端技术	原生 HTML + CSS + JavaScript
HTTP 客户端	httpx

3.3 核心模块实现

（1）MCP 工具服务端

基于 FastMCP 封装 12306 查询工具，完全遵循 MCP 协议标准。通过模拟浏览器请求头、维护 Cookie 会话的方式对接官方余票接口，解决了接口重定向、反爬拦截等问题；同时实现车站名称与电报码的映射转换，支持用户输入城市名或具体站名。

（2）智能体核心模块

基于智谱 AI 的 Function Calling 能力实现工具调用决策，智能体可自主判断是否需要调用工具、调用哪个工具。实现了 ConversationMemory 记忆模块，自动保留最近 10 轮对话历史，支持上下文信息复用。针对大模型自动精简长文本的问题，采用「工具结果直出」方案，确保所有车次信息完整展示不遗漏。

（3）网页前端界面

采用前后端一体的轻量化设计，Flask 托管静态页面。前端实现了聊天气泡样式、回车发送、输入框自适应高度、清空对话等交互功能；后端服务启动后自动调用系统浏览器打开页面，无需用户手动输入地址，降低使用门槛。

四、功能演示

示例 1：自然语言对话

示例 2：基础车次查询

示例 3：多轮上下文对话

五、项目地址与使用方式

项目仓库

GitHub 仓库地址：https://github.com/south-symphony/train-query-agent

使用方式

1. 安装依赖

Windows 系统在项目根目录依次执行：

创建虚拟环境
python -m venv .venv

激活虚拟环境
.venv\Scripts\activate

安装所有依赖
pip install -r requirements.txt

2. 配置密钥

将 .env.example 重命名为为 .env ，打开 .env 文件，填入你的智谱 AI API 密钥并保存

3. 三种启动模式

模式一：命令行模式

适合开发者调试、快速测试，无需网页界面。

确保已完成依赖安装和密钥配置
在项目根目录执行：
python agent\agent_core.py
在控制台直接输入文字对话即可，输入 退出 结束程序。

模式二：网页界面模式（推荐）

可视化聊天界面，普通用户推荐使用此模式。

确保已完成依赖安装和密钥配置
在项目根目录执行：
python web\app.py
程序启动后会自动打开默认浏览器，进入聊天界面
关闭命令行窗口即可停止服务。

模式三：发行版可执行模式

无需安装 Python 环境与依赖，下载即可运行。

从 GitHub Release 页面下载发行版压缩包并解压
将解压目录中的 .env.example 重命名为 .env
打开 .env 文件，填入你的智谱 AI API 密钥并保存
双击 12306-Train-Agent.exe 启动程序
程序会自动打开浏览器进入聊天界面，关闭黑色命令行窗口即可停止。

六、小组分工

成员	负责模块	具体工作
吴东鹏	智能体核心开发	智能体逻辑开发、MCP工具封装
姚祥捷	前端开发	网页前端界面开发
杨梓南	项目设计与文档编写	需求分析、整体架构设计、博客文档撰写

七、项目心得

本次项目让我们完整实践了 AI 智能体从需求设计到工程落地的全流程，对 MCP 协议下 “感知 - 决策 - 执行” 的智能体闭环有了具象的理解，也在接口对接、工程打包、项目规范等方面积累了实战经验，提升了团队协作与技术落地的能力。

八、遇到的问题与解决

1、接口反爬拦截：直接发请求被 302 重定向，拿不到数据。解决：模拟浏览器请求头，先拿 cookie 再查询。
2、.env 编码不兼容：记事本存的文件读取报错。解决：代码加双编码兼容，UTF-8 不行自动切 GBK。
3、大模型自动删车次：车次多了被大模型精简省略。解决：查询结果直出，不经过模型二次改写。
4、端口占用启动失败：服务启动提示 5000 端口被占。解决：关闭占用端口的程序，或修改端口号。
5、模型输出不稳定：回答格式忽长忽短。解决：调低 temperature 参数，输出更稳定可控。

九、参考资料

1. MCP 官方文档 - MCP 协议官方入门教程
2. Hello-Agents 智能体实战教程 - 国内优质智能体开源学习资料
3. 智谱 AI 开放平台 - 大模型 API 服务平台
4. 12306 官方余票查询接口 - 车次数据来源