vps/docs/archive/agent-runbook-guide.md

# 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）》，本仓库存档为规范参考。