# SmartBizTrip 企业差旅智能体

本项目用于学习意图识别、任务规划、A2A 子助手协作、MCP 工具调用和对话记忆。预订功能为模拟演示，不会实际下单或出票。

## 1. 准备 Python 环境

安装 uv 后，在项目根目录（能看到本文件和 `pyproject.toml`）打开终端：

```sh
uv sync --locked
uv run python --version
```

看到 Python 3.12.x，并且依赖安装无报错后继续。保留 `pyproject.toml`、`uv.lock` 和 `.python-version`；不需要复制他人的 `.venv`。

## 2. 填写自己的配置

macOS / Linux：

```sh
cp .env.example .env
cp .env.mysql.example .env.mysql
```

Windows PowerShell：

```powershell
Copy-Item .env.example .env
Copy-Item .env.mysql.example .env.mysql
```

编辑这两个文件，把 `your_...` 替换成自己的配置：

- `DEEPSEEK_API_KEY`：聊天模型密钥；`DEEPSEEK_MODEL` 填自己的账号可用的模型名。
- `MYSQL_PASSWORD`：两个文件中保持一致；数据库账号、库名也应一致。
- `QWEATHER_API_KEY`、`QWEATHER_API_HOST`：使用天气 API 时填写。
- `DASHSCOPE_API_KEY`：使用会务套餐向量检索时填写，不能用聊天模型密钥代替。
- `WEATHER_SOURCE=database`：使用 SQL 中的天气样例；`api` 使用天气接口。

示例配置不含真实密钥。填写后的 `.env`、`.env.mysql` 只保留在自己的电脑，不提交或发送给别人。

## 3. 先运行离线测试

```sh
uv run python -B -m tests.run_offline
```

看到 `OK` 后继续。此命令使用模拟对象并阻止网络连接，不消耗真实模型额度。需要数据库或 A2A 服务的集成测试会显示 `skipped`，这不代表它们已通过联网验证。

## 4. 启动数据服务

使用本项目的 Docker 配置时，先打开 Docker，再运行：

```sh
docker compose up -d mysql milvus
docker compose ps
```

看到所需服务为 `healthy` 后继续。此 Compose 只启动 MySQL 和 Milvus，不启动 Python 服务。

SQL 样例主要是 **2026-05-01，北京到成都、成都当地资源**。首次使用空数据卷会执行建表和样例导入；已有数据卷不会因为重启自动重新导入。`sql/create_all_tables.sql` 含删库重建语句，只用于准备教学样例库，不要对已有重要数据执行。

仅学习会务套餐检索时，填写向量模型配置并启动 Milvus 后，再手动运行：

```sh
uv run python sql/init_meeting_package_rag.py
```

看到插入成功和样例检索结果后再查询会务套餐。此脚本会删除并重建同名集合，不是增量导入。

## 5. 分别启动 Python 服务

每条命令使用一个终端，均在项目根目录执行。目录名称可以修改，不必叫 `SmartBizTrip`。

先启动 MCP 工具服务，看到各自监听端口后继续：

```sh
uv run python -m mcp_server.mcp_ticket_server
uv run python -m mcp_server.mcp_weather_server
uv run python -m mcp_server.mcp_trip_server
```

再启动 A2A 子助手：

```sh
uv run python -m a2a_server.ticket_server
uv run python -m a2a_server.weather_server
uv run python -m a2a_server.trip_server
```

最后启动网页 API：

```sh
uv run api_server.py
```

看到 API 监听 `127.0.0.1:8080` 后，浏览器打开 `http://127.0.0.1:8080`。

| 服务 | 端口 |
| --- | --- |
| 网页 API | 8080 |
| 天气 / 票务 / 差旅 A2A | 5005 / 5006 / 5007 |
| 票务 / 天气 / 差旅 MCP | 8001 / 8002 / 8003 |
| MySQL / Milvus | 3306 / 19530 |

导入样例数据后，可询问：“查询 2026 年 5 月 1 日北京到成都的二等座高铁票”。若使用天气数据库模式，可询问同一天的成都天气。其他日期不保证有样例数据。

## 6. 阅读代码

从 `api_server.py` 的启动与路由开始，再看 `ChatService.chat_stream()`，然后追踪票务助手和 MCP 的 `query_train`。

```text
网页 → API → ChatService → A2A 子助手 → MCP 工具 → 数据源
网页 ← SSE ← 主助手汇总 ← 子助手回复 ← 工具结果 ← 数据源
```

`agent_learn/` 是独立概念示例；`课件示例/项目实现/` 中的编号文件是随课程逐步组合的片段，部分依赖前面章节的导入、类或变量，不应逐个当完整程序运行。完整项目以根目录及 `a2a_server/`、`mcp_server/` 为准；课件中的 Docker 全服务部署片段需要按章节整合，根目录 Compose 仅负责数据服务。

若要运行需要真实服务的测试，先准备对应服务和自己的配置，再设置 `RUN_ONLINE_TESTS=1`。这些测试可能调用模型；平时练习使用离线测试命令即可。