第一次团队作业

作业所属课程 https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS/
作业要求链接 https://edu.cnblogs.com/campus/gdgy/Class56-Grade2024-CS/homework/16766
团队名称 不想加班队
团队成员 陈梓铤-3124004053
郑剀元-3124004075
GitHub 仓库地址 Zztt417/----3

一、团队展示与项目背景

在大模型能力日益普及的今天，如何让模型真正“动手做事”而不是仅仅聊天，成为很多开发者探索的方向。本次作业我们以gpt为蓝图实现了一个运行在本地的个人助手——MyBot，它同时提供 CLI 命令行和 Web UI 两种交互方式。

项目参考了 nanobot 的极简架构，核心目标是实现：接收用户输入 → LLM 判断是否需要调用工具 → 执行工具 → 把结果返回给 LLM → 继续推理，直到给出最终答案。

在实际生活中，它能够像一个真正的私人助理一样，帮你整理并制作个人课程表、自动读取并回复邮件、解析本地 PDF 文档，成为一个可以真正辅助日常学习与工作的本地智能体。

二、项目标志与迭代规划

（注：此处为占位符，可替换为实际设计好的 Logo 图片）

MyBot —— 你的本地智能执行体。
🤖 🛠️ 💻 (极简、工具、本地化)

2.2 迭代记录表格

本项目采取敏捷开发模式，按功能模块拆分为四个主要迭代：

迭代阶段 时间节点 核心目标与交付物 状态
迭代一：需求与架构 第1-2周 完成需求分析、技术选型；跑通基础 LLM 客户端与消息格式；确定项目骨架。 ✅ 已完成
迭代二：核心循环与工具 第3-4周 实现 ReAct 主循环；完成本地工具（文件、Shell、网页搜索、PDF解析）的注册与执行框架。 ✅ 已完成
迭代三：记忆与双端交互 第5-6周 接入短期记忆滑动窗口与摘要压缩；基于 Chroma 和 bge 实现长期记忆；完成 Vue 3 前端界面与 FastAPI 联调。 ✅ 已完成
迭代四：MCP 扩展与测试 第7-8周 实现 MCP 同步桥接，接入邮件收发能力；完成多会话隔离；进行全局安全性审计与文档编写。 ✅ 已完成

三、需求描述与功能清单

3.1 功能描述

本系统的功能设计围绕“个人本地助手”的定位展开，具体如下：

  • 智能办公与日程管理：能够根据用户提供的碎片化信息，自动生成并排版每周课程表；同时通过 MCP 协议接入邮箱，实现自动收取、总结邮件并进行智能回复。
  • ReAct 工具生态：支持一次返回多个工具调用。支持本地文件读写、Shell 命令执行、网页搜索与抓取、PDF 正文及嵌套表格解析。
  • 双层记忆机制：
    • 短期记忆：滑动窗口 + 溢出摘要压缩，保证当前对话连贯。
    • 长期记忆：基于本地 Chroma 向量库 + bge 中文向量模型，支持跨会话的知识持久化与语义检索。
  • 多会话隔离管理：支持新建、切换、列出、删除、查看历史。不同对话互不干扰，长期记忆按 session_id 物理隔离。
  • 双端交互体验：命令行 REPL 支持连续对话；Vue 3 + Vite 提供可视化界面，Markdown 渲染让课表等结构化数据展示更美观。

3.2 需求约束

本项目默认是个人本地工具：run_shell 可执行本机命令，文件工具可访问本机文件。FastAPI 默认仅监听 127.0.0.1，请勿将其直接暴露到公网，真实密钥必须放在仓库外。

四、系统设计：思维导图与类图

4.1 思维导图 (Mind Map)

系统功能模块划分如下：

mindmap root((MyBot 本地智能体)) 交互层 CLI REPL Web UI (Vue 3 + Vite) Agent 核心层 ReAct 循环控制 短期记忆 (滑动窗口+摘要) 长期记忆 (Chroma 向量检索) 会话隔离 (ContextVar) 工具生态 内置工具 (文件/Shell/搜索/PDF) MCP 扩展 (邮件收发) 基础设施 FastAPI 接口 OpenAI 兼容客户端 安全审计脚本

4.2 核心类图 (Class Diagram)

核心模块之间的依赖与调用关系如下：

classDiagram class Agent { +run(input, session_id) -_react_loop() -_execute_tools() } class LLMClient { +chat_completion(messages, tools) } class ToolRegistry { +register(tool) +execute(name, kwargs) } class Tool { <<interface>> +name +description +parameters +execute(**kwargs) } class Memory { +append(message) +compress() } class LongMemory { +save(text, metadata) +search(query, session_id) } class SessionManager { +create_session() +switch_session() +get_history() } Agent --> LLMClient : 调用推理 Agent --> ToolRegistry : 执行工具 Agent --> Memory : 读写短期记忆 Agent --> LongMemory : 检索长期记忆 Agent --> SessionManager : 管理会话 ToolRegistry --> Tool : 注册与管理

五、验收标准 (Acceptance Criteria)

为确保项目交付质量，我们设定了以下验收标准：

  1. 核心循环 (ReAct)：
    • 输入明确需要工具的问题（如“读取 README.md 概括”），Agent 能正确调用 read_file 工具并将结果回填。
    • 工具执行异常时（如文件不存在），系统不崩溃，能向用户返回友好的错误提示。
  2. 记忆系统：
    • 在单次会话中连续对话超过 20 轮，系统能自动触发摘要压缩，不报 Token 超限错误。
    • 重启程序后，同一会话中提问“我之前说我爱喝什么？”，能准确提取长期记忆并回答。
  3. 多会话隔离：
    • 在会话 A 中设定的记忆，在会话 B 中提问，系统默认不会检索到。
  4. 工具与扩展：
    • 能够成功解析包含嵌套表格的测试 PDF，并输出 Markdown 格式。
    • 启用邮件 MCP 配置后，能成功调用发送工具发送一封测试邮件。
  5. UI 与部署：
    • 无需额外配置 Node.js 环境，通过 python api_server.py 即可启动 Web UI 并正常对话。
    • 执行 scripts/check_github_safety.py 脚本，不报敏感信息泄露告警。

