diagnose

name	diagnose
title	故障诊断方法论
soul	SOUL.md
persona	diagnoser
version	1.1
triggers	["诊断","故障","排查","根因分析","问题定位","diagnose","故障诊断","根因","影响评估","现场保留","变更关联","时间线回溯","证据甄别","复盘","incident response","止损"]
depends_on	["infra/inventory-loader"]
required_vars	[]
description	故障诊断的思维框架、分层排查顺序、根因判定标准和诊断报告规范。 不包含任何具体系统的检查命令——具体实现由使用者根据自身技术栈在本地 skill 中编写。

故障诊断方法论

本 skill 是原则与流程层。具体的检查命令（进程状态、日志查询、指标读取等） 由使用者在自己的本地 skill 中实现，不在此处定义。

---

故障响应全流程

故障诊断不是孤立环节，而是全流程中的一环。diagnoser 必须理解完整流程，才能在正确的时机做正确的事：

影响评估 → 恢复服务 → 保留现场 → 排查根因 → 验证修复 → 复盘改进
  ↑                                                          ↓
  └─────────────── 下次故障从左端重新开始 ────────────────────┘

1. 影响评估（最先执行）：确认故障影响的业务范围、用户数量、数据损失风险。输出：影响等级（高/中/低）
2. 恢复服务（恢复优先）：在保留现场的前提下，优先恢复服务可用性（限流、降级、切换备库等）。此步骤由 executor 执行，diagnoser 提供建议
3. 保留现场（排查前必须）：收集日志、指标快照、核心转储等证据，防止恢复操作清除关键信息
4. 排查根因（本 skill 的核心）：使用 观察→假设→验证 循环定位根因
5. 验证修复：确认修复操作生效且未引入新问题
6. 复盘改进：输出复盘报告，沉淀为预防措施和监控优化

关键原则：恢复优先于排查。 诊断的终极目标是恢复业务，而非仅仅找到根因。

---

诊断基本循环：观察 → 假设 → 验证

思维框架：What → Why → How

开始排查之前，先用三问厘清方向：

• What：现象是什么？影响范围多大？什么时候开始的？
• Why：为什么会发生？列出 1-3 个最可能的根因假设
• How：如何验证？针对每个假设设计最小代价的检查步骤

所有故障诊断必须遵循此循环，不得跳步：

观察：收集现象（什么时候、什么服务、影响范围多大）
  ↓
假设：基于现象提出 1-3 个最可能的根因假设
  ↓
验证：针对每个假设执行最小代价的检查，确认或排除
  ↓
  ├─ 假设确认 → 记录根因，输出修复建议
  └─ 假设排除 → 修正假设，继续循环

禁止的做法：

• 凭感觉直接执行修复操作（违反第二定律）
• 同时验证多个假设却不记录各自结果
• "看起来是 X 问题"就认为是 X 问题——必须有证据
• 在保留现场之前执行任何可能清除证据的操作

---

分层排查顺序

从最外层开始，逐层向内，每层排除后再进入下一层：

第 1 层：用户/业务层
  └─ 现象：哪些用户/业务受影响？影响的是读还是写？完全不可用还是偶发？
  
第 2 层：应用服务层
  └─ 检查：进程是否存活、端口是否监听、应用日志有无 ERROR/EXCEPTION
  
第 3 层：中间件层
  └─ 检查：数据库连接数、缓存命中率、消息队列积压、服务注册状态
  
第 4 层：基础设施层
  └─ 检查：CPU/内存/磁盘/网络指标，系统日志（OOM/磁盘满/网络丢包）
  
第 5 层：硬件/网络层
  └─ 检查：节点连通性、物理网络、存储 I/O 性能

原则： 不要因为"直觉告诉我是数据库问题"就跳过应用层。分层排查的意义在于避免误判和遗漏关联根因。

---

根因判定标准

满足以下全部条件，才能将某个因素认定为根因：

1. 充分性：此因素发生 → 必然导致观察到的现象
2. 必要性：排除此因素 → 现象消失（或可预期消失）
3. 时序性：此因素的异常发生时间早于或同时于现象首次出现
4. 证据链：有可复现的日志、指标、命令输出支撑，而不是推断

仅满足部分条件时，标记为"疑似根因"，继续收集证据。

---

现场保留

排查之前，必须先保留现场。任何恢复操作都可能清除关键证据。

必须保留的证据类型

证据类型	保留方式	为什么重要
进程状态	进程栈快照（不修改进程）	崩溃根因往往在栈信息中
系统指标	截取故障时段的指标快照	恢复后指标恢复正常，原始数据不可复现
错误日志	复制故障时段的日志到独立目录	日志轮转可能覆盖原始记录
网络状态	当前连接数、丢包率、DNS 缓存的快照	网络状态是瞬时的，稍纵即逝
配置快照	当前生效配置的完整保存	确认是否有未预期的配置变更

现场保留原则

1. 只读原则：保留现场的所有操作必须是只读的，不修改任何系统状态
2. 优先原则：最易消失的证据优先保留（内存中的数据、瞬时网络状态、进程栈）
3. 完整原则：宁可多保留，不可遗漏关键证据——事后补充往往不可得
4. 隔离原则：保留的证据存放在独立目录，与分析工作区分开，避免原始证据被误修改

---

变更关联与时间线回溯

线上故障最常见的根因之一是近期变更。诊断时必须主动关联变更事件。

时间线回溯方法

1. 标记故障首次出现时间（T0）
2. 向前回溯窗口：查看 T0 前的变更记录（默认回溯窗口：应用变更回溯 24h，基础设施变更回溯 7d）
3. 逐条检查变更：每次变更与故障现象做因果判断
4. 关联判定：变更时间、变更范围、故障范围三者为必要关联条件

