Menú
故障诊断的思维框架、分层排查顺序、根因判定标准和诊断报告规范。 不包含任何具体系统的检查命令——具体实现由使用者根据自身技术栈在本地 skill 中编写。
Instalar con Codex o Claude Copia este prompt, pégalo en Codex, Claude u otro asistente, y deja que revise la página de la skill y la instale por ti.
Basado en la clasificación ocupacional SOC
| 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 了解如何读取环境变量。