# TravelPlanner-Agent

基于 LangGraph + MCP 的智能旅行规划 Agent。通过自然语言对话，自动调用高德地图 API 获取真实天气和景点数据，按地理距离聚类分组，生成结构化的多天行程（含地图标点、就近餐厅推荐）。

## 功能特性

- **多 Agent 编排**：LangGraph 图驱动（偏好提取 → 记忆检索 → 意图判断 → 工具调用 → 行程规划）
- **真实数据**：通过 MCP 连接高德地图，获取实时天气、景点（带坐标）、周边餐厅
- **路径规划**：K-means 聚类 + 最近邻链，地理相近的景点安排在同一天，游览顺路不折返
- **向量记忆**：本地 embedding 模型 + ChromaDB，自动提取用户偏好并按语义检索注入
- **结构化输出**：`with_structured_output` 生成 TripPlan JSON，前端卡片 + 高德地图展示
- **Eval 回归**：固定用例自动评估意图分流、结构化输出、工具调用、偏好提取

## 技术栈

| 类别 | 技术 |
|---|---|
| 后端 | FastAPI + LangGraph |
| LLM | DeepSeek（主对话 / 结构化输出 / 偏好提取） |
| 外部服务 | 高德地图 API（通过 MCP） |
| 向量 | ChromaDB + BGE 本地 embedding |
| 前端 | 内嵌 HTML + 高德 JS API |

## 架构

```
用户输入
  → extract（偏好提取，两级过滤：关键词粗筛 + LLM 精判）
  → retrieve（记忆检索，从向量库查相关偏好注入）
  → route（意图判断：规划 or 闲聊）
  → model（LLM 决定调用工具）
  → tools（MCP 高德：天气 / 景点 / 周边餐厅）
  → plan（K-means 聚类分组 + LLM 结构化输出 TripPlan）
  → 前端卡片 + 地图展示
```

## 快速开始

### 环境要求

- Python 3.10+
- 本地 embedding 模型（BGE，需下载，见下文）

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 下载本地 embedding 模型

项目使用 `BAAI/bge-small-zh-v1.5` 做向量检索。从魔搭（ModelScope）下载到 `models/` 目录：

```bash
mkdir -p models
python -c "from modelscope import snapshot_download; snapshot_download('AI-ModelScope/bge-small-zh-v1.5', local_dir='./models/bge-small-zh-v1.5')"
```

### 3. 配置环境变量

复制 `.env.example` 为 `.env`，填写你的 key：

```env
# DeepSeek（主对话 + 结构化输出 + 偏好提取）
DEEPSEEK_API_KEY=your_deepseek_key
DEEPSEEK_BASE_URL=https://api.deepseek.com

# 高德地图（Web 服务 API Key，后端调天气/景点/餐厅）
AMAP_API_KEY=your_amap_web_key
```

### 4. 前端高德 JS Key

打开 `app.py`，把 HTML 里的 `YOUR_AMAP_JS_KEY` 替换成你的高德 **JS API Key**（和 Web 服务 Key 是两个不同的 key）。

### 5. 启动

```bash
python app.py
```

浏览器访问 http://localhost:8000 ，输入如"帮我规划西安三天行程"。

## 目录结构

```
TravelPlanner-Agent/
├── app.py                # 主后端（FastAPI + LangGraph 图）
├── amap_mcp_server.py    # 高德 MCP Server（天气/景点/周边餐厅）
├── config.py             # 配置（从 .env 读取）
├── eval_app.py           # Eval 回归测试
├── requirements.txt      # 依赖
└── examples/             # 学习版示例（V0-V5 逐步搭建过程）
    ├── main.py           # V0 最小 LLM 调用
    ├── trip_agent.py     # V2 手写 Agent Loop
    ├── graph_agent.py    # V3 LangGraph 版
    ├── v4_memory.py      # V4 手工记忆
    ├── v4_vector_memory.py  # V4 向量检索记忆
    ├── v5_eval.py        # V5 Eval
    └── test_structured.py   # 结构化输出验证
```

## 运行 Eval

```bash
python eval_app.py
```

会运行 6 个用例，自动评估：意图分流、结构化输出完整性、工具调用、偏好提取。

## 安全说明

- `.env` 已加入 `.gitignore`，请勿提交真实 API Key
- 高德 JS Key 是前端 key，明文暴露靠域名白名单限制；请配置自己的白名单
- 本地模型和向量库数据不提交到仓库

## License

MIT