内容
# 🔥 多智能体消防员 – 多智能体森林火灾决策支持平台
> 本仓库包含一个用于森林火灾应急决策支持的原型Web平台。
> 它结合了基于地图的操作工作流、**React**、**FastAPI**、**PostgreSQL**、可选的**MCP服务器**和**LangGraph多智能体系统**，用于解释事件更新并生成结构化的操作指导。
## 📚 目录
- [🔥 多智能体消防员 – 多智能体森林火灾决策支持平台](#-多智能体消防员-–-多智能体森林火灾决策支持平台)
- [📚 目录](#-目录)
- [🚀 概述](#-概述)
- [🏗️ 架构](#️-架构)
- [⚙️ 技术](#️-技术)
- [🧩 项目结构](#-项目结构)
- [🧭 如何运行（手动设置）](#-如何运行手动设置)
- [🔍 健康检查](#-健康检查)
- [🧠 多智能体工作流](#-多智能体工作流)
- [📸 截图](#-截图)
- [🧰 有用的命令](#-有用的命令)
- [🔒 安全检查清单](#-安全检查清单)
- [👤 作者](#-作者)
## 🚀 概述
**多智能体消防员**是一个研究原型，探索人类操作员如何在请求基于AI的系统提供操作支持之前建立结构化的森林火灾事件上下文。
该系统包括：
- 使用 **React + MapLibre GL** 构建的交互式操作地图
- 使用 **FastAPI** 实现的后端API
- 使用 **PostgreSQL** 的操作数据库
- 使用 **Alembic** 的数据库迁移
- 使用 **LangGraph** 构建的多智能体决策支持工作流
- 针对选定的站点、团队、资源和位置的实体解析
- 可选的 **模型上下文协议（MCP）** 服务器，用于天气查询等辅助工具
平台不依赖于纯文本聊天，而是让用户定义事件区域、火点、站点、团队、资源和支持实体。首先确认该上下文，然后将用户的消息与多智能体系统一起发送。
## 🏗️ 架构
当前原型分为四个主要层：
| 层 | 责任 |
|-------|----------------|
| **前端** | 提供地图、工作流面板、操作表单、上下文审查和聊天界面 |
| **后端** | 提供位置和操作数据，验证请求，并触发多智能体运行器 |
| **数据库** | 存储位置、几何形状、站点、团队、资源和分配 |
| **多智能体系统** | 规范化消息，解析实体，协调智能体，并综合最终答案 |
| **MCP服务器** | 用于天气数据等外部工具的可选扩展层 |
**主要流程：**
```text
用户
|
v
React + MapLibre 前端
|
v
FastAPI 后端
|
+--> PostgreSQL 操作数据库
|
v
LangGraph 多智能体管道
|
v
在操作聊天中显示的最终响应
```
## ⚙️ 技术
| 层 | 技术 | 描述 |
|-------|------------|-------------|
| 前端 | **React + TypeScript + Vite** | Web界面和操作工作流 |
| 地图 | **MapLibre GL** | 交互式地图渲染 |
| 后端 | **FastAPI** | 前端和事件聊天的REST API |
| 数据库 | **PostgreSQL** | 操作数据持久化 |
| ORM / 迁移 | **SQLAlchemy + Alembic** | 数据库模型和模式演化 |
| 多智能体运行时 | **LangGraph + LangChain** | 智能体图编排 |
| 验证 | **Pydantic** | 结构化数据验证 |
| MCP工具 | **Python MCP SDK** | 可选的外部工具服务器 |
| 包管理 | **uv + npm** | Python和前端依赖管理 |
## 🧩 项目结构
```text
MASs-firefighter/
|-- backend/ # 前端使用的FastAPI API
| |-- src/backend_api/
| `-- pyproject.toml
|
|-- frontend/ # React + Vite操作界面
| |-- src/
| |-- public/
| `-- package.json
|
|-- mcp-server/ # 可选的MCP服务器，带有辅助工具
| |-- app/
| `-- server.py
|
|-- multi-agent/ # LangGraph多智能体系统和数据库设置
| |-- app/
| |-- alembic/
| |-- data/
| |-- tests/
| `-- docker-compose.yml
|
|-- docs/
`-- README.md
```
## 🧭 如何运行（手动设置）
### 1. 准备多智能体服务和数据库
```bash
cd multi-agent
cp .env.example .env
cp app/config/.env.example app/config/.env
uv sync
docker compose up -d
uv run alembic upgrade head
uv run python -m app.db.operational.seed
```
这将启动PostgreSQL，应用迁移，并播种操作数据库。
### 2. 启动后端API
```bash
cd ../backend
cp .env.example .env
uv sync
uv run uvicorn src.backend_api.main:app --reload
```
后端URL：
```text
http://127.0.0.1:8000
```
### 3. 启动MCP服务器
```bash
cd ../mcp-server
uv sync
uv run python server.py
```
默认MCP端点：
```text
http://127.0.0.1:8001/mcp
```
### 4. 启动前端
```bash
cd ../frontend
npm install
npm run dev
```
前端URL：
```text
http://localhost:5173
```
## 🔍 健康检查
- 端点：`GET /health`
- 预期目的：验证FastAPI后端是否正在运行
示例：
```bash
curl -i http://127.0.0.1:8000/health
```
主要API端点：
| 方法 | 端点 | 目的 |
|--------|----------|---------|
| `GET` | `/health` | 后端健康检查 |
| `GET` | `/api/locations/map` | 地图GeoJSON位置 |
| `GET` | `/api/locations/unmapped` | 无几何位置 |
| `POST` | `/api/locations/{location_id}/geometry` | 保存位置几何 |
| `GET` | `/api/operational/stations/compositions` | 站点、团队和资源 |
| `POST` | `/api/incident/chat` | 运行事件聊天工作流 |
## 🧠 多智能体工作流
多智能体系统从后端接收两个输入：
- 用户的自然语言消息
- 在前端确认的结构化事件上下文
工作流包括：
| 步骤 | 描述 |
|------|-------------|
| **规范化** | 将用户的消息转换为结构化的内部表示 |
| **实体解析** | 将提到的团队、资源、站点和位置链接到选定的上下文 |
| **协调** | 构建执行计划并决定哪些智能体应运行 |
| **专用智能体** | 运行情况、资源、风险和决策支持智能体 |
| **综合** | 生成在聊天中显示的最终操作响应 |
当前专用智能体包括：
- 情况评估智能体
- 资源分析智能体
- 风险分析智能体
- 决策支持智能体
- 最终综合智能体
## 📸 截图
| 地图布局 | 操作聊天 |
|--------------|------------------|
|  |  |
| 节点图 | MCP服务器 |
|----------------|------------------|
|  |  |
## 🧰 有用的命令
```bash
# 从多智能体模块启动PostgreSQL
cd multi-agent
docker compose up -d
# 应用数据库迁移
uv run alembic upgrade head
# 播种操作数据
uv run python -m app.db.operational.seed
# 运行多智能体测试
uv run pytest
# 启动后端API
cd ../backend
uv run uvicorn src.backend_api.main:app --reload
# 启动前端
cd ../frontend
npm run dev
# 构建前端
npm run build
# 运行前端linting
npm run lint
```
## 🔒 安全检查清单
- `.env`文件被忽略，不应提交
- 为本地设置提供了示例环境文件
- PostgreSQL默认通过Docker Compose本地运行
- 前端仅与配置的后端API通信
- API CORS仅限于本地开发前端源
- 请勿在仓库中存储真实的紧急、个人或敏感的操作数据
- 这是一个原型，不得用作真实的紧急响应系统
## 👤 作者
- **Daniel Serrano Segura**
- **Eduardo Peralta**
