第四次作业-构建一个能说会做的智能体

ExamMate：面向大学生的智能学习与备考任务推进 Agent

这个作业属于哪个课程	https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS
这个作业要求在哪里	https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS/homework/16760
这个作业的目标	创造一个期末复习的小助手
学号	汪琳3224004195、陈沐兰3224004191
GitHub 链接	https://github.com/Stella-0203/Exammate.git

一、Agent 定位

ExamMate 是面向大学生的 AI 学习助手，结合日常知识问答与备考任务推进能力。Agent 以聊天为主要交互入口，围绕课程组织学习资料、学习成果和任务状态，帮助用户逐步完成考纲整理、复习缺口分析和复习计划制定等备考工作。

与直接使用通用大模型相比，ExamMate Agent 不仅需要回答用户当前提出的问题，还需要结合课程资料、已有学习成果和任务执行状态，判断下一步应该做什么，并在必要时调用相关业务能力。对于已经生成的有效成果，Agent 应优先复用；当资料或需求发生变化时，应判断成果是否需要更新，而不是重复执行全部流程。

二、需求描述

2.1 核心需求

1. 理解用户意图

Agent 需要识别用户当前的需求，并区分日常知识问答与备考任务。

• 日常问答：例如“TCP 三次握手是什么？”，直接回答问题。
• 整理考纲：根据课程资料整理考试范围和知识点。
• 分析复习缺口：结合考纲与课程资料，分析各知识点的资料覆盖情况。
• 制定复习计划：结合考纲、复习缺口及考试相关信息，制定复习安排。
• 其他需求：根据具体情况回答问题，或向用户询问必要信息。

2. 获取课程上下文

Agent 应以当前课程为主要上下文，按需获取相关资料、已有考纲、分析结果、复习计划及其他学习成果，避免要求用户反复提供已经存在的信息。

不同课程之间的数据和上下文应相互隔离。切换课程后，Agent 应使用对应课程的资料和学习成果。

3. 规划并推进任务

Agent 应根据用户目标和现有数据，确定任务执行顺序，检查前置条件，并调用相应的业务能力。

例如，用户要求分析复习缺口时，如果当前没有可用考纲，Agent 应先整理或确认考纲，再开展覆盖分析，而不是直接生成缺乏依据的分析结果。

4. 管理学习成果

考纲、复习缺口分析和复习计划等重要结果应能够独立保存，并在后续对话中重复查看和使用。

• 已存在且有效的成果：优先读取和复用。
• 缺少必要成果：按需生成。
• 课程资料或考纲发生变化：判断相关成果是否过期，并标记为“待更新”。
• 普通知识问答：仅在聊天中展示回答，不默认保存为学习成果。

5. 支持必要的用户确认

Agent 不应在信息不足时擅自作出影响任务正确性的决定，也不应未经用户确认就覆盖已有成果。

• 缺少必要信息时，向用户提出针对性问题。
• 首次生成学习成果后，先在聊天中展示结果，再询问是否保存。
• 更新已有成果前，说明更新对象及原因，并征求用户确认。
• 用户拒绝保存或更新时，保留原有数据，不执行对应操作。

三、业务流描述

ExamMate Agent 以用户的自然语言输入为业务入口，以当前课程为任务上下文，通过意图识别、条件检查、任务执行、结果反馈和成果管理形成完整的业务流程。

1. 接收需求与识别意图

用户进入某门课程后，可以向 Agent 提出知识问题，也可以提出整理考纲、分析复习缺口、制定复习计划等任务需求。

Agent 首先结合当前课程和用户输入识别意图，并将请求分为普通知识问答与具体学习任务两类。

对于普通知识问答，Agent 直接组织回答；对于具体学习任务，则进入相应的业务处理流程。

2. 检查已有资源与任务条件

对于具体学习任务，Agent 优先检查当前课程已有的资料、考纲、分析报告和复习计划，判断是否存在可以复用的有效成果。

