# RUNBOOKS — 仓库级规范

本文件统一所有 Runbook 的字段、命名、评审与变更规则。上游参考：[docs/archive/agent-runbook-guide.md](docs/archive/agent-runbook-guide.md)。

## 目录结构

```text
runbooks/
├── README.md                 # 意图 → 文件 路由索引（本目录的入口）
├── _template.md              # 新建 runbook 的标准模板（复制后填写）
├── <intent>.md               # 每份 runbook 只描述一种可识别的操作意图
└── ...
```

## 最小字段模型

每份 runbook 必须显式包含以下控制信息，否则盲目执行或错误恢复的风险会升高：

| 字段 | 作用 | 写作要求 |
|---|---|---|
| **Action** | 定义当前要执行的动作 | 可观察、可执行的动词；避免“检查一下”“适当调整” |
| **Expected** | 描述正常状态或预期输出 | 具体信号、阈值、状态码、测试结果或页面表现 |
| **Decision** | 定义分支与下一跳 | “条件 → 下一步”；无法判断时指向 `STOP` |
| **Verification** | 确认变更真正生效 | 每个有副作用的步骤后执行，不可跳过 |
| **Stop condition** | 规定何时不得继续 | 列出信息缺失、状态冲突、权限不足、验证失败等 |
| **Rollback** | 如何恢复到变更前状态 | 触发条件、前提、撤销步骤、回滚后验证 |

> 只读类 runbook 不产生副作用，可省略 Rollback；但必须保留 Stop condition（状态与预期冲突即 `STOP` 并记录证据）。

**只读类变体（read-only variant）**：只读 runbook（health 类、参考类）不强制
六字段模型，但必须包含以下最小结构，否则不视为达标：

- `## Purpose`（1–2 行）+ `## Scope`（适用/不适用）
- `## Safety` 或等效章节，其中**必须**含显式 Stop condition（状态与预期冲突即
  `STOP` 并记录证据；不得在执行中自行"顺手修复"）
- 只读健康类另含可观察的 `## Pass criteria`（或等效的 Expected 信号）
- 每份 runbook 顶部/元信息区必须标注 `Last reviewed: <YYYY-MM-DD>`

## 命名与拆分规则

- 文件名采用小写连字符，反映**操作意图**而非目标主机，例如 `mailcow-health.md`、`release.md`。
- 一份文件只描述一种意图。流程出现明显分叉时拆分为独立文件，不堆叠“万能流程”。
- 只读诊断与变更操作应分离：health 类 runbook 保持只读，变更走 `ansible-operations.md`、`release.md`、`rollback.md` 或对应 gated playbook。

## 章节约定

- 每份 runbook 顶部含 `## Purpose`（1–2 行）与 `## Scope`（适用/不适用情形）。
- 变更型 runbook 额外含 `## Approval gates` 表；破坏性/不可逆操作必须获得明确批准。
- 语言约定：**runbook 正文统一使用英文**（由 agent 逐字执行，降低二义性）；
  元规范文件（AGENTS.md / RUNBOOKS.md / 模板注释）可保留中文。
- 变更型 runbook 的两种形态：
  - **流程式（Procedure 型）**：使用六字段模型，适用多分支/多步骤变更
    （现有：`fix-ci.md`、`issue-to-merge.md`、`network-change.md`、
    `network-recovery.md`、`release.md`、`rollback.md`）。
  - **门控命令式（gated command reference）**：已稳定、低歧义、可验证的
    操作以命令集 + 门控呈现（现有：`mailcow-update.md`、
    `ansible-operations.md`、`home-assistant-maintenance.md`、
    `vaultwarden-sqlite-to-postgres.md`），必须含 Approval gates 或确认变量
    要求 + 显式 STOP，不替代流程式形态。新写的变更 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.
```

## 评审与变更规则

- 新建/修改 runbook 与代码同仓评审，随系统演进更新。
- 每份 runbook 标注 `Last reviewed`；流程执行过程中发现的偏差记入对应的 Linear `vps` 项目 issue。
- 破坏性流程（迁移、删除、DNS 变更、网络变更）保持人工审批，不自动下沉。

## 成熟路径

1. **人工处理** → 现场处置与复盘，记录证据。
2. **Markdown runbook** → 固化步骤与证据要求，Agent 可辅助诊断。
3. **Agent + runbook** → 严格按流程执行，受 Stop/Approval 约束。
4. **Script / Ansible / Skill** → 把已稳定、低歧义、可验证的操作程序化（本仓库的执行层是 Ansible playbook）。
5. **人工审批 + 自动执行** → 审批门控下的自动变更（如 gated playbook + 确认变量）。

原则：先证据后变更，先小范围后扩大，先验证后结束，不确定则停止。