# TravelMind Agent Lab

一个可以直接运行、适合逐文件学习的多 Agent 旅行规划项目。默认 `demo` 模式不需要
API Key；主 Agent 会并行调用航班、酒店、活动三个专家，读取本地旅行知识，最后生成
结构化方案并保存到 SQLite。

## 你会在这里学到什么

- LangGraph 状态图与主 Agent 编排
- `asyncio.gather` 并行专家调用
- Pydantic 请求/响应模型
- FastAPI、后台任务与 SSE 事件流
- 本地 RAG、SQLite 会话持久化
- DeepSeek V4 Pro 的 OpenAI-compatible API
- 可选 Redis 任务状态、PostgreSQL 报告存储、FastMCP 工具

## 3 分钟启动

```powershell
uv sync --extra dev
Copy-Item .env.example .env
uv run travelmind-api
```

浏览器打开 <http://127.0.0.1:8000/docs>，调用 `POST /api/v1/plan`：

```json
{
  "query": "帮我规划一次四天的巴黎旅行",
  "origin": "Shanghai",
  "destination": "Paris",
  "days": 4,
  "budget": 12000,
  "currency": "CNY",
  "thread_id": "lesson-001"
}
```

默认结果是可重复的模拟数据，目的是先学清 Agent 数据流。测试命令：

```powershell
uv run pytest
uv run ruff check .
```

## 切换 DeepSeek

在 `.env` 中填写：

```dotenv
APP_MODE=deepseek
DEEPSEEK_API_KEY=你的密钥
DEEPSEEK_MODEL=deepseek-v4-pro
```

DeepSeek 只负责润色基于工具结果的摘要，航班、酒店和活动仍使用演示 Provider，避免
模型虚构价格。以后可在 `providers.py` 中替换为真实 Amadeus/地图 API。

## 可选基础设施

```powershell
docker compose -f docker/compose.yml up -d
uv sync --extra redis --extra postgres --extra mcp
```

- `REDIS_URL=redis://localhost:6379/0`：任务状态放入 Redis。
- `DATABASE_URL=postgresql://travelmind:travelmind@localhost:5432/travelmind`：
  报告放入 PostgreSQL。
- `uv run travelmind-mcp`：把 `plan_trip` 暴露为 MCP 工具。

没有 Redis/PostgreSQL 时会自动使用内存任务表和 SQLite，因此核心项目始终能启动。

## 学习顺序

1. `models.py`：理解输入、专家结果和最终报告。
2. `agents.py`：看三个专家如何并行工作。
3. `graph.py`：看主 Agent 如何连接检索、专家和汇总节点。
4. `service.py`：看图执行和持久化。
5. `api.py`：看 HTTP、后台任务和 SSE。
6. `storage.py`、`jobs.py`：再学习数据库与 Redis 适配器。

## 项目边界

这是可运行的学习版，不是出票系统。演示价格不应被用于真实预订。真实供应商 API、
认证、限流、退款和支付属于后续工程阶段。

来源与许可证说明见 [UPSTREAM.md](UPSTREAM.md)。