# TravelMind — 多角色智能旅行规划系统 TravelMind 是一个基于 **LangGraph 多角色 Agent 工作流** 的智能行程规划系统：用户用自然语言描述旅行需求（出发地、目的地、日期、预算、偏好等），系统自动完成需求解析、航班/酒店资源查询、目的地地图研究、行程编排、风险评审与迭代优化，最终输出结构化多日行程。 > 项目名中的 "Mind" 取自 *multi-agent mind*：多个各司其职的 Agent 以 Supervisor 模式协同工作，像一支"思维团队"一样规划行程。 ## ✨ 核心特性 - **自然语言直接规划**：输入"帮我规划 6 月下旬从北京去东京玩 5 天，预算 1.5 万以内"，即可获得完整行程方案 - **多角色 Agent 协作**：需求解析、资源查询、地图研究、行程规划、行程评审 5 个 Agent 分工协作 - **Supervisor 迭代评审**：规划结果经过确定性校验与独立评审，不合格自动重新规划（带重试上限，避免死循环） - **真实数据查询**：航班/酒店走 **SerpApi Google Flights/Hotels**，景点/餐饮/天气走 **高德地图官方 MCP** - **MCP 标准化接入**：自建航班/酒店搜索 MCP 服务器（FastMCP），与外部高德 MCP 统一接入 - **防编造设计**：候选筛选、路线评估、计划校验等环节使用**确定性代码**而非 LLM，保证 ID、日期、价格等信息的真实性，防止模型编造航班、酒店、景点和价格 - **模型无关**：兼容 OpenAI 及其兼容服务（DeepSeek、通义千问等），仅需配置 `MODEL_BASE_URL` ## 🏗️ 架构总览 系统采用 **LangGraph 状态图** 编排完整工作流，Supervisor 在关键节点做路由决策： ``` 用户需求 │ ▼ ┌──────────────┐ 澄清/报错(条件路由) ┌──────────────────┐ │ 需求解析Agent │ ─────────────────────► │ 补充需求/终止 │ └──────┬───────┘ └──────────────────┘ │ TravelRequest（结构化） ▼ ┌──────────────┐ 高德 MCP 工具 ┌──────────────────┐ │ 资源查询Agent │ ─────────────────────► │ 地图研究Agent │ │ 航班/酒店 │ │ 景点/餐饮/天气 │ └──────┬───────┘ └────────┬─────────┘ │ 候选资源 │ POI 数据 ▼ ▼ ┌──────────────────────────────────────────────────────────────┐ │ 候选筛选 → 路线评估 → 行程规划Agent │ │ （生成结构化多日行程） │ └──────────────────────┬───────────────────────────────────────┘ │ ▼ ┌──────────────────┐ 未通过（重新规划循环） ┌──────────────┐ │ 校验 → 评审Agent │ ◄────────────────────── │ Supervisor │ └──────┬───────────┘ │ (路由决策) │ │ 通过 └──────────────┘ ▼ ┌──────────────────┐ │ 最终定稿/输出 │ └──────────────────┘ ``` 工作流环节：**需求解析 → 资源查询 → 候选筛选 → 地图研究 → 路线评估 → 行程规划 → 校验 → 评审 → 最终定稿**，其中规划/评审环节存在带重试上限的迭代循环（`recursion_limit = 80`）。 ### 角色分工 | Agent | 职责 | |-------|------| | **RequirementAgent** 需求解析 | 把自然语言转换为结构化 `TravelRequest`，意图识别与字段提取（仅解析，不规划）；缺字段时走澄清流程 | | **ResourceSearchAgent** 资源查询 | 调用航班/酒店 MCP 工具搜索外部资源，指导工具调用顺序并汇总为结构化结果 | | **MapResearchAgent** 地图研究 | 调用高德地图 MCP 工具，搜索目的地周边景点、餐饮与天气，返回结构化 POI 数据 | | **ItineraryPlannerAgent** 行程规划 | 基于候选资源与地图研究结果，生成包含每日活动安排的结构化多日行程 | | **TripReviewerAgent** 行程评审 | 从风险控制角度独立评审，识别节奏、地理、预算等维度的问题并给出修改意见 | | **Supervisor** 监督协调 | 汇总校验与评审意见，决定 `replan` / `finalize` / `finalize_with_risks` / `terminate` | ### 确定性模块（不使用 LLM） 以下环节刻意使用确定性代码，保证准确性与成本控制： | 模块 | 原因 | |------|------| | Candidate Selector | 排序和过滤规则确定 | | Route Evaluator | 距离和评分可确定性计算 | | Plan Validator | ID、日期、预算必须准确 | | Finalizer | 防止最终展示阶段重新编造信息 | LLM 只负责自然语言理解、复杂取舍、行程编排和体验审查。 ### MCP 集成 通过 `langchain-mcp-adapters` 的 `MultiServerMCPClient` 同时接入两个 MCP 服务器： 1. **travel_search（自建）**：stdio 传输，`mcp_servers/travel_search_server.py`（FastMCP）包装 `TravelSearchService`，提供 `search_airports`、`search_flights`、`search_return_flights`、`search_hotels` 工具，底层调用 SerpApi 2. **amap（高德官方）**：Streamable HTTP 传输，`https://mcp.amap.com/mcp`，提供 `maps_*` 系列工具（POI 搜索、餐饮、天气、距离测量、路线规划等） ## 🛠️ 技术栈 - **Python ≥ 3.10**，[uv](https://docs.astral.sh/uv/) 包管理 - **LangChain 1.x / LangGraph**：Agent 与状态图编排 - **langchain-openai**：统一模型接入（OpenAI / DeepSeek / Qwen 等） - **langchain-mcp-adapters + mcp**：MCP 客户端与自建 MCP 服务器（FastMCP） - **httpx**：SerpApi HTTP 调用（支持 SOCKS 代理） - **pydantic / pydantic-settings**：数据模型与配置管理 - **rich**：终端输出美化 - **pytest**：单元测试 ## 🚀 快速开始 ### 1. 环境准备 需要 [uv](https://docs.astral.sh/uv/) 包管理器（或使用任意虚拟环境工具）： ```bash # 进入项目目录并安装依赖（自动创建 .venv） uv sync ``` ### 2. 配置环境变量 ```bash cp .env.example .env ``` 编辑 `.env`，填写以下必填项（`app/config.py` 会从项目根目录 `.env` 读取，缺配置时会给出明确错误）： | 变量 | 说明 | 必填 | |------|------|------| | `MODEL_API_KEY` | OpenAI 或兼容服务的 API Key | ✅ | | `MODEL_NAME` | 模型名，如 `gpt-4.1-mini`、`qwen-plus`、`deepseek-chat` | ✅ | | `MODEL_BASE_URL` | OpenAI 官方接口可留空；兼容接口填对应 Base URL | 视服务 | | `SERPAPI_API_KEY` | SerpApi 密钥（Google Flights/Hotels 搜索） | ✅ | | `AMAP_API_KEY` | 高德开放平台密钥（MCP 地图服务） | ✅ | | `REQUEST_TIMEOUT_SECONDS` | 请求超时（秒），默认 `120` | 否 | > ⚠️ `.env` 包含敏感密钥，已被 `.gitignore` 排除，**切勿提交到版本库**。密钥缺失时，`Settings.require()` 会抛出带具体变量名的错误。 ### 3. 运行 支持两种输入方式： ```bash # 方式一：命令行参数直接传入 uv run python main.py 帮我规划6月下旬从北京去东京玩5天，预算1.5万以内 # 方式二：交互式输入（支持多行，输入空行结束） uv run python main.py ``` 运行结束后会输出最终行程方案与执行状态（trace_id、各环节执行次数、Supervisor 决策、总耗时等）。 ## 🧪 测试 ```bash # 运行全部单元测试 uv run pytest # 或使用自动化回归入口（只跑本地单元测试） uv run python -m scripts.run_regression # 真实接口集成测试（会调用真实模型、SerpApi 和高德 MCP，可能产生费用） uv run python -m scripts.run_regression --integration ``` ## 📁 项目结构 ``` travel-mind/ ├── main.py # CLI 入口：读取需求并执行完整工作流 ├── pyproject.toml # 项目配置与依赖（uv） ├── .env.example # 环境变量模板（.env 不入库） ├── app/ │ ├── config.py # pydantic-settings 配置中心（读取 .env） │ ├── llm.py # 大模型工厂（兼容 OpenAI/DeepSeek/Qwen） │ ├── mcp_client.py # MCP 工具加载器（自建 + 高德双服务器） │ ├── agents/ # 五个角色 Agent │ │ ├── requirement_agent.py # 需求解析 │ │ ├── resource_agent.py # 资源查询 │ │ ├── map_agent.py # 地图研究 │ │ ├── itinerary_agent.py # 行程规划 │ │ └── reviewer_agent.py # 行程评审 │ ├── graph/ # LangGraph 工作流（builder + nodes + state） │ │ ├── planner_builder.py # 完整主图编排 │ │ ├── supervisor_nodes.py # 监督协调与路由 │ │ └── ... # 各环节节点 │ ├── schemas/ # Pydantic 数据模型（航班/酒店/行程/路线…） │ ├── services/ # 业务服务（搜索/筛选/评估/校验/定稿） │ ├── clients/ │ │ └── serpapi_client.py # SerpApi HTTP 客户端 │ └── logging_config.py # 日志与 trace_id ├── mcp_servers/ │ └── travel_search_server.py # 自建旅行搜索 MCP 服务器（FastMCP） ├── scripts/ # 各环节调试脚本 + 回归测试入口 └── tests/ # pytest 单元测试 ``` ## 📌 当前限制 该项目是生产架构导向的可运行 MVP，而不是已上线商业系统： - 航班和酒店数据用于查询与规划，不执行真实预订 - 航班接口报价的计价范围需以供应商页面为准 - 部分未来日期无法查询准确天气 - 未完整覆盖门票、餐饮和市内交通价格 - 没有数据库和长期会话持久化 - 没有针对大规模并发进行压力测试 - MCP 和第三方 API 失效时的降级能力仍可增强 ## 🔭 生产化方向 - FastAPI 服务接口 - Redis 缓存与限流 - LangGraph Checkpointer 持久化 - 用户会话管理 - MCP 超时、熔断和降级 - OpenTelemetry 链路追踪 - Agent 调用成本统计 - Prompt 和工作流评测集 - Docker 与 CI/CD - 多供应商数据源切换 ## 📄 许可 个人学习/作业项目，未指定开源许可证。