团队作业

从“能说”到“会做”：基于 Python 与 MCP 的学习任务管家

项目	内容
这个作业属于哪个课程	https://edu.cnblogs.com/campus/gdgy/Class78-Grade2024-CS/
这个作业要求在哪里	https://edu.cnblogs.com/campus/gdgy/Class78-Grade2024-CS/homework/16761
这个作业的目标	理解智能体的基本工作机制，使用 Python 构建具备中文交互、工具调用和数据持久化能力的学习任务助手，并完成项目运行、功能测试和文档整理。
学号	成员一：3124004212李智杰；成员二：3124004223沈彦丞；成员三：3124004221潘健龙；成员四：3124004207黄俊达
GitHub 仓库地址	https://github.com/Zikie222/Zikie222/tree/main/3124004212团队作业

一、项目背景与选题

学习中经常会同时出现课程作业、复习安排、实验报告等任务。如果只是把它们写在零散的聊天记录或备忘录中，后续很难统一查看截止日期和完成状态。因此，我们选择“学习任务管理”作为本次智能体实践的应用场景，项目名称为“学习任务管家”。

我们的目标是让用户通过中文描述需求，由程序完成任务的新增、查询、修改、完成和导出。对于任务管理系统，“会说”并不是简单输出一句“已经完成”，“会做”也不应只停留在生成一段操作建议，而应当有可以核对的数据库记录、状态变化和导出文件。

项目提供两种运行模式：

• 离线规则模式：解析约定格式的中文输入，真实调用任务工具，无需模型 API Key，适合日常任务管理和业务功能验证。
• 大模型对话模式：接入支持工具调用的模型，由模型理解用户意图、选择工具，并根据真实执行结果组织回复。

本次我在本机运行项目，对新增、查询、修改、完成和导出功能进行了测试，下面结合运行截图说明测试过程与结果。项目同时已提供大模型 API 接入代码，配置后可启动大模型对话模式；由于本次没有进行真实 API 调用，其配置与操作方法单独作为使用说明介绍。“语言交互”在本项目中指文字交互，尚未实现语音输入和语音播报。

二、需求描述

2.1 使用对象与应用场景

使用对象是需要管理学习事项的学生。典型场景包括：记录明天需要提交的作业，查询待办任务，提高某项复习任务的优先级，将完成的作业标记为已完成，以及导出清单供复盘或归档。

2.2 功能需求

编号	功能	需求描述
F01	新增任务	接收任务标题、截止日期和优先级，写入数据库并返回真实任务编号。
F02	查询任务	支持待完成、已完成、全部任务，以及关键词、截止日期上界和分页查询。
F03	修改任务	根据编号修改标题、截止日期或优先级，未指定字段保持原值。
F04	完成任务	更新任务状态并记录完成时间；重复完成不改变原完成时间。
F05	导出任务	按指定状态导出 Markdown 或 CSV 文件，返回真实路径及任务数量。
F06	中文交互	规则模式支持约定句式，正式模式支持通过大模型进行自然语言交互。

2.3 质量要求

1. 数据可保存：使用 SQLite 持久化任务，程序退出后不丢失已提交的数据。
2. 执行可核对：显示工具名称、参数和返回结果，便于判断操作是否真正成功。
3. 输入有校验：拒绝空标题、非法日期、不合法优先级和无效任务编号。
4. 模块可维护：将交互、模型调用、工具通信与数据操作分离，方便独立排查问题。

三、业务流程与系统设计

3.1 业务流程

以“记录一项学习任务”为例，流程如下：

用户输入中文需求
        ↓
规则解析器或大模型识别意图、生成参数
        ↓
调用 add_task 等任务工具
        ↓
业务层校验参数并操作 SQLite 或导出文件
        ↓
返回真实结果和工具执行记录
        ↓
助手向用户反馈

规则模式直接依据约定句式选择工具；正式模式则把工具执行结果返回给模型，模型可以继续调用工具或生成最终回答。两种模式共用业务工具，避免维护两套任务操作逻辑。

3.2 系统分层

层次	主要模块	职责
交互层	app.py	读取命令行参数，接收输入，打印工具记录和回复。
意图处理层	study_agent/demo.py、study_agent/agent.py	分别提供有限规则解析与模型决策循环。
模型接口层	study_agent/llm.py、study_agent/config.py	读取配置，发送模型请求，处理接口异常。
工具通信层	study_agent/transport.py、mcp_server.py	提供本地直连和 MCP 两种调用通道。
业务与存储层	study_agent/tools.py	执行任务操作、字段校验、SQLite 读写和文件导出。

