vps/RUNBOOKS.md

RUNBOOKS — 仓库级规范

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

目录结构

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 或正文中复用以下通用安全规则（更严格要求优先）。

## 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 + 确认变量）。

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