构建一个能说会做的智能体

这个作业属于哪个课程 计科24级56班
这个作业要求在哪里 构建一个能说会做的智能体
这个作业的目标 构建一个既能进行自然语言交互，又能通过真实工具执行任务的智能体，理解模型、MCP、外部 API 与数据库之间的协作方式，并完成可演示的软件成果。
小组成员（姓名＋学号） 陈建志：3124007214；陈信儒：3124004160；肖琳瀚：3124004184；陈憬乐：3124004050；陈康泓：3124004159

小组成员信息

姓名 学号 GitHub仓库链接
陈建志 3124007214 StudyMateAgent
陈信儒 3124004160 Agent
肖琳瀚 3124004184 linyanzhi591-afk
陈憬乐 3124004050 LAYG13
陈康泓 3124004159 —

课伴 StudyMate：构建一个能说会做的课业协作智能体

一、项目简介与需求描述

小组作业通常需要拆分任务、确定负责人、安排时间并持续更新进度。如果这些信息只保留在群聊里，就容易出现“谁负责哪一项”“什么时候有空”“这项任务是否已经完成”等信息不一致的问题。

我们围绕这一场景开发了“课伴 StudyMate”。用户用自然语言描述作业要求，智能体结合项目成员生成可检查的任务草案；用户确认后，系统把任务写入数据库，再根据成员明确填写的可用时间安排日程。后续可以查询、开始、暂停、继续或完成任务，并导出当前项目计划。

课伴也支持一般知识问答、联网资料搜索和城市天气查询。课业协作是主要业务，查询辅助功能用于展示智能体对不同外部工具的选择和调用能力。

1.1 主要需求

需求 对应功能
根据作业要求明确分工 自然语言拆解、负责人和估时草案、确认后保存
根据实际时间制定安排 成员可用时间、日程草案、冲突及工时覆盖检查
在多轮对话中继续操作 会话历史、当前任务焦点、待确认草案持久化
记录实际进度 待开始、进行中、已暂停、已完成四种任务状态
同时参与不同小组 新建与切换项目，分别保存成员、任务、日程和对话
区分当前发言者 选择聊天成员，按项目和成员恢复历史
便捷输入与查看成果 语音转文字、回复朗读、网页看板、Markdown 导出
获取外部资料 Tavily 网页搜索、Open-Meteo 天气查询及来源展示

当前的成员切换是本机视角选择，不是手机号或微信登录，也不等于个人账号权限隔离。多项目分别保存数据，但暂不自动检查同一个人跨项目的日程冲突。

二、业务流描述

2.1 课业任务主流程

新建或选择项目，选择当前聊天成员
    ↓
输入作业要求、截止时间和分工需求
    ↓
模型理解意图，读取实际成员信息，生成任务草案
    ↓
用户检查并确认采用
    ↓
通过 MCP 工具把正式任务写入 SQLite
    ↓
填写成员可用时间，生成并校验日程草案
    ↓
用户确认保存，查看项目日程
    ↓
多轮对话或卡片操作：开始 → 暂停 → 继续 → 完成
    ↓
调用导出工具，下载当前项目计划

草案与正式任务分开保存，生成草案不代表任务已经落库。排程存在冲突或容量不足时，系统说明缺口，不捏造空闲时间，也不把不可行排程保存为正式日程。暂停任务保留内容和截止时间，不自动顺延。

2.2 外部信息查询流程

普通知识问题由模型直接回答；需要公开资料或最新信息时，模型可以调用 web_search，根据实际返回的摘要回答并展示来源。城市天气问题优先调用 get_weather：先识别城市、查询经纬度，再请求结构化天气数据。城市不明确时需要澄清，同名地点需要确认。

查询天气或网页不会自动改写课业任务。用户需要据此规划任务时，应在后续消息中明确提出，系统继续按草案确认流程处理。

三、实现说明

3.1 系统结构

网页：HTML / CSS / JavaScript
    │ 自然语言、按钮操作、语音转写
    ▼
FastAPI 后端与 Agent 编排
    ├─ 千问 qwen-plus：理解问题、选择工具、组织回复
    ├─ 会话管理：项目、成员、历史、焦点及草案
    └─ MCP 客户端（stdio）
           ▼
       独立 MCP 工具服务
           ├─ SQLite：成员、任务、可用时间、日程与导出记录
           ├─ Tavily API：公开网页搜索
           └─ Open-Meteo API：城市地理编码及天气数据
