文章目录

• • 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.txt
    • 7.3 .env example
    • 7.4 data/test_cases.json
    • 7.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：输出渲染与保存