# MaintainX

**Repository Path**: wu-xinz/maintain-x

## Basic Information

- **Project Name**: MaintainX
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-11
- **Last Updated**: 2026-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于 LangGraph + GraphRAG + IoT Agent 的工业智能运维与 EHS 安全决策平台

> Industrial Intelligent Operation & Safety Decision Agent Platform

面向电力、工业制造、能源化工等高风险工业场景，融合**实时设备感知、GraphRAG 知识推理、Multi-Agent 协同、状态机诊断以及 EHS 安全审签**的工业智能运维与安全决策平台。

## 核心目标

> 将"设备异常发现 → 故障分析 → 安全审查 → 维修指导 → 人工确认 → 结果记录"串联为完整的工业智能决策闭环。

平台面向现场运维工程师、安全管理人员以及设备管理人员，提供：

1. 设备实时状态感知
2. 复杂硬件故障交互诊断
3. 工业知识图谱与多模态知识检索
4. 高危作业票智能审签
5. 动态环境风险评估
6. 维修任务与安全审批联动
7. 人工确认与操作闭环
8. 自动生成维修及安全作业报告

## 总体系统架构

```
                         工业智能运维与安全决策平台

                                  用户
                                   |
                    +--------------+--------------+
                    |                             |
              设备故障处理                    高危作业申请
                    |                             |
                    v                             v
           Fault Diagnosis Agent             EHS Safety Agent
                    |                             |
          +---------+---------+           +-------+-------+
          |                   |           |               |
          v                   v           v               v
     SCADA/PLC Tool       IoT Tool    Sensor Tool    人员/门禁Tool
          |                   |           |               |
          +---------+---------+           +-------+-------+
                    |                             |
                    +-------------+---------------+
                                  |
                                  v
                       LangGraph Agent Orchestrator
                                  |
                    +-------------+-------------+
                    |                           |
                    v                           v
             GraphRAG知识推理               安全规则引擎
                    |                           |
          +---------+---------+          +------+------+
          |                   |          |             |
       Neo4j               Milvus     EHS规则       企业制度
          |                   |          |             |
          +---------+---------+          +------+------+
                    |                           |
                    +-------------+-------------+
                                  |
                                  v
                         人机协同闭环执行
                                  |
                                  v
                    维修报告 / 作业票 / 风险记录
```

## Multi-Agent 架构

采用 Supervisor + 专业 Agent 架构：

```
                       Supervisor Agent
                              |
             +----------------+----------------+
             |                |                |
             v                v                v
       Fault Agent        EHS Agent       Report Agent
             |                |                |
             v                v                v
        故障诊断          安全审签          报告生成
        SOP匹配           风险评估          工单记录
        路径规划          作业票检查        维修总结
```

| Agent | 职责 |
| --- | --- |
| Supervisor Agent | 意图识别、任务拆解、Agent 路由、状态管理、人工确认、异常回退 |
| Fault Diagnosis Agent | 故障分析、实时设备数据查询、GraphRAG 检索、SOP 匹配、交互式故障排查、维修建议 |
| EHS Safety Agent | 作业票解析、环境风险判断、人员资质检查、PPE 检查、安全规则验证、作业阻断 |
| Report Agent | 故障诊断报告、维修工单、安全审签记录、风险整改记录、维修过程总结 |

## 人机协同机制

工业场景不能让 LLM 直接控制高风险设备，系统采用：

> **Agent 决策 + 规则校验 + 人工确认 + Tool 执行**

而不是：Agent 自主执行所有操作。

关键节点设置 Human-in-the-Loop：

```
Agent提出操作建议 → 安全规则校验 → 人工确认 → Tool执行 → 读取执行结果 → Agent继续决策
```

对于高危操作：危险操作 → 强制人工确认 → 未确认 → 禁止执行。

## 作业票签字制(负责人签字流程)

作业票存在负责人签字流程，**系统不自动审批**。系统根据「以往的作业票内容 + 本次故障维修可能发生的安全风险」自动生成作业票草稿，交负责人校验签字：

```
故障诊断完成(定位故障/生成维修建议)
   ↓
自动生成作业票草稿(draft)
  - 风险推导: 设备类型 → 作业类型/风险等级/安全措施/PPE/资质要求
  - 历史参考: 同设备/同作业类型的近期作业票, 合并其安全措施与PPE
  - 自动预检: 环境检测 + 规则断言(附注草稿, 仅供参考, 不自动审批)
   ↓
负责人校验签字(可修改安全措施/PPE/资质/人员)
   ├── 批准 → 作业票生效(approved)
   └── 驳回 → 记录驳回原因(rejected)
   ↓
签字生效后才允许进入维修(文档 7 联动)
```

## 风电知识库(基于真实图纸)

已接入两份真实风机图纸的矢量文字层,构建风电 GraphRAG 知识库:

