一句话定义:运行手册(Runbook)是把"出事了该怎么办"提前写好的分步骤操作清单——值班的人不需要临场发挥,按顺序执行就能把系统拉回正常。
打个比方:飞机发动机报警时,飞行员不会临时讨论气动原理,而是翻开检查单,一条条念、一条条做。Runbook 就是软件系统的检查单。它最反直觉的地方在于:写它的人往往不是出事时值班的人。平时头脑最清醒的那批人,在系统还活着的时候,把最坏的情况先想一遍,写成文字留给凌晨三点的那个人。
放到 AI 系统里,值得写进 Runbook 的场景其实很集中:
- 智能体(Agent)跑飞:某个智能体开始无限调用工具、反复重试同一件事。第一步不是读代码,而是一键收回它的工具权限、或把并发降到零,先止血;再保留现场(日志、调用链 trace)慢慢查。
- 成本飙升:模型调用量或 token 消耗在监控上出现异常斜率。手册要写清楚:谁有权限流、限到多少、降级到哪个更小的模型、同时通知谁。
- 工具全挂:依赖的外部 API 大面积超时。写明降级路径——返回缓存结果、切备用供应商,还是给用户一个诚实的失败提示。
- 密钥失效:鉴权报 401。写清楚密钥存在哪、谁能轮换、轮换后哪些服务需要重启,避免"只有某个人知道"。
判断标准很朴素:每一步都应是一个可以执行的动作,而不是"评估一下情况"。带上判断条件和止损线,比如"若 5 分钟内未恢复,执行回滚"。
和相邻概念的区别:
| 概念 | 回答的问题 | 典型形态 |
|---|---|---|
| 运行手册 Runbook | 出事时具体按哪个键 | 分步骤清单,含止血与回滚 |
| 应急预案 Playbook | 这类事故谁牵头、怎么决策 | 角色分工与决策树 |
| 架构文档 | 系统长什么样 | 架构图与说明 |
| 告警规则 | 什么时候该知道 | 阈值与通知渠道 |
Runbook 也常被误当成自动化的替代品。其实两者是接力关系:先写成人能照着做的步骤,跑顺了,再把其中最机械的几步交给脚本,人就只管判断和决策。
实际意义:对 AI 从业者,Runbook 是把团队记忆从"最懂的那个人脑子里"搬出来,让值班不再是一场赌博;写的过程本身还会逼出设计问题——如果一步关不掉,说明架构缺个开关。对普通职场人,凡是会重复发生的应急处置,都值得写成这样一张纸。写完要演练,过期要更新,一份从没人真跑过的手册,约等于没有。涉及具体平台的操作路径与默认参数,以官方页面为准。