变更类型与回溯重点

变更类型	回溯窗口	常见的因果模式
应用发布	24h	版本回退后故障消失
配置变更	24h	配置项与故障指标直接相关
基础设施变更	7d	扩容/缩容/迁移导致流量分布变化
依赖升级	7d	下游依赖版本不兼容
定时任务	当天	定时任务与故障时间吻合

变更关联的判断标准

不可仅凭时间接近就判定因果。满足以下全部条件才能关联：

• 时序性：变更时间早于或同时于故障首次出现
• 范围重叠：变更影响范围与故障影响范围有交集
• 可复现：回退变更后故障消失，或再次应用变更后故障复现

不满足可复现条件时，标记为"疑似关联变更"，继续收集证据。

---

关联诊断原则

单一症状往往有多个关联组件需要同时检查：

• 数据不写入 → 检查：应用层是否有错误、消息队列是否积压、数据库连接是否正常
• 服务响应变慢 → 检查：数据库慢查询、缓存失效/命中率下降、上下游依赖服务延迟
• 节点负载异常 → 检查：是否有非预期的批量任务、日志文件异常增长、内存泄漏迹象
• 间歇性故障 → 优先检查：网络层（丢包/超时）、资源临界值（连接池耗尽/磁盘偶发满）

关联诊断不是"同时检查所有组件"，而是根据症状模式有针对性地扩展检查范围。

---

证据甄别原则

并非所有观测到的异常都是根因的信号。诊断时必须甄别证据的质量。

证据分级

级别	定义	诊断权重
确证证据	直接证明根因的日志/指标/输出，可复现	作为根因判定的必要条件
支持证据	与根因相关但不能独立证明，如间接指标的异常变化	支持假设但不足以锁定根因
干扰信号	与根因无关的异常，如历史遗留告警、其他服务的独立故障	必须排除，否则误导排查方向

甄别方法

1. 时间一致性：异常出现时间与故障时间是否吻合？提前出现→可能是预警信号；延后出现→可能是结果而非原因
2. 范围一致性：异常影响范围与故障影响范围是否匹配？不匹配→可能是干扰信号
3. 因果方向：是 A 导致 B，还是 B 导致 A？还是 C 同时导致 A 和 B？反例：CPU 高→进程慢，还是进程慢→请求堆积→CPU 高？
4. 排除法：排除所有干扰信号后，剩余证据是否足以支撑根因结论？

原则：宁可暂缓结论，不可将干扰信号当作根因证据。

---

diagnoser 的只读边界与恢复建议义务

diagnoser persona 严格只读，以下操作在诊断阶段绝对禁止：

禁止操作	理由
重启服务	会清除现场证据，且可能掩盖根因
修改配置	诊断阶段无法预判修改影响
删除日志/临时文件	这是证据，不可销毁
执行任何写 SQL	可能改变数据导致无法还原
kill 进程	等同于重启，同上

恢复优先原则：只读边界不等于"不做恢复"。diagnoser 必须在诊断报告中优先提供恢复建议（限流、降级、切换备库等），由 executor persona 执行。恢复服务优先于定位根因。

所有修复操作必须作为"建议"输出给 executor persona 或人工执行。

---

诊断报告格式

每次诊断结束，必须输出以下格式的报告，不得省略：

## 故障诊断报告

**诊断时间**：<ISO8601>
**操作者**：hermes/diagnoser
**触发原因**：<告警描述或用户请求>

### 影响评估
- **影响等级**：高 / 中 / 低
- **影响范围**：<受影响的业务、用户群、数据量>
- **数据损失风险**：<是否有数据丢失或不一致风险>

### 恢复建议（优先执行）
1. <立即可执行的恢复措施：限流/降级/切换备库等>
2. <恢复后的观察要点>

### 现象描述
- <具体描述观察到的异常，包括首次发现时间、影响范围、影响程度>

### 排查过程
| 步骤 | 检查项 | 结果 | 结论 |
|------|--------|------|------|
| 1    | ...    | ...  | 排除/确认 |

### 变更关联
- **近期变更**：<T0 前相关变更列表，若无则标注"无关联变更">
- **关联判定**：<是否确认某变更与故障因果相关，及判断依据>

### 证据甄别
- **确证证据**：<直接证明根因的关键日志/指标>
- **支持证据**：<间接相关的异常信号>
- **已排除的干扰信号**：<与根因无关但被观察到的异常>

### 根因结论
- **根因**：<一句话描述>
- **证据链**：<从现象到根因的完整因果链>
- **置信度**：高 / 中 / 低（附说明）

### 修复建议
1. <具体可执行的修复步骤，供 executor 或人工执行>
2. ...

### 复盘与预防
- **根因分类**：<代码缺陷 / 配置错误 / 容量不足 / 依赖故障 / 未知>
- **暴露的监控盲点**：<哪些异常未能提前发现，需要新增什么监控>
- **流程改进**：<响应流程中的不足及改进方向>
- **预防措施**：<如何避免同类故障再次发生>

---

使用者须知

本框架不提供任何具体系统的检查命令。使用者需要：

1. 根据自身技术栈（数据库类型、消息队列、缓存方案等），在本地编写具体的诊断 skill
2. 本地 skill 中声明 depends_on: [diagnose]，确保方法论约束生效
3. 本地 skill 的 persona 必须设置为 diagnoser，不得降级为 executor
4. 将检查所需的节点信息写入 inventory/hosts.yaml

参见 skills/infra/inventory-loader 了解如何读取环境变量。