docs(runbooks): add runbook spec, template, index and 6 first-batch runbooks; light-enhance existing 10
- RUNBOOKS.md: repo-level spec (six-field model, naming, safety, maturity path) - runbooks/_template.md + README.md: standard template and 16-entry routing index - new: issue-to-merge, fix-ci, release, rollback, network-change, network-recovery - light-enhance 10 existing runbooks with Purpose/Scope/Safety headers - AGENTS.md: point step 3 at index/spec, add runbook execution rules - docs/agent-runbook-guide.md: archive of Manus AI guide
This commit is contained in:
windyboy
@@ -0,0 +1,326 @@
|
||||
# Agent Runbook 实用指南（v1）
|
||||
|
||||
> **定位**：本指南用于把团队的重复性运维、交付与故障处理经验写成可由 Agent 安全执行的流程。它适用于以 Git 仓库为中心的工程协作模式，优先采用 **Markdown + Git 版本控制 + 明确的 Agent 路由规则**，而不是一开始引入复杂的自动化平台。
|
||||
|
||||
> 本文件为上游参考存档。仓库内落地规范见 [`RUNBOOKS.md`](../RUNBOOKS.md)，标准模板见 [`runbooks/_template.md`](../runbooks/_template.md)，索引见 [`runbooks/README.md`](../runbooks/README.md)。
|
||||
|
||||
## 1. 什么是 Agent Runbook
|
||||
|
||||
Runbook 是预先设计的、可重复执行的操作流程，用于处理部署、告警、故障、配置变更、CI 修复等标准化工作。传统 Runbook 的主要读者是人；**Agent Runbook 则必须把人的隐性判断显式化**，使 Agent 能知道做什么、看到什么才算正常、下一步去哪里、何时停止以及如何撤销。
|
||||
|
||||
Google SRE 强调在事故发生前设计响应流程、系统化排障，并逐步将重复性运维工作自动化。[1] [2] AWS Systems Manager Automation 则把可执行 Runbook 建模为顺序步骤：每个步骤调用一个动作，前一步输出可以传递给后续步骤。[3] 这两种思路共同构成了 Agent Runbook 的实用基础。
|
||||
|
||||
| 层次 | 核心问题 | 应承担的职责 |
|
||||
|---|---|---|
|
||||
| `AGENTS.md` | **何时使用哪份流程？** | 工作路由、通用操作约束、无匹配流程时的默认行为 |
|
||||
| `runbooks/*.md` | **这件事按什么流程做？** | 前置条件、分步操作、决策分支、验证、停止条件与回滚 |
|
||||
| Skill / MCP / Tool | **有哪些可调用能力？** | 具体能力、参数、权限边界和使用说明 |
|
||||
| Shell / GitHub / Linear / SSH 等 | **实际如何执行？** | 对系统、代码库或外部服务执行操作 |
|
||||
|
||||
## 2. 设计目标与适用边界
|
||||
|
||||
Agent Runbook 的目标不是让 Agent 在所有异常下“想办法修好”，而是在一个**已知、受控、可验证、可回退**的边界中提高执行一致性。它应当优先覆盖高频、后果明确、流程稳定的操作，例如 CI 失败定位、Issue 到合并请求、发布前检查、标准部署、回滚及网络变更。
|
||||
|
||||
| 适合纳入 Runbook | 暂不适合直接自动执行 |
|
||||
|---|---|
|
||||
| 明确输入、固定步骤、可观察结果的操作 | 目标或验收标准尚不清楚的探索性任务 |
|
||||
| 可在每次修改后验证状态的变更 | 缺失关键参数、权限或上下文的任务 |
|
||||
| 具有安全回滚路径的发布与配置调整 | 高破坏性、不可逆或影响面未知的操作 |
|
||||
| 可由权限与审批规则约束的运维流程 | 与既有流程事实冲突、无法判断根因的异常场景 |
|
||||
|
||||
> **基本原则**：当实际状态与 Runbook 的假设冲突，Agent 应停止并呈报，而不是补全未知信息、绕过检查或继续试错。
|
||||
|
||||
## 3. Agent Runbook 的最小字段
|
||||
|
||||
与普通人工 Runbook 相比，Agent Runbook 必须显式包含以下六类控制信息。缺少其中任一项，都会增加盲目执行或错误恢复的风险。
|
||||
|
||||
| 字段 | 作用 | 写作要求 |
|
||||
|---|---|---|
|
||||
| **Action** | 定义当前要执行的动作 | 使用可观察、可执行的动词；避免“检查一下”“适当调整”等模糊表述 |
|
||||
| **Expected** | 描述正常状态或预期输出 | 给出具体信号、阈值、状态码、测试结果或页面表现 |
|
||||
| **Decision** | 定义分支与下一跳 | 用“条件 → 下一步”的形式；无法判断时指向 `STOP` |
|
||||
| **Verification** | 确认变更真正生效 | 在每个有副作用的步骤后执行，不能被跳过 |
|
||||
| **Stop condition** | 规定何时不得继续 | 明确列出信息缺失、状态冲突、权限不足、验证失败等条件 |
|
||||
| **Rollback** | 描述如何恢复到变更前状态 | 标明触发条件、前提、撤销步骤及回滚后的验证方式 |
|
||||
|
||||
## 4. 推荐目录与路由机制
|
||||
|
||||
建议把流程与代码一起保存在 Git 仓库中。这样 Runbook 可以评审、版本化、随系统演进更新，也能与相关 Issue、PR 和配置建立可追溯关系。
|
||||
|
||||
```text
|
||||
repo/
|
||||
├── AGENTS.md
|
||||
├── RUNBOOKS.md
|
||||
├── runbooks/
|
||||
│ ├── README.md
|
||||
│ ├── issue-to-merge.md
|
||||
│ ├── fix-ci.md
|
||||
│ ├── release.md
|
||||
│ ├── rollback.md
|
||||
│ ├── network-change.md
|
||||
│ └── network-recovery.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
### `AGENTS.md`：只做路由与通用约束
|
||||
|
||||
`AGENTS.md` 不应重复流程细节。它只需要规定 Agent 在进行操作类工作前，先查找最具体且适用的 Runbook，并严格遵守其中的步骤、验证、停止和审批要求。
|
||||
|
||||
```markdown
|
||||
# Operational Rules
|
||||
|
||||
Before performing operational work:
|
||||
|
||||
1. Inspect `runbooks/`.
|
||||
2. Select the most specific applicable runbook.
|
||||
3. Follow its steps in order.
|
||||
4. Do not skip verification steps.
|
||||
5. Respect STOP and approval conditions.
|
||||
6. If no runbook applies, diagnose only; do not mutate production state.
|
||||
|
||||
## Routing
|
||||
|
||||
- CI failure → `runbooks/fix-ci.md`
|
||||
- GitHub issue implementation → `runbooks/issue-to-merge.md`
|
||||
- Deployment → `runbooks/release.md`
|
||||
- Rollback → `runbooks/rollback.md`
|
||||
- Network configuration → `runbooks/network-change.md`
|
||||
- Network outage → `runbooks/network-recovery.md`
|
||||
```
|
||||
|
||||
### `RUNBOOKS.md`：仓库级规范
|
||||
|
||||
`RUNBOOKS.md` 用于统一所有 Runbook 的字段、命名、评审要求和变更规则。每份 Runbook 只描述一种可识别的操作意图；如果流程已有明显分叉，应拆分为独立文件，而不是堆叠成长篇“万能流程”。
|
||||
|
||||
## 5. 规范模板
|
||||
|
||||
以下模板可直接保存为 `runbooks/_template.md` 使用。
|
||||
|
||||
```markdown
|
||||
# Runbook: <名称>
|
||||
|
||||
## Purpose
|
||||
说明本 Runbook 要解决的问题及成功结果。
|
||||
|
||||
## Scope
|
||||
- 适用环境：<如 development / staging / production>
|
||||
- 适用对象：<服务、仓库、组件或告警类型>
|
||||
- 不适用情形：<需要改用其他 Runbook 或转人工的场景>
|
||||
|
||||
## Ownership
|
||||
- Owner：<团队或角色>
|
||||
- Last reviewed：<YYYY-MM-DD>
|
||||
- Related systems：<系统名称>
|
||||
|
||||
## Preconditions
|
||||
- <执行前必须满足的权限、备份、窗口、健康状态或已知信息>
|
||||
|
||||
## Inputs
|
||||
| 输入 | 来源 | 是否必需 | 校验方法 |
|
||||
|---|---|---:|---|
|
||||
| <参数> | <来源> | 是/否 | <如何确认有效> |
|
||||
|
||||
## Safety
|
||||
### Non-negotiable rules
|
||||
- 先只读诊断，后执行变更。
|
||||
- 不得把删除现有配置作为首次恢复动作。
|
||||
- 不得猜测或编造缺失参数。
|
||||
- 不得绕过失败的测试、检查或审批。
|
||||
- 每次变更后必须完成对应验证。
|
||||
- 破坏性操作必须获得明确批准。
|
||||
|
||||
### Stop conditions
|
||||
- 实际状态与本文档的前提或预期结果冲突。
|
||||
- 缺少必要输入、权限、审批或回滚能力。
|
||||
- 验证失败且本文档没有明确的下一步。
|
||||
- 影响范围超出 Scope。
|
||||
|
||||
### Approval gates
|
||||
| 动作 | 风险级别 | 是否需要明确批准 | 批准记录位置 |
|
||||
|---|---|---:|---|
|
||||
| <动作> | 低/中/高 | 是/否 | <Issue / PR / 变更单> |
|
||||
|
||||
## Procedure
|
||||
|
||||
### Step 1 — Diagnose
|
||||
|
||||
**Action**
|
||||
|
||||
<执行只读诊断动作。>
|
||||
|
||||
**Expected**
|
||||
|
||||
<列出预期输出、状态或证据。>
|
||||
|
||||
**Decision**
|
||||
|
||||
- 若 <条件 A>，进入 Step 2。
|
||||
- 若 <条件 B>，进入 Troubleshooting A。
|
||||
- 若无法判断或状态冲突，`STOP` 并记录证据。
|
||||
|
||||
### Step 2 — Change
|
||||
|
||||
**Action**
|
||||
|
||||
<描述单一、可审计的变更动作。>
|
||||
|
||||
**Expected**
|
||||
|
||||
<变更后应出现的状态。>
|
||||
|
||||
**Verification**
|
||||
|
||||
<给出可重复执行的验证命令、测试、监控指标或检查清单。>
|
||||
|
||||
**Rollback**
|
||||
|
||||
- 触发条件：<什么情况需要回滚>
|
||||
- 回滚动作：<如何撤销>
|
||||
- 回滚验证：<如何确认恢复成功>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Troubleshooting A — <异常名称>
|
||||
|
||||
- 证据收集：<日志、指标、命令输出、链接>
|
||||
- 允许动作：<仅限已验证且低风险的动作>
|
||||
- 下一步：<回到某步 / 转入另一 Runbook / STOP 并升级>
|
||||
|
||||
## Final Verification
|
||||
|
||||
只有同时满足以下标准，流程才算成功：
|
||||
|
||||
- <功能或服务状态>
|
||||
- <自动化测试或健康检查>
|
||||
- <监控指标或告警状态>
|
||||
- <变更记录、PR 或 Issue 已更新>
|
||||
|
||||
## Failure Handling
|
||||
|
||||
若未能完成：
|
||||
|
||||
1. 停止进一步变更。
|
||||
2. 收集 <命令输出、时间范围、请求 ID、日志链接、截图或复现步骤>。
|
||||
3. 记录已完成步骤、实际结果、未满足的预期和是否执行过回滚。
|
||||
4. 按 <升级渠道> 交接，不继续猜测。
|
||||
|
||||
## References
|
||||
|
||||
- <关联 Issue、PR、架构文档、仪表盘、配置仓库或外部文档>
|
||||
```
|
||||
|
||||
## 6. 编写步骤的标准写法
|
||||
|
||||
每个步骤应只承担一个清晰目的，并使用“动作—预期—决策”的闭环表达。如下表所示，前者会导致 Agent 自主扩大操作范围，后者则为其提供安全边界。
|
||||
|
||||
| 不推荐写法 | 推荐写法 |
|
||||
|---|---|
|
||||
| “检查部署是否正常，不正常就修复。” | “读取部署状态与最近一次发布记录。若所有副本 `Ready` 且版本等于目标版本，进入 Final Verification；若副本未就绪，收集事件与日志并进入 Troubleshooting A；若版本不匹配且原因未知，`STOP`。” |
|
||||
| “必要时修改配置。” | “仅当配置差异与变更单 `CHG-123` 完全一致且审批已记录时，应用指定键的值；应用后运行健康检查；失败则按 Rollback 回退。” |
|
||||
| “测试失败时可先跳过。” | “任何必需测试失败均不得继续部署。记录失败测试、日志和提交版本；仅按 Troubleshooting B 处理。” |
|
||||
|
||||
## 7. 通用安全规则
|
||||
|
||||
以下规则适合在每份 Runbook 的 `Safety` 章节中复用。若某流程存在更严格要求，应以更严格要求为准。
|
||||
|
||||
```markdown
|
||||
## Safety Rules
|
||||
|
||||
- Never delete an existing configuration as the first recovery action.
|
||||
- Prefer read-only diagnosis before mutation.
|
||||
- After every mutation, verify the expected state.
|
||||
- If actual state conflicts with this runbook, STOP.
|
||||
- Do not invent missing parameters.
|
||||
- Do not bypass failed tests.
|
||||
- Destructive actions require explicit approval.
|
||||
```
|
||||
|
||||
这些约束体现了一个关键顺序：**先证据，后变更；先小范围，后扩大；先验证，后结束；不确定则停止。** 特别是停止条件必须可操作，例如“权限不足”“缺少变更单”“生产状态与前提不一致”“错误率超过 1%”等，而不应写成“情况复杂时停止”。
|
||||
|
||||
## 8. 运行与审计流程
|
||||
|
||||
Agent 执行 Runbook 时，应按照固定运行模型工作。每一步的输入、动作、输出和下一跳都应可追踪，这与 AWS 自动化 Runbook 的顺序步骤和输出传递思想一致。[3]
|
||||
|
||||
```text
|
||||
输入与前置条件
|
||||
↓
|
||||
只读诊断
|
||||
↓
|
||||
确认预期状态或决策分支
|
||||
↓
|
||||
获取审批（如需要）
|
||||
↓
|
||||
执行最小变更
|
||||
↓
|
||||
立即验证
|
||||
↓
|
||||
成功收尾 / 回滚 / 停止并升级
|
||||
```
|
||||
|
||||
| 阶段 | Agent 必须产出的证据 | 禁止行为 |
|
||||
|---|---|---|
|
||||
| 输入确认 | 参数来源、环境、目标资源、权限与审批状态 | 用猜测值补全必需参数 |
|
||||
| 诊断 | 命令输出、日志、指标或页面状态 | 在未诊断前直接修改生产状态 |
|
||||
| 变更 | 实际执行内容、变更范围、时间 | 将多个无关变更混在一起执行 |
|
||||
| 验证 | 测试、健康检查、监控状态与预期对比 | 以“命令执行成功”代替业务验证 |
|
||||
| 失败处理 | 已做步骤、异常证据、回滚状态和升级对象 | 无限制重试或绕过失败检查 |
|
||||
|
||||
## 9. 从人工操作到自动化的成熟路径
|
||||
|
||||
不建议在流程尚未稳定时先构建复杂 DSL 或全自动编排。应先积累真实案例，把可重复部分固化为 Markdown Runbook，再把已稳定、低歧义、可验证的操作迁移到脚本、CI、Skill 或自动化系统。Google SRE 将能够由机器替代的重复性人工工作视为应逐步消除的 toil。[4]
|
||||
|
||||
| 阶段 | 主要形式 | 人的角色 | 自动化边界 |
|
||||
|---|---|---|---|
|
||||
| 1. 人工处理 | 现场处置与复盘 | 执行、判断、记录 | 不自动化 |
|
||||
| 2. Markdown Runbook | 固化步骤与证据要求 | 审核流程与异常判断 | Agent 可辅助诊断 |
|
||||
| 3. Agent + Runbook | 严格按流程执行 | 审批高风险动作、处理例外 | 受停止条件约束的执行 |
|
||||
| 4. Script / Skill / CI / Automation | 把稳定步骤程序化 | 处理异常和维护自动化 | 自动完成重复性操作 |
|
||||
| 5. 人工审批 + 自动执行 | 常规流程端到端运行 | 决策、审计与治理 | 审批门控下的自动变更 |
|
||||
|
||||
## 10. 上线前检查清单
|
||||
|
||||
在将一份新 Runbook 交给 Agent 使用前，建议由流程所有者按以下清单审核。
|
||||
|
||||
| 检查项 | 合格标准 |
|
||||
|---|---|
|
||||
| 问题边界 | Purpose 与 Scope 清楚描述适用和不适用情形 |
|
||||
| 输入 | 所有必需输入都有来源、格式和校验方法 |
|
||||
| 步骤 | 每一步均有 Action、Expected 与明确的下一跳 |
|
||||
| 变更控制 | 所有修改动作都有 Verification；关键动作有 Rollback |
|
||||
| 安全控制 | Stop conditions、审批门槛和禁止行为已列明 |
|
||||
| 异常处理 | 失败时知道收集什么证据、交给谁，而非继续猜测 |
|
||||
| 可维护性 | 有 Owner、最近复审日期与关联文档；已在版本控制中评审 |
|
||||
| 可演练性 | 已在安全环境或历史案例上走通至少一次 |
|
||||
|
||||
## 11. 建议的首批 Runbook
|
||||
|
||||
首次落地时，应优先选择频率较高、输入相对明确、变更可回退的场景。以下集合通常能覆盖大部分工程协作的基础需求。
|
||||
|
||||
| Runbook | 目的 | 关键安全控制 |
|
||||
|---|---|---|
|
||||
| `issue-to-merge.md` | 从已明确 Issue 到可评审变更 | Scope 锁定、测试门槛、PR 证据 |
|
||||
| `fix-ci.md` | 诊断并修复 CI 失败 | 不跳过测试、不修改无关代码 |
|
||||
| `release.md` | 执行标准发布 | 发布窗口、审批、健康检查、回滚点 |
|
||||
| `rollback.md` | 恢复到已知稳定版本 | 明确触发条件、版本选择、回滚后验证 |
|
||||
| `network-change.md` | 实施受控网络配置变更 | 影响评估、变更单、回退配置 |
|
||||
| `network-recovery.md` | 处理网络异常与服务恢复 | 只读诊断优先、状态冲突即停止 |
|
||||
|
||||
## 12. 结论
|
||||
|
||||
Agent Runbook 的价值不在于把每一项运维工作立即自动化，而在于将团队的工程判断编码为**可路由、可验证、可停止、可回滚**的操作系统。对于多数团队，从仓库中的 `AGENTS.md`、`RUNBOOKS.md` 和一组 Markdown Runbook 起步，已经足够实用。
|
||||
|
||||
当某个流程经过多次执行、输入稳定、异常分支收敛且验证可靠后，再将其下沉为脚本、CI 或其他自动化能力。这样既能逐步降低重复性 toil，也能始终保留人类对高风险和例外情形的决策权。[4]
|
||||
|
||||
## References
|
||||
|
||||
[1]: https://sre.google/sre-book/managing-incidents/ "Google SRE Book — Managing Incidents"
|
||||
[2]: https://sre.google/sre-book/effective-troubleshooting/ "Google SRE Book — Effective Troubleshooting"
|
||||
[3]: https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-documents.html "AWS Systems Manager — Creating your own runbooks"
|
||||
[4]: https://sre.google/sre-book/eliminating-toil/ "Google SRE Book — Eliminating Toil"
|
||||
[5]: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-automation.html "AWS Systems Manager Automation"
|
||||
[6]: https://docs.aws.amazon.com/systems-manager-automation-runbooks/latest/userguide/automation-runbook-reference.html "AWS Systems Manager Automation Runbook Reference"
|
||||
[7]: https://learn.microsoft.com/en-us/azure/automation/manage-runbooks "Microsoft Learn — Manage runbooks in Azure Automation"
|
||||
|
||||
---
|
||||
|
||||
**来源**：Manus AI《Agent Runbook 实用指南（v1.0）》，本仓库存档为规范参考。
|
||||
Reference in New Issue
Block a user