Incident Brief

---
name: incident-brief
description: 生成线上问题排查简报。把日志、监控、GitHub 变更记录和工单对齐成一条统一时间线，定位指标异常起点，输出按可疑度排序的候选变更，每个候选带支持证据、反证和一句可在两分钟内验证的推论。当用户在排查线上故障、告警、服务异常、错误率或延迟上涨、接口报错、发布后出问题，或说「线上炸了」「什么时候开始的」「是哪次变更导致的」「帮我看下这个告警」「出个排查简报」「故障复盘材料」时使用。本技能不下根因结论，只提供排序过的候选与证据链，判断权保留给工程师。需要明确的时间窗；时间窗不明确时必须先问，不要猜。
author: Captain
version: 0.1.0
display_name: "线上排查简报"
display_name_en: "Incident Brief"
description_zh: "把变更、指标异常与人工观察对齐成一条时间线，按可疑度排序候选变更并给出反证与可验证推论，不下根因结论。"
description_en: "Align changes, metric anomalies and manual observations on one timeline; rank suspect changes with counter-evidence and a testable prediction, without asserting root cause."
examples_zh:
  - "线上错误率 14:23 开始上涨，帮我出一份排查简报"
  - "把这段时间的变更、告警和指标对齐成时间线"
  - "哪次变更最可疑？给我证据和反证"
examples_en:
  - "Error rate started climbing at 14:23, draft an incident brief"
  - "Align changes, alerts and metrics from this window on one timeline"
  - "Which change is the most suspicious? Give evidence and counter-evidence"
metadata:
  {
    "openclaw":
      {
        "requires": { "bins": ["python3"] },
        "os": ["darwin", "linux", "win32"],
        "emoji": "🚨"
      }
  }
---

# 线上问题排查简报

排查线上问题时，人最痛的不是不知道怎么修，而是**在告警、日志、监控、变更记录四个系统之间来回跳、手动对齐时间线**。这 15 分钟发生在最紧张的时刻，而且每次都一样。

这个技能把那 15 分钟压成 1 分钟。

## 最重要的约束：不下结论

**绝对不要输出「根因是 X」。** 三个理由：

1. 事故场景下一个自信但错误的结论会把人带进沟里，代价远大于不给结论
2. 你拿不到全部上下文：灰度状态、业务背景、上下游的口头约定
3. 错一次，工程师就再也不信这个工具了

**要输出的是：按可疑度排序的候选，每个带支持证据、反证、和一句可验证的推论。**

```
候选 1：14:23 的配置变更　可疑度：高
  支持：错误率抬升起点 14:23:40，与变更时间差 40s
  反证：该配置只影响 B 集群，但 A 集群同样有错误率上升
  可验证推论：若成立，A 集群错误应为下游传导，检查 A→B 调用链错误码
```

最后一行是灵魂——**让工程师 30 秒内证实或排除这个候选**，比任何根因判定都有用。写不出反证的候选，说明证据不足，降级或删掉。

## 前置：确认时间窗

时间窗猜错，整份简报作废。必须明确：

- 异常**被发现**的时刻（告警触发时间，或用户报障时间）
- 观察窗口：默认 `[T-30min, T+10min]`
- 基线窗口：再向前取 2 小时。**不知道正常长什么样，就判断不了哪里不正常**

信息不全就问，不要猜。

## 执行流程

### 第 1 步：采集 GitHub 变更

```bash
python3 {baseDir}/scripts/collect_changes.py \
  --repo owner/name --since "2026-09-14T13:50:00Z" --until "2026-09-14T14:40:00Z" \
  --out out/changes.json
```

抓取窗口内的 releases、deployments、合并的 PR。需要 `GITHUB_TOKEN` 环境变量（只读权限即可）。
`--repo` 可重复传，多服务一起查。

### 第 2 步：找异常起点

有指标 CSV（两列：`timestamp,value`）就跑：

```bash
python3 {baseDir}/scripts/changepoint.py --input metrics.csv \
  --baseline-until "2026-09-14T13:50:00Z" --out out/anomaly.json
```

用滑动基线 + 3σ 找**第一个连续 3 点越界**的位置。

注意：找的是**变化点**，不是超阈值点。阈值告警只告诉你"现在坏了"，变化点告诉你"什么时候开始坏的"——后者才能对上变更。

不要换更复杂的算法。事故场景下**可解释性比精度重要**。

### 第 3 步：合并时间线（核心价值）

手工观察到的事件（用户报障、人工操作、群里的消息）写进一个 CSV，字段见 `references/manual-events.example.csv`。

```bash
python3 {baseDir}/scripts/timeline.py \
  --changes out/changes.json --anomaly out/anomaly.json \
  --manual manual-events.csv --out out/timeline.md
```

**这一步就已经交付 80% 的价值。** 一张对齐的时间线，人自己往往就能看出问题。

### 第 4 步：候选排序（你来做，不是脚本）

读 `out/timeline.md`，对每个变更事件按下表打分，然后**人工复核**：

| 因子 | 权重 | 判断依据 |
|---|---|---|
| 时间接近度 | 高 | 变更时刻与异常起点的距离。越近越可疑，但注意有的变更是延迟生效的 |
| 作用域重合 | 高 | 变更影响的服务/集群是否覆盖异常范围。不重合是强反证 |
| 变更类型风险 | 中 | 配置 > 发布 > 扩缩容。配置生效快且回滚记录少 |
| 历史相关性 | 低 | 该类变更过去是否引发过同类告警 |

**排序不等于判定。** 每个候选必须同时给反证。

### 第 5 步：按输出契约渲染

## 输出契约

```markdown
# 排查简报　<服务名>　<时间窗>

## 现象
一句话：什么指标、从什么值变成什么值、什么时候开始。

## 影响面
- 受影响服务 / 集群 / 用户比例（有数据才写，没有就写「未知」）
- 是否仍在持续

## 时间线
| 时刻 | 来源 | 事件 | 链接 |

## 可疑候选（按可疑度排序，非结论）
### 候选 N：<摘要>　可疑度：高/中/低
- 支持证据：
- 反证：
- **可验证推论**：若成立，应能观察到 ___，验证方式 ___

## 已排除
- <项>：排除依据 ___

## 数据缺口
- <数据源> 不可用：<原因>。本简报未覆盖 <哪部分判断>。

## 建议下一步
1. 先验证候选 1 的推论（预计 N 分钟）
```

硬约束：

- "可疑候选"标题必须含「非结论」三字
- 每个候选必须有反证
- "数据缺口"一节即使为空也要保留，写「无」。**缺数据比错数据危险，但隐瞒缺数据最危险**

## 额度控制

事故场景下人会反复追问，上下文累积极快，额度会爆。

- 第 1、2、3 步**全部脚本完成，不进模型**。只有第 4、5 步进模型
- 进模型的是**归一化后的时间线**（几 KB），不是原始日志（几 MB）
- 日志必须先聚类采样：同模式折叠成 `<pattern> × N 次`，只留首末各 3 条
- 追问时只带时间线摘要，不重传原始数据

## 安全

简报产物含生产日志片段。**默认只写本地。** 若使用云端模型参与第 4、5 步，先确认已脱敏：IP、手机号、身份证、token、内网域名。

## 版本

v0.1 —— GitHub 变更自动采集；日志与监控走手工喂数据。
后续：v0.2 接 Prometheus，v0.3 接 Loki/ES 并做日志聚类，v0.4 内网适配器与脱敏管线。