- **变桨图纸.pdf**(SSB Wind Systems, P081 2MW 105m SLIP 变桨系统, 119 PDF 页)
- **主控系统原理图.pdf**(上海电气电力电子 SPTD-2MW-B W2000 电控系统, 66 页)

**知识规模**: 125 实体(设备/组件/传感器/故障现象/SOP/安全要求) + 120 关系 + 500+ 向量语料(185 页图纸全量文字)。

**风电诊断场景**(状态机反馈路由支持编码器/电池/温控/变频器/偏航/PLC/UPS 等线索):

```
"5号机变桨系统故障" → 反馈"轴柜1编码器无信号输出" → 定位: 桨叶位置编码器故障 → 维修建议
"5号机偏航系统故障" → 反馈"偏航位置SSI反馈异常"   → 定位: 偏航位置反馈故障
"5号机主控系统报警" → 反馈"X20模块通讯丢失"       → 定位: PLC模块故障
```

详见 `backend/docs/drawings/README.md`。注意: 图纸为电气结构图(非故障码手册), 真实故障码→现象→SOP 映射需提供故障代码手册后补充。

## 技术栈

| 类别 | 技术 |
| --- | --- |
| Agent | LangGraph、LangChain、ReAct、Function Calling |
| RAG | Milvus、Neo4j、BGE-M3、BGE-Reranker、GraphRAG、Hybrid Search |
| 工业数据 | MQTT、OPC UA、SCADA、PLC API、IoT Gateway |
| 后端 | Python、FastAPI、Pydantic、AsyncIO |
| 数据库 | PostgreSQL、TimescaleDB、Redis、Milvus、Neo4j |
| 前端 | React、ECharts、WebSocket |

## 目录结构

```
electirc_power/
├── backend/
│   ├── app/
│   │   ├── main.py            # FastAPI 入口
│   │   ├── config.py          # 配置中心
│   │   ├── models/            # Pydantic 数据模型
│   │   ├── db/                # SQLAlchemy 数据库模型
│   │   ├── agents/            # Multi-Agent(S/F/E/R) 与 LangGraph State
│   │   ├── tools/             # SCADA/IoT/Sensor/人员门禁 Tool
│   │   ├── graphrag/          # Milvus + Neo4j + Hybrid Search + Rerank
│   │   ├── ehs/               # EHS 确定性规则引擎
│   │   ├── workflows/         # LangGraph 工作流(诊断状态机/EHS审签/维修联动)
│   │   ├── api/routes/        # REST 路由
│   │   ├── ws/                # WebSocket 实时推送
│   │   └── seed/              # 种子数据
│   └── tests/                 # pytest 测试
├── frontend/                  # React + ECharts + WebSocket
├── docs/
└── docker-compose.yml         # PostgreSQL/TimescaleDB、Redis、Milvus、Neo4j
```

## 快速开始

### 1. 基础设施(可选)

需要真实 PostgreSQL/TimescaleDB、Redis、Milvus、Neo4j 时：

```bash
docker compose up -d
```

不启动基础设施时，系统自动使用内置 Mock(内存向量库 / 内存图 / SQLite)，可完整运行。

### 2. 后端

```bash
cd backend
python -m venv .venv
.venv\Scripts\activate        # Windows
pip install -r requirements.txt
python -m app.seed.run        # 初始化种子数据
uvicorn app.main:app --reload --port 8000
```

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

### 3. 前端

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

访问：http://localhost:5173

## 核心工作流示例

**场景 A：普通设备故障**（如输入 `3号设备出现 E203 故障`）

设备报警 → Supervisor → Fault Agent → SCADA Tool 获取实时数据 → GraphRAG 检索 → 匹配历史案例/SOP → 生成检测步骤 → 工程师执行并返回检测结果 → State Machine 路由 → 继续排查 → 定位故障 → 生成维修方案

**场景 B：涉及高危维修**

设备报警 → Supervisor → 识别高危设备 → 触发 EHS Agent → 读取作业票 → 检查人员资质 → 调用环境 Sensor Tool → 检查实时环境 → EHS 规则判断 → 安全条件不满足则阻断维修并给出整改建议；满足则进入 Fault Agent 诊断 → 人工确认 → 维修执行 → 结果验证 → Report Agent 生成闭环报告

## 设计说明

- **实时数据 Tool**：SCADA/PLC/OPC UA/MQTT/IoT Gateway 统一抽象，Mock 返回文档约定的 JSON 结构，可替换为真实工业接口
- **GraphRAG**：Milvus 向量召回 + Neo4j 图谱召回 → Hybrid Search → Rerank → 上下文构建 → LLM/Agent 推理
- **EHS 规则引擎**：确定性规则断言(动火+可燃气体超阈值→阻断审批等)，不依赖 LLM 判断安全
- **Human-in-the-Loop**：诊断检测操作、高危作业执行等关键节点等待人工确认，未确认禁止执行