mcp作业

04_work/README.md

@@ -0,0 +1,212 @@
+# 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
+- 多供应商数据源切换
+
+## 📄 许可
+
+个人学习/作业项目，未指定开源许可证。