同时，Agent 检查任务所需的前置条件。例如，考纲整理需要可供处理的课程资料或其他必要信息；复习缺口分析需要已有考纲及可用于比对的课程资料；复习计划制定则需要考纲、复习缺口分析结果以及必要的时间安排等信息。

如果现有信息不足，Agent 通过对话向用户询问必要信息，待条件满足后再继续执行。如果已有有效成果能够满足需求，则优先复用；如果成果可能过期，则根据具体任务判断是否需要重新分析或更新。

3. 执行学习任务并展示结果

在任务条件满足后，Agent 根据任务类型执行相应操作：

• 考纲整理：结合课程资料整理考纲内容，并区分原始内容与推断内容，供用户检查。
• 复习缺口分析：将考纲条目与课程资料进行比对，识别已覆盖、部分覆盖、未覆盖或需要进一步核查的知识点，并提供相应依据。
• 复习计划制定：结合考纲、复习缺口和必要的时间信息，生成复习任务安排。

任务完成后，Agent 将结果展示给用户，并反馈相应的任务状态。若执行失败，则明确告知用户，不将失败伪装为成功，也不以失败结果覆盖已有有效成果。

4. 确认操作与管理学习成果

Agent 根据操作类型和已有成果状态决定后续处理方式。

对于首次生成的学习成果，Agent 先展示结果，再询问用户是否保存。用户确认后，系统才将结果保存至当前课程的学习成果中；用户暂不保存时，保留当前对话中的结果，不自动创建正式成果。

对于已有成果的更新，Agent 先说明更新内容并征求用户确认，只有在用户确认后才执行更新。用户未确认时，不提前覆盖原有成果。

保存后的学习成果可以在后续对话和课程学习中被查询与复用。若相关资料或考纲发生变化，系统可以将引用这些来源的成果标记为可能过期，供后续任务判断是否需要重新分析或更新。

5. 形成持续学习闭环

学习成果保存后，Agent 将其作为当前课程后续任务的可用上下文。用户可以继续提出新问题、重新分析复习缺口、调整复习计划或更新已有成果。

由此形成以下持续学习闭环：

用户提出需求 → Agent 识别意图 → 检查资源与条件 → 执行任务或补充信息 → 展示结果 → 用户确认 → 保存或更新学习成果 → 为后续任务提供依据。

通过这一流程，ExamMate Agent 将分散的学习问答与备考活动连接起来，使学习成果能够持续积累和复用，逐步形成围绕课程开展的长期学习支持过程。

6.业务流程图如下

四、实现说明

4.1 系统总体设计

ExamMate 是一款面向大学生考试复习场景的 AI 学习辅助 Agent，旨在将自然语言交互与实际业务操作相结合，帮助用户围绕课程资料、考试考纲和复习任务开展复习准备。与仅提供通用知识问答的对话系统不同，ExamMate 更强调将用户的复习需求与课程相关数据相结合，并通过业务工具完成考纲整理、复习计划生成及任务状态管理等操作。

系统采用 Python 作为主要开发语言，以 DeepSeek API 提供大语言模型能力，使用 SQLite 实现业务数据的持久化存储，并通过 Agent Tool Calling 机制将自然语言请求转化为具体的工具调用。同时，系统基于 MCP 提供标准化的工具服务，为后续通过不同客户端调用后端业务能力提供支持。前端计划采用 Streamlit 构建交互界面，并通过统一的接口层调用后端服务，以降低界面逻辑与核心业务之间的耦合。

在整体架构上，系统主要由模型调用与 Agent 运行、课程考纲管理、课程资料导入与解析、复习计划与任务管理、数据持久化以及 MCP 工具服务等部分组成。各模块围绕课程和考试目标组织业务数据，通过相对清晰的职责划分，使模型的自然语言理解能力与后端可执行、可验证的业务操作相结合。

4.2 核心模块实现

1. 大语言模型调用与 Agent 运行模块

该模块负责连接 DeepSeek API，并为上层业务提供统一的模型调用能力，支持自然语言问答和结构化输出。在此基础上，系统利用 Tool Calling 机制，使模型能够根据用户请求选择相应的业务工具，由后端执行具体操作，再将执行结果返回模型进行整理和反馈。