在正式模式的设计中，模型负责理解与决策，MCP 负责工具通信，业务代码负责实际操作。MCP 通道采用独立服务端与 stdio 通信，通过初始化、工具发现与工具调用连接客户端和服务端。

需要注意，规则模式也可以使用 MCP 通道：是否使用大模型与是否使用 MCP，是两个不同的配置维度。

四、核心实现说明

4.1 五个业务工具

工具名称	主要参数	执行结果
add_task	title、due_date、priority	新增记录，返回任务编号和字段。
list_tasks	status、keyword、due_before、limit、offset	返回任务列表、总数量和分页信息。
update_task	task_id 及需要更新的字段	仅更新指定字段，返回修改后的记录。
complete_task	task_id	将任务设为 done 并记录完成时间。
export_tasks	format、status	生成 Markdown 或 CSV 文件，返回路径和数量。

这些工具由 TaskTools 统一实现，MCP 服务端注册同一组业务方法。工具列表通过白名单限定；项目不提供任意执行系统命令的工具。

4.2 数据库设计

项目使用 SQLite 的 tasks 表保存任务：

字段	含义
id	自增任务编号。
title	任务标题。
due_date	截止日期，格式为 YYYY-MM-DD；空字符串表示未设置。
priority	优先级，取值为高、中、低。
status	状态，取值为 pending 或 done。
created_at	带时区的创建时间。
completed_at	完成时间，未完成时为空。

数据库操作使用参数化 SQL。查询时先按截止日期排列，无日期的任务排在后面；截止日期相同时再按优先级排列。

4.3 模型决策与工具执行

LLMAgent 保留最近 10 轮对话，并将当前本地时间、工具说明及对话内容发送给模型。如果模型返回 tool_calls，程序会检查调用结构和参数，然后依次执行工具。

工具返回后，Agent 使用对应的 tool_call_id 将结果回传给模型。每轮最多进行 6 次模型请求，每次最多接受 8 个工具调用，以限制无休止的调用循环。

项目的系统提示词要求模型依据真实结果回答，对不明确的同名任务先澄清，不随意猜测编号。此类提示词属于行为约束，不能代替程序校验和实际效果测试。

4.4 文件导出与异常处理

导出文件保存在数据目录的 exports 子目录，文件名包含时间和随机标识，以降低覆盖已有文件的风险。Markdown 适合直接阅读，CSV 便于在表格软件中查看。

程序还对日期、优先级及任务编号进行校验，对 CSV 任务标题中的公式起始字符做处理。模型接口在写入后失败时，已提交的数据保留，程序返回工具执行记录，避免用户误以为所有操作都没有发生。

五、正常运行与 API 接入说明

5.1 环境准备

项目要求 Python 3.10 或更新版本。电脑有多个 Python 时，需要明确选择解释器，而不是仅凭默认的 python 或 py 判断版本。

首次使用时，在 PowerShell 中进入项目目录并创建独立环境。下面以 Python 3.13 为例，应以本机实际可用的 Python 3.10 或更新版本为准：

cd C:\Users\Lenovo\Downloads\python_task_agent\task_agent
py -0p
py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

py -0p 用于查看启动器能够识别的解释器；若某个版本没有被识别，可使用其 python.exe 的实际路径创建环境。后面的命令直接指定虚拟环境解释器，无需先执行激活脚本。已建立环境并安装依赖后，再次使用时直接启动程序即可。

5.2 不接入 API 时的交互使用

在项目目录执行以下命令进入交互界面：

.\.venv\Scripts\python.exe app.py

程序启动后，在“你：”提示符后输入需求并按回车。离线模式支持约定的中文句式，例如：

添加任务：完成软件工程作业，截止明天，优先级高
添加任务：复习数据库，截止后天，优先级中
查看待办
搜索任务：数据库
查看全部任务
导出全部任务为Markdown
导出全部任务为CSV
退出

修改或完成任务时，使用新增、查询结果中实际返回的编号。例如，若目标编号是 2，可输入：

修改任务2：标题改为复习数据库第三章，优先级高
完成任务2

离线模式的日期支持“今天、明天、后天”或 YYYY-MM-DD。标题以外的截止日期与优先级可以省略；输入“帮助”可以查看可用格式。

安装依赖后，也可以通过 MCP 通道进行交互：

.\.venv\Scripts\python.exe app.py --mode demo --transport mcp

