hello-agents/Co-creation-projects/2248652135-Trip-Planner-Pro

Trip Planner Pro — HelloAgents 智能旅行助手 🌍✈️

项目信息

• 项目名称: Trip Planner Pro — HelloAgents 智能旅行助手
• 项目类型: 生活服务

项目简介

AI 驱动的智能旅行规划助手，基于 HelloAgents 框架构建，后端 FastAPI + 前端 Vue 3 + TypeScript。通过多智能体 LLM 编排和高德地图 MCP 协议集成，实现个性化的旅行计划生成。系统支持多智能体协作自动搜索景点、查询天气、推荐酒店并生成完整行程，同时提供 AI 旅游对话和行程管理功能。

核心功能

• AI 智能生成旅行计划 — 基于多智能体流水线自动生成详细的多日旅程，涵盖景点、住宿、交通、餐饮推荐
• 流式 AI 旅游对话 — 基于 SSE 的流式聊天，具备用户画像自动提取、跨会话上下文记忆
• 高德地图深度集成 — 通过 MCP 协议接入高德地图服务，支持 POI 搜索、天气预报、路线规划（公共交通 / 自驾 / 步行 / 混合）
• 出行人群定制 — 支持 7 种出行人群（独自旅行、情侣夫妻、朋友结伴、家庭亲子、公司团建、老年旅行、研学旅行）个性化行程定制
• 用户认证系统 — 双 JWT + HttpOnly Cookie + Redis 持久化 + RSA 加密密码传输
• 历史行程管理 — 历史行程 CRUD，支持 PDF/图片导出

🏗️ 技术栈

后端

• 框架: HelloAgents (SimpleAgent) + FastAPI
• 数据库: 原生 SQLite（WAL 模式，无 ORM）
• 缓存: Redis（Refresh Token 持久化）
• MCP 工具: amap-mcp-server（高德地图服务）
• LLM: 支持多种 LLM 提供商（OpenAI、DeepSeek 等）
• 认证: 双 JWT（HS256）、HttpOnly Cookie、RSA-OAEP 密码加密

前端

• 框架: Vue 3 + TypeScript
• 构建工具: Vite
• UI 组件库: Ant Design Vue 4
• 地图服务: 高德地图 JavaScript API
• HTTP 客户端: Axios（withCredentials 自动携带 Cookie）

技术亮点

• 多智能体流水线架构 — 4 个顺序/并行步骤（景点搜索 → 天气 → 酒店 → 规划），采用 ThreadPoolExecutor 并行执行无依赖任务，显著提升生成效率
• MCP 协议集成 — 通过 JSON-RPC 子进程方式接入高德地图 MCP 服务，Agent 自动调用地图工具获取实时数据
• 用户画像系统 — 异步提取用户意图和偏好，跨会话持久化缓存，按需加载注入上下文
• 双 JWT 认证 — Access Token（30 分钟）+ Refresh Token（7 天），HttpOnly Cookie 传递 + Redis 持久化，支持轮换和撤销
• SSE 流式输出 — AI 对话采用 Server-Sent Events 实时推送 Token，前端使用 ReadableStream.getReader() 解析流数据
• 模块级单例模式 — 每个服务暴露 get_*() 函数惰性初始化并缓存全局实例，无依赖注入框架

📁 项目结构

helloagents-trip-planner/
├── backend/                    # 后端服务
│   ├── app/
│   │   ├── agents/            # Agent 实现
│   │   │   ├── trip_planner_agent.py  # 多智能体旅行规划系统
│   │   │   ├── mcp_tool.py           # MCP 工具封装
│   │   │   └── profile_extraction_agent.py  # 用户画像提取
│   │   ├── api/               # FastAPI 路由
│   │   │   ├── main.py        # 应用入口，CORS、中间件、路由注册
│   │   │   └── routes/
│   │   │       ├── auth.py    # 用户认证
│   │   │       ├── trip.py    # 旅行计划生成
│   │   │       ├── chat.py    # AI 旅游对话（SSE）
│   │   │       ├── history.py # 历史行程
│   │   │       ├── map.py     # 地图服务
│   │   │       └── poi.py     # POI 详情
│   │   ├── services/          # 服务层
│   │   │   ├── amap_service.py       # 高德地图 HTTP 封装
│   │   │   ├── llm_service.py        # LLM 客户端
│   │   │   ├── travel_chat_service.py # AI 聊天服务
│   │   │   ├── user_profile_service.py # 用户画像管理
│   │   │   └── unsplash_service.py   # 图片服务
│   │   ├── models/
│   │   │   └── schemas.py     # Pydantic 数据模型
│   │   ├── config.py          # 配置管理
│   │   ├── database.py        # SQLite 数据库
│   │   ├── jwt_utils.py       # JWT 工具
│   │   ├── redis_service.py   # Redis 客户端
│   │   ├── rsa_service.py     # RSA 加解密
│   │   └── user_context.py    # 用户上下文中间件
│   ├── requirements.txt
│   ├── .env.example
│   └── run.py
├── frontend/                   # 前端应用
│   ├── src/
│   │   ├── views/             # 页面视图
│   │   │   ├── Home.vue       # 旅行表单首页
│   │   │   ├── Result.vue     # 行程展示（地图、导出）
│   │   │   ├── Login.vue      # 登录/注册
│   │   │   ├── History.vue    # 历史行程列表
│   │   │   └── Chat.vue       # AI 旅游对话
│   │   ├── components/        # 公共组件
│   │   ├── services/          # API 服务（Axios）
│   │   ├── types/             # TypeScript 类型
│   │   └── App.vue
│   ├── package.json
│   ├── .env.example
│   └── vite.config.ts
└── README.md

