vent-device-daily-report — 设备设施在线率统计与设备管理日报 Skill

基于通防管控平台（tf_mcp）数据，自动统计设备设施当天在线情况（重点：主通风机、局部通风机、风门、风窗、各类传感器），生成设备管理日报（Markdown + JSON）。

一、这是什么

能力	说明
设备在线统计	按设备类型分组统计：总数 / 在线 / 离线 / 未知 / 模拟数 / 在线率
在线判定	分类型混合判定：主通风机看 fan 表开机状态、风门看 ai_gate 状态、其余看关联分站连接状态
自动告警	🔴 主通风机 ≥1 套不在线即红色报警；🟠 其余类型在线率 <90% 橙色报警
日报输出	Markdown 日报（可读）+ JSON（可二次处理）

二、安装方法（在其他 agent 中使用）

解压 vent-device-daily-report.zip，得到 vent-device-daily-report/ 文件夹
将整个文件夹放到目标机器的用户级技能目录：
- ~/.agents/skills/（通用 agent 技能目录）
重启 agent，技能自动加载
前置条件：目标 agent 必须已连接 tf_mcp（本 skill 通过 mcp__tf_mcp__execute_sql_query 从 vent 库取数）

三、使用方法

方式一：直接对 agent 说（推荐）

用户说出以下任一需求即可自动触发本 skill：

"给我设备管理日报" / "生成今天的设备管理日报"
"统计设备在线率" / "设备设施在线情况"
"哪些设备在线/不在线" / "主通风机在线情况"
"传感器在线率" / "在线率低于90%报警"

Agent 会按 SKILL.md 中的流程自动执行：取数（4 条 SQL）→ 判定 → 统计 → 告警 → 输出 Markdown + JSON。

方式二：手动运行脚本（有 Python 3 的环境）

python scripts/device_online_report.py \
  --devices devices.json \              # 必填：SQL-1 查询结果（见 SKILL.md）
  [--fan fan.json] \                    # 可选：fan 表开机状态
  [--aigate aigate.json] \              # 可选：ai_gate 风门状态
  [--groups groups.json] \              # 可选：自定义设备分组
  [--threshold 0.90] \                  # 可选：在线率告警阈值，默认 0.90
  [--fan-tol 0] \                       # 可选：主通风机容忍离线台数，默认 0
  [--outdir ./report] \                 # 可选：输出目录，默认当前目录
  [--date 2026-08-10]                   # 可选：日报日期，默认当天

脚本无第三方依赖（纯 Python 标准库），输入 JSON 支持直接保存 tf_mcp 返回的 {"result": [...]} 完整结构。

四、字段与参数含义详解

4.1 设备字段（deviceinfo 表 + 关联分站字段）

字段	含义	取值
`ID`	设备唯一 ID（bigint）	-
`strName`	设备名称	-
`deviceKind`	设备大类编码	fanmain / fanlocal / gate / window / modelsensor / safetymonitor / gasmonitor 等 36 类
`strType`	设备小类编码（型号）	modelsensor_speed（风速传感器）、modelsensor_ch4（甲烷传感器）、gate_qd（气动风门）等 76 类
`nSubStationID`	关联分站 ID	对应 sub_station.ID；NULL=未关联分站
`StationName`	分站名称	如"测试分站"、"元宝湾安全监控"
`monitorFlag`	监测标志	0=不监测；1=统一类型参数监测；2=独立参数监测
`testFlag`	模拟数据标志	1=模拟数据；0=真实数据
`status`	设备状态	1=正常；0=删除（删除的不参与统计）
`linkStatus`	分站连接状态（来自 sub_station）	1=已连接；0=未连接
`isUse`	分站启用状态（来自 sub_station）	1=开启监控；0=删除；2=不开监控

4.2 判定专用表字段

表	字段	含义
`fan`（主通风机）	`bOn`	是否开机：1=开机（在线）；0=停机（离线）；NULL=无数据（跳过此规则）
`ai_gate`（智能风门）	`name` / `status`	风门名称 / 状态：1=正常；0=离线；2=故障；按名称与 deviceinfo.strName 匹配

4.3 脚本参数

