我们交付的每一个智能体系统都带一份 runbook。六页,除了一张流程图没有别的图,语气像 2010 年代的 SRE 文档。它刻意写得乏味。
我们逐渐把 runbook 视作主要交付物,而非文书工作。如果一个刚做完的智能体写不出 runbook,那它就还没准备好上生产。下面解释为什么,以及里面到底有什么。
为什么 runbook 就是规格
runbook 强迫你回答六个否则就会被搁置的问题:
- “正常工作”是什么样? 不是感觉——是具体的检查。“p95 延迟低于 X、evals 通过率高于 Y、每请求成本在 A 和 B 之间。”
- “坏了”是什么样? 带阈值的具体症状,而不只是“用户在抱怨”。
- 坏了谁被呼? 一个名字、一条升级链、一个电话号码。
- 每种已知故障的应对手册是什么? 一步一步,包括“先什么都别做 5 分钟”——如果答案就是这个的话。
- 何时回滚? 不是“变糟的时候”。一个无需开会就能触发回滚的具体条件。
- 什么状态会保留,什么不会? 如果回滚了智能体,正在进行中的工作流、部分完成的请求、排队中的请求会怎样?
如果团队不能把这六个全部书面回答出来,那这个智能体还不算生产级。runbook 不是对已成事实的记录——写它 这件事本身是让它成真的过程。
结构
我们交付的每份 runbook 都有同样的六节:
1. 服务概要
一段话。这个智能体做什么、依赖什么、被什么依赖。智能体职责变化时更新。
2. 健康度
仪表板 URL。定义“健康”的那四五个指标。绿/黄/红的阈值。不超过五个——如果你有十个,没人会盯。
3. 常见故障
每个失败模式独立一节:
- 症状——运维人员在仪表板上看到的。
- 诊断——如何确认这是真正原因,而不是貌似的东西。
- 缓解——按顺序要做的步骤及预期结果。
- 解决——成功是什么样。
我们的目标是记录 6–10 种失败模式。多数运维人员只会用到其中三种,但长尾才是凌晨三点救你的部分。
4. 升级
按何种顺序、为何种问题联系谁。是电话号码,不是 Slack handle。包括“这超出 on-call 范围——升级到工程团队”的路径。
5. 回滚
我们回滚的具体条件,以及执行流程。关键是:谁有权 决定 无需开会就回滚。通常是 on-call。
回滚动作本身应当只是一条命令。如果是三步加一次协调会,那就不是回滚流程——那是项目计划。
6. 变更日志
自上次 runbook 评审以来的每一项变更:prompt 版本、模型版本、检索索引版本、依赖升级。一条时间线,让 on-call 能在系统开始异常时看到“过去 24 小时变了什么”。
不在里面的东西
runbook 不是用来解释智能体 如何工作 的。那是架构文档的事。runbook 是在它停止工作时用来操作它的。
它也不是给新人入职用的。runbook 假定你已经了解这个系统;它告诉你它坏了该怎么办。别用解释性散文稀释它。
有了 runbook 之后会变什么
团队与智能体之间的关系会变。没有 runbook 时,每次事故都是未知——工程师即兴发挥,事后复盘多半靠编。
有了 runbook,事故就成了对一份成文预期的 例外。事后复盘变成 runbook 更新:“这种故障没在第 3 节里;这是新的一条。”每次事故都教导着 runbook。
六个月内,一份维护良好的 runbook 能覆盖系统实际遇到的 90% 的故障。剩下 10% 才是有趣的事故——那些需要真正工程而不是照本宣科的事故。
交接的信号
runbook 同时也是我们的交接文档。我们离开某次合作时,客户团队拥有一个系统 和 一份 runbook,使他们能不靠我们独立运维。我们见过太多交接失败,就是因为离开的团队把运维知识留在了自己脑袋里。
刻意乏味。runbook 让智能体运维起来变得乏味。而生产级的样子,就是乏味。