层次 技术与作用
模型 qwen-plus，通过兼容接口进行自然语言对话及 Function Calling
工具协议 官方 MCP Python SDK，客户端与独立工具进程通过 stdio 通信
服务端 Python 3.11+、FastAPI、httpx
数据存储 SQLite，保存业务数据、会话与防重复记录
前端 原生 HTML、CSS、JavaScript；本地 Markdown 渲染与清理
语音 浏览器 Web Speech 语音识别及语音合成
外部接口 Tavily Search API、Open-Meteo Geocoding / Forecast API

老师推荐使用 MCP 或兼容框架，本项目采用了真实 MCP 服务。系统并非只在聊天中输出一份计划：工具执行会改变实际数据库，网页和下载文件反映这些真实变化。

3.2 模型如何调用工具

后端读取当前项目和成员会话，将实际 MCP 工具定义提供给模型。模型返回工具名和参数，应用校验参数、注入可信项目范围及防重复标识，再通过 MCP 执行。工具返回成功或失败结果后，模型继续组织回答。

目前注册了13个 MCP 工具：

类型 工具
成员管理 manage_member
任务管理 list_tasks、create_tasks、update_task
可用时间 get_preferences、set_preferences
日程 check_schedule、propose_schedule、save_schedule
项目与文件 get_plan、export_plan
外部信息 web_search、get_weather

draft_tasks 和 draft_schedule 是 Agent 层的本地编排工具，不计入上述13个独立 MCP 工具。它们先形成待确认草案，最终写入通过真实 MCP 工具完成。

网页显示实际处理阶段、工具执行与等待时间；这些是执行进度，不是模型内部思考过程，也不是虚构的进度百分比。按钮操作复用相同工具链，不需要每次都额外请求模型。

3.3 数据持久化与多轮记忆

SQLite 保存项目、成员、任务、可用时间、日程、会话、请求及导出快照。会话绑定项目和成员，保存完整对话回合、待确认草案和任务焦点。用户先指定任务，再说“暂停它”“继续它”时，系统可以结合本会话焦点定位任务；存在多个候选时需要澄清。

请求和工具写操作使用防重复机制，避免断网重试创建多份任务。保存日程前检查版本、时间冲突、可用时段、截止时间与工时覆盖。重新打开网页后，可以恢复已保存的历史与业务状态。

3.4 联网搜索与天气接口

网页搜索使用 Tavily 的基础搜索接口，返回标题、URL 和摘要。来源由实际工具结果生成，在页面独立展示并保存到历史；搜索失败时不能假称已经查证。索引摘要可能过时，搜索成功不等于已经获得最新事实。

天气查询使用 Open-Meteo：地理编码接口把城市转换为经纬度，天气接口返回气温、天气代码、体感温度、湿度、风速和今明两日预报。后端对字段、单位、数值、时间、响应大小与超时进行校验，再交给模型生成回复。回答注明来源及数据有效时间。

Open-Meteo 数据是天气模型估计，不是校园现场传感器实测。 免费接口适用于本项目的非商业教学用途；模型回复仍消耗千问额度。城市不明确、接口超时或数据不完整时，系统应说明原因，不编造气温。

3.5 网页与语音交互

页面提供对话、任务看板、日程、成员、项目切换、空闲时间及导出入口。回复支持标题、列表、加粗、代码和来源链接；对模型 Markdown 输出进行清理后渲染，避免直接显示大量排版标记或执行不可信脚本。

语音输入先转成可编辑文字，用户检查后手动发送，避免误识别直接执行任务。界面支持暂停、继续和停止输入，以及回复朗读和停止朗读。识别和朗读效果受浏览器、设备、网络和授权影响。

四、使用示例与功能演示

本次演示使用“课程展示准备”项目。以下图1—图3来自实际操作，依次展示成员填写、主界面以及自然语言任务分配结果。后续示例继续使用同一项目。图片已缩小展示，点击可查看原图。

4.1 填写项目和成员

点击“新建项目”，将项目名称填写为“课程展示准备”，本人姓名填写为陈建志，并添加陈信儒、肖琳瀚、陈康泓和陈憬乐四位组员。界面显示共5名成员，成员数量可以继续调整。

图1 新建项目及五名成员

图1展示的是提交前的填写界面，点击“创建并进入”后才能进入对应项目。

4.2 查看主界面并选择聊天成员

主界面左侧用于与AI对话，右侧显示任务和日程，顶部可以切换项目、选择当前聊天成员、设置空闲时间或导出计划。