此时仍由规则模块解析输入，工具操作通过 MCP 执行。程序会自动启动 MCP 服务端，无需额外打开一个终端。

默认数据保存在项目的 data/tasks.db，导出文件保存在 data/exports/。如需继续使用本次测试的数据，可以指定原数据目录：

.\.venv\Scripts\python.exe app.py --data-dir paper_demo_data

正常使用时保留同一个数据目录，才能持续查询和管理已有任务。只有需要隔离测试数据时，才另外指定新的目录。

5.3 接入大模型 API

项目已在 study_agent/llm.py、study_agent/config.py 和 study_agent/agent.py 中实现模型接口请求、配置读取及工具调用循环。用户可以配置支持项目请求格式的模型服务，启用大模型对话。

以下是已有 API 接入功能的使用说明，本次未进行真实模型调用。

5.3.1 接口要求

模型服务需要支持项目使用的 Chat Completions 兼容请求格式，以及 tools / tool_calls 工具调用。仅支持普通文本生成的接口不能完成这里的自动工具选择。模型名称应以服务商账号实际可用、支持工具调用的标识为准。

项目通过可配置的服务地址连接接口，不把服务绑定到某个固定模型。是否可以连接某个服务，应以其协议兼容性和实际调用结果为准。

5.3.2 创建配置文件

在项目根目录执行以下命令。已有 .env 时直接编辑原文件，无需重新复制：

if (-not (Test-Path .env)) {
    Copy-Item .env.example .env
}
notepad .env

按自己的模型服务信息填写：

LLM_API_KEY=替换为自己的API密钥
LLM_BASE_URL=https://你的服务商域名/v1
LLM_MODEL=替换为实际可用且支持工具调用的模型标识
LLM_TIMEOUT=60

配置项	含义	填写要求
LLM_API_KEY	模型接口访问密钥	使用本人服务账号的密钥，在本机填写。
LLM_BASE_URL	API 根地址	以服务商给出的兼容接口根地址为准，程序会自动追加 /chat/completions。
LLM_MODEL	模型标识	填实际可调用、支持工具调用的模型名，不能保留模板占位符。
LLM_TIMEOUT	单次接口请求超时	单位为秒，默认 60，代码允许范围为 1～300。

上面的域名是填写提示，不是可以直接使用的服务地址。LLM_BASE_URL 不要再包含 /chat/completions，也不要附带查询参数。系统中已有的同名环境变量优先于 .env；若修改文件后配置未生效，需要检查环境变量。

API 密钥不应出现在博客截图或公共 GitHub 仓库中。项目保留 .env.example 供说明配置格式，真实 .env 在本机保存。

5.3.3 启动大模型对话模式

保存 .env 后执行：

.\.venv\Scripts\python.exe app.py --mode llm

该模式默认使用 MCP 通道，并自动创建工具服务端子进程。若希望继续管理 paper_demo_data 中的任务，可运行：

.\.venv\Scripts\python.exe app.py --mode llm --data-dir paper_demo_data

5.3.4 自然语言操作示例

启动后可以尝试以下输入。这些是接入后的操作示例，不是本次已经获得的模型回复：

你好，介绍一下你能帮我做什么。
帮我记一下：明天完成软件工程作业，优先级高。
我有哪些待办任务？按截止时间列出来。
把刚才的软件工程作业标记为完成。
把数据库复习任务的截止日期改到下周五。
把所有任务导出为CSV。
给我一些复习建议，暂时不要创建任务。
退出

与离线模式不同，大模型模式由模型理解表达并生成工具参数，不局限于规则模块的固定句式。模型可能查询任务、询问存在歧义的编号或直接给出建议，实际回答与工具选择需要通过真实调用验证。

涉及新增、修改、完成和导出的操作，可以核对终端中的 [工具]、[结果]、任务编号及实际文件。普通聊天或学习建议不一定需要调用工具。当前进程保留最近 10 轮对话，任务保存在数据库中；退出后对话历史不会跨进程保留。

5.3.5 配置与连接问题排查

问题	检查方法
提示缺少配置	检查项目根目录是否为 .env，确认密钥、模型名称不是模板占位符。
提示缺少 MCP 依赖	使用本项目的虚拟环境解释器重新安装 requirements.txt。
接口返回 401	检查 API 密钥是否正确。
接口返回 400 或 404	核对根地址、模型名称、接口格式以及模型是否支持工具调用。
连接失败或超时	检查网络、服务地址和超时设置。
需要区分模型接口与 MCP 问题	使用下面的本地工具通道命令进行排查，模型调用仍会发生。

