# Medical-triage-assistant

**Repository Path**: BLOGSFan/Medical-triage-assistant

## Basic Information

- **Project Name**: Medical-triage-assistant
- **Description**: 医疗导诊助手是一个面向互联网医院的智能导诊 Agent 系统，实现 「主诉采集 → 科室建议 → 号源查询 → 就诊须知」 全流程自动化。

系统采用 主 Agent + 导诊子 Agent 的双层架构：主 Agent 负责多轮问诊编排与状态管理，导诊子 Agent 基于 LLM 进行分诊推理并输出科室建议与注意事项。所有分诊结果均为辅助建议，非诊断结论。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-05
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 医疗导诊助手

**基于 LangGraph + MCP 的智能导诊 Agent 系统**

[![Python](https://img.shields.io/badge/Python-3.11%2B-blue?logo=python)](https://www.python.org/)
[![LangChain](https://img.shields.io/badge/LangChain-0.3%2B-green?logo=chainlink)](https://www.langchain.com/)
[![LangGraph](https://img.shields.io/badge/LangGraph-0.2%2B-orange)](https://langchain-ai.github.io/langgraph/)
[![Vue](https://img.shields.io/badge/Vue-3.5-brightgreen?logo=vue.js)](https://vuejs.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688?logo=fastapi)](https://fastapi.tiangolo.com/)
[![MySQL](https://img.shields.io/badge/MySQL-8.0-4479A1?logo=mysql)](https://www.mysql.com/)
[![Docker](https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker)](https://www.docker.com/)
[![License](https://img.shields.io/badge/License-MIT-red)](./LICENSE)

</div>

---


## 项目简介

医疗导诊助手是一个面向互联网医院的智能导诊 Agent 系统，实现 **「主诉采集 → 科室建议 → 号源查询 → 就诊须知」** 全流程自动化。

系统采用 **主 Agent + 导诊子 Agent** 的双层架构：主 Agent 负责多轮问诊编排与状态管理，导诊子 Agent 基于 LLM 进行分诊推理并输出科室建议与注意事项。所有分诊结果均为辅助建议，非诊断结论。

### 核心流程

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  开场白   │───▶│ 主诉采集  │───▶│ 追问补充  │───▶│ 分诊推理  │───▶│ 结果推荐  │
│  greet   │    │ collect  │    │ follow_up│    │  triage  │    │ recommend│
└──────────┘    └──────────┘    └──────────┘    └──────────┘    └──────────┘
                                                                       │
                                          ┌──────────┐    ┌──────────┐  │
                                          │  完 成    │◀───│ 号源查询  │◀─┘
                                          │ complete │    │query_slots│
                                          └──────────┘    └──────────┘
```

> **免责声明**：本系统仅提供导诊辅助建议，不构成任何医疗诊断或治疗方案。如有紧急情况，请立即拨打 120 或前往最近医疗机构。

## 功能特性

- **多轮智能问诊** — 基于 LangGraph 状态机，实现主诉采集、追问补充、分诊推理的全流程编排
- **智能分诊建议** — 导诊子 Agent 基于 LLM 进行症状分析，推荐最合适的科室
- **急诊识别** — 自动识别危重症状关键词，触发急诊通道提醒
- **禁忌提示** — 根据症状自动输出就诊前禁忌注意事项
- **号源查询** — 通过 MCP 协议对接号源服务，实时查询可预约号源
- **院内导航** — 提供科室位置与院内路线指引
- **Vue 聊天界面** — 实时聊天交互，侧边栏展示分诊状态与科室信息
- **Docker 部署** — 一键启动 MySQL + API + 前端完整环境
- **多 LLM 支持** — 默认 DeepSeek，兼容 OpenAI / Ollama(本地部署)

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| **Agent 框架** | LangChain + LangGraph | 多轮对话编排、状态机管理 |
| **MCP 协议** | FastMCP | 号源查询、院内导航工具服务 |
| **后端 API** | FastAPI + Uvicorn | RESTful API、异步高性能 |
| **前端** | Vue 3 + Vite | 聊天界面、响应式布局 |
| **数据库** | MySQL 8.0 + SQLAlchemy | 科室、号源、预约数据持久化 |
| **LLM** | DeepSeek / OpenAI / Ollama | 分诊推理、症状分析 |
| **部署** | Docker Compose + Nginx | 容器化部署 |

## 项目结构

```
medical-triage-assistant/
├── backend/                            # 后端服务
│   ├── main.py                         # 统一启动入口
│   ├── Dockerfile                      # 后端 Docker 镜像
│   ├── requirements.txt                # Python 依赖
│   ├── .env.example                    # 环境变量模板
│   ├── src/
│   │   ├── agents/                     # Agent 模块
│   │   │   ├── state.py                #   LangGraph 状态定义
│   │   │   ├── main_agent.py           #   主 Agent - 多轮问诊编排
│   │   │   └── triage_agent.py         #   导诊子 Agent - 分诊推理
│   │   ├── mcp_server/
│   │   │   ├── server.py               #   MCP Server - 号源/导航工具
│   │   │   └── his_adapter.py          #   HIS 系统适配器
│   │   ├── models/                     # 数据模型
│   │   │   ├── base.py                 #   SQLAlchemy ORM 基类
│   │   │   ├── department.py           #   科室 & 症状模型
│   │   │   ├── appointment.py          #   号源 & 预约模型
│   │   │   ├── consultation.py         #   问诊会话模型
│   │   │   └── patient.py              #   患者信息模型
│   │   ├── skills/                     # 技能模块
│   │   │   ├── triage_dialogue.py      #   分诊话术 & 追问策略
│   │   │   ├── contraindication.py     #   禁忌提示 & 急诊识别
│   │   │   ├── evaluation.py           #   分诊评估模块
│   │   │   └── knowledge_base.py       #   RAG 知识库
│   │   ├── utils/                      # 工具层
│   │   │   ├── config.py               #   全局配置 (Pydantic Settings)
│   │   │   ├── database.py             #   异步数据库引擎
│   │   │   ├── llm.py                  #   LLM 模型工厂
│   │   │   ├── logger.py               #   日志配置 (Loguru)
│   │   │   ├── auth.py                 #   JWT 认证模块
│   │   │   └── i18n.py                 #   多语言支持
│   │   └── web/
│   │       ├── app.py                  #   FastAPI 应用主入口
│   │       ├── schemas.py              #   API 请求/响应 Schema
│   │       └── websocket.py            #   WebSocket 流式推送
│   ├── scripts/
│   │   └── init_db.sql                 #   数据库初始化脚本
│   └── tests/
│       └── test_api.py                 #   基础测试
├── frontend/                           # 前端服务
│   ├── Dockerfile                      # 前端 Docker 镜像
│   ├── nginx.conf                      # 生产 Nginx 配置
│   ├── package.json                    # Node 依赖
│   ├── vite.config.js                  # Vite 配置
│   ├── index.html                      # 入口 HTML
│   └── src/
│       ├── App.vue                     #   聊天界面组件
│       └── main.js                     #   Vue 入口
├── docker-compose.yml                  # Docker 编排配置
├── .gitignore                          # Git 忽略规则
└── README.md                           # 项目说明
```

## 快速开始

### 环境要求

- Python 3.11+
- Node.js 18+ (前端开发)
- MySQL 8.0+ (或使用 Docker)
- Docker & Docker Compose (可选)

### 方式一：本地开发

#### 1. 克隆项目

```bash
git clone https://gitee.com/your-username/medical-triage-assistant.git
cd medical-triage-assistant
```

#### 2. 创建虚拟环境

```bash
python -m venv venv

# Windows
venv\Scripts\activate

# Linux / macOS
source venv/bin/activate
```

#### 3. 安装依赖

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

#### 4. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入你的配置：

```ini
# LLM 配置 (DeepSeek)
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-your-deepseek-api-key
DEEPSEEK_API_BASE=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

# 数据库配置
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USER=triage_user
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=medical_triage
```

#### 5. 初始化数据库

```bash
mysql -u root -p < scripts/init_db.sql
```

#### 6. 启动后端

```bash
# 统一入口：同时启动 API + MCP Server
python main.py

# 或单独启动
python main.py --api-only    # 仅 FastAPI
python main.py --mcp-only    # 仅 MCP Server
```

API 文档访问：http://localhost:8000/docs

#### 7. 启动前端 (开发模式)

```bash
cd frontend
npm install
npm run dev
```

前端访问：http://localhost:3000

### 方式二：Docker 一键部署

```bash
# 克隆项目
git clone https://gitee.com/your-username/medical-triage-assistant.git
cd medical-triage-assistant

# 配置环境变量
cd backend
cp .env.example .env
# 编辑 .env 填入 DEEPSEEK_API_KEY 等配置
cd ..

# 启动所有服务
docker-compose up -d
```

| 服务 | 地址 |
|------|------|
| 前端界面 | http://localhost:3000 |
| API 服务 | http://localhost:8000 |
| API 文档 | http://localhost:8000/docs |
| MySQL | localhost:3306 |

```bash
# 查看日志
docker-compose logs -f api

# 停止服务
docker-compose down
```

## API 接口文档

启动服务后访问 http://localhost:8000/docs 查看完整的 Swagger 文档。

### 核心接口

| 方法 | 路径 | 说明 |
|:----:|------|------|
| `POST` | `/api/consultation/start` | 开始新的问诊会话 |
| `POST` | `/api/consultation/chat` | 发送聊天消息 |
| `GET` | `/api/consultation/{id}/status` | 查询会话状态 |
| `DELETE` | `/api/consultation/{id}` | 结束并清理会话 |
| `GET` | `/api/departments` | 获取所有科室列表 |
| `GET` | `/api/departments/{id}` | 获取科室详情 |
| `POST` | `/api/slots/query` | 查询可预约号源 |
| `GET` | `/api/navigation/{dest}` | 院内导航 |
| `GET` | `/health` | 健康检查 |

### 请求示例

**开始问诊：**

```bash
curl -X POST http://localhost:8000/api/consultation/start \
  -H "Content-Type: application/json" \
  -d '{"patient_name": "张三", "patient_gender": "男", "patient_age": 35}'
```

**发送消息：**

```bash
curl -X POST http://localhost:8000/api/consultation/chat \
  -H "Content-Type: application/json" \
  -d '{"session_id": "abc12345", "message": "我头疼两天了，还有点恶心"}'
```

**查询号源：**

```bash
curl -X POST http://localhost:8000/api/slots/query \
  -H "Content-Type: application/json" \
  -d '{"department_id": 10}'
```

## 架构设计

### Agent 架构

```
+-------------------------------------------------+
|                  用户 (Vue 前端)                 |
+---------------------------+---------------------+
                            | HTTP API
+---------------------------v---------------------+
|              FastAPI 后端服务                     |
|                                                 |
|  +-------------------------------------------+ |
|  |          主 Agent (LangGraph)              | |
|  |                                           | |
|  |  greet -> collect -> follow_up -> triage  | |
|  |         -> recommend -> query_slots       | |
|  |                                           | |
|  |  +---------------------------------+      | |
|  |  |     导诊子 Agent                 |      | |
|  |  |  - LLM 分诊推理                  |      | |
|  |  |  - 科室推荐                      |      | |
|  |  |  - 急诊识别                      |      | |
|  |  +---------------------------------+      | |
|  +-------------------------------------------+ |
|                                                 |
|  +--------------+  +-------------------------+ |
|  |   Skills     |  |     MCP Server          | |
|  | - 分诊话术   |  | - 号源查询              | |
|  | - 禁忌提示   |  | - 科室信息              | |
|  | - 急诊识别   |  | - 院内导航              | |
|  +--------------+  +-------------------------+ |
|                                                 |
|  +-------------------------------------------+ |
|  |              MySQL 数据库                   | |
|  |  departments | doctors | appointments      | |
|  +-------------------------------------------+ |
+-------------------------------------------------+
```

### LangGraph 状态流转

| 阶段 | 说明 | 触发条件 |
|------|------|----------|
| `greet` | 开场白，引导患者描述症状 | 会话创建 |
| `collect` | 主诉采集，LLM 提取关键信息 | 患者输入描述 |
| `follow_up` | 针对性追问（部位、性质、时间等） | 信息不足时循环 |
| `triage` | 调用导诊子 Agent 进行分诊推理 | 信息充足或追问 >= 5 轮 |
| `recommend` | 生成分诊建议 + 禁忌提示 | 分诊完成 |
| `query_slots` | 查询推荐科室的可预约号源 | 推荐完成 |
| `complete` | 流程结束 | 号源查询完成 |

## 配置说明

### LLM 供应商切换

项目默认使用 **DeepSeek**，在 `.env` 中配置：

```ini
# DeepSeek (默认)
LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-xxx
DEEPSEEK_API_BASE=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat
```

也支持切换到其他供应商：

```ini
# OpenAI
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-xxx
OPENAI_MODEL=gpt-4o-mini

# 本地 Ollama
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:7b
```

### MCP 工具扩展

MCP Server 位于 `backend/src/mcp_server/server.py`，使用 `@mcp.tool()` 装饰器即可添加新工具：

```python
@mcp.tool()
def your_new_tool(param: str) -> str:
    """工具描述"""
    return "result"
```

## 测试

```bash
# 运行测试
pytest tests/ -v

# 带覆盖率
pytest tests/ --cov=src --cov-report=html
```

## 待办事项

- [x] 接入真实 HIS 系统号源数据 — `backend/src/mcp_server/his_adapter.py` 适配器模式
- [x] 添加用户认证与就诊卡绑定 — `backend/src/utils/auth.py` JWT + 就诊卡绑定
- [x] 支持 WebSocket 实时推送 — `backend/src/web/websocket.py` 流式聊天 + 状态推送
- [x] 添加分诊准确率评估模块 — `backend/src/skills/evaluation.py` 评分/统计/标注
- [x] 向量数据库集成 (RAG 增强分诊知识) — `backend/src/skills/knowledge_base.py` 向量检索
- [x] 多语言支持 — `backend/src/utils/i18n.py` 中/英双语切换
- [x] 移动端适配 — Vue 前端响应式 CSS (@media)

## 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 提交 Pull Request

## 开源许可

本项目基于 [MIT License](./LICENSE) 开源。

## 联系方式

如有问题或建议，请通过以下方式联系：

- 提交 [Issue](https://gitee.com/your-username/medical-triage-assistant/issues)
- 邮箱：2318745133@qq.com

---

<div align="center">

**如果本项目对你有帮助，请给一个 Star 支持一下！**

</div>