图2 项目主界面

图2中项目还没有任务，聊天成员显示“未指定成员（旧公共对话）”，输入框和发送按钮暂不可用。接下来从“当前聊天成员”选择“陈建志”，即可用该身份与AI对话。

4.3 用自然语言分配展示任务

在陈建志的对话中发送以下要求：

我们需要准备课伴课程展示。请根据当前项目的实际成员，每人分配1项展示准备任务，每项估时30分钟，截止北京时间2026年10月25日22:00。任务覆盖需求与工具链说明、数据库操作复核、网页交互检查、语音和记忆验证、测试与报告整理。请先生成草案，等我确认再保存。

图3 自然语言要求与任务列表

图3中，左侧保留了用户的原始要求及模型回复，右侧任务总数为5，剩余预计工时为2.5小时。可见任务卡片显示负责人、30分钟估时、截止时间和“待开始”状态，说明结果已经出现在实际任务看板中。当前成员可操作自己的任务，查看其他成员任务时则出现切换到对应成员后操作的提示。

这张截图没有包含“采用草案”的中间过程，因此不把它单独作为确认步骤的截图证据。正式任务的创建与操作详情可以通过实际工具记录和数据库进一步核对。此处的30分钟是展示准备任务估时，不是开发整个课伴项目的工时；演示分配也不代替第八节的实际贡献记录。

4.4 多轮对话修改同一任务

在陈建志的对话中，先发送“把我的任务「需求与工具链说明准备」标记为进行中”。系统更新后，回复和右侧卡片显示同一任务为“进行中”，负责人仍为陈建志。

图4-1a 对话确认进行中 图4-1b 看板中的进行中状态
图4-1a 对话确认进行中 图4-1b 看板中的进行中状态

接着发送“先暂停它，我稍后继续”，没有再次提供任务标题。系统根据前一轮上下文定位同一任务，将其改为“已暂停”，并在卡片提供“继续任务”入口。任务负责人、30分钟估时与截止时间保持不变。

图4-2a 用“它”指代并暂停 图4-2b 看板中的已暂停状态
图4-2a 用“它”指代并暂停 图4-2b 看板中的已暂停状态

本次开始任务时也出现了工具重试：首次更新返回“当前项目中没有该任务”，随后查询任务并再次更新成功，界面仍保留“处理未全部完成”的提示。因此本次展示的是最终状态更新和后续指代成功，不将整个过程描述成无错误的一次执行；工具标识选择和重试后的反馈仍可继续优化。

4.5 天气API调用

切换到陈信儒的会话，发送“今天广州天气如何”。实际执行记录显示一次“查询城市天气”，成功取得天气模型数据。回复给出局部多云、气温29.9°C，并提供今明两日的最高最低温及降水概率。回复下半段展示有效时间2026年10月24日17:30（北京时间）和Open-Meteo来源，注明为数值天气模型估计。

图5-1 天气工具与返回结果 图5-2 有效时间与来源链接
图5-1 天气工具与返回结果 图5-2 有效时间与来源链接

29.9°C是这次查询的返回值，不是固定温度。通过问题、工具记录、天气结果、时间和来源，可以核对这次外部API调用的完整过程。已有独立的本机自然问答验收记录见 docs/WEATHER_MAC_UI_VERIFICATION.json。

4.6 语音转写与任务查询

在陈憬乐会话中使用语音输入“查询我的任务，只列出标题”。图6-1显示“正在聆听”、累计00:15，输入框已出现识别文字，用户可以暂停或停止录音。

图6-1 正在聆听与语音转写 图6-2 结束后发送并查询任务
图6-1 正在聆听与语音转写 图6-2 结束后发送并查询任务

结束语音输入并发送后，系统执行一次工具调用，返回当前成员的任务“网页交互检查”，与该成员的任务卡片一致。图6-2同时保留语音已结束的状态及00:19计时，展示从语音输入到实际任务查询的完整衔接。

实际试听中，回复能够朗读，并在播放一段时间后自行结束；手动点击“停止朗读”未能正常中断。当前已验证语音输入、转写与任务查询链路，语音输出的手动停止控制仍需完善。

4.7 生成并保存成员日程

分别保存五名成员的可用时段后，以陈建志的身份发送一次日程安排请求。系统读取当前项目所有成员的任务与可用时间，生成候选安排，并给出无冲突、可在截止前完成的校验结果。五项展示准备任务各30分钟，安排在2026年10月25日19:00—19:30。

