旋转机械振动健康快速筛查 v1.2.0

本 Skill 是 "通用鲁棒振动健康筛查" ——评委从 U 盘随手拷一个振动文件过来，不管格式、单位、采样率是否标注，都要给出一个 有依据 的 ISO 20816-3 健康判定。

核心设计：单点 + 通用

• 单点：只做"振动健康筛查"这一件事（不做轴承故障定位、不做齿轮诊断、不做寿命预测）
• 通用：接入层能吃 9 种格式 + 元数据三级回退 + 单位归一，遇到没见过的格式时由 Claude 现场写代码

标准依据（严格）

何时调用此 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），自动写入 .meta.json sidecar，Step 2 自动读取
• candidates — 仅 MAT 多变量时存在；若有多个候选变量，先和用户确认选哪个
• warnings — 必须告诉用户的提示（多列 CSV 选哪列、MAT 多变量等）

特殊情况：

• 不支持的格式（status=error 且提示）→ 由你（Claude）现场写 Python 读取（用 nptdms/librosa/或自定义解析），保存为 NPY 后从 Step 2 继续
• MAT 多个候选变量 → 用 --mat-var 重跑（支持嵌套路径如 bearing.gs），或先问用户

Step 2：补全元数据

python scripts/infer_metadata.py \
    --original <用户原始文件路径> \
    --signal <Step 1 输出的 signal_path> \
    [--fs-user <用户明确给的采样率>] \
    [--unit-user <用户明确给的单位>] \
    [--rpm-user <用户明确给的 RPM>]

> 重要：脚本会自动读取 .meta.json sidecar（Step 1 写的），把文件内嵌的 fs/rpm 等元数据无缝接入——你不需要手动传递。

返回：{fs, unit, canonical_unit, rpm, confidence, reasoning, needs_user_confirm, warnings}

多级回退（优先级从高到低）：

1. --*-user 用户明确指定
2. 同目录的 _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）

不规范输入的处理决策树

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（大型）

Group 2（中型，最常用）

> 单位均为 RMS 速度 mm/s。

健康度评分对应表

算法鲁棒性承诺

1. 永远给 ISO 区 — A/B/C/D 永远有值（或明确 不可评估 + 原因）
2. 信号长度自适应 — 0.5 秒到 30 分钟均能处理；过短时降级到时域评估
3. 转速未知反推 — 从频谱主峰反推 1x 频率（含谐波一致性校验）
4. 异常采样清洗 — NaN/Inf 线性插值；超 5% 时告警
5. 异常采样鲁棒 — NaN/Inf 会清洗或降级为“不可评估”；当前版本不单独计算 SNR
6. 永不超时 — 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 进程内完成，无需任何后端服务：

> 不依赖任何 HTTP 服务，无 daemon，无域名/端口。Skill 完全自包含可独立分发。

> 部署到 71 服务器只需 pip install -r requirements.txt，详见 INSTALL.md。

算法依据

参考资料

• 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 新增的"接入层鲁棒"场景）