| name | offline-disk-fault-diagnosis |
| description | 通过分析服务器的【系统级离线日志】——iBMC/SEL 带外日志（磁盘在位/热插拔/错误事件）、OS 系统日志（dmesg、syslog、messages）、InfoCollect 采集日志（SMART 信息/RAID 卡日志/性能数据）——并在日志包含有希捷 FARM 底层遥测日志（farmlog）时执行【OS+FARM 联合底层定界】，诊断离线磁盘硬件、RAID 控制器及存储链路故障，做多源时序对齐、物理级根因溯源与冷存储根因定界（R1-R16 R 码：磁头信号退化/磁头飞行异常/盘片介质退化/振动致伤/固件异常/机械电机退化/链路/RAID/EXP/OS 域）。当用户提供 ibmc_logs / messages（dmesg、syslog）/ infocollect_logs / farmlog 等服务器日志包（任意组合），或询问 RAID 掉盘降级（Offline/Degraded）、I/O 超时阻塞（Timeout/Blocked）、SAS/SATA/NVMe 链路不稳定（PHY Reset/ICRC）、物理槽位异常、磁盘巡检/SMART 告警、文件系统因底层存储故障切只读（Read-only）、磁头级退化定位与 Depop 延寿评估需要从日志反查底层根因时，调用本技能。**双模式**：仅有 OS/iBMC/InfoCollect 系统日志时按纯 OS 侧流程定界根因；同时存在 farmlog 时 Step 5 必须执行，输出结合 OS+FARM 的联合分析报告（逐磁头底层细节 + R 码根因定界）。**若用户只提供希捷 FARM 底层日志（farmlog / openSeaChest .json / 华为 disktool .txt），而无任何 OS/iBMC/InfoCollect 系统日志，应改用 `seagate-farm-disktool-health-analysis` 技能。** |
离线磁盘故障诊断
本技能通过分析从服务器收集的标准日志文件，重点诊断离线磁盘及存储子系统物理/链路级故障。
技能目录结构
本技能的目录结构如下，包含诊断脚本、参考资料和文档：
offline-disk-fault-diagnosis/
├── SKILL.md # 本技能的主文档
├── scripts/ # 诊断脚本目录
│ ├── diagnose_summary.py # Step 0: 故障日志采集脚本
│ ├── diagnose_ibmc.py # Step 2: iBMC日志分析脚本
│ ├── diagnose_infocollect.py # Step 2: InfoCollect/磁盘专项分析脚本
│ ├── diagnose_messages.py # Step 2: OS消息日志分析脚本
│ ├── diagnose_health_rules.py # Step 3: 健康度评估与规则匹配脚本
│ └── analyze_farm.py # Step 5: FARM 底层日志分析脚本（json 优先/txt 兜底 + 8 类部位 + 冷存储 R 码定界引擎）
└── references/ # 参考资料目录
├── DISK_fault_scenarios.md # 磁盘故障场景分类表
├── DISK_scenario_analysis.md # 磁盘故障场景专项分析指南
├── disk_health_rules.md # 硬盘健康度评估规则（SAS/SATA 硬故障 + 存活概率）
├── infocollect_guide.md # InfoCollect诊断指南
├── messages.md # OS消息日志分析指南
├── huawei_ibmc.md # 华为iBMC分析指南
├── h3c_ibmc.md # H3C iBMC分析指南
├── Inspur_ibmc.md # Inspur iBMC分析指南
├── farm_analysis.md # FARM 底层诊断指南（单快照 · 8 类故障部位）
├── farm_field_reference.md # FARM 字段与指标参考字典（json↔txt↔SMART 三方映射）
└── root_cause_rules.md # 冷存储故障根因定界规则 R1-R16（用户定义《故障根因分类表》,Step 5 权威规则集:六列规则/量化阈值/仲裁规则/决策树/修复能力矩阵）
输入日志目录结构与对应诊断脚本
以 /path/to/logs/xxxx 为例，标准的服务器日志收集包通常具有以下层级结构。本技能提供了针对性的脚本来分析不同层级的日志。
注意：在实际场景中，用户提供的日志包可能不完整，可能仅包含以下三种目录中的一种或多种。请根据实际存在的日志类型灵活选择对应的分析脚本。
<日志根目录> (例如: 10.120.6.76)
├── ibmc_logs/ # iBMC 硬件带外管理日志
│ └── (磁盘在位/热插拔/错误事件) -> 使用 scripts/diagnose_ibmc.py
├── infocollect_logs/ # 系统信息收集工具生成的分类日志
│ └── (SMART信息/RAID卡日志/性能数据) -> 使用 scripts/diagnose_infocollect.py
├── messages/ # 操作系统层面的系统日志
│ └── (dmesg, syslog, messages) -> 使用 scripts/diagnose_messages.py
└── farmlog/ # FARM 底层日志目录 (可选;存在时 Step 5 必须执行)
└── (<SN>_FARM_<时间戳>_<IP>_<设备名>.json [openSeaChest, 优先], <SN>_FARM_disktool_<时间戳>_<IP>_<设备名>.txt [华为 disktool, 兜底];
另兼容时间戳前置格式 <时间戳>_<SN>_FARM_<IP>_<设备名>[_disktool].{json,txt}) -> 使用 scripts/analyze_farm.py
双模式声明：本技能在纯 OS 模式（仅 ibmc_logs/messages/infocollect_logs 的任意组合）与 OS+FARM 联合模式（另有 farmlog/）下都必须给出根因结论。纯 OS 模式走 Step 0→4→6；联合模式额外强制执行 Step 5，报告必须体现磁头/盘面级底层细节与 R 码定界。
⚠️ 强制执行流程
必须严格按以下顺序执行，禁止跳过或乱序：
Step 0 (故障日志采集) → Step 1 (场景分类) → Step 2 (深入分析) → Step 3 (健康度评估与规则匹配) → Step 4 (根因反思与证据双向校验) → [Step 5 (FARM+OS 联合底层定界，farmlog 存在时必须执行)] → Step 6 (界面输出分析报告)
执行规则：
- 顺序强制：必须完成当前步骤并验证通过后，才能进入下一步
- 场景分支：Step 1 输出场景标签后，Step 2 必须针对性收集相关证据
- 数据校验：Step 4 必须通过证据矩阵校验后才能得出最终结论
- 文件适配：日志文件不全时自动降级分析策略，但必须至少有一个日志文件
- 专注存储：分析过程应锁定存储链路及介质，排查文件系统只读等现象的底层诱因。
- FARM 分支强制：Step 0 扫描时必须探测
farmlog/ 目录（或散落的 *_FARM_*.{json,txt} 文件）是否存在——存在则 Step 5 必须执行且不可省略，最终报告必须是 OS+FARM 联合分析形态（含逐磁头底层细节与 R 码定界）；不存在则跳过 Step 5，按纯 OS 侧证据完成根因定界（仍应参考 root_cause_rules.md 的 OS 侧量化标准给出候选 R 码，并标注"无 FARM 数据，硬盘内部细节未验证"）。
每步完成标志：
- Step 0：输出日志文件时间范围、文件统计、错误关键词概览、是否存在 farmlog 的判定
- Step 1：确定故障场景（如 DISK_HARDWARE_FAILURE 等）
- Step 2：输出物理级精准定位、传导链及初步根因
- Step 3：输出每块涉事磁盘的基础元数据、判定结论及标准化对象
- Step 4：输出根因证据校验表、原生日志证据及置信度定性
- Step 5（farmlog 存在时必须执行）：输出 FARM 逐磁头分析表、8 类故障部位评级、**冷存储 R 码定界结论（含 OS 侧交叉验证闭环与 Depop 适用性）**及处置建议
- Step 6：在界面上按固定结构输出最终的分析报告（严禁生成独立文件）
分析流程总览
| 步骤 | 阶段目标 | 主要工具/方法 |
|---|
| Step 0 故障日志采集 | 全量/定点扫描日志目录并识别关键报错 | diagnose_summary.py <log_dir> [-k/-d/-s] |
| Step 1 场景分类 | 判定现象并确定故障场景类型 | 根据 Step 0 采集结果进行场景匹配 |
| Step 2 深入分析 | 构建起止 T0 的传导链并执行诊断 | 使用 diagnose_ibmc.py/diagnose_infocollect.py/diagnose_messages.py 获取多维证据 |
| Step 3 健康度评估与规则匹配 | 对每块涉事磁盘按 SAS/SATA 规则集做客观判定与存活概率计算 | diagnose_health_rules.py <log_dir> [--format md/json/table] 配合 disk_health_rules.md |
| Step 4 根因反思与证据双向校验 | 交叉质询证据链，执行证据双向校验（含 E4 规则一致性） | 对比 iBMC/内核/系统日志的一致性 + 规则评估结果，防止结论发散 |
| Step 5 FARM+OS 联合底层定界（farmlog 存在时必须执行） | 将故障收敛至磁头/盘面级别（8 类部位），并按冷存储 R1-R16 规则完成 R 码根因定界（FARM 侧判据 + OS 侧交叉验证闭环） | analyze_farm.py <log_dir>/farmlog（json 优先/txt 兜底，内置 R 码定界引擎），结合 farm_analysis.md / farm_field_reference.md / root_cause_rules.md 判读 |
| Step 6 界面输出分析报告 | 汇总证据链与确认根因，在界面直接输出报告内容 | 结构化输出：结论 + 故障链条 + 规则评估 + 根因 + 修复建议（联合模式另含 FARM+OS 联合定界章节） |
Step 0：故障日志采集
全量扫描（宏观分析）
目标：快速扫描所有日志文件，识别磁盘及存储子系统的异常，建立故障全景视图。当存在特定报错或时间范围时，利用参数进行第一轮初步精确定位。
执行命令（根据场景选择）：
python3 scripts/diagnose_summary.py <log_dir>
python3 scripts/diagnose_summary.py <log_dir> -k "disk_fail" "slot0"
python3 scripts/diagnose_summary.py <log_dir> -d "Mar 16"
python3 scripts/diagnose_summary.py <log_dir> -s "2026-03-10 08:00:00" -e "2026-03-10 12:00:00"
FARM 日志探测（本步骤强制输出项）：扫描的同时必须判定日志包内是否存在 farmlog/ 目录或任何 *_FARM_*.{json,txt} 文件（如 ls <log_dir>/farmlog/ 2>/dev/null; find <log_dir> -name "*_FARM_*" | head），并在 Step 0 结论中明确声明分析模式：纯 OS 模式 或 OS+FARM 联合模式（后者 Step 5 必须执行）。
精细定位（微观分析）
目标：在优先使用上述带有参数的扫描命令锁定范围的基础上，结合全量扫描结果，辅以 grep / less 等文件操作命令查看更细节的原始日志上下文。
注意：使用脚本时，可优先执行 --help 参数，了解脚本多维度过滤用法。
Step 1：场景分类（故障域优先）
根据 Step 0 采集的日志概览，分析故障现象并确定故障场景类型。本步骤采用双层分类：先按用户定义的故障域（权威顶层分类）划定根因归属，再用现象场景标签辅助取证。
1.A 故障域划分（权威顶层分类，以用户《故障根因分类表》为准）
📖 权威规则集：冷存储故障根因定界规则 R1-R16 §0 故障域总览
用户《故障根因分类表》定义了 5 个实体故障域 + 1 个待定界状态，覆盖 R1-R16 全部根因。Step 1 必须先判定涉事对象落在哪个故障域（后续 Step 5 在该域内收敛到具体 R 码）：
| 故障域 | 范围 | 覆盖 R 码 | 主要特征（判域入口） |
|---|
| 硬盘域 | 硬盘本体（磁头/介质/机械/固件） | R1-R6 | 单/多磁头退化、坏道/重分配、飞行异常、振动致伤、固件异常、主轴电机退化——FARM 盘体侧有异常 |
| 链路域 | 互联链路（PCIe + SAS/SATA） | R7-R8 | SAS/SATA 链路重置/降速、ICRC、PCIe AER/降速——FARM 盘体全健康，问题在链路 |
| RAID域 | RAID 卡（硬件/固件/驱动） | R9-R10 | RAID 卡离线/card error、固件挂死/驱动 Bug、整卡下挂盘同时受影响 |
| EXP域 | EXP 背板（硬件/固件） | R11-R12 | 背板固件跑挂/命令超时、背板芯片损伤、EXP 下挂盘全部不可见 |
| OS域 | 操作系统/文件系统/内核 | R13-R16 | 资源耗尽(OOM)、IO 栈配置/慢盘、文件系统损坏、内核 Bug——非硬盘硬故障 |
| 待定界 | —（数据不全） | TBD | FARM/OS 日志缺失或质量存疑，无法定界，需补采后重判 |
⚠️ 判域原则：① 故障域可多域并发（如 R1 硬盘域主因 + R7 链路域辅因），取因果链起始点/主导域为主，其余标注为并发；② FARM 盘体是否健康是硬盘域 vs 其它域的分水岭——盘体有磁头/介质/振动异常 → 硬盘域；盘体全健康而 OS 有链路/RAID/背板/OS 侧证据 → 对应链路/RAID/EXP/OS 域；③ 整卡级/整背板级（多盘同时受影响）优先怀疑 RAID域/EXP域。
1.B 现象场景标签（辅助取证层，映射到故障域）
📖 参考详见：磁盘故障场景分类
现象场景标签用于快速锁定 Step 2 取证方向，每个标签标注其归属/可能归属的故障域：
| 场景标签 | 中文描述 | 主要特征 | → 归属故障域 |
|---|
DISK_HARDWARE_FAILURE | 磁盘硬件故障 | SMART 阈值超限、UNC/UF 坏道 (MEDIUM ERROR)、WP 写保护报错、磁盘离线 | 硬盘域(R1-R6) |
DISK_IO_PERFORMANCE | I/O 性能问题 | I/O 延迟高、落盘缓慢 (Await 激增)、块请求堆积、SCSI 指令超时 | 硬盘域(R1早期)/ OS域(R14) |
DISK_RAID_ERROR | RAID/控制器故障 | RAID 掉盘、控制器 Cache 故障、电池/超级电容告警、阵列降级 | RAID域(R9-R10) |
DISK_LINK_ISSUE | 链路/背板故障 | 频繁 SAS 链路重置 (PHY Reset)、ICRC/ABRT 接口错误、PCIe AER、链路及背板供电不稳定 | 链路域(R7-R8)/ EXP域(R11-R12,背板级) |
STORAGE_INDUCED_FS_ERROR | 存储诱发的文件系统故障 | 底层 I/O 错误引发文件系统 Remount Read-only（注：纯逻辑 FS 损坏属文件系统技能范畴） | OS域(R15) + 底层硬盘/链路域根因 |
DISK_SYSTEM_CONFIG | 系统/配置与兼容性限制 | 盘符漂移 (Drift)、磁盘不支持特定指令 (Illegal Request)、磁盘挂载数量过载 | OS域(R13资源/配置类) |
场景辅助分析与根因假设
确定场景标签后，必须参考专项分析指南进行候选根因的初步验证：
🔍 专项分析指南：磁盘故障场景专项分析指南
| 场景标签 | 候选根因假设（需在 Step 2 中验证） |
|---|
DISK_HARDWARE_FAILURE | ① 磁盘物理损坏引发大量坏道 ② 磁盘固件 Bug 导致逻辑死锁/写保护 ③ No Medium/介质丢失 — 此场景下 Step 3 必执行规则评估 |
DISK_IO_PERFORMANCE | ① 磁盘老化导致写缓存落盘缓慢 ② 业务压力超过 IOPS 限制 ③ RAID 背景扫描任务 — 此场景下 Step 3 仍须执行规则评估 |
DISK_RAID_ERROR | ① RAID 卡缓存校验错误 ② 电池能量耗尽导致写策略回退 — 此场景下 Step 3 仍须执行规则评估 |
DISK_LINK_ISSUE | ① SAS 线缆接触不良触发 PHY Reset ② 磁盘背板电气特性不稳定 ③ HBA 接口 CRC 错误 — 此场景下 Step 3 仍须执行规则评估（排除链路问题掩盖介质问题） |
STORAGE_INDUCED_FS_ERROR | ① 底层介质/链路持续 I/O 错误触发内核安全机制 ② 存储日志写入失败导致日志提交异常 — 此场景下 Step 3 仍须执行规则评估 |
DISK_SYSTEM_CONFIG | ① 挂载未采用 UUID 导致漂移 ② 下发指令与磁盘固件不兼容 ③ 数量超过 HBA/内核上限 — 此场景下 Step 3 仍须执行规则评估 |
⚠️ 强制要求：在进入 Step 2 深入分析前，应先通过 DISK_scenario_analysis.md 了解对应场景的分析路径与关键证据点。分析结束后，必须对上述候选根因方案逐一标注：✅ 已证实 / ❌ 已排除 / ❓ 证据不足。
⚠️ Step 3 强制范围：无论 Step 1 判定为何种场景，Step 3 健康度评估都必须对涉事磁盘执行 disk_health_rules.md 全量规则比对。唯一例外是 Step 2 完全无法锚定任何物理磁盘对象（仅有控制器/背板级故障）时，Step 3 输出"无涉事磁盘对象，规则评估不适用"声明。
Step 1 完成标志：
- ✅ 判定主要故障域（硬盘域/链路域/RAID域/EXP域/OS域/待定界，以用户《故障根因分类表》为准；多域并发时标注主导域与并发域）
- ✅ 确定辅助现象场景标签（从 §1.B 中选择）并记录故障现象与关键证据
- ✅ 为 Step 2 深入分析、Step 5 R 码收敛提供明确的故障域方向
Step 2：深入分析
根据 Step 1 的场景分类结果，必须首先完成时序关联与故障传导链重建，然后再通过多源脚本收集证据，最终给出精确的物理坐标定位。
2.1 时序关联与传导链重建 (核心理论框架)
目标：通过多源日志的时间戳对齐，重建故障发生的完整时间轴，厘清事件的先后顺序与因果链，为根因定位提供时序证据。
2.1.1 确定磁盘故障零点 (T0)
故障零点（T0）是时序分析的基准锚点，定义为最早可观测到异常的时间戳。确定优先级（由高到低）：
| 优先级 | 来源 | 说明 |
|---|
| P1 | 硬件错误日志（iBMC / SEL） | 底层致命报错（如 Drive Fault, Hot Plug Removal），时间点最准确。 |
| P2 | 内核感知层（dmesg / messages） | 最早出现的 SCSI Error、I/O Error 或 Device Reset。 |
| P3 | 系统调度层（syslog / messages） | 系统级重试、文件系统切只读或 OOM 相关 IO 阻塞。 |
| P4 | 应用感知层 | 业务响应超时、数据库写入失败等应用级异常，通常滞后较大。 |
⚠️ 时钟偏差处理：多节点场景下，需留意 iBMC 时间与 OS 时间（NTP）是否存在时钟偏移。多源对齐时需留意并修正该偏差量。
2.1.2 多维日志对齐与时间轴矩阵
以 T0 为基准，将 iBMC 传感器告警、dmesg 报错、RAID 卡日志和 OS 系统日志统一映射到绝对时间轴上，构建事件序列矩阵。
示例：因底板/背板供电异常导致磁盘掉盘与文件系统只读的时间轴
T0-5m ├─ [iBMC SEL] 检测到背板（Backplane）供电电压出现瞬间短幅跌落告警。
T0-1m ├─ [OS dmesg] `mpt3sas_cm0: log_info(0x31110d01): originator(PL)...` (频繁出现 SAS 链路重置)。
T0-30s ├─ [OS iostat] 底层块设备 I/O await 严重阻塞，请求大量堆积，应用层感知死锁。
T0 ├─ [iBMC SEL] 记录 `Drive 8 Fault` 拔出或离线错误 → 标定为致命故障节点 T0。
T0+1m ├─ [OS messages] 存储写入失败重试达到内核阈值，文件系统触发内核安全保护并触发 `Remount read-only`。
2.1.3 磁盘故障传导链推断 (示例)
结合对齐的时间轴矩阵，运用以下规则推导故障传导链方向：
- 规则一：层级自下而上（硬件损坏主导）
- 传导链：磁盘物理损坏 (T0) → 触发底层报错 (SMI/NMI) → 操作系统驱动报错 (I/O Error) → 文件系统切只读。
- 规则二：环境向硬件传导（链路/压力主导）
- 传导链：业务高负载 (T0) → 触发链路重置 (SAS Reset) → RAID 卡性能下降 → 最终应用超时。
⚠️ 精确定位强制要求：在磁盘诊断中，严禁仅使用“磁盘故障”这类含糊结论。
必须通过证据追踪到细粒度的三维物理坐标定位，例如：
- ✅ 正确结论：
Slot 4 (Disk Index: 8) -> Media Error -> Reallocated Sectors Exceeded。
- ❌ 错误结论：
发生 I/O 错误 或仅仅说是 磁盘 sdb 损坏。
2.1.4 存储数据流拓扑梳理
在推断故障传导链的同时，必须梳理受影响的存储数据拓扑网络（即从用户业务层直达物理磁盘层的映射关系），以便确认底层硬件异常最终影响的业务定损边界。明确逆向映射：
- 挂载点，即用户入口（例如
/data/vols/vol13/phenix_data） → 文件系统类型（例如 ext4/xfs） → 对应的分区或 LVM 逻辑卷（例如直接分区块设备 或 /dev/mapper/xxx） → 发生告警/故障的真实底层物理磁盘设备（例如 /dev/sda）。
2.2 日志脚本分析执行 (执行工具动作)
2.2.1 通用分析流程
通用分析流程适用于所有磁盘故障场景，提供基础的日志提取与数据分析能力：
python3 scripts/diagnose_ibmc.py <log_dir>
python3 scripts/diagnose_infocollect.py <log_dir>
python3 scripts/diagnose_messages.py <log_dir>
注意：使用脚本时，可优先执行 --help 参数，了解脚本多维度过滤用法。
2.2.2 按场景专项分析
当 Step 1 确定故障场景后，优先分析对应的关键指标：
- 磁盘硬件故障：重点查看 SMART 中的
Reallocated_Sector_Ct 和 Standard_Health_Status。
- I/O 性能问题：重点查看
iostat 中的 await 和 util%。
- RAID故障：重点查看
sasraidlog 中的 Logical Drive Status 和 Battery/Capacitor 状态。
2.2.3 分析执行原则
- 场景优先原则：当故障现象明确匹配某个场景时，优先针对该场景取证。
- 组合使用原则：必须同时使用带外（iBMC）和带内（OS）脚本进行相互验证。
- 逐步深入原则：从宏观概览开始，逐步根据时序对齐结果深入特定日志行。
Step 2 完成标志：
- ✅ 输出故障零点 T0 的精确时间戳及其所依托的具体日志行。
- ✅ 梳理出以 T0 为基准的结构化事件序列矩阵与至少 3 步的确定故障传导链。
- ✅ 给出精确到物理部件（例如 Slot ID / Disk Index）的细粒度定位结果。
- ✅ 收集脚本产出的相关原生日志片段作为强有力的支撑证据。
- ✅ 成功梳理出底层设备故障直达业务挂载点的重点存储数据流拓扑映射关系。
Step 3：健康度评估与规则匹配（客观硬指标判定）
目标：基于客观规则集对 Step 2 识别到的涉事磁盘进行评估，作为硬指标侧验证。
3.1 评估对象锚定
从 Step 2 的结果中提取涉事磁盘清单，逐盘抽取以下要素：
| 字段 | 来源 | 缺失时表现 |
|---|
卷_id（卷标识） | diskmap.txt / mount / lsblk | 必填；输出缺失原因说明 |
SCSI 磁盘设备（盘符） | smartctl / dmesg / phy_info | 输出缺失原因说明 |
物理槽位 | iBMC SEL / sasraidlog | 输出缺失原因说明 |
接口类型 | SAS / SATA / NVMe | "Unknown" 或原因说明 |
型号 / 序列号 | smartctl 信息段 | 输出缺失原因说明 |
容量 | smartctl User Capacity | 输出缺失原因说明 |
通电时间 | SMART ID 9 或 Accumulated time | 输出缺失原因说明 |
⚠️ 卷_id 要求：若无映射证据，应在 "分析原因" 中提示补充信息，严禁伪造。
3.2 规则判定与存活概率计算
执行逻辑规范：
📖 判定标准详情参考：硬盘健康度评估技术规范
- 规则比对：根据规范 §2 (SAS) 或 §3 (SATA) 执行全量规则逐条比对。
- 存活概率：若未命中硬故障规则，按规范 §4 计算偏离程度及半年存活概率。
- 处置等级：按规范 §5 确定
"是否已更换" 和 "是否可修复" 布尔值。
- NVMe 降级：NVMe 盘不适用当前规则集，输出“无法评估”声明，并推荐
nvme-cli 命令。
执行命令：
python3 scripts/diagnose_health_rules.py <log_dir> --format md
python3 scripts/diagnose_health_rules.py <log_dir> --format json
python3 scripts/diagnose_health_rules.py <log_dir>
python3 scripts/diagnose_health_rules.py <log_dir> --include-passed
3.3 数据缺失与异常声明
- 模型补全机制：若自动化脚本未能成功提取关键元数据（如
"物理槽位"、"序列号"、"卷_id" 等），模型必须尝试使用 grep / less 等文件操作命令深入检索原始日志上下文（如 iBMC SEL、sasraidlog.txt 等），力求最大限度补全标准化诊断对象。
- 数据冲突与时效纠错：
- 最新原则：若脚本产出与模型自动检索结果不一致（如因盘符漂移导致的名称变更），模型必须以最接近故障时刻（T0）且逻辑闭环的证据为准，确保数据“最新且真实”。
- 修正逻辑：若模型纠正了脚本的错误输出（如识别出脚本解析了过时的旧配置），必须在
分析原因 中记录纠错依据。
- 任何无法索取的字段，应在对应字段位置输出具体的缺失原因说明字符串（如"日志缺失无法定位"），严禁输出
null 或占位符，严禁编造。
3.4 标准化诊断对象（Step 3 最终落地形式）
每块涉事磁盘必须输出符合以下 13 字段 结构的标准化诊断对象，并以 "磁盘列表" 数组形式聚合到报告级两个字段（"故障服务器IP" / "分析日期"）下：
{
"故障服务器IP": "10.78.26.27",
"分析日期": "YYYY-MM-DD",
"磁盘列表": [
{
"卷_id": "vol13",
"物理槽位": "Slot 4",
"SCSI 磁盘设备": "/dev/sdx",
"硬盘型号": "ST20000NM007D-3DJ103",
"序列号": "ZVT6MK9K",
"接口类型": "SATA",
"容量": "20.0 TB",
"通电时长小时": 16502,
"是否已更换": "否",
"是否可修复": "是",
"半年存活概率": 0.933,
"命中故障规则": [],
"分析原因": ["未命中任何故障规则"]
}
]
}
字段规约：
"是否已更换" / "是否可修复"：NVMe 或数据严重缺失时，在对应字段输出具体原因说明（如"NVMe 盘不适用此规则"或"缺少关键 SMART 记录无法判定"）。"分析原因"：至少包含一条自然语言原因。
Step 3 完成标志：
- ✅ 列出涉事磁盘清单及基础元数据。
- ✅ 完成基于规范的全量规则比对与概率计算。
- ✅ 输出 13 字段标准化诊断对象（Card 或 JSON 视图）。
Step 4：根因反思与证据双向校验 (Cross-Examination Rules)
目标：对 Step 2 输出的“初步传导链与定位结果”、Step 3 输出的"客观规则评估结果"进行"交叉质询"，确保得出的最终结论 100% 由底层日志支撑。
4.1 交叉质询铁律 (Cross-Examination Rules)
- 孤证不立原则：任何物理级磁盘故障（如磁盘坏道），绝对不能仅凭系统层的一个报错（如 I/O Error）就下断言。必须同时找到硬件层（如 SMART 或 iBMC SEL）的第二独立证据源支撑。Step 3 的硬故障规则命中本身已是客观证据，但仍须配合 Step 2 时序传导链验证其与本次故障的因果关联（避免"长期亚健康盘背锅，实际故障在链路"）。
- 逻辑闭环原则：从 T0 到最终业务故障结果，传导链不允许出现跳跃。例如：
链路重启不能直接等同于驱动器彻底故障，除非伴随连续的硬件离线记录。
- 互斥排异原则：如果判定故障是磁盘 A 损坏，则必须验证同背板/同通道的其他磁盘是否正常，以排除共性故障（如背板供电）。
4.2 强制：根因证据校验表 (Evidence Validation Matrix)
在确认最终结论前，强制要求进行证据校验：
| 校验维度 | 校验标准要求 | 强制证据格式（分析打样要求） |
|---|
| E1: 时序连续性 | 硬件告警时间是否早于或同步于系统层报错？ | [✅/❌ 结果] + 时序对齐说明 + [绝对路径 : 行号/行号范围] + 原生日志片段 |
| E2: 物理同一性 | 各级日志指控的逻辑盘符（sdX）与物理槽位（Slot Y）是否对应？ | [✅/❌ 结果] + 盘符与槽位映射日志梳理 + [绝对路径 : 行号/行号范围] + 原生日志片段 |
| E3: 现象排他性 | 是否排除了 RAID 重建或巡检等预定后台任务的干扰？ | [✅/❌ 结果] + RAID 卡状态及任务日志排除说明 + [绝对路径 : 行号/行号范围] + 原生日志片段 |
| E4: 客观规则一致性 | Step 3 规则命中结论是否与 Step 2 的因果链推断一致？若不一致（如命中硬故障规则但 §2 推断为链路问题），是否在结论中说明并采取更保守的处置策略？ | [✅/❌ 结果] + 规则命中与因果链对照说明 + 指向 Step 3 §3.4 标准化诊断对象（具体到对应 "磁盘列表" 项）的引用 + 原生日志片段 |
4.3 结论防发散拦截机制 (Anti-Hallucination Mechanism)
- 断链阻断：若无法从日志中找到证明因果传导的片段，强制触发流程拦截，回溯重新收集。
- 降级处分：若确实缺乏某一层关键日志（如无 iBMC），必须在报告中声明为**"疑似故障 (Suspected)"**并标注证据断层位置。
- 严禁用词限制：在证据链未能满足完全闭环标准前，严禁使用"肯定"、"必然"、"磁盘绝对已坏"等决定性断言。
Step 4 完成标志：
- ✅ 结构化地产出《根因证据校验表》中每一项（E1/E2/E3/E4）的自查结论。
- ✅ 每个通过项均附带 Trace 日志中的 Timestamp、Text 以及其明确的 [绝对路径 : 行号/行号范围]。
- ✅ 输出与之等位置信度（已证实 / 高度疑似 / 多重原因交织）的严谨研判方向。
- ✅ E4 维度明确给出规则评估结论与因果链推断的一致性判断（一致 / 部分一致 / 冲突）；冲突时采取更保守的处置策略。
Step 5：FARM+OS 联合底层定界 (farmlog 存在时必须执行)
触发条件：日志包内存在 farmlog/ 目录或任何 *_FARM_*.{json,txt} 文件——只要存在就必须执行本步骤，不再以"前置步骤已锁定某块盘"为前提（未锁定盘时对 farmlog 内所有盘做机群级定界，再与 OS 侧证据对齐锁定涉事盘）。若完全没有 FARM 日志，跳过本步骤，但仍应参考 root_cause_rules.md 的 OS 侧量化标准给出候选 R 码。
目标：两层递进——
- 部位层（8 类）：不再局限于"哪块盘坏了"，探究**"这块盘的内部哪里坏了"**（磁头/盘面/接口/固件等 8 类部位）；
- 根因层（R 码）：按用户定义的冷存储故障根因定界规则 R1-R16（root_cause_rules.md），将 FARM 侧量化判据与 Step 0-4 的 OS/iBMC 证据交叉验证闭环，输出最终 R 码（如 R1 磁头信号退化 / R4 振动致伤 / R7 链路故障）、Depop 适用性与修复路径。
[!IMPORTANT]
FARM 是单帧快照，没有 poh 时间序列。严禁套用"旧→新趋势/活跃增长 vs 暂稳"这类趋势话术。 活跃度改用 Reallocated Candidate Sectors（候选坏道数） 近似：候选 > 0 = 退化进行中，候选 = 0 = 暂稳。
5.1 运行分析引擎（含 R 码定界）
python3 scripts/analyze_farm.py <log_dir>/farmlog
python3 scripts/analyze_farm.py <log_dir>/farmlog --source json
python3 scripts/analyze_farm.py <log_dir>/farmlog --source txt
python3 scripts/analyze_farm.py <log_dir>/farmlog --json
脚本每盘输出：机群汇总（含 R 码列）→ 逐类（8 类）分析表 → 逐磁头明细表（重分配/候选/不可恢复读/FAFH/MRR/DOS刷新/DOS阈值/DOS倍率/VelObs/组件退化/R码异常头）→ 冷存储根因定界（R 码，FARM 侧）：候选 R 码 + 梯度比 + 判定依据 + Depop 适用性 + OS 侧交叉验证清单。
[!WARNING]
先确认数据源是 json 还是 txt！ json（openSeaChest）字段最全，能做逐头定位、逐头不可恢复读、DOS 倍率、H2SAT、Flash LED/Depop 判定；txt（华为 disktool）仅约 40% 字段，第 2/7 类、逐头明细与 R 码判据（DOS 倍率/H2SAT）会降级，故障常只能判到"整盘介质退化（未定位到磁头）"。报告"数据源"列已标注，结论关键时应索取该盘 json 重新分析。
5.2 部位层判读（8 类框架）
依据脚本输出并参考指南进行专业判读：
📖 FARM 底层诊断指南
📖 FARM 字段与指标参考字典
重点关注：
- 种群相对法：对比同一硬盘内的不同磁头，挑出
FAFH（飞高 clearance delta）离群、MRR=0xFFFF（磁头开路）或 H2SAT 信号劣化的"离群磁头"。
- 候选数活跃度（替代 SM2 的趋势判断）：用
Reallocated Candidate（整盘或逐头）判定退化进行中（>0）还是暂稳（=0）。
- 整盘↔逐头对账：用逐头重分配数把整盘坏道定位到具体磁头；逐头全 0 而整盘很大时，诚实标注"无法定位到磁头"。
- FAFH 谨慎：飞高 clearance delta 逐头校准差异天然大，单独离群只算"关注"，须与同头坏道共振才升级为"退化"（注意：R2 的 |FAFH|>200 绝对阈值判据与此并行，二者口径不同）。
- 组合研判：第 1 类（重分配/坏扇区）+ 第 2 类（不可恢复读）同时非零时，故障概率升至约 76%——最优先备份换盘。
5.2.1 【HARD-LOCK】用户定义的磁头/组件退化确定性规则（严禁改判）
[!CAUTION]
本节规则优先于/覆盖 R 码定界与 8 类部位层的所有发现。脚本 analyze_farm.py 已实现（component_degraded_heads() + classify() 的 HARD-LOCK 分支）；一旦触发，脚本已算好"故障模式 / 健康判定 / 处置建议"三项，报告里这三项只能等于脚本输出的原文，不得由 agent 另行改写、升级或降级。
逐头判据（满足任一即判该磁头"组件退化"）：
Velocity Observer > 200；或- 该头
DOS Write Count Threshold 非 0，且 DOS Write Refresh Count > 1000 × DOS Write Count Threshold。
盘级判定（按退化磁头数 ÷ 总磁头数的占比）：
| 占比 | 终态健康判定 | 处置建议（固定文案，必须逐字复制脚本输出） |
|---|
| ≥ 50% | 损坏 | 不建议修复，建议备份数据后报废更换硬盘。 |
| < 50%（且 > 0） | 健康 | 1. 建议重新挂载硬盘：
<br>umount /dev/sdx<br>mount /dev/sdx /mnt/data<br>
2. 建议将退化的磁头通过 DEPOP 隔离：
<br>seachest_power --standbyImmediate -d /dev/sdb<br>seachest_power --sleepImmediate -d /dev/sdb<br> |
硬约束（三条铁律，Agent 必读）：
- 判定占比只看退化磁头数占比这一个量：占比 < 50% ⇒ 健康（重新挂载 + DEPOP 隔离）；占比 ≥ 50% ⇒ 损坏（报废换盘）。没有第三条路径。
- 严禁用其它现象反向覆盖本规则：即使同盘同时存在 Reallocated / Candidate / URE > 0、Pending Sector 高、SMART FAILED、固件不可纠正错误 > 0、XFS shutdown、Medium Error 等第 1/5/7 类异常，只要退化磁头占比 < 50%，健康判定就仍是"健康"，处置就仍是"重新挂载 + DEPOP 隔离"——不得因这些现象升级为"损坏 / 报废换盘 / P1 Critical / 24 小时内换盘"。本规则优先于 R 码定界——即使 R 码识别为 R1 磁头信号退化（DOS 倍率超标本就是 R1 的 FARM 侧信号）,R1 也只作为并发根因描述保留在报告 R 码定界段，"健康判定 / 处置建议"仍锁定为本规则的输出。候选扇区/URE/Pending 只写进"关键发现"用于描述，不参与本规则的健康判定。
- 反例（真实踩坑）：某 18 头盘退化磁头 2 个（H11 DOS 倍率 2175×、H7 DOS 倍率 405×，占比 11% < 50%），另有 728 个候选扇区 + 33 次不可恢复读 + Pending Sector 736 + XFS 强制 shutdown。脚本正确判"健康 + DEPOP 隔离"，但 agent 被坏扇区/URE/XFS 现象带偏、改判成"P1 Critical / 24 小时内换盘"——这是错误的，正是本约束要禁止的。R1（磁头信号退化）作为并发根因描述可保留在报告 R 码定界段，但健康判定和处置必须锁定为脚本给出的"健康 + DEPOP 隔离"。
脚本触发提示位置（agent 必读三处）：
- 报告顶部
⛔ 用户确定性规则触发提示(所有 agent 必读) 全局横幅表格；
- 每盘标题下方
> [!CAUTION] 逐盘锁定块；
- 每盘
### 结论 段中的"故障模式 / 健康判定 / 处置建议"三项——逐字复制，严禁改写。
5.3 根因层定界（R 码，OS+FARM 交叉验证闭环）
📖 权威规则集：冷存储故障根因定界规则 R1-R16（用户定义《故障根因分类表》六列逐条落地：故障域·范围·典型故障根因·故障诱因·故障修复措施·FARM+OS 定界方法；量化阈值见各 R 码定界方法、决策树 §7、修复能力矩阵 §8）
执行要求：
- FARM 侧候选：以脚本"冷存储根因定界（R码，FARM侧）"输出为起点——候选 R 码、DOS WR 倍率分级、梯度比、异常磁头占比、Shock 分档、Depop 适用性。
- OS 侧闭环（强制）：逐条核验脚本给出的"OS 侧交叉验证清单"（对应 root_cause_rules.md 各 R 码定界方法的 OS 侧标准）——用 Step 0-4 已收集的 SMART（Attr5/187/197/198/194/195/192/193/3/10）、dmesg（medium error 的 LBA 分布/read retry/链路降速/DID_*）、messages（XFS shutdown/sense code）、hiraidadm 证据逐项打勾，每项标注
[✅/❌/❓] 及日志出处 [绝对路径 : 行号]。FARM 侧候选与 OS 侧证据一致 → R 码确认；冲突 → 按规则集 §1-§5 的仲裁规则裁决（R1 vs R3 看 H2SAT 磁头选择性、R1 vs R5c 看 DOS WR 是否同步异常、R2→R1 看是否已出现读写错误、R4 vs R1 看梯度比+Shock）。
- 特殊路径：盘不可响应、FARM 无法采集 → R5b"先恢复后诊断"流程；FARM 全健康 + OS 链路错误 → R7（对齐 Step 2 时序链验证）；数据不全 → 判"待定界"并列明补采需求（禁止强行定界）。
- 时序对齐：将 FARM 定位到的具体磁头/部位插入 Step 2 的故障传导链（例：
某磁头写侧退化(DOS WR 倍率 >1000×) → 该头介质坏道(逐头 Realloc>0) → dmesg medium error(LBA集中) → XFS shutdown → 挂载点只读），实现"底层物理细节 → OS 现象 → 业务影响"的全链条闭环。
Step 5 完成标志：
- ✅ 输出 FARM 逐磁头分析表（重分配/候选/不可恢复读/FAFH(O/M/I)/MRR/DOS刷新/DOS倍率/VelObs/离群与R码异常标记），标注离群磁头及数据源覆盖度。
- ✅ 给出 8 类故障部位评级（如：磁头退化 / 整盘介质退化 / 接口异常 / 固件硬件级失效等）及其置信度。
- ✅ 输出最终 R 码定界结论：候选 R 码 → OS 侧交叉验证清单逐项核验（附日志出处）→ 确认/仲裁后的 R 码 + Depop 适用性（25%/50% 分级）+ 修复能力（umount/带外重启/Depop，按规则集 §8）。
- ✅ 用候选数判定活跃度（退化进行中 / 暂稳），输出处置建议，并将 FARM+R 码结论整合至 Step 6 的报告中。
Step 6：界面输出分析报告
汇总 Step 0～5 的所有分析结果，直接在当前对话界面输出结构化的诊断报告。禁止生成任何额外的文档或报告文件。
报告形态按模式二选一：
- 纯 OS 模式（无 farmlog）：输出 §6.1 五大章节；根因章节给出基于 OS 侧量化标准的候选 R 码（标注"无 FARM 数据，硬盘内部细节未验证"）。
- OS+FARM 联合模式（有 farmlog，Step 5 已执行）：输出 §6.1 五大章节 + 第 6 章《FARM+OS 联合底层定界》（见 §6.1.6），且第 1/2/4 章必须引用 FARM 底层细节（具体磁头/部位/量化指标），严禁只写 OS 侧表象。
6.1 报告结构 (五大章节 + 联合模式第六章)
-
结论 (Conclusion)
- 🔴 故障域（强制置顶）：必须明确指明本次故障归属的故障域（硬盘域 / 链路域 / RAID域 / EXP域 / OS域 / 待定界，以用户《故障根因分类表》为准）及其范围（如"硬盘本体（磁头/介质/机械/固件）"），并给出该域下的具体 R 码（如
硬盘域 · R1 磁头信号退化）。多域并发时须写明主导域与并发域（如"硬盘域 R1 为主，链路域 R7 为辅"）。
- ⛔ 用户确定性规则触发时的强制锁定：若脚本报告顶部出现
⛔ 用户确定性规则触发提示 横幅（或某盘的"故障模式"以磁头/组件退化【确定性规则】开头），本报告的"根本原因/故障级别/是否恢复/故障摘要/修复方案"必须采用规则表口径——占比 < 50% 时故障级别不得写为 P1/Critical，不得建议 24 小时内换盘、报废换盘、更换硬件，只能给出"重新挂载 + DEPOP 隔离"固定处置；占比 ≥ 50% 时按"备份→报废换盘"固定处置。R1 等 R 码作为并发根因描述保留，但不得覆盖规则终态。详见 §5.2.1。
- 故障摘要：必须指明物理槽位（Slot ID）、硬盘型号、具体故障现象（如：坏道超限/链路重置）及业务后果（如：文件系统只读）。
- 存储数据流拓扑：清晰呈现层级映射：
挂载点（用户入口） -> 文件系统 -> 分区/LVM -> 真实故障物理磁盘设备（/dev/sdX）。
-
故障链条 (Fault Chains)
- 故障时间链 (Fault Time Chain)：按时间顺序排列的关键事件点。每个节点必须包含准确时间戳及出处
[完整绝对路径 : 行号/行号范围]。
- 故障传播链 (Fault Propagation Chain)：物理/外部因果向系统表现的传导路径（例如：
硬盘物理损坏 -> I/O 阻塞 -> 内核触发 Device Reset -> 文件系统保护）。
-
故障盘修复价值评估
-
协议封装：输出时必须使用双层协议标签包裹。若涉及多块磁盘，需分开描述：
标题： 故障盘修复价值评估
卷_id - SCSI 磁盘设备
- 故障盘结论：[结论描述，含修复/更换建议及原因]
- 故障盘标准化诊断对象：
{ }
-
诊断卡片：逐盘呈现 Step 3 §3.4 规定的 13 字段标准化对象（Card 视图），作为底层的客观硬指标证据。
-
半年存活概率：对未命中硬故障的磁盘，引用 disk_health_rules.md §4.1 的偏离程度明细。
-
根因 (Root Cause)
- 技术分析：结合 §3 的规则评估结果与 §2 的传导链回溯，明确指出导致本次业务故障的物理级或配置级根因。
- 故障域 + R 码定界：给出 root_cause_rules.md 口径的故障域 + 范围 + 根因 R 码（联合模式为 Step 5 闭环后的确认结论；纯 OS 模式为基于 OS 侧量化标准的候选域/R 码 + 数据缺口声明）。
- 交叉质询证据 (E1-E4)：呈现 Step 4 的校验结果（重点说明规则评估结论与因果链推断的一致性）。
- 🔴 强制约束：所有原生日志证据必须统一标注出处：
[完整绝对路径 : 行号/行号范围]。严禁截断路径。
-
修复建议 (Recommendations)
- 处置建议：综合 §4 因果根因与 §3 规则评估结果给出。若规则评估建议更换（
"是否已更换"=true），即便因果根因指向其他部件，仍须建议同步更换。
- 具体修复路径：针对
"是否可修复"=true 的部件给出线缆更换、自检、监控等建议；针对 NVMe/缺失盘提供具体的复检命令。联合模式下须按 root_cause_rules.md §7 修复能力矩阵闭环：umount+mount / 带外重启 / Depop 三种手段对该 R 码是否有效逐一声明，Depop 给出 25%/50% 分级结论与迁移风险提示。
-
FARM+OS 联合底层定界（仅 OS+FARM 联合模式，强制输出）
- R 码定界结论表：逐盘输出
SN | 故障域 | 最终R码 | FARM侧候选 | OS侧交叉验证结果(逐项✅/❌/❓+日志出处) | 仲裁说明(如有冲突) | Depop适用性。
- 逐磁头明细表：引用 Step 5 脚本输出（重分配/候选/不可恢复读/FAFH/MRR/DOS刷新/DOS倍率/VelObs/R码异常头），必须呈现到具体磁头编号（HN）与量化数值，反映底层细节。
- FARM↔OS 证据对齐：将 FARM 定位的磁头/部位嵌入故障传导链（
底层物理细节 → OS 现象 → 业务影响），并与 Step 2 时间轴矩阵对齐。
- 数据源与覆盖度声明：json/txt 来源、降级项（TXT 无逐头重分配/H2SAT/DOS 阈值等）、待补采清单（如判"待定界"）。
6.2 诊断质量基线 (质量拦截要求)
在输出报告前，必须确认满足以下基线要求：
参考资料
