# Multi‑Agent 日程规划助手

> 基于 HelloAgents 多智能体架构的本地日程规划系统，通过总控 Agent 调度解析、规划、校验子 Agent 完成用户日程生成与多轮修改。

## 📝 项目简介

问题：  
--  传统大模型日程规划容易出现时间冲突、将任务排到已过去时刻、多轮对话丢失上下文、用户记忆无法复用等问题；  
解决方案：  
-- 本项目通过分工式多智能体，把输入解析、日程规划、合法性校验进行职责拆分，提升日程输出稳定性。  
特色功能：  
- 总控 Agent 调度多子 Agent 流水线处理；  
- 支持多轮对话记忆，理解 “再加任务”“修改刚才任务” 这类指代式指令；  
- 内置时间合法性校验，禁止将今日任务排到过去时刻；  
- 支持用户记忆画像，保存用户作息、偏好、休息日；支持会话 JSON 持久化保存与加载。

## ✨ 核心功能

-  功能1:总控调度 Agent：负责流转调度 nl_parser、planner、validator 三个子 Agent，控制执行循环，异常自动降级兜底
-  功能2:自然语言解析子 Agent：解析用户自然语言输入，输出标准化 Task 任务结构体，识别新建 / 修改 / 长期规划三种意图
-  功能3:日程规划推理子 Agent：基于任务列表、用户记忆、当前真实时间生成 ScheduleItem 时间条目，禁止将今日任务排至过去时刻
-  功能4:计划校验子 Agent：校验时间重叠、违反作息、历史时间任务等违规项，输出错误标记与提示信息
-  功能5:本轮会话内存记忆：保存 user/assistant/tool 对话历史，多轮交互支持上下文指代
-  功能6:用户记忆画像：独立维护用户作息、休息日、偏好配置，与聊天会话解耦
-  功能7:会话持久化：支持将会话历史、用户记忆、最后生成计划保存 / 加载 JSON 文件
-  功能8:异常降级机制：Agent 链路解析失败时自动调用备用 bak 逻辑，保障可用性

## 🛠️ 技术栈

- HelloAgents框架 : SimpleAgent、ToolRegistry 工具注册机制
- 智能体范式: 分工流水线多 Agent（Plan‑and‑Solve 衍生，任务拆解→生成→校验闭环）
- API: 大模型 LLM API（兼容 OpenAI 兼容接口）
- 其他依赖库: pydantic (数据模型校验)、python‑json

## 🚀 快速开始

### 环境要求

- Python 3.12+
- 可用的大模型 API Key（OpenAI 兼容接口）

### 安装依赖


pip install -r requirements.txt


### 配置API密钥


# 创建.env文件
cp .env.example .env

# 编辑.env文件，填入你的API密钥


### 运行项目

# 打开main.py并运行


## 📖 使用示例

运行后在对话框输入测试指令，如：  

- [ ] 请输入你的需求：帮我规划明天，复习90分钟  
- 【助手回复】：已为您规划明天（9月6日，星期日）的日程。为您安排了90分钟的复习任务（09:00-10:30）。明天是您的休息日，完成任务后您可以自由安排慢跑或看书等休闲活动，注意劳逸结合，祝您周末愉快！   
🚀 ---日程列表---  
2026-09-06 09:00 ~ 2026-09-06 10:30 | 复习

- [ ] 请输入你的需求：将复习任务修改为下午，并设置为120分钟  
- 【助手回复】：已为您更新明天（9月6日）的计划。复习任务已调整至下午 13:30-15:30，时长更新为120分钟。完成复习后，您还有充足的下午时间进行慢跑或看书等休闲活动，祝您周末愉快！  
🚀 ---日程列表---  
2026-09-06 13:30 ~ 2026-09-06 15:30 | 复习

- [ ] 请输入你的需求：不进行复习了，明天下午进行3小时锻炼  
- 【助手回复】：  已为您更新明天（9月6日）的计划。取消了复习任务，为您安排了3小时的锻炼（13:30-16:30）。明天是休息日，下午锻炼后您还可以安排看书等放松活动，注意补充水分，祝您周末愉快！
🚀 ---日程列表---  
2026-09-06 13:30 ~ 2026-09-06 16:30 | 锻炼

- [ ] 请输入你的需求：明天下午还有一个两小时的会议需要安排  
- 【助手回复】：明天下午（13:30-18:00）的可用时间共4.5小时，无法同时安排3小时的锻炼和2小时的会议。请问您希望缩短锻炼时长、将锻炼调整至其他时间段，还是取消锻炼任务？  
⚠️未生成有效计划，请根据提示补充信息或者重新输入。

## 🎯 项目亮点

- 亮点1:职责分离多 Agent 架构：解析、规划、校验各司其职，单一模块 prompt 改动不会全局影响，便于迭代调优
- 亮点2:双重时间保护：规划阶段禁止排过去时间 + 校验 Agent 二次兜底检查，规避 “任务落在已过去时刻” 问题
- 亮点3:完整记忆体系：内存会话记忆支持多轮指代；会话、用户画像、计划可 JSON 落盘，重启可恢复
- 亮点4:强结构化输出：全部输出使用 Pydantic 模型校验，拒绝自由文本，降低大模型输出混乱带来的 bug
- 亮点5:故障容错：链路解析异常自动降级 bak 备份逻辑，不会直接崩溃


## 🔮 未来计划

- [ ] 增加工具调用能力，接入日历导出、提醒生成
- [ ] 优化长会话上下文裁剪，解决 token 无限膨胀
- [ ] WebUI 前端界面，可视化查看 / 编辑日程
- [ ] 用户记忆自动更新，从对话中自动提取用户作息偏好 

## 🤝 贡献指南

欢迎提出Issue和Pull Request！

## 📄 许可证

MIT License

## 👤 作者

- GitHub: [learner0102](https://github.com/learner0102)


## 🙏 致谢

感谢Datawhale社区和Hello-Agents项目！