.\.venv\Scripts\python.exe app.py --mode llm --transport local

如果工具操作已成功、但之后的模型请求失败，已写入的记录仍然保留。此时先查询任务状态，再决定是否重新提交新增请求。

六、本人功能测试与实际结果

我在本机运行项目，对任务管理流程进行了功能测试。测试日期为 2026 年 10 月 25 日，数据目录为 paper_demo_data，覆盖五个业务工具，共进行了八步操作。下表根据本次测试截图和导出文件整理。

6.1 测试输入与结果

步骤	中文输入	截图中的实际结果
1	添加任务：完成 Python 智能体作业，截止明天，优先级高	创建任务 #1，截止日期为 2026-10-26，状态为 pending。
2	添加任务：复习数据库，截止后天，优先级中	创建任务 #2，截止日期为 2026-10-27，状态为 pending。
3	查看待办	查询到两项待完成任务。
4	修改任务2：标题改为复习数据库第三章，优先级高	任务 #2 的标题和优先级更新，截止日期仍为 2026-10-27。
5	完成任务1	任务 #1 的状态变为 done，记录完成时间。
6	查看全部任务	显示一项已完成任务和一项待完成任务。
7	导出全部任务为Markdown	返回 Markdown 文件路径，count 为 2。
8	导出全部任务为CSV	返回 CSV 文件路径，count 为 2。

“明天”和“后天”分别被转换为 2026 年 10 月 26 日、27 日。这里的相对日期处理来自规则解析器，不将其解释为真实模型的推理结果。

6.2 运行截图

图1：任务管理功能测试

图1：用户输入、工具调用参数、结构化返回值及中文回复。发布到博客园时，请将图片上传至编辑器，并替换为上传后生成的图片地址。

例如，修改任务时可看到 update_task 的真实参数；完成任务时可看到返回记录的 status 变为 done。这种日志让操作具有可检查的依据。

截图从数据目录信息开始，未包含程序最上方的模式与工具通道标题，因此该图本身不能单独证明本次使用了 MCP 通道。若要展示 MCP 验证，需补充包含 工具通道：mcp 的启动截图或 MCP 集成测试输出。

6.3 导出文件核对

本次测试实际生成以下文件：

paper_demo_data/
├── tasks.db
└── exports/
    ├── tasks_20261025_012124_095c7243.md
    └── tasks_20261025_012124_72da5cb5.csv

Markdown 文件的实际内容为：

# 学习任务清单

共 2 项任务。

- [x] #1 完成 Python 智能体作业（截止：2026-10-26；优先级：高）
- [ ] #2 复习数据库第三章（截止：2026-10-27；优先级：高）

CSV 文件包含编号、任务、截止日期、优先级和状态五列，两条任务内容与 Markdown 文件一致。这表明本次测试中，工具不仅返回了成功文本，也实际创建了可以读取的清单文件。

图2：导出文件内容

图2：实际导出文件中的任务内容，与终端测试结果对应。

七、测试设计与验证范围

7.1 当前能够确认的结果

验证项目	当前依据	结论
新增、查询、修改和完成	图1 的工具记录与状态变化	本次本人测试中的对应操作成功。
Markdown / CSV 导出	图1 返回路径及实际文件内容	两种格式均生成，内容与测试任务一致。
SQLite 数据文件生成	paper_demo_data/tasks.db 文件存在	已生成数据库文件；跨进程持久化仍应通过重启查询单独验证。
MCP 通道	项目提供实现与集成测试代码	当前图1缺少通道标题，不据此单独认定本次已验证 MCP。
自动化测试	tests/test_project.py 中有 27 项测试	本篇材料未提供本机测试汇总，不宣称本次 27 项全部通过。
大模型 API 接入	已实现配置读取、接口请求和工具调用循环	本文提供使用说明，本次未运行真实 API，尚未验证模型效果。

7.2 自动化测试覆盖

项目包含 27 项自动化测试，覆盖内容如下：

测试类别	数量	主要覆盖点
业务工具测试	11	持久化、排序、校验、更新字段保留、重复完成、SQL 特殊字符、筛选、分页及文件导出。
Agent 测试	10	规则流程、无效输入、工具循环、会话历史、错误 JSON、未知工具、重复调用编号、调用上限及接口失败。
HTTP 接口测试	2	工具结果回传、接口错误处理与密钥不出现在报错中。
配置测试	2	环境变量优先级、缺失配置与错误接口地址。
MCP 集成测试	2	五个工具的真实 stdio 调用，以及模拟模型 HTTP 接口经 MCP 写入数据库。

