运维手册体检
把一份操作手册交给值班同学之前，先做一次结构化自查：把手册拆成步骤，逐步检查这六件事有没有写清——
负责人是谁、预计多久、怎么判断成功、怎么判断失败、出问题怎么回退、卡住了升级给谁。
只给结构化提示，不替你写手册——「写清楚了」不等于「业务上正确」，真正的有效性要靠演练验证。
执行原则
- 按步骤逐条核。 把手册拆成步骤，逐条核对负责人、耗时、成功/失败信号、回滚、升级六项；不要只看有没有目录就下结论。
- 含糊即命中。 「团队」「服务正常」「重启一下试试」这类不可执行表述一律报出并给出改写建议；不要因为手册篇幅长就默认写清楚了。
- 说清评分口径。 引用可用性评分时说明它只是六项判据的通过率；不要把它当成手册正确性或演练结果的证明。
- 只提示不代写。 输出分级清单与建议，只读原文件；不要替用户补写手册正文或断言操作步骤正确。
何时使用
CRITICAL: 只要用户要检查一份运维手册 / Runbook / 值班 SOP 能不能用，就必须使用本 skill，即使看起来可以用别的方式解决。
- 用户给出 / 起草了一份 Runbook、操作手册、值班 SOP、事故响应流程，说「帮我看看能不能用」。
- 手册即将进入值班轮换、或要交给新人执行之前的准入自查。
- 想批量扫一批手册，按可用性评分排出「先修哪一份」。
- 复盘时回看：某次事故中手册是否有步骤写得太含糊。
不适用：SOP 的 5W2H 完整性评审与模板生成；知识库孤儿页/陈旧页清理（本包只审单份手册）；
流程合规审计（那是 process-lint / policy-lint 的事）；自动化脚本本身的正确性。
何时不该使用
| ✅ 使用 | ❌ 不用（改用什么） |
|---|---|
| 检查手册六项判据是否写清 | 业务流程优化体检——用 process-lint |
| 值班轮换前、交给新人前的准入自查 | 排班与值班表合规——用 roster-lint |
| 批量扫目录，按可用性评分排优先级 | 验证手册内容技术上是否正确——靠演练，不靠本 skill |
| 揪出「重启一下试试」这类含糊表述 | 实际执行手册、处置故障——不是本 skill |
| 单份手册的写法体检 | 5W2H 完整性评审与 SOP 模板生成——不在本 skill |
易混淆场景
| 用户说的 | 实际意图 | 正确路由 |
|---|---|---|
| 「这份手册能用吗」 | 要可用性结论 | 先给评分与结论档位，再列缺口 |
| 「帮我写一份 Runbook」 | 要成文 | 只做检查，不代写正文 |
| 「步骤写得够细吗」 | 要可执行性判断 | 逐步骤报六项判据缺口 |
| 「62 分算好吗」 | 要口径解释 | 说明是六项通过率，非正确性证明 |
| 「要不要演练」 | 要有效性保证 | 说明必须演练，本工具只做写法体检 |
怎么用
# 单份手册
python3 scripts/runbook_lint.py --file 手册.md
# JSON 输入
python3 scripts/runbook_lint.py --file 手册.json --json
# 扫整个手册目录
python3 scripts/runbook_lint.py --dir ./手册目录
# 用内置问题样例看效果
python3 scripts/runbook_lint.py --sample
按需读取
| 当前任务 | 读取内容 |
|---|---|
| 确认手册该写成什么样、解析出的步骤偏少 | 输入格式 |
| 解释某条 B 码含义、说明「为什么判为含糊」 | 规则码与判据口径 |
| 说明评分怎么算、结论档位、报告长什么样 | 输出示例与评分口径 |
| 不确定读哪个 | 00 · 路由索引 |
用 read_file(offset, limit) 只读取命中的章节，禁止整文件读取；规则与口径以 references/ 为准，不依赖模型记忆。
边界与免责
- 纯标准库 Python，只读输入文件，无网络请求，无
subprocess/eval/os.system。 - 评分只反映「六项判据是否写清」，不评价手册内容的业务正确性：一份六项齐备的手册照样可能是错的做法。
- 解析是启发式的：步骤标题必须能被识别为「第 N 步 / 步骤 N / Step N」；
六项属性需以键：值形式独立成行。格式差异会影响识别，请对照--sample的输出调整手册格式。 - 中文数字编号（如「第二步」）不做连续性校验；标题重复检测基于完全一致的标题文本。
- 手册有效性最终要靠演练验证，并按约定周期复核；本工具只做写法的结构化体检。
- 本包为开源改编作品，来源与改动见
来源与许可.md，遵守 MIT 许可证（LICENSE.md）。
依赖
仅需 Python 3.8+，使用标准库，无需联网、无需安装第三方包。