参数	必填	含义
`--devices`	✅	设备明细 JSON（SQL-1 结果），包含每台设备的 ID/strName/deviceKind/strType/nSubStationID/StationName/monitorFlag/testFlag/linkStatus/isUse
`--fan`	❌	fan 表查询结果 JSON（SQL-2），用于主通风机 bOn 开机判定
`--aigate`	❌	ai_gate 查询结果 JSON（SQL-3），用于风门状态判定
`--groups`	❌	自定义分组 JSON，格式 `{"分组名": ["deviceKind", ...]}`，覆盖默认分组
`--threshold`	❌	在线率告警阈值（小数），默认 0.90，低于即橙色报警
`--fan-tol`	❌	主通风机允许离线台数，默认 0（1 台离线即红色报警）
`--outdir`	❌	输出目录，默认当前目录
`--date`	❌	日报日期，默认当天

4.4 输出文件

report.md（Markdown 日报）： | 章节 | 内容 | |---|---| | 一、总体概况 | 正常接入/在线/离线/未知/模拟设备数量与总体在线率 | | 二、分类型在线统计 | 每分组：总数/在线/离线/未知/在线率/告警标记（🔴🟠🟢） | | 三、告警信息 | 逐条告警级别与内容 | | 四、离线/异常设备明细 | 每台离线/未知设备：名称/类型/分站/状态/原因/是否模拟 |

report.json（结构化数据）： | 字段 | 含义 | |---|---| | report_date | 日报日期 | | generated_at | 生成时间 | | summary | 总体概况：total/online/offline/unknown/sim/online_rate | | alarms | 告警数组：level（RED/ORANGE/GREEN）/group/message | | threshold / fanmain_offline_tolerance | 本次使用的告警阈值 | | groups | 本次使用的设备分组定义 | | detail | 每个分组的统计与明细：total/online/offline/unknown/sim/online_rate/online_list/offline_list/unknown_list（列表内每项含 id/name/deviceKind/strType/stationName/monitorFlag/testFlag/state/reason/judge_source） |

4.5 设备分组默认定义

分组名	包含 deviceKind	说明
主通风机	fanmain	矿井主扇，1 套不在线即红色报警
局部通风机	fanlocal	掘进面局扇
风门	gate	自动风门/气动风门等
风窗	window	自动风窗
传感器	modelsensor, safetymonitor, gasmonitor, gas, gaspatrol, dusting, fiber, bundletube, windrect, atomizing, duaSpeCamera, imgFireDet	各类传感器与监测装置
其他	其余 deviceKind	自动归入

五、判定与告警规则速查

在线判定链（按优先级，命中即止）：

主通风机：fan.bOn = 1 → 在线；=0 → 离线
风门：ai_gate.status = 1 → 在线；0/2 → 离线
通用：关联分站 linkStatus=1 且 isUse=1 → 在线；否则离线
兜底：未关联分站 → "未知"（不计入在线率分母，单独说明）

统计口径：分母 = 正常接入设备（status=1）；在线率 = 在线 ÷ (总数 − 未知) 告警：主通风机离线+未知 ≥1 → 🔴 RED；其他分组在线率 < 阈值 → 🟠 ORANGE；全部达标 → 🟢 GREEN

六、常见问题与踩坑

问题	说明
`window` 表报 SQL 语法错误	`window` 是 MySQL 保留字，必须写成 `window`
名称列表被截断	服务端 group_concat_max_len=1024，大类型名称用明细查询（`SELECT strName FROM deviceinfo WHERE strType='...'`）
实时数据接口查不到	`query_device_realtime_data`（Redis）多数设备无数据，在线判定不要依赖它
gate/window/fan 表数据量巨大	这些是模型数据（gate 2.5万条），设备在线统计以 deviceinfo 为准，专用表只作状态补充
全部设备显示离线	检查 sub_station 的 linkStatus——分站未连接时设备全部离线，属真实状态
总数对不上	聚合用 `COUNT(DISTINCT d.ID)` 防止 JOIN 膨胀

七、文件清单

vent-device-daily-report/
├── README.md                              # 本说明文件
├── SKILL.md                               # 技能主文件（agent 执行流程、SQL 模板、规则）
└── scripts/
    └── device_online_report.py            # 日报生成脚本（纯标准库）

README.md 8.2 KB Permalink Verlauf Originalformat