运行命令：

.\.venv\Scripts\python.exe -W error::ResourceWarning -m unittest discover -s tests -v

提交前补充本机终端实际输出与截图。 未安装 MCP 时，两项 MCP 测试会被跳过；即使看到 OK，也应同时核对是否存在 skipped=2。项目已有 docs/verification.txt 属于随代码提供的既有记录，不应代替本次本机测试证据。

HTTP 集成测试使用的是本地模拟模型接口，它可以验证请求、工具结果回传及数据落盘的链路，不能证明真实模型具有同样的语言理解效果。

图3：自动化测试结果

实际结果填写： 运行日期【待填写】；执行测试【待填写】项；失败【待填写】项；错误【待填写】项；跳过【待填写】项。

图3：本机执行自动化测试后得到的实际汇总。

7.3 建议补充的边界操作

输入或操作	预期行为
添加任务：错误日期测试，截止2026-02-30	拒绝非法日期，不新增记录。
完成任务999（先确认不存在该编号）	返回任务不存在，不修改其他任务。
再次完成已完成任务	保留原完成时间，不产生新任务。
退出后用相同数据目录重新查询	仍能读取原有任务，验证跨进程持久化。

以上为补充测试建议和预期，不作为已经执行的结果。

八、四人小组分工

下表为四人分工草稿，请按实际贡献调整后提交。代码初稿由 ChatGPT 辅助生成，不应把未实际完成的工作写成成员独立开发成果。

成员	姓名 / 学号	职责	应对应的实际产出
成员一	李智杰 / 3124004212	需求分析与项目整合	整理使用场景和功能需求，检查项目结构与配置，协调运行与测试。
成员二	沈彦丞 / 3124004223	Agent 与交互模块核对	理解并核对中文输入处理、提示词、会话管理和工具调用循环，整理实现说明。
成员三	潘健龙 / 3124004221	工具、MCP 与数据模块核对	核对五个业务工具、MCP 通信、SQLite 字段和导出文件，解释数据流向。
成员四	黄俊达 / 3124004207	测试与材料整理	执行功能和边界测试，保留真实输出与截图，整理博客和演示材料。

分工可以体现协作，例如功能测试由一位成员操作，另一位成员核对日志与导出结果；最终每位成员都应能够说明自己负责部分的输入、输出与实现逻辑。

九、小组成员心得

9.1 成员一：需求分析与项目整合

这次作业让我认识到，需求描述需要明确到可以检查的程度。例如，“帮助管理任务”还比较笼统，进一步拆成新增、查询、修改、完成和导出，才容易判断系统是否实现了目标。整理项目时，我也意识到运行环境、依赖和启动方式是交付的一部分，不能只关注代码文件是否齐全。

9.2 成员二：Agent 与交互模块

通过梳理 Agent 的代码，我对“模型决策—工具执行—结果反馈”的循环有了更具体的理解。模型返回工具名称和参数后，还需要程序校验、执行并回传真实结果。本次离线功能测试帮助我们理解业务流程，API 接入则提供了使用大模型理解需求的入口；接入效果仍需要通过实际调用进一步检验。

9.3 成员三：工具与数据模块

任务工具让我看到自然语言需求如何转换成数据库和文件操作。更新任务时保留未指定字段、重复完成时保留原时间、导出时返回真实路径，这些细节都直接影响使用体验。MCP 将工具调用与业务实现连接起来，但输入校验、SQL 参数化和数据一致性仍需要业务代码承担。

9.4 成员四：测试与材料整理

测试材料不能只保留一段看起来成功的终端文字，还需要核对任务状态和实际文件。本人功能测试、自动化测试和真实模型实验分别回答不同的问题。整理博客时，我会区分实际结果与预期结果，特别是测试跳过项和模拟接口，避免让报告结论超过已有证据。

十、局限与后续改进

当前版本是单用户命令行原型，尚未实现图形界面、定时提醒、账号管理和语音交互。聊天历史只保留在当前进程内，任务数据持久化；重复发送新增请求仍可能产生重复记录，跨请求幂等性有待完善。

后续可以优先按本文的 API 接入说明完成真实模型测试，并补齐本机自动化测试记录，再增加更直观的日历界面、提醒功能和请求去重机制。对于真实模型，可另外设计不同表达方式、含糊指代和多任务输入的测试集，记录实际任务成功率，而不是只展示单一成功样例。

图5：GitHub 作业源码目录