图7-1 日程候选及可行性说明 图7-2 保存后的五人日程
图7-1 日程候选及可行性说明 图7-2 保存后的五人日程

确认后，右侧“日程”页面显示五项安排及各自负责人，底部版本为“日程v1”，表明结果已保存。成员分别完成自己的任务，所以不同成员的日程可以同时开始；同一时段出现在不同成员名下不等于个人时间冲突。

4.8 导出并核对计划文件

在陈建志会话执行“导出计划”，系统完成一次工具调用，给出文件 StudyMate-20261024-232113.md 的下载入口。

图8-1 导出工具与下载入口

打开下载的Markdown文件，可以看到项目“课程展示准备”、导出时间、日程版本1，以及任务和日程表。陈建志的任务仍标记为“已暂停”，与前面的任务状态演示一致；五项日程的日期、时间与负责人也和网页安排一致。

图8-2 实际导出的任务和日程

这说明导出成果包含系统保存的项目数据，而不只是聊天中声称“已生成文件”。

五、老师要求与加分项对应

类别 老师要求 本项目对应实现与验证情况
基本项 自然语言对话，“能说” 真实 qwen-plus 对话；可以理解任务需求和一般问题
基本项 执行操作或调用工具，“会做” MCP 创建、查询、修改任务，校验/保存日程，导出文件；结果写入数据库
推荐技术 MCP 或兼容框架 官方 MCP SDK，独立 stdio 工具服务；MCP 是推荐项，不是唯一允许框架
加分项1 多轮对话记忆 项目/成员会话持久化，保存历史、焦点、草案与偏好；有真实多轮修改和恢复记录
加分项2 语音输入/输出 已实现语音转写、录音控制和回复朗读；已有语音查询实操截图。手动停止朗读未正常生效，作为待改进项
加分项3 外部API或数据库交互 SQLite真实读写，Tavily搜索及Open-Meteo天气API；已有本机真实工具调用与来源保存记录
加分项4 简洁前端界面 网页聊天、任务看板、日程、成员/项目切换、执行进度和来源展示

天气和联网搜索用于补充展示外部API交互能力，课业任务管理是本项目的主要业务。

六、测试结果与当前局限

截至2026年10月24日，已有以下本机记录：

验证内容 结果 证据
Python自动测试 138项通过 本机执行记录；tests/ 包含业务、HTTP/MCP、搜索与天气边界测试
Markdown及语音事件测试 15项通过 tests/test_markdown.mjs、tests/test_speech.mjs；受控事件不等于所有设备实测
真实模型完整课业流程 14步、33项核对通过 docs/FULL_FLOW_VERIFICATION.json
真实网页搜索 真实工具与来源保存已验证，时效与总结仍需审阅 docs/WEB_SEARCH_VERIFICATION.json
天气工具及自然问答 Mac真实网页问答通过，任务未增加 docs/WEATHER_MAC_UI_VERIFICATION.json
旧失败历史影响 在独立验收库中带旧失败回复复测，真实调用天气工具成功 docs/WEATHER_NATURAL_VERIFICATION.json；旧历史为测试样例
语音实机 转写及实际任务查询已有截图；人工确认朗读可播放并自行结束，但手动停止朗读无效 图6-1、图6-2及实际试听反馈

自动测试中的供应商响应采用受控数据，不能冒充真实模型或真实网络成功；真实验收记录另行保存。基础版本和后续优化使用了 Codex 辅助开发，小组仍需理解实现、独立操作并检查生成结果。

当前局限包括：模型可能误解意图或遗漏工具调用；网页搜索摘要可能滞后；天气数据不是现场实测；排程暂不处理任务依赖和跨项目冲突；语音兼容性依设备而异，手动停止朗读暂未正常生效；未实现个人账号和细粒度权限。

七、GitHub链接与运行方式

本小组项目仓库：DexJocelyn / StudyMateAgent。

本次小组成果统一使用该仓库提交。运行步骤、依赖及配置方法以仓库中的 README.md 为准。

安装Python 3.11或以上版本后，在项目目录创建本机虚拟环境，安装依赖：

python -m venv .venv
# 激活本机虚拟环境后执行：
python -m pip install -r requirements.lock
python scripts/check_env.py
python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000

