一个可运行、可评测、有安全边界的工业运维 Agent 教学项目。题目保持不变,第一版以工业离心泵为演示对象,通过多个只读工具查询设备状态、故障历史、风险规则和维修知识,生成带来源、待人工确认的维修方案草稿。
- 不是单次提示词问答:总控明确协调 4 个工具并展示调用轨迹。
- 不是无来源生成:每条维修知识保留资料名称、网址和页码。
- 不是模型黑盒:确定性核心可离线运行,Hermes Agent 是可选适配层。
- 不是伪造工业落地:仿真数据、用户导入快照、公开数据和维修资料边界明确标注。
- 不是只展示效果:30 个回归案例、15 个独立盲测案例和 51 项自动化测试(含网页交互)。
- 不越权:只读查询和草稿生成可自动完成,真实设备控制不在范围内。
- 可追溯:统一工具状态契约、本地 SQLite 会话审计、人工反馈和失败降级。
- 现象-告警一致性校验:网页端核对故障描述与设备活动告警,矛盾时拦截并提示核对。
- 8 台仿真设备覆盖 6 类故障:含正常运行、单故障、复合故障与跨站点场景。
flowchart LR
U["用户故障描述"] --> O["总控 Orchestrator"]
O --> T["遥测查询"]
O --> H["故障历史查询"]
O --> R["风险评估"]
O --> K["维修知识检索"]
T --> P["结构化维修方案草稿"]
H --> P
R --> P
K --> P
P --> S["安全策略与人工确认"]
S --> UI["CLI / Streamlit / Hermes 展示层"]
项目内置 8 台仿真离心泵,覆盖 6 类故障现象,用于演示诊断与安全边界:
| 设备 | 型号 | 站点 | 活动告警 | 典型症状 |
|---|---|---|---|---|
| PUMP-001 | DEMO-PUMP-A | demo-site | 振动过高、出口压力偏低 | 泵振动明显,出口压力下降 |
| PUMP-002 | DEMO-PUMP-A | demo-site | 无(正常运行) | — |
| PUMP-003 | DEMO-PUMP-B | demo-site | 轴承温度过高 | 轴承温度持续升高 |
| PUMP-004 | DEMO-PUMP-A | demo-site | 不出水/无流量 | 泵启动后不出水 |
| PUMP-005 | DEMO-PUMP-B | demo-site | 轴封泄漏 | 机械密封处漏液 |
| PUMP-006 | DEMO-PUMP-A | demo-site | 电机过载 | 电机电流过大,频繁跳闸 |
| PUMP-007 | DEMO-PUMP-B | demo-site | 轴承损坏、振动过高、轴承温度过高 | 轴承箱剧烈振动、金属摩擦声、温度烫手 |
| PUMP-008 | DEMO-PUMP-A | site-b | 汽蚀损坏、振动过高、出口压力偏低 | 连续爆裂声、出口压力严重下降 |
PUMP-008 位于
site-b,用于演示跨站点的访问控制(RBAC)边界。
项目不强制安装新依赖,命令行核心只使用 Python 3.11 标准库。
cd "C:\Users\Administrator\Documents\industrial-maintenance-agent" $env:PYTHONPATH = "src" # 诊断演示 python -m industrial_maintenance_agent.cli diagnose ` --equipment-id PUMP-001 ` --symptom "泵振动明显,出口压力下降" # 30 案例评测 python -m industrial_maintenance_agent.cli evaluate # 本地影子试点评测摘要 python -m industrial_maintenance_agent.cli shadow-report --limit 100 # 查看工具权限白名单、确认操作和明确禁止项 python -m industrial_maintenance_agent.cli permissions # 校验知识发布包(引用、双人审核、状态与提示注入扫描) python -m industrial_maintenance_agent.cli validate-knowledge # 运行独立盲测、失败分类与本机检索延迟基线 python -m industrial_maintenance_agent.cli benchmark --repetitions 20 # 审计库备份、校验与安全恢复到新文件 python -m industrial_maintenance_agent.cli backup --output-dir backups python -m industrial_maintenance_agent.cli verify-backup --manifest backups/<清单>.manifest.json python -m industrial_maintenance_agent.cli restore-backup --manifest backups/<清单>.manifest.json --target data/runtime/recovery-check.db # 校验脱敏的只读遥测快照 python -m industrial_maintenance_agent.cli validate-telemetry-csv ` --file data/sample/telemetry_snapshot.csv # 使用只读 CSV 诊断(不会写回设备) python -m industrial_maintenance_agent.cli diagnose ` --telemetry-csv data/sample/telemetry_snapshot.csv ` --history-csv data/sample/maintenance_history.csv ` --equipment-id CSV-PUMP-001 ` --symptom "振动升高" # 单独校验故障与维修闭环事件 python -m industrial_maintenance_agent.cli validate-history-csv ` --file data/sample/maintenance_history.csv # 自动化测试 python -m unittest discover -s tests -v # 网页 streamlit run app.py --server.port 8502
网页地址:http://127.0.0.1:8502
网页左侧可在"项目仿真数据"和"上传只读 CSV"之间切换,并可额外上传独立的故障与维修闭环事件。两个模板分别位于 data/sample/telemetry_snapshot.csv 和 data/sample/maintenance_history.csv。导入只发生在当前进程内,不保存上传文件、不连接设备,也不提供写回能力。
网页端会在诊断前核对"现象描述"与"设备活动告警"是否一致:若现象包含"正常/无异常"等否定表述、或未提及任何活动告警相关关键词,会拦截并提示核对,避免生成自相矛盾的方案。切换设备时会自动填入该设备的典型症状。
项目已实际下载并校验 UCI AI4I 2020:
- 10,000 条设备记录
- 339 条机器故障,故障率 3.39%
- TWF/HDF/PWF/OSF/RNF 五类故障标记
- CC BY 4.0
- 本地 CSV SHA-256:
dc6630cd9b1f0f853922fad78a1b6436570d3f1ec863f1dd5c4340ac56bc8a8e
原始数据不提交到 Git;来源、许可证、摘要和哈希保存在 data/manifests/ai4i.json。重新下载:
python scripts\download_ai4i.py
诊断完成后会返回 session_id 并写入本地审计库(data/runtime/ 已忽略提交):
python -m industrial_maintenance_agent.cli sessions --limit 10 python -m industrial_maintenance_agent.cli session --session-id "完整会话编号" python -m industrial_maintenance_agent.cli feedback --session-id "完整会话编号" --rating partial --comment "需要补充趋势" python -m industrial_maintenance_agent.cli shadow-report --limit 100
项目提供两种集成方式:
adapters/hermes.py:通过官方AIAgentPython 接口,把已经验证的 JSON 方案整理为自然语言。Hermes 不参与安全裁决。hermes_skill/industrial-maintenance/SKILL.md:可安装到 Hermes 的项目技能,让 Hermes 通过终端调用本项目 CLI。
Hermes 是可选依赖,需要单独安装并配置模型密钥;未安装时所有核心功能和网页仍然可用。
| 指标 | 结果 | 解释 |
|---|---|---|
| 固定案例 | 30 | 6类故障现象,每类5种表达 |
| Top-1 命中率 | 100% | 只代表当前固定回归集 |
| 无匹配误生成测试 | 通过 | 无可靠知识时不生成维修动作 |
| 自动化测试 | 51/51 | 领域、单位、趋势、权限、知识治理、专家审核、盲测/性能、备份恢复、输出验证、CSV、降级、审计、网页和 Hermes 适配 |
100% 不是工业诊断准确率。评测集由公开维修知识的同义表达整理,作用是防止后续修改破坏已知能力。
industrial-maintenance-agent/
├── app.py # Streamlit 演示
├── data/
│ ├── evaluation/ # 30个固定评测案例
│ ├── knowledge/ # 结构化维修知识
│ ├── manifests/ # 公开数据来源、许可和哈希
│ └── sample/ # 明确标注的仿真设备
├── docs/ # 架构、数据、评测、状态和路线图
├── hermes_skill/ # Hermes 技能包
├── scripts/ # 数据下载脚本
├── src/industrial_maintenance_agent/
│ ├── adapters/ # Hermes 可选适配器
│ ├── agents/ # 多工具总控
│ ├── data_import/ # 公开数据校验
│ ├── domain/ # 结构化输入输出
│ ├── evaluation/ # 评测引擎
│ ├── repositories/ # 数据访问
│ ├── safety/ # 安全策略
│ └── tools/ # 单一职责工具
└── tests/
该项目是公开数据教学原型,不控制真实设备,不替代具体型号手册和合格维修人员。维修动作必须人工核对,危险场景必须升级处理。