runbook-generator

Runbook 生成器

分析代码库，并生成可用于生产环境的操作手册，其中包含可复制粘贴的命令、每个步骤后的验证检查、每项破坏性操作的回滚流程、附带联系信息的升级路径，以及用于容量规划的时间估算。检测技术栈（CI/CD、数据库、托管平台、容器），并生成针对实际基础设施的操作手册。包含过时检测功能，在所引用的配置文件发生变化时标记操作手册。

**关键词：**操作手册、运维流程、事件响应、部署、回滚、数据库维护、扩缩容、监控、值班、SRE、事后复盘

核心能力

• 技术栈检测 — 从仓库文件中识别 CI/CD 平台、数据库、托管平台和编排工具；匹配操作手册模板；提取连接字符串、部署命令和基础设施详情。
• 操作手册类型 — 部署（预检查、部署、冒烟测试、回滚）、事件响应（分诊→诊断→缓解→解决→事后复盘）、数据库维护（备份、迁移、清理、重建索引）、扩缩容（水平/垂直），以及监控（告警、仪表板、值班轮换）。
• 格式规范 — 使用编号步骤和可复制粘贴的命令；每个步骤后都必须有验证检查；提供时间估算、每项破坏性操作的回滚流程，以及包含决策标准的升级路径。
• 维护 — 根据配置文件修改日期检测过时情况，按季度进行审查，并提供暂存环境中的试运行验证框架。

适用场景

• 代码库没有操作手册，需要从零开始搭建。
• 现有操作手册已过时或不完整。
• 为新工程师加入值班轮换做准备。
• 准备进行事件响应演练。
• 事件后的改进：根据经验教训更新操作手册。

先澄清

生成操作手册前，请确认以下信息。如果有任何信息未知或含糊不清，请先询问，不要自行假设：

• 操作手册类型 — 部署 / 事件响应 / 数据库维护 / 扩缩容 / 监控（决定模板和步骤结构）
• 实际技术栈 — CI/CD 平台、数据库、托管平台和编排工具（所有可复制粘贴的命令和回滚步骤都因技术栈而异）
• 升级联系人及严重级别路由 — 各级别下通知哪些人（用于填写升级表；缺少此信息的操作手册无法用于值班）

停止规则：只询问对输出影响最大的 2–3 项。如果用户说“直接起草”，则继续，并在文档顶部列出你的假设。

工具

工具	用途	命令
runbook_scaffolder.py	根据 JSON 服务定义生成操作手册 Markdown 模板	python scripts/runbook_scaffolder.py -i service.json --type deployment -o runbook.md
runbook_validator.py	检查操作手册 Markdown 的完整性和质量（必需章节、VERIFY 块、硬编码凭据、升级表）	python scripts/runbook_validator.py --dir docs/runbooks --strict
staleness_checker.py	根据可配置的过时阈值检查操作手册的新鲜度	python scripts/staleness_checker.py docs/runbooks --threshold 90 --json

参考资料

加载与任务匹配的参考资料——保持本文件精简，按需获取详细信息：

• references/runbook-templates.md — 用于检测技术栈的 shell 命令，以及完整的部署、事件响应和数据库维护操作手册模板，其中包含可复制粘贴的命令、VERIFY 块、回滚和升级表。扫描代码库或编写操作手册时阅读。
• references/staleness-and-maintenance.md — 过时检测 CI 脚本和季度审查的 7 个步骤。自动化新鲜度检查或进行季度审查时阅读。
• references/quality-and-troubleshooting.md — 常见问题、最佳实践清单、故障排查表和成功标准。发布操作手册前阅读。

范围与限制

此技能涵盖：

• 根据代码库分析生成部署、事件响应、数据库维护、扩缩容和监控操作手册
• 检测常见 CI/CD 平台（GitHub Actions、GitLab CI、Jenkins）、数据库（PostgreSQL、MySQL、MongoDB）和托管服务提供商（Vercel、Fly.io、Kubernetes、AWS）的技术栈
• 过时检测自动化和季度审查流程
• 基于严重程度进行路由的升级路径模板

此技能不涵盖：

• 自动执行操作手册步骤——它生成文档，而非编排（自动化流水线请参阅 ci-cd-pipeline-builder）
• 基础设施预配或 Terraform/Pulumi 代码生成（架构迁移工具请参阅 migration-architect）
• Prometheus 规则、Grafana 仪表板或告警定义等可观测性技术栈的设置（监控基础设施请参阅 observability-designer）
• 安全事件响应或漏洞修复手册（安全相关分析请参阅 skill-security-auditor）

集成点

技能	集成方式	数据流
ci-cd-pipeline-builder	操作手册中的部署步骤与流水线阶段保持一致	流水线配置用于生成部署操作手册；操作手册中的回滚步骤会引用流水线回滚触发条件
observability-designer	监控操作手册会引用告警规则和仪表板	可观测性输出（告警名称、仪表板 URL）会嵌入操作手册的 VERIFY 和 Monitor 步骤
migration-architect	数据库维护操作手册采用迁移工具的约定	迁移文件路径和命令会流入数据库操作手册模板；回滚步骤与迁移回滚命令保持一致
release-manager	发布流程会触发操作手册执行检查点	发布标签和变更日志会用于操作手册过时检查；发布门禁会引用操作手册的部署前检查清单
env-secrets-manager	操作手册中的命令会引用由密钥工具管理的环境变量	密钥名称和保管库路径会流入操作手册的环境变量引用；轮换计划会影响操作手册的更新频率
changelog-generator	部署后的操作手册步骤会交叉引用变更日志条目	变更日志差异有助于确定发布后需要重新验证哪些操作手册步骤