整体处理过程包括用户请求接收、意图与参数识别、工具选择、业务函数执行、结果返回及自然语言回复等环节。通过将模型负责的请求理解与后端负责的数据操作相结合，系统能够在回答问题之外执行实际业务任务，例如查询课程与考试信息、创建复习计划以及修改复习任务状态。工具的实际执行结果作为后续回复的依据，减少仅依靠模型生成文本而无法确认操作是否真正完成的问题。

2. 课程考纲管理模块

该模块围绕考试考纲的整理与审核展开，重点解决原始考纲条目粒度不一、部分内容较为概括，以及难以直接用于具体复习安排等问题。

系统首先保留用户提供的原始考纲条目，再利用大语言模型对条目进行细化，生成相应的知识点或能力要求候选项。生成结果与原始条目建立关联，并记录候选项的来源及审核状态。用户可以对模型生成的内容进行审核和确认，使原始考纲与模型推断内容得到区分，避免将模型生成的候选项未经检查直接视为确定的考试要求。

在业务流程上，考纲解析、候选项生成和人工审核相互衔接。对于考纲内容的新增、修改或审核状态变化，系统还需要考虑其对后续复习计划有效性的影响，为后续实现依赖数据变化后的更新提醒与重新生成机制提供基础。

3. 课程资料导入与解析模块

该模块负责接收用户提供的课程学习资料，提取可读取的文本内容，并将原始文件、解析结果及相关元数据保存到系统中，为考纲整理和复习辅助提供资料基础。

资料解析服务支持 TXT、PDF、DOCX、PPTX、Markdown 和 XLSX 等常见格式。针对不同文件类型，系统采用相应的解析方式提取文本内容，再将资料与对应课程或考试目标关联。资料元数据和提取文本通过数据库进行管理，原始文件则按照既定存储路径保存，便于后续查询和业务处理。

该模块将资料导入与后续分析流程分开，使用户能够先完成资料整理，再根据需要触发考纲处理或其他学习任务。需要注意的是，格式支持主要针对可读取的文档内容，并不代表系统已具备所有文件类型的完整语义解析能力；例如，扫描版 PDF 的文字识别仍需额外的 OCR 能力支持。

4. 复习计划生成与任务管理模块

该模块将课程考纲及考试目标等信息转化为可执行的复习安排，是系统从学习辅助建议走向实际业务执行的重要部分。

在计划生成过程中，系统根据现有考试信息和复习需求调用模型生成结构化的复习计划，并将计划内容及其对应任务保存到 SQLite 数据库。通过结构化数据存储，复习计划不再只是一次对话中临时生成的文本，而能够在后续查询中重新读取，并支持对任务状态进行更新。

在预期的完整使用流程中，系统还需要检查制定计划所需的信息是否充分，并在必要时向用户询问缺失条件；生成结果展示后，再根据业务流程决定是否保存或更新已有计划。考纲或相关资料发生变化时，也需要判断已有复习计划是否仍然适用，避免用户继续依赖过期的安排。

目前，复习计划创建、读取和任务状态更新等后端能力已有相应业务逻辑与测试基础；计划生成、保存和状态修改在完整前端交互中的衔接效果，将在后续联调阶段进一步验证。

5. 数据持久化与业务服务模块

系统采用 SQLite 保存课程、考试目标、考纲条目、课程资料元数据、复习计划和任务状态等业务数据。数据库访问通过相应的数据访问与业务服务模块进行组织，由上层业务逻辑调用相关接口完成数据读取、创建和更新，避免在 Agent 或交互界面中直接分散编写数据库操作。

在此基础上，系统通过业务服务承接考纲审核、资料导入、复习计划管理等具体操作，使数据存储与业务规则相对分离。对于需要验证数据更新效果的场景，可以通过重新查询数据库中的业务记录，确认操作结果是否得到持久化，而不只依据模型返回的文字判断执行是否成功。

6. MCP 工具服务模块