🚀 快速开始

前提条件

• Python 3.10+
• Node.js 16+
• 高德地图 API 密钥（Web 服务 API 和 Web 端 JS API）
• LLM API 密钥（OpenAI / DeepSeek 等）
• Redis 服务（可选，用于 Refresh Token 持久化）

后端安装

cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate | macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # 填入 API 密钥
python run.py          # 启动 uvicorn，端口 8000

前端安装

cd frontend
npm install
cp .env.example .env  # 填入高德地图密钥
npm run dev           # Vite 开发服务器，端口 5173
npm run build         # 生产构建

HTTPS（可选）

cd backend && openssl req -x509 -newkey rsa:2048 -keyout certs/key.pem -out certs/cert.pem -days 365 -nodes -subj "//CN=localhost"
# 在 backend/.env 中设置 SSL_ENABLED=true，重启后端
# 前端代理目标已指向 https://localhost:8000

📝 使用指南

1. 注册/登录 — 在登录页面注册账号（密码经过 RSA 加密传输）
2. 填写旅行信息 — 目的地城市、旅行日期、交通方式、住宿偏好、出行人群、旅行风格标签
3. 生成旅行计划 — 点击"生成旅行计划"，系统将：
   • 并行搜索景点、查询天气、推荐酒店
   • 整合信息生成完整行程
   • 调用高德地图 API 获取真实交通路线数据
4. 查看结果 — 每日详细行程、景点信息与地图标记、交通路线规划、天气预报、餐饮推荐、预算汇总
5. AI 旅游对话 — 针对行程进行智能问答，系统自动提取用户偏好

🔧 核心实现

多智能体流水线

# 4 个 Agent 协同工作
attraction_agent.run()   # [MCP] 搜索景点 POI
weather_agent.run()      # [MCP] 查询天气
hotel_agent.run()        # [MCP] 搜索酒店
planner_agent.run()      # [LLM 仅] 整合生成行程
_enrich_with_real_routes()  # [HTTP] 获取真实交通路线

其中景点搜索、天气查询、酒店推荐通过 ThreadPoolExecutor 并行执行，行程规划 Agent 在并行结果上顺序执行。

MCP 工具调用

Agent 自动调用高德地图 MCP 工具获取实时数据：

• maps_text_search — 景点 / 酒店 POI 搜索
• maps_weather — 天气查询
• maps_direction_* — 步行 / 驾车 / 公共交通路线规划

AI 聊天 SSE 流

POST /api/chat/sessions/{id}/messages
  → 保存用户消息 → 加载用户画像 → 注入系统提示词
  → SSE 流式返回 Token (type: token/error/done)
  → 保存 AI 回复 → 异步提取用户画像

📄 API 文档

启动后端后访问 http://localhost:8000/docs 查看 Swagger 文档。

6 组路由（前缀 /api）：

路由	功能
POST /api/auth/*	登录/注册/刷新 Token
POST /api/trip/plan	生成旅行计划
POST /api/chat/sessions/{id}/messages	AI 对话（SSE 流式）
GET /api/history/*	历史行程 CRUD
GET /api/map/*	POI 搜索、天气、路线规划
GET /api/poi/*	POI 详情和图片

数据流：旅行计划生成

请求 → POST /api/trip/plan
  → MultiAgentTripPlanner.plan_trip()
    ┌─ attraction_agent.run()    [MCP: maps_text_search]  ─┐
    ├─ weather_agent.run()       [MCP: maps_weather]      ├─ 并行执行
    └─ hotel_agent.run()         [MCP: maps_text_search]  ┘
    → planner_agent.run()        [仅 LLM，无工具]
    → _enrich_with_real_routes() [HTTP 高德 API]
  → TripPlanResponse

配置说明

后端 .env 主要配置项：

• LLM_MODEL_ID、LLM_API_KEY、LLM_BASE_URL — LLM 提供商
• AMAP_API_KEY — 高德地图 API 密钥（必填）
• REDIS_HOST/PORT/PASSWORD/DB — Redis 配置
• JWT_SECRET — 首次运行自动生成
• SSL_ENABLED/SSL_CERTFILE/SSL_KEYFILE — 可选 HTTPS

前端 .env 主要配置项：

• VITE_API_BASE_URL — 后端地址（默认 https://localhost:8000）
• VITE_AMAP_WEB_KEY/VITE_AMAP_WEB_JS_KEY — 高德 JS API 密钥

自检清单

• 代码能够正常运行
• README 文档完整
• requirements.txt 完整
• 有清晰的使用示例
• 代码有适当的注释

🤝 贡献指南

欢迎提交 Pull Request 或 Issue！

📜 开源协议

CC BY-NC-SA 4.0

🙏 致谢

• HelloAgents — 智能体教程
• HelloAgents 框架 — 智能体框架
• 高德地图开放平台 — 地图服务
• amap-mcp-server — 高德地图 MCP 服务器

---

Trip Planner Pro — 让旅行计划变得简单而智能 🌈