六、系统架构与业务流

6.1 整体架构

项目在前后端分离的基础上，通过 Agent 核心层统一调度大模型与工具链：

┌──────────────────────┐
│      Vue 3 Web UI    │
│  会话列表 / 聊天 / 状态 │
└──────────┬───────────┘
           │ HTTP /api
           ▼
┌──────────────────────┐
│       FastAPI        │
│ 聊天 / 会话 / 历史接口 │
└──────────┬───────────┘
           │
           ▼
┌──────────────────────┐
│        Agent         │
│  ReAct + Session     │
└──────┬───────┬───────┘
       │       │
       ▼       ▼
┌──────────┐ ┌──────────────┐
│ LLMClient│ │ ToolRegistry │
└──────────┘ └──────┬───────┘
                    │
      ┌─────────────┼─────────────┐
      ▼             ▼             ▼
  文件/Shell     网页/PDF        MCP 工具
      │             │             │
      └─────────────┴─────────────┘
                    │
                    ▼
           短期记忆 / 长期记忆

6.2 关键技术决策

在项目开发中，我们为了保持代码的极简与健壮性，做出了以下技术决策：

技术难点 决策方案 原因
异步 MCP 桥接 MCP 使用后台线程桥接，对外提供同步接口 MCP SDK 是异步的，但 Agent 内部工具均基于同步开发，桥接可大幅降低复杂度
会话 ID 传递 使用 ContextVar 传递当前会话 ID 工具实例全局唯一，用 ContextVar 可避免模型自行编造会话 ID
上下文截断保护 摘要压缩只在回合开始执行 避免在循环中间截断 tool_calls 与 tool 的对应关系
PDF 表格识别 缩进按 X 坐标聚类 PDF 没有显式缩进结构，依靠坐标聚类能有效还原表格层级
并发安全 FastAPI 使用 RLock 保证单例运行 避免多请求并发修改 Agent 状态，导致 JSONL 或向量库写入冲突
前端免安装 ui/dist 随仓库提交 普通用户无需配置 Node.js 环境即可直接启动 Web UI

七、快速上手与功能演示

7.1 环境安装与配置

配置读取优先级为：MYBOT_ENV_FILE > 项目根目录 .env > 用户目录 ~/.mybot/.env。推荐将真实密钥放在用户目录下。

# 1. 创建虚拟环境并安装依赖
python -m venv .venv
source .venv/bin/activate  # Windows 使用 .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# 2. 配置密钥
mkdir -p ~/.mybot
cp .env.example ~/.mybot/.env
# 编辑 ~/.mybot/.env，填入 OPENAI_API_KEY、OPENAI_BASE_URL 等配置

# 3. 启动（二选一）
python main.py          # CLI 模式
python api_server.py    # Web UI 模式 (访问 http://127.0.0.1:8000)

7.2 实际场景演示

场景一：文件与系统操作

用户：在当前目录创建 schedule.txt，内容为“周一：高数；周二：英语”，然后运行 python --version 告诉我版本。
Agent：自动调用 write_file 创建文件，随后调用 run_shell(command="python --version")，最后整合信息回复。

场景二：网页搜索与 PDF 解析

用户：解析 samples/_synthetic_nested.pdf 的第 1 页，提取其中包含嵌套结构的表格。
Agent：调用 pdf_parse 工具，按坐标聚类还原缩进，最终以 Markdown 表格形式输出。

场景三：记忆管理与跨会话检索

用户：记住：我的项目使用 FastAPI + Vue 3，我喜欢喝美式咖啡。
Agent：调用 memory_save 写入长期记忆。重启程序后，用户提问“我喜欢喝什么？”，系统生成查询向量从 Chroma 检索，回复“你喜欢喝美式咖啡。”

八、团队分工

成员 主要职责
陈梓铤 3124004053 核心模块研发：Agent 核心 ReAct 循环、ToolRegistry 工具层实现、PDF 解析与坐标聚类、MCP 后台线程桥接与邮件扩展。
郑剀元 3124004075 系统与前端研发：短期/长期记忆系统设计、FastAPI 接口层搭建、Vue 3 前端开发、ContextVar 会话隔离机制。

两人在接口约定和联调阶段保持紧密配合，确保 CLI 与 Web UI 两个入口共用同一套 Agent 运行时和工具生态。

九、总结与展望

MyBot 是一次将大模型从“聊天对象”推向“本地执行体”的完整实践。通过 ReAct 循环、工具调用、双层记忆和双端交互的设计，项目验证了本地个人 Agent 在课表制作、邮件自动回复、文件操作、信息检索等场景下的巨大潜力。

后续可以改进的方向：

  • 安全沙箱：为 run_shell、文件操作和邮件发送增加更细粒度的权限控制和用户二次确认机制。
  • 工具生态扩展：基于 MCP 协议接入更多外部服务（如校园教务系统、本地日历），降低新工具的接入成本。
  • 记忆策略优化：探索更智能的摘要触发条件和长期记忆检索排序策略，提升大段上下文的理解能力。
  • 前端体验：增强 Web UI 中的工具调用过程可视化，让 Agent 的“思考与行动”链路对用户更加透明。

项目仓库：Zztt417/----3

posted @ 2026-11-08 22:34  zkyy  阅读(11)  评论(0)    收藏  举报