为了使系统的核心业务能力能够通过统一的工具协议对外提供，项目基于 MCP 实现了工具服务，并封装以下六项工具：

• list_courses：查询系统中的课程列表，为后续业务调用提供课程信息。
• list_exams：查询考试目标列表，辅助确定具体的复习任务上下文。
• get_exam_details：获取指定考试目标的详细信息。
• create_and_save_review_plan：创建复习计划并保存至数据库。
• get_review_plan：读取已保存的复习计划。
• update_task_status：更新指定复习任务的执行状态。

这些工具覆盖了课程与考试信息查询、复习计划创建与读取，以及复习任务状态修改等操作。其中，查询类工具用于获取已有业务数据，写入类工具则负责将业务操作落实到持久化存储中。

MCP 服务与普通 Agent Tool Calling 的应用场景有所区别：前者通过标准化协议对外提供工具能力，后者用于模型在应用内部根据用户意图选择和调用业务工具。两者共同为系统提供了自然语言交互与实际业务执行的基础，也为后续连接前端界面或其他兼容客户端提供了扩展空间。

4.3 数据持久化与测试

系统使用 SQLite 保存核心业务数据，并通过统一的数据访问方式完成记录的创建、查询与更新。在测试过程中，针对模型调用、考纲解析与审核、资料导入、复习计划管理、Agent 工具调用及 MCP 工具服务等部分分别编写了相应测试。

测试覆盖了基础设施可用性、核心业务逻辑、工具调用流程以及部分集成场景。其中，部分测试使用模拟模型或临时数据库，以减少外部服务调用的不确定性，避免测试数据污染正式数据库，并提高测试的可重复性。

通过模块级测试与集成测试相结合的方式，项目逐步验证了从业务函数执行到数据持久化的关键环节。不过，单个模块测试通过并不等同于完整用户流程已经全部验证。后续仍需结合 Streamlit 前端，对请求传递、参数与返回结构匹配、业务结果展示、数据重新读取及异常提示等环节开展联调与端到端验收。

六、小组分工

汪琳	负责 ExamMate 后端核心业务的设计与开发，包括考纲条目解析与审核流程、资料导入与解析、复习计划及任务管理、Agent 工具调用和 MCP 工具服务，并通过模块测试与集成测试验证关键业务逻辑，依据接口约定推进后续整合与联调
陈沐兰	负责 ExamMate 前端原型设计与开发，基于 Python + Streamlit 搭建课程管理、聊天交互、课程资料库及学习成果等界面；梳理前后端接口约定与交互逻辑，编写 Agent 需求说明文档

七、小组成员心得

汪琳: 通过 ExamMate 的开发，我对大语言模型应用从普通问答向实际业务执行的转变有了更具体的认识。除了模型调用本身，还需要设计清晰的业务工具、维护数据状态，并处理模型输出与实际业务规则之间的衔接。开发过程中，我逐步完善了考纲审核、复习计划管理、数据库操作和 MCP 工具调用等模块，也更加重视通过独立测试与集成测试验证代码的可靠性。

这次实践让我认识到，一个可用的 Agent 不仅需要能够理解用户意图、生成合理的回答，还应当能够调用真实工具、保存操作结果，并在后续查询中正确反映状态变化。下一步，我将重点完成前后端联调与端到端功能验收，进一步检验系统在真实使用流程中的完整性与稳定性

陈沐兰: 通过这次 ExamMate 项目的开发，我对软件开发的整体流程有了更深入的认识。作为前端开发人员，我不仅需要使用 Python 和 Streamlit 完成课程管理、聊天交互、课程资料库及学习成果等界面的搭建，还需要从用户需求出发，思考页面布局、交互逻辑以及不同功能之间的衔接。在开发过程中，我逐渐认识到，前端开发并不只是实现页面的视觉效果，还需要与后端保持清晰的接口约定，明确数据的传递方式和功能边界，才能保证前后端独立开发后顺利对接。此外，通过梳理 Agent 的产品定位、功能需求和核心业务流程，我对如何将一个初步的产品构想转化为具体、可实现的功能有了更清晰的理解。