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
2026-08-17 15:59:46 +08:00
parent 047ac03346
commit b0c01b2551
21 changed files with 1140 additions and 2 deletions
+68
View File
@@ -0,0 +1,68 @@
# RUNBOOKS — 仓库级规范
本文件统一所有 Runbook 的字段、命名、评审与变更规则。上游参考:[docs/agent-runbook-guide.md](docs/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` 并记录证据)。
## 命名与拆分规则
- 文件名采用小写连字符,反映**操作意图**而非目标主机,例如 `mailcow-health.md``release.md`
- 一份文件只描述一种意图。流程出现明显分叉时拆分为独立文件,不堆叠“万能流程”。
- 只读诊断与变更操作应分离:health 类 runbook 保持只读,变更走 `ansible-operations.md``release.md``rollback.md` 或对应 gated playbook。
## 章节约定
- 每份 runbook 顶部含 `## Purpose`12 行)与 `## Scope`(适用/不适用情形)。
- 变更型 runbook 额外含 `## Approval gates` 表;破坏性/不可逆操作必须获得明确批准。
- 统一在 `## 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 + 确认变量)。
原则:先证据后变更,先小范围后扩大,先验证后结束,不确定则停止。