第四次作业

从自然语言到文件操作：AI 办公助理 Agent 的设计与实现

这个作业属于哪个课程	计科24级56班
这个作业要求在哪里	构建一个能说会做的智能体
这个作业的目标	开发一个能够理解中文自然语言请求、通过 MCP 调用办公工具完成文件管理与待办清单生成，并将操作限制在 workspace 沙箱内的 AI 办公助理 Agent。
学号	苏炜康：3124004106；何锦烨：3124004092；陈浩良：3124004087

一、需求描述

日常办公中，整理文件、查找资料、生成待办等操作琐碎且重复。本项目希望提供一个中文自然语言办公助手，让用户通过对话完成文件管理和待办清单生成，而不必记忆命令或手动编写脚本。

核心需求如下：

1. 通过网页聊天界面接收中文自然语言请求，并以中文反馈结果。
2. 借助大模型理解请求，在需要时选择并调用办公工具，而不是臆造操作结果。
3. 支持目录浏览、文本文件读写和追加、搜索、重命名、移动、删除、待办生成、文本统计和获取当前时间。
4. 通过 MCP 将 Agent 与工具服务连接；文件工具的读写范围限制在项目的 workspace/ 沙箱目录。
5. 在界面中展示工具调用及其结果，方便用户了解执行过程。

二、业务流描述

一次对话的主要业务流程如下：

1. 用户在 Streamlit 页面输入自然语言需求。
2. Agent 将系统提示、历史对话和本轮请求提交给 OpenAI 兼容的大模型接口。
3. Agent 同时获取 MCP 工具清单，并将工具的输入 Schema 转换为模型可用的函数调用格式。
4. 若模型决定调用工具，Agent 通过 MCP stdio 会话把工具名称和参数发送给办公工具服务器。
5. 工具服务器校验路径并执行操作，将结果返回给 Agent。
6. Agent 把工具结果交给模型继续处理；模型可能继续调用工具，直到生成最终答复或达到轮数上限。
7. 页面显示最终答复和本轮工具调用记录，并保留对话历史。

用户 → Streamlit 界面 → Agent 主循环 ↔ 大模型
                              ↕ MCP（stdio）
                         办公工具服务器 → workspace 沙箱

三、实现说明

系统组成

• app.py：Streamlit 聊天界面、会话状态和工具调用记录展示。
• agent/config.py：从 .env 读取 OpenAI 兼容接口的地址、API Key 和模型名；项目示例配置包含 DeepSeek、Qwen 和 GLM。
• agent/core.py：Agent 主循环，组织对话上下文、向模型提供工具定义、执行工具调用并生成最终答复；最多进行 8 轮模型交互。
• agent/mcp_client.py：通过 stdio 启动 MCP 工具服务器，将 MCP 工具 Schema 转换为 OpenAI function calling 所需格式。
• mcp_server/office_server.py：注册并实现办公工具。
• mcp_server/sandbox.py：解析并校验文件路径，确保目标在 workspace/ 内。

工具能力

工具	用途
list_directory	列出目录下的文件和子目录
read_file	读取 UTF-8 文本文件
write_file / append_file	写入或追加文本
search_files	按文件名或文本内容搜索
rename_file / move_file	重命名或移动文件
delete_file	删除文件
create_todo_list	将事项整理为 Markdown 待办清单
count_text	统计字符、中文字数和英文单词数
get_current_time	获取本地日期和时间

安全与配置

文件工具会将用户路径解析为规范化路径，并检查其是否仍位于 workspace/ 下；越界路径会被拒绝。删除、覆盖等破坏性操作也被写入 Agent 的交互准则，要求先向用户确认。请勿将 API Key 提交到仓库：从 .env.example 复制出本地 .env 后再填入密钥。

四、使用示例（功能演示）

启动项目

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
Copy-Item .env.example .env
# 编辑 .env，填入所选模型服务的 API Key
streamlit run app.py

打开终端提示的本地地址（通常为 http://localhost:8501），即可在聊天框中试用。

启动后可以看到应用主界面、当前模型和可用工具：

示例一：新建文件

用户输入：

帮我在 workspace 新建一个 notes.txt，写入“明天交作业”

Agent 可调用 write_file，成功后在页面展示工具结果和中文答复。文件保存在项目的 workspace/notes.txt。

打开文件可以验证写入内容：

示例二：搜索文件

用户输入：

帮我找找哪个文件提到了“作业”

Agent 可调用 search_files，在文件名及 UTF-8 文本内容中搜索，并返回匹配文件及命中行。

下图展示了列出 workspace 文件并搜索到“作业”关键词的对话：

示例三：生成待办

用户输入：

帮我生成今天的待办清单：写报告、开会、健身

Agent 可调用 create_todo_list，在沙箱中生成 todo.md，将事项写为 Markdown 复选框。

资源管理器中可以看到生成的待办文件：

示例四：删除前确认

用户提出删除 notes.txt 后，Agent 会先说明将要删除的文件并请求确认。确认后才执行删除，并反馈操作结果。

六、GitHub 仓库

项目代码：https://github.com/Jiyue0321/gdut-homework3

七、小组分工

成员	分工
苏炜康	负责整体方案设计与项目统筹，完成 Agent 主循环及 MCP 客户端对接，整合各模块，并主要负责测试和文档整理。
何锦烨	负责 MCP 办公工具服务器，实现文件读写、搜索、移动、待办清单等工具，并参与测试。
陈浩良	负责 Streamlit 聊天界面与模型配置相关工作，协助联调、演示和问题修复。

八、小组成员心得

苏炜康

参与本项目让我对 Agent 的完整工作流程有了更清晰的认识。从需求梳理、主循环设计到 MCP 客户端与工具服务的连接，各模块需要通过明确的接口协作。项目整合和测试也让我体会到，除了让功能跑通，还要关注异常反馈、操作边界和用户能否理解执行结果。后续我会继续加强模块化设计和协同测试。

何锦烨

通过实现 MCP 办公工具，我进一步理解了如何把文件操作封装成可供 Agent 调用的工具。路径校验尤其重要：工具不仅要完成读写、搜索和待办生成等功能，也必须将文件操作限制在 workspace 范围内。这个过程让我认识到，工具描述、参数和返回结果设计得清楚，才能让模型更可靠地使用工具。

陈浩良

参与聊天界面、模型配置和联调工作后，我体会到，用户体验不只取决于模型回答，也取决于操作入口是否清晰、工具执行过程是否可见，以及配置错误能否得到明确提示。把界面、Agent 和工具服务串联起来，让我对一个 AI 应用从配置到交互的整体协作有了更具体的认识。