Skip to main content
L

dsh-incident-full-chain

liuhange789/dsh-incident-full-chain

On-call incident full chain: `oncall_start` classifies an alert into a fault family (timeout / error-rate / resource / dependency / data) and returns ranked likely causes plus a branch-specific checklist; `mitigate` records every action and its result on a timeline and re-plans the next steps from that family, dropping steps already tried; `postmortem` writes postmortem.md (and an HTML copy) with a sorted timeline, key actions, and MTTR measured from the first effective mitigation. Rule-based and local-only: no network, no model call, state kept in incident.json next to the workspace.

Install

dsh plugin --profile web add github:liuhange789/dsh-incident-full-chain

README

dsh-incident-full-chain

故障发生时别靠记忆——三个命令走完全链路:值班定性 → 记录缓解 → 自动复盘。

A DSH plugin for the three phases of an incident. incident_oncall turns an alert into a ranked cause list plus an ordered first-response checklist; incident_mitigate records every action and its result and returns the next step from a built-in fault tree (without re-suggesting an action that already failed); incident_postmortem writes postmortem.md with an exact MTTR computed from the alert time to the first effective action.

It is deliberately not an alerting/monitoring platform: no PagerDuty integration, no auto-remediation, no LLM calls. Every fact in the report comes from what you recorded.

Install

npm install @liuhange/dsh-incident-full-chain

Add the bundle to a DSH profile (alongside the base bundles):

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-headless",
        "@liuhange/dsh-incident-full-chain"
      ]
    }
  },
  "dependencies": {
    "@liuhange/dsh-incident-full-chain": "0.1.0"
  }
}

Restart the profile. Three tools become available; no configuration needed.

Quick start

你:支付接口大面积超时,帮我起一个故障
模型:incident_oncall  alert="支付接口 P99 超时 8s,错误率 21%"  service="pay-api"
      symptoms="504 gateway timeout, upstream timed out after 10s"  severity="SEV1"

模型:incident_mitigate  action="重启 pay-api 全部实例"  result="failed"  note="错误率仍 18%"
      → 下一步建议里不会再有「重启」

模型:incident_mitigate  action="回滚到 v2.7"  result="worked"  note="错误率回到 0.3%"
      → 已恢复,MTTR 14 分钟

模型:incident_postmortem  author="张三"
      → 已写入 postmortem.md

Commands

incident_oncall — start (or restart) an incident

参数必填说明
alert是一行告警描述,例如「api 网关 5xx 错误率 12%」
symptoms否日志片段、错误码、监控指标;用于归类告警族与排序假设
service否受影响服务/模块
severity否SEV1 / SEV2(默认) / SEV3 / SEV4
at否告警时间(ISO 8601),默认当前时间;补录时填真实时间

返回:incidentId、signal(告警族)、hypotheses(按置信度排序的假设)、checklist(有序排查路径)、statePath、replacedPrevious。

告警族由 alert + symptoms 文本自动归类:memory / database / cpu / timeout / error-rate / latency / generic。每个族都有独立的假设表与排查清单,例如超时族会先让你确认「全局还是集中在下游」,再查 DNS 与连接池。

incident_mitigate — record one action

参数必填说明
action是实际做了什么,例如「回滚到 v1.42」
result是worked 已恢复 / partial 部分缓解 / failed 无效
note否指标变化、报错、链接
kind否restart / rollback / scale / drain / config / network / data / other;不填则按 action 推断
at否动作时间(ISO 8601),默认当前时间

返回:recovered、recoveredNow、mttrMinutes、elapsedMinutes、actionCount、nextSteps、warnings。

规则(全部是确定性的,不依赖模型猜测):

  • 恢复时间取最早的有效动作(按 at 排序):补录一个更早的 worked 会把 MTTR 修正到真实值,晚到的有效动作不会把它改大。
  • partial / failed 走该告警族的升级路径,且已经失败过的动作类型不会再次被建议。
  • 连续 3 个以上动作无效时提醒先保存现场证据。

incident_postmortem — write the report

参数必填说明
output否工作区内的输出路径,默认 postmortem.md
author否记录人
at否生成时间(ISO 8601),用于计算未恢复时长

报告章节固定为:摘要、影响、时间线表格(含相对分钟数)、根因假设与验证结论、处置与恢复、阻塞点、改进项(可勾选)、经验教训。生成后事故标记为 closed。

Workspace layout

All state lives under the session workspace (the same cwd the file tools use):

.incident/
  current.json                 # pointer to the incident mitigation/postmortem continue
  INC-20261118-100000/
    state.json                 # append-only timeline + recoveredAt
postmortem.md                  # generated by incident_postmortem

current.json is an atomic write, so a crash never leaves a half-written state. A later tool call in a new process continues the same incident — no in-memory session required.

MTTR definition

MTTR = first(worked action time) − alert time, in whole minutes. It is computed from the timeline, never inferred. An unresolved incident reports elapsed minutes instead.

Limits (by design)

  • One active incident per workspace; starting a new one replaces the pointer while the previous state stays on disk.
  • The fault tree is a fixed, shallow table — it ranks what to check first, it does not claim to diagnose.
  • Reports are Markdown; no charts, no PDF, no external services.

Development

npm install
npm run typecheck   # tsc --noEmit, strict, no any
npm test            # build + real plugin load + tool calls

src/core/ holds the state machine, fault tree, and template; src/host/ only wires them into defineTool.

License

MIT

Related plugins