🧙♂️ 周末巫师
周末巫师是 基于CLI的AI代理 计划舒适的周末想法 工具调用（MCP） 和一个 规划器→ 执行者 建筑。它在本地运行，使用 奥拉玛 （使用Mistral 7B），可以调用天气查询、书籍推荐、笑话、狗图片和琐事等工具。
该项目展示了 鲁棒代理循环 这避免了常见的LLM故障（如部分输出，如 1)通过将计划与执行分开。
______________________________________________________________________
✨ 特性
- 交互式CLI代理
- 规划师→ 执行器设计（在小型型号上稳定）
- 通过MCP（模型上下文协议）调用工具
- 使用Ollama执行本地LLM
- 防御性JSON解析和重试
可用工具（来自 server_fun.py):
get_weather(lat, lon)book_recs(topic, limit)random_joke()random_dog()trivia()
______________________________________________________________________
📁 项目结构
weekend-wizard/
│
├── agent_fun.py # Main CLI agent (planner + executor)
├── server_fun.py # MCP tool server (defines tools)
├── README.md # Project documentation
└── .venv/ # (optional) virtual environment______________________________________________________________________
🔧 需求
- Python 3.10+ （用Python 3.13测试）
- 奥拉玛 已安装并正在运行
- 互联网连接（用于OpenLibrary和天气API）
______________________________________________________________________
🧠 LLM设置（Ollama）
- 从以下位置安装Olama：
https://ollama.com
- 拉动所需的模型：
ollama pull mistral:7b- 确认Ollama正在运行：
ollama list______________________________________________________________________
🐍 Python设置
1.️⃣ 创建虚拟环境（推荐）
python -m venv .venv激活它：
- 视窗
.venv\Scripts\activate- macOS/Linux
source .venv/bin/activate2.️⃣ 安装依赖项
pip install -r requirements.txt______________________________________________________________________
▶️ 如何跑步
基本执行
python agent_fun.py指定自定义工具服务器文件（可选）
python agent_fun.py server_fun.py跑步后，你会看到：
Connected tools: ['get_weather', 'book_recs', 'random_joke', 'random_dog', 'trivia']然后与代理交互：
You: I want 2 book ideas about mystery输出示例：
🔧 LLM called tool: book_recs
Agent:
1) The Hound of the Baskervilles – Arthur Conan Doyle
2) The Girl with the Dragon Tattoo – Stieg Larsson类型 exit 或 quit 停止。
______________________________________________________________________
🧩 工作原理（高级）
- 用户输入 去规划师LLM
- 规划师决定：
- 调用哪个工具 - 用什么论据
- MCP服务器执行该工具
- 工具结果被发送回LLM
- LLM格式化最终的自然语言答案
这种设计可以防止：
- 部分输出(
1,ok等等） - 无效的JSON崩溃
- 无限工具循环
______________________________________________________________________
🛠 故障排除
❌ 代理人回应 1
- 确保您正在使用 规划器→ 执行者版本 的
agent_fun.py - 将Ollama温度设置为
0.0 - 确认
mistral:7b已安装
❌ JSON错误
- 除非您理解代理合同，否则不要修改SYSTEM提示
- 确保工具返回有效的JSON可序列化对象
❌ 未找到工具
- 验证工具是否存在于
server_fun.py - 更改工具定义后重新启动代理
______________________________________________________________________
🚀 下一个想法
- 添加内存（对话状态）
- 添加工具使用跟踪/日志记录
- 升级为多智能体规划师+评论家
- 将Mistral替换为更大的模型（13B+）以获得更好的推理
______________________________________________________________________
📜 许可证
这个项目是为了学习和实验。
黑客快乐！ 🎉