文章目录1. 项目概述与架构设计1.1 GiftGenius 是什么？1.2 核心架构：三智能体流水线1.3 三大核心亮点1.4 技术栈总览2. 环境准备与配置管理2.1 系统要求2.2 Python 与 Jupyter 安装2.3 获取 API 密钥（必须提前申请）（A）大模型 API 密钥（必填）（B）Tavily Search API（二选一）（C）百度优选 MCP Token（二选一）2.4 项目目录结构2.5 依赖安装2.6 环境变量配置步骤 1：创建 `.env example` 模板步骤 2：创建并填写 `.env` 真实配置3. 代码实现详解第 1 部分：环境配置第 2 部分：定义统一搜索工具第 3 部分：创建智能体第 4 部分：读取用户数据第 5 部分：核心业务逻辑——礼物计划生成5.1 辅助函数：预算解析与价格提取5.2 核心搜索函数：四重防御机制5.3 主执行循环第 6 部分：输出渲染与保存第 7 部分：总结与展望已实现的功能遇到的挑战与解决方案未来改进方向4. 测试验证指南4.1 启动项目4.2 运行步骤4.3 验证检查点4.4 切换搜索引擎5. 常见问题排查（FAQ）Q1：`ModuleNotFoundError: No module named 'hello_agents'`Q2：`LoadError: API key is required`Q3：百度 MCP 连接超时Q4：搜索结果为空Q5：生成的价格明显不合理Q6：`RuntimeError: This event loop is already running`6. 总结与未来展望7. 附录：完整代码清单7.1 完整文件列表7.2 requirements.txt7.3 .env example7.4 data/test_cases.json7.5 main.ipynb Cell 1：环境配置7.6 main.ipynb Cell 2：定义统一搜索工具7.7 main.ipynb Cell 3：创建智能体7.8 main.ipynb Cell 4：读取数据7.9 main.ipynb Cell 5：核心业务逻辑（含辅助函数、搜索函数、主循环）7.10 main.ipynb Cell 6：输出渲染与保存1. 项目概述与架构设计1.1 GiftGenius 是什么？GiftGenius 是一个智能化的礼物推荐 Multi-Agent 系统，基于 HelloAgents 框架构建的多智能体协作流水线。它解决"送什么礼物"这个现实难题：根据送礼对象的MBTI 人格、星座、年龄、预算等个性化画像，从全网实时检索最新商品信息，最终生成一份图文并茂、价格透明的送礼指南。1.2 核心架构：三智能体流水线GiftGenius 采用多智能体分工协作的流水线架构，各智能体职责分明、松耦合协同工作：┌─────────────────────────────────────────────────────────────┐ │ GiftGenius 系统架构 │ ├─────────────────────────────────────────────────────────────┤ │ 用户输入 (user_profile.json) │ │ │ │ │ ▼