复制 .env.example 为 .env，在本机填写模型配置，选择真实模型模式 AGENT_MODE=llm；搜索需要额外的 Tavily 密钥，天气接口默认无需密钥。macOS和Windows也可使用相应启动脚本。打开 http://127.0.0.1:8000/ 使用。其他电脑需要自己的运行环境，不能复制Mac虚拟环境直接运行。

.env、.env.share、真实数据库、私人迁移包和虚拟环境不能提交公共仓库。截图和录屏也不要暴露密钥、分享密码或支付信息。

八、小组分工

小组按模型集成、工具与数据库、前端交互、记忆与语音、测试文档五个方向分工：

成员 学号 负责模块与工作内容 对应材料
陈建志 3124007214 智能体与集成：模型配置、MCP调用链联调、自然问答及天气接口复测、功能集成验证 工具调用记录、接口联调说明、天气验收结论
陈信儒 3124004160 工具与数据库：复核任务CRUD、暂停继续、持久化和导出一致性，检查排程边界 数据状态核对、测试用例及问题记录
肖琳瀚 3124004184 前端与交互：检查项目及成员切换、任务负责人提示、Markdown排版、来源链接和执行状态 界面优化、功能截图及浏览器测试记录
陈康泓 3124004159 记忆与语音：验证多轮“它”的指代、刷新恢复、录音暂停继续停止、转写和朗读 语音实操截图、会话恢复与兼容性说明
陈憬乐 3124004050 测试与文档：执行演示案例、汇总反馈、复核报告与四类加分项、检查仓库可访问性 演示清单、回归结果、报告与仓库核对记录

成员仓库链接见本文开头的“小组成员信息”表，项目源码统一使用第七节的小组仓库。

九、每位成员的心得

9.1 陈建志，3124007214

这次我对Agent的理解更具体了。接上模型只是第一步，还要让它在需要时选对工具，拿到结果再回答。像天气查询，能正常聊天不代表能查到天气，搜索到网页也不一定就有当前气温，需要把模型、工具和接口分开检查。

我觉得联调时最有用的还是看实际记录：调用了什么、返回了什么、页面最后显示什么。不能只用一句特意写好的指令测试，还得试“今天广州天气如何”这种平时会问的话，这样才容易发现使用中的问题。

9.2 陈信儒，3124004160

我比较关注任务状态有没有真正保存。页面上变成“已暂停”以后，刷新和导出也应该保持一致，否则用户就不知道哪个结果才是准的。任务标题、负责人和截止时间也要一起核对，不能只看状态变没变。

模型有时会传错参数，所以数据库和工具这一层的校验很重要。日程同样不能只排出一张好看的表，还要检查成员有没有空、时间是否冲突、任务能不能在截止前完成。把这些规则交给程序检查，比完全依赖模型回答更稳妥。

9.3 肖琳瀚，3124004184

谁在聊天、任务归谁，应该一眼就能看清。成员切换、任务筛选和任务转交看起来都和“人”有关，但作用不一样，提示不清楚就容易误操作。我觉得界面设计不只是把按钮摆好，还要让用户知道点下去会发生什么。

回复的排版和等待提示也很影响体验。满屏符号或者点发送后一直没有动静，都会让人以为程序出了问题。把列表、标题和来源显示清楚，再展示实际工具进度，比继续增加几个入口更能改善使用感受。

9.4 陈康泓，3124004159

多轮对话里的“它”看着只是一个字，系统却需要记住前面说的是哪项任务。切换成员或项目以后，上下文也不能混用。这让我觉得，记忆功能不只是把聊天文字存下来，还要保存当前操作对象，并在不确定时问清楚。

语音也是一样，能识别出文字只是开始，还要考虑暂停后文字会不会丢、什么时候结束、是否让用户检查后再发送。目前朗读可以播放，但手动停止还有问题。这类交互需要在真实设备和浏览器里试，单看代码或按钮存在还不够。

9.5 陈憬乐，3124004050

测试和报告都要把结果对清楚。一句“已完成”不够，还要看任务卡片、日程和导出文件是不是一致。如果中途报错后又成功了，也应该保留过程，不能只看最后一句回复就当作整轮没有问题。

整理演示材料时，我觉得截图最重要的是让别人看懂操作前后发生了什么。全屏图适合介绍界面，具体功能则用局部图更清楚。报告也要对应实际版本，把已验证的功能和还存在的问题分开写，比堆很多技术名词更有说服力。

十、学习与参考资料

posted @ 2026-10-25 15:39  玖斯琳  阅读(15)  评论(0)    收藏  举报