Menu
故障诊断的思维框架、分层排查顺序、根因判定标准和诊断报告规范。 不包含任何具体系统的检查命令——具体实现由使用者根据自身技术栈在本地 skill 中编写。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| 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-3 个最可能的根因假设
↓
验证：针对每个假设执行最小代价的检查，确认或排除
↓
├─ 假设确认 → 记录根因，输出修复建议
└─ 假设排除 → 修正假设，继续循环
禁止的做法：
从最外层开始，逐层向内，每层排除后再进入下一层：
第 1 层：用户/业务层
└─ 现象：哪些用户/业务受影响？影响的是读还是写？完全不可用还是偶发？
第 2 层：应用服务层
└─ 检查：进程是否存活、端口是否监听、应用日志有无 ERROR/EXCEPTION
第 3 层：中间件层
└─ 检查：数据库连接数、缓存命中率、消息队列积压、服务注册状态
第 4 层：基础设施层
└─ 检查：CPU/内存/磁盘/网络指标，系统日志（OOM/磁盘满/网络丢包）
第 5 层：硬件/网络层
└─ 检查：节点连通性、物理网络、存储 I/O 性能
原则： 不要因为"直觉告诉我是数据库问题"就跳过应用层。分层排查的意义在于避免误判和遗漏关联根因。
满足以下全部条件，才能将某个因素认定为根因：
仅满足部分条件时，标记为"疑似根因"，继续收集证据。
排查之前，必须先保留现场。任何恢复操作都可能清除关键证据。
| 证据类型 | 保留方式 | 为什么重要 |
|---|---|---|
| 进程状态 | 进程栈快照（不修改进程） | 崩溃根因往往在栈信息中 |
| 系统指标 | 截取故障时段的指标快照 | 恢复后指标恢复正常，原始数据不可复现 |
| 错误日志 | 复制故障时段的日志到独立目录 | 日志轮转可能覆盖原始记录 |
| 网络状态 | 当前连接数、丢包率、DNS 缓存的快照 | 网络状态是瞬时的，稍纵即逝 |
| 配置快照 | 当前生效配置的完整保存 | 确认是否有未预期的配置变更 |
线上故障最常见的根因之一是近期变更。诊断时必须主动关联变更事件。
| 变更类型 | 回溯窗口 | 常见的因果模式 |
|---|---|---|
| 应用发布 | 24h | 版本回退后故障消失 |
| 配置变更 | 24h | 配置项与故障指标直接相关 |
| 基础设施变更 | 7d | 扩容/缩容/迁移导致流量分布变化 |
| 依赖升级 | 7d | 下游依赖版本不兼容 |
| 定时任务 | 当天 | 定时任务与故障时间吻合 |
不可仅凭时间接近就判定因果。满足以下全部条件才能关联：
不满足可复现条件时，标记为"疑似关联变更"，继续收集证据。
单一症状往往有多个关联组件需要同时检查：
关联诊断不是"同时检查所有组件"，而是根据症状模式有针对性地扩展检查范围。
并非所有观测到的异常都是根因的信号。诊断时必须甄别证据的质量。
| 级别 | 定义 | 诊断权重 |
|---|---|---|
| 确证证据 | 直接证明根因的日志/指标/输出，可复现 | 作为根因判定的必要条件 |
| 支持证据 | 与根因相关但不能独立证明，如间接指标的异常变化 | 支持假设但不足以锁定根因 |
| 干扰信号 | 与根因无关的异常，如历史遗留告警、其他服务的独立故障 | 必须排除，否则误导排查方向 |
原则：宁可暂缓结论，不可将干扰信号当作根因证据。
diagnoser persona 严格只读，以下操作在诊断阶段绝对禁止：
| 禁止操作 | 理由 |
|---|---|
| 重启服务 | 会清除现场证据，且可能掩盖根因 |
| 修改配置 | 诊断阶段无法预判修改影响 |
| 删除日志/临时文件 | 这是证据，不可销毁 |
| 执行任何写 SQL | 可能改变数据导致无法还原 |
| kill 进程 | 等同于重启，同上 |
恢复优先原则：只读边界不等于"不做恢复"。diagnoser 必须在诊断报告中优先提供恢复建议（限流、降级、切换备库等），由 executor persona 执行。恢复服务优先于定位根因。
所有修复操作必须作为"建议"输出给 executor persona 或人工执行。
每次诊断结束，必须输出以下格式的报告，不得省略：
## 故障诊断报告
**诊断时间**：<ISO8601>
**操作者**：hermes/diagnoser
**触发原因**：<告警描述或用户请求>
### 影响评估
- **影响等级**：高 / 中 / 低
- **影响范围**：<受影响的业务、用户群、数据量>
- **数据损失风险**：<是否有数据丢失或不一致风险>
### 恢复建议（优先执行）
1. <立即可执行的恢复措施：限流/降级/切换备库等>
2. <恢复后的观察要点>
### 现象描述
- <具体描述观察到的异常，包括首次发现时间、影响范围、影响程度>
### 排查过程
| 步骤 | 检查项 | 结果 | 结论 |
|------|--------|------|------|
| 1 | ... | ... | 排除/确认 |
### 变更关联
- **近期变更**：<T0 前相关变更列表，若无则标注"无关联变更">
- **关联判定**：<是否确认某变更与故障因果相关，及判断依据>
### 证据甄别
- **确证证据**：<直接证明根因的关键日志/指标>
- **支持证据**：<间接相关的异常信号>
- **已排除的干扰信号**：<与根因无关但被观察到的异常>
### 根因结论
- **根因**：<一句话描述>
- **证据链**：<从现象到根因的完整因果链>
- **置信度**：高 / 中 / 低（附说明）
### 修复建议
1. <具体可执行的修复步骤，供 executor 或人工执行>
2. ...
### 复盘与预防
- **根因分类**：<代码缺陷 / 配置错误 / 容量不足 / 依赖故障 / 未知>
- **暴露的监控盲点**：<哪些异常未能提前发现，需要新增什么监控>
- **流程改进**：<响应流程中的不足及改进方向>
- **预防措施**：<如何避免同类故障再次发生>
本框架不提供任何具体系统的检查命令。使用者需要：
depends_on: [diagnose]，确保方法论约束生效persona 必须设置为 diagnoser，不得降级为 executorinventory/hosts.yaml参见 skills/infra/inventory-loader 了解如何读取环境变量。