旋转机械振动健康快速筛查 v1.2.0
本 Skill 是 "通用鲁棒振动健康筛查" ——评委从 U 盘随手拷一个振动文件过来，不管格式、单位、采样率是否标注，都要给出一个 有依据 的 ISO 20816-3 健康判定。
核心设计：单点 + 通用
- 单点：只做"振动健康筛查"这一件事（不做轴承故障定位、不做齿轮诊断、不做寿命预测）
- 通用：接入层能吃 9 种格式 + 元数据三级回退 + 单位归一，遇到没见过的格式时由 Claude 现场写代码
标准依据（严格）
| 项目 | 内容 |
|---|---|
| 主标准 | ISO 20816-3:2022 Mechanical vibration — Part 3 |
| 中国国标 | GB/T 6075.3（等同采用 ISO 20816-3） |
| 适用范围 | 功率 > 15 kW，转速 120–30000 RPM 的联轴工业机械 |
| 评估量 | RMS 振动速度（mm/s） |
| 有效频率范围 | 10 Hz – 1000 Hz（< 600 RPM 设备扩展到 2 Hz – 1000 Hz） |
| 评估前提 | 稳态运行工况，不适用于启停瞬态 |
何时调用此 Skill
满足任一即触发：
- 用户上传 任意格式 的振动信号文件，询问设备是否健康
- 关键词：
振动筛查/健康度/设备状态/健不健康/ISO 20816/振动区/点检/巡检/RMS 速度/振动严重度 - 现场评审、设备健康看板、批量信号初筛
- 任意旋转机械（电机/泵/风机/压缩机/汽轮机/发电机）的健康初筛
> 注：本 Skill 是 筛查工具，不做故障定位。如用户要识别具体故障类型（外圈/内圈/齿轮等），应转用 bearing-fault-diagnosis 或 gear-diagnosis。
工作流（严格按此顺序）
四个脚本配合完成一次筛查。所有脚本输出 JSON，可串联调用。
Step 1：解析信号文件
python scripts/load_signal.py <用户给的文件>
# 例：python scripts/load_signal.py /data/U盘里的奇怪.csv
返回字段：
- signal_path — 归一后的 NPY 临时文件路径（后续步骤都用这个）
- n_samples — 样本数
- format — 检测到的格式
- fs_from_file — 文件头自带的采样率（仅 WAV/TDMS 有），可为 null
- amplitude_stats — RMS / peak / mean / min / max（供 Step 2 用）
- embedded_metadata — 文件内嵌的元数据（如 MAT struct 的 bearing.sr/rate），自动写入 <signal_path>.meta.json sidecar，Step 2 自动读取
- candidates — 仅 MAT 多变量时存在；若有多个候选变量，先和用户确认选哪个
- warnings — 必须告诉用户的提示（多列 CSV 选哪列、MAT 多变量等）
特殊情况：
- 不支持的格式（status=error 且提示）→ 由你（Claude）现场写 Python 读取（用 nptdms/librosa/或自定义解析），保存为 NPY 后从 Step 2 继续
- MAT 多个候选变量 → 用 --mat-var <name> 重跑（支持嵌套路径如 bearing.gs），或先问用户
Step 2：补全元数据
python scripts/infer_metadata.py \
--original <用户原始文件路径> \
--signal <Step 1 输出的 signal_path> \
[--fs-user <用户明确给的采样率>] \
[--unit-user <用户明确给的单位>] \
[--rpm-user <用户明确给的 RPM>]
> 重要：脚本会自动读取 <signal_path>.meta.json sidecar（Step 1 写的），把文件内嵌的 fs/rpm 等元数据无缝接入——你不需要手动传递。
返回：{fs, unit, canonical_unit, rpm, confidence, reasoning, needs_user_confirm, warnings}
多级回退（优先级从高到低）：
1. --*-user 用户明确指定
2. 同目录的 <stem>_metadata.json 旁路文件（沿用主项目约定）
3. Step 1 写的 sidecar .meta.json（含 MAT struct 内的 sr/rate、WAV 头的 fs 等）
4. 文件名正则（_fs25600 / _25kHz / _1800rpm / _mms / _g）
5. 信号幅值启发（含 g vs m/s² 模糊带的诚实低置信标注）
6. 兜底默认 + 显式警告
Step 3：与用户确认（仅当 needs_user_confirm 非空）
如果 Step 2 返回的 needs_user_confirm 包含 fs 或 unit，必须在调用 Step 5 之前与用户对话确认，模板：
> "我从这个文件中没找到明确的采样率信息，按工业常见值默认假设为 25600 Hz——如果实际不是请告诉我。
>
> 信号的 RMS 是 0.99，峰值 6.2，单位我判断不出来是 g 还是 m/s²（这两种在这个幅值范围都合理）。请问采样率是多少？单位是哪个？"
仅当 confidence=high 时可以跳过确认直接出结果。
Step 4：单位归一（仅当 canonical_unit ∉ {g, mm/s}）
python scripts/convert_unit.py \
--signal <Step 1/2 后的 NPY> \
--from <canonical_unit> \
--to <g 或 mm/s> \
[--fs <采样率，跨类时必传>]
返回新的 signal_path。常见路径：m/s^2 → g、μm → mm/s、mil → mm/s。
Step 5：调用 ISO 评估
python scripts/screen.py \
--信号 <最终的 NPY 路径> \
--采样率 <Step 2 确定的 fs> \
--单位 <g 或 mm/s> \
[--转速 <RPM>] \
[--机器组别 1 或 2]
Step 6：组织给用户的回答
必须包含：
1. 整体判定 + 健康度评分（永远有值）—— 用 emoji 标识，如 🟡 监视 / 评分 72
2. ISO 区 + 阈值依据
3. 关键指标（RMS、峭度、峰值因子、主频）
4. 算法做的所有自动处理：
- 选了哪一列（如 CSV 多列时）
- 用了哪些元数据来源（sidecar JSON / filename / amplitude heuristic）
- 走了什么降级路径
- 单位转换过程
5. 可信度等级（高/中/低）
6. 建议行动
7. 报告字段状态（v1.2.0 暂不生成 HTML，_报告.HTML 为 null）
不规范输入的处理决策树
| 情形 | 处置 |
|---|---|
不支持的格式（如 .tdms） |
你现场用 nptdms 读，存 NPY，从 Step 2 继续 |
| MAT 多个候选变量 | 用 --mat-var <name> 重跑；或问用户 |
| CSV 多列且没有列名暗示 | load_signal 已按"列名+方差+单调性"启发选一列；告诉用户选了哪列、其他候选有哪些 |
| 采样率未知 | infer_metadata 默认 25600 Hz + 低置信；必须问用户确认 |
| 单位未知（且幅值模糊） | infer_metadata 默认 g + 低置信；必须问用户 |
单位是 m/s² / μm / mil 等 |
自动走 Step 4 convert_unit.py |
| 转速未知 | 不用问用户，screen.py 内部会从频谱反推 |
| 信号过短 / 噪声大 / NaN 多 | screen.py 内部已有降级路径，结果里会有 _警告 字段 |
| 用户提供错误的机器组别（3 或 4） | 告诉用户 ISO 20816-3 只有 Group 1 和 Group 2 |
ISO 20816-3 机器组（严格按标准 5.2 节）
Group 1：大型机器
- 功率 > 300 kW 或电机轴高 H ≥ 315 mm
- 通常采用滑动轴承
- 转速 120 – 30000 RPM
Group 2：中型机器（最常见，默认值）
- 功率 15 kW < P ≤ 300 kW 或电机轴高 160 mm ≤ H < 315 mm
- 通常采用滚动轴承
- 转速通常 > 600 RPM
> 严格只有 2 个组。早期 ISO 10816 有更多分组但已被 20816-3 合并简化。
支撑分类（rigid vs flexible）
按机器+基础最低自然频率与主激振频率（通常是转频）的比例：
- 自然频率 ≥ 1.25 × 主激振频率 → rigid（刚性）
- 其它情况 → flexible（柔性）
> 经验：中型电机/水泵/风机 → rigid；大型汽轮发电机（> 10 MW）/立式机组 → flexible。
ISO 评估阈值表（Annex A）
Group 1（大型）
| 支撑 | A/B | B/C | C/D |
|---|---|---|---|
| Rigid | 2.3 | 4.5 | 7.1 |
| Flexible | 3.5 | 7.1 | 11.0 |
Group 2（中型，最常用）
| 支撑 | A/B | B/C | C/D |
|---|---|---|---|
| Rigid | 1.4 | 2.8 | 4.5 |
| Flexible | 2.3 | 4.5 | 7.1 |
> 单位均为 RMS 速度 mm/s。
健康度评分对应表
| ISO 区 | 评分 | 业务动作 |
|---|---|---|
| A | 85–100 | 例行巡检 |
| B | 60–84 | 缩短监测周期，2–4 周复测 |
| C | 35–59 | 1–2 周内详细诊断 |
| D | 0–34 | 立即停机检查 |
| 信号质量不足 | — | 不下结论，重新采集 |
算法鲁棒性承诺
- 永远给 ISO 区 — A/B/C/D 永远有值（或明确
不可评估+ 原因） - 信号长度自适应 — 0.5 秒到 30 分钟均能处理；过短时降级到时域评估
- 转速未知反推 — 从频谱主峰反推 1x 频率（含谐波一致性校验）
- 异常采样清洗 — NaN/Inf 线性插值；超 5% 时告警
- 异常采样鲁棒 — NaN/Inf 会清洗或降级为“不可评估”；当前版本不单独计算 SNR
- 永不超时 — 50 MB 以内单文件 < 5 秒响应
不要做的事
- ❌ 不要在
needs_user_confirm非空时直接出结果，必须先问用户 - ❌ 不要静默接受算法降级或元数据猜测，必须把过程告诉用户
- ❌ 不要把"信号质量不足"包装成"机器正常"
- ❌ 不要在机器组别参数填入 3 或 4——ISO 20816-3 只有 Group 1 和 Group 2
- ❌ 不要承诺已生成 HTML 报告；v1.2.0 仅返回
_报告.HTML = null - ❌ 不要给具体故障类型结论（"外圈故障"等）——本 Skill 是筛查工具
- ❌ 不要在 Step 4 之前调用 Step 5 ——
screen.py只接受g或mm/s - ❌ 不要直接
import主项目predictive-maintenance-mcp/src/signal_loader.py——Skill 必须自包含可独立分发
给用户回答的模板（高置信场景）
> ✅ 整体判定：健康（A 区） 健康度评分：89 / 100
>
> 📐 ISO 20816-3:2022
> - 区：A — 新机器交付水平，长期运行健康
> - RMS 速度：1.0 mm/s
> - 适用组：Group 2 rigid（A/B=1.4，B/C=2.8，C/D=4.5）
> - 阈值依据：ISO 20816-3:2022 Table A.2
>
> 📊 关键指标
> RMS=0.12 g，峭度=2.8，峰值因子=3.1，主频=30 Hz
>
> 🔧 算法处理
> - 采样率 25600 Hz 来自文件名解析（高置信）
> - 单位 g 来自旁路 metadata.json（高置信）
> - 转速由频谱主峰反推：1800 RPM
> - 无降级路径
>
> 💡 建议行动：例行巡检即可，30 天后复测对比
>
> 📄 HTML 报告：当前版本暂未生成（_报告.HTML = null）
给用户回答的模板（低置信场景）
> 我看了你这个文件，但有几个信息需要你确认：
>
> 1. 采样率不确定：文件里没有标注，文件名也没有暗示。我先按工业常见值 25600 Hz 算了一次——如果你实际用的是 97656 Hz 或别的，请告诉我，我重算。
> 2. 单位不确定：信号 RMS=0.99、峰值 6.2，在 g 和 m/s² 之间都合理——前者意味着 ISO C 区（可疑），后者意味着 A 区（健康）。结论会反过来，请务必确认。
>
> 暂按 (fs=25600 Hz, unit=g) 给一份参考结果：
> 🟠 整体判定：可疑（C 区） 评分：48
> ...
运行架构（v1.2.0 本地版）
所有评估在 Python 进程内完成，无需任何后端服务：
| 组件 | 位置 | 职责 |
|---|---|---|
scripts/iso_engine.py |
Skill 自带 | ISO 20816-3 评估核心算法（移植自主项目，已裁剪） |
scripts/screen.py |
Skill 自带 | CLI 入口，本地调用 iso_engine.evaluate() |
| Python 依赖 | requirements.txt |
numpy / scipy / pandas / openpyxl / h5py / pyarrow |
> 不依赖任何 HTTP 服务，无 daemon，无域名/端口。Skill 完全自包含可独立分发。
> 部署到 71 服务器只需 pip install -r requirements.txt，详见 INSTALL.md。
算法依据
| 维度 | 标准 |
|---|---|
| 诊断架构 | ISO 13374 六块诊断体系 |
| 严重度评估 | ISO 20816-3:2022 Annex A |
| 加速度→速度积分 | 时域积分 + 4 阶 Butterworth 高通 @2 Hz 去趋势 |
| 转速反推 | 频谱主峰检测 + 谐波一致性校验 |
| 信号清洗 | NaN/Inf 线性插值，5% 阈值告警 |
| 变化趋势 | ISO 20816-3 Criterion II（变化 > B/C 边界 25% 视为显著） |
参考资料
scripts/load_signal.py— 多格式信号加载（9 种格式 + MAT 嵌套 struct 递归 + CSV 智能选列）scripts/infer_metadata.py— 元数据嗅探（六级回退 + 自动 sidecar）scripts/iso_engine.py— ISO 20816-3 评估算法（本地化，无 HTTP 依赖）requirements.txt— Python 依赖清单INSTALL.md— 71 服务器部署指南scripts/convert_unit.py— 单位归一（加速度 / 速度 / 位移）scripts/screen.py— ISO 20816-3 评估调用references/api_spec.md— 历史 API 规范（v1.2.0 已切换到本地，仅供字段语义参考）references/output_format.md— 筛查结果字段含义examples/— 典型场景示例（含 4 个 v1.2.0 新增的"接入层鲁棒"场景）
