知识运营

knowledge-ops

面向运营负责人 / 知识库管理员 / 内部 TPM 的公司 SOP + 内部运行手册编写、5W2H 完整性验证及 KB 健康度报告工具。

目的

一个运营组织在运行三年后通常会积累大量碎片化信息：600 个 Notion 页面、200 个 Confluence 运行手册、三个 Obsidian 库、一个 Drive/SOPs/ 文件夹，以及一个因为没人能找到权威文档而存在的 Slack #ops-questions 频道。常见的失效模式包括：

1. 缺乏负责人 —— 40% 的 SOP 将负责人写成“团队”而非具体个人。当文档过时时，无人负责。
2. 缺乏最后审核日期 —— 一年前的供应商离职 SOP 仍在使用一年多前就已停用的采购工具。
3. 成功信号模糊 —— 运行手册第 4 步写着“验证服务已启动”。新操作员无法判断这意味着什么。
4. 缺乏回滚路径 —— 事故沟通级联运行手册告诉如何发送警报，但没告诉在警报错误时如何撤回。
5. 孤立页面 —— 知识库中有一半页面没有入站链接。没人能通过导航找到它们，仅靠记得 URL 的人才能访问。
6. 术语漂移 —— “CSM”在三份文档中指客户成功经理 (Customer Success Manager)，在另外五份中指客户解决方案经理 (Customer Solutions Manager)。新员工在半年内一直猜错。
7. 仅覆盖理想路径的 SOP —— 文档只涵盖一切正常的情况，而忽略了 30% 的异常情况。

本技能旨在回答操作员最关心的问题：“我应该优先修复哪 20 份文档，每份文档具体出了什么问题？” —— 且基于确定性的逻辑而非直觉。

使用场景

• 为跨职能公司流程编写新 SOP（如采购申请、供应商离职、事故沟通级联、员工入职、费用报销、客户升级剧本、安全事故沟通、系统权限配置）。

• 在内部运行手册投入使用前进行验证（确保每一步都有明确的负责人、预期时长、可观测的成功信号、可观测的失败信号、回滚路径和升级联系人）。

• 导入多文档 KB 导出文件（Notion zip、Confluence 空间导出、Obsidian 库、Drive/SOPs/ 目录）并揭示问题：孤立页面、陈旧页面（超过 12 个月未编辑）、术语漂移、缺失负责人页面、失效的交叉链接。

• 为新入职的运维人员生成其在第一周需要阅读的 SOP 和运维手册页面，完成入职引导。

• Wiki 清理冲刺 —— 每季度进行一次卫生维护，由组织决定将哪些 30 份文档进行存档、重写或合并。

工作流

四步确定性流程（匹配运维组织的实际工作流，而非抽象过程）：

1. 知识库摄取 (Ingest KB)。 对现有的 Wiki 导出文件运行 kb_ingester.py --input <vault-dir>。输出为一份 Markdown 健康报告：包含孤立页面、陈旧页面、术语漂移、缺失所有者的页面、交叉链接图谱以及优先级清理列表。报告会列出前 20 个优先修复的文档 —— 通常是高流量的陈旧文档和涉及合规性但缺失所有者的文档。将此列表带入清理冲刺。
2. 验证现有 Runbook。 对于清理列表中的每个 Runbook（或任何在投入轮转前的新 Runbook），运行 runbook_validator.py --input <runbook.md>。验证器将根据六项检查（指定所有者、预期时长、可观测的成功信号、可观测的失败信号、回滚路径、升级联系人）对每一步进行评分，并生成每步的红绿灯状态 + 0-100 的整体有效性得分 + 必须修复 (MUST-FIX) 的问题列表。得分 < 60 的 Runbook 在事故处理中被视为不安全。
3. 生成缺失的 SOP。 对于需要从零开始编写（或因现有版本无法挽救而需要重写）的 SOP，运行 sop_generator.py --input <metadata.json> --profile <ops|support|finance|hr|it|regulated>。输出是一个 5W2H 结构的 SOP 骨架：Who (RACI)、What (流程步骤)、When (触发条件 + 频率)、Where (系统 + 工具)、Why (目的 + 监管依据)、How (分步操作)、How-much (单次执行成本 + 时间)。regulated 配置文件会增加版本控制、签核和审计追踪章节（符合 ISO 9001 / FDA 21 CFR Part 211 / SOC 2 / HIPAA）。
4. 交叉链接 + 闭环。 在清理冲刺后重新运行 kb_ingester.py，以验证孤立页面数量是否下降且术语漂移是否得到解决。核心指标是 “无法找到的文档” (orphans) 和 “不安全的 Runbook” (有效性得分 < 60)，而非页面总数。

脚本

scripts/sop_generator.py —— 读取描述 SOP 的 JSON 元数据文件（流程所有者、触发事件、受众角色、频率、监管覆盖、输入、输出、步骤大纲），并输出一份完整的 5W2H 结构 Markdown SOP（或标准化 JSON）。--profile 标志用于调整输出：ops（通用内部运维）、support（客户支持 Runbook 风格）、finance（侧重控制 + 对账）、hr（敏感数据标记）、it（侧重系统 + 权限）、regulated（增加版本控制、签核矩阵、审计追踪）。监管覆盖项（SOC2, HIPAA, ISO13485, GDPR, SOX）会附加相应的合规前言。--sample 将打印一个完整的供应商离职 SOP 示例。仅使用标准库。

scripts/runbook_validator.py —— 读取 Runbook（Markdown 文件或 JSON），并根据六个必要属性验证每一步：(1) 指定所有者（不能是“团队”或“运维”），(2) 预期时长（具体数字 + 单位），(3) 可观测的成功信号（例如 “/healthz 返回 HTTP 200” —— 而非 “服务已启动”），(4) 可观测的失败信号，(5) 回滚路径（或明确标注 “此步骤无法回滚，请升级至 X”），(6) 升级联系人（具体人员或指定的 On-call 轮值人员）。输出为每步的红绿灯状态 (GREEN/AMBER/RED)、0-100 的整体有效性得分以及必须修复 (MUST-FIX) 的问题列表。判定标准：≥ 80 = 安全使用 (SAFE-TO-USE)，60-79 = 谨慎使用 (USE-WITH-CAUTION)，< 60 = 不安全 (N...
OT-SAFE。--sample 会打印一份故意损坏的事件沟通运行手册（runbook），用于演示故障检测。仅使用标准库。

scripts/kb_ingester.py — 遍历 Markdown 文件目录（Notion 导出、Confluence 空间导出、Obsidian 库、Drive/SOPs/ 目录）。提取以下内容：(a) 交叉链接映射（通过 Markdown link 语法识别页面间的引用关系）；(b) 术语表候选词（在 3 个以上文档中出现但缺乏统一定义页面的常用专有名词和缩写）；(c) 孤立页面（库中没有任何入站链接的页面）；(d) 术语漂移（同一术语在不同文档中的定义或用法不一致，例如 "CSM" 在两处有不同的展开定义）；(e) 过时页面（超过 12 个月未编辑，通过文件系统 mtime 或 YAML last_reviewed 前置元数据检测）；(f) 缺失所有者的页面（前置元数据中无 owner: 字段）。输出一份 KB 健康报告 Markdown，其中包含一份优先级最高的 Top-20 清理清单，按 过时程度 × 入站链接数 排序（高流量的过时文档优先）。--sample 会在临时目录中构建一个包含 8 个页面的微型合成库并运行完整流水线。仅使用标准库。

快速示例

# 构建一个 8 页的合成库并输出 KB 健康报告（孤立页、过时页、术语漂移、Top-20 清理清单）
cd business-operations/skills/knowledge-ops && python3 scripts/kb_ingester.py --sample

参考资料

• references/5w2h_sop_canon.md — 石川馨的 5W2H 法、丰田标准作业规范、Atul Gawande 的《清单革命》、Atlassian Confluence SOP 指南、ISO 9001 SOP 要求、ITIL v4 服务运营、FDA 21 CFR Part 211。涵盖 SOP 编写准则的 8 个引用来源。

• references/runbook_canon.md — Google SRE Workbook（运行手册章节）、Atlassian 事件管理运行手册、PagerDuty 事件响应分类法、AWS Well-Architected 卓越运营支柱、Charity Majors 关于可观测性与运行手册集成、Susan Fowler 关于生产就绪微服务、ITIL v4 运营。涵盖运行手册设计准则的 7 个引用来源。

• references/kb_hygiene_anti_patterns.md — 汲取自 Notion/Confluence Wiki 行业研究、Mozilla SUMO 知识库经验、Stack Overflow 社区管理研究、Atlassian Team Playbook、MIT TIK 组织 Wiki 研究、Cynthia Lee 关于术语漂移以及 Adam Wiggins 关于“文档腐烂”的 8 种反模式。

假设条件

1. KB 为 Markdown 格式（或可导出为 Markdown —— Notion, Confluence, Obsidian 和 Google Docs 均支持）。仅限 HTML 或 PDF 的 KB 需要先进行转换；这不在本范围之内。
2. 用户有权委派重写或存档工作。产生一份无人执行的清理清单是浪费时间 —— 在运行 ingester 之前，请将发现的问题路由至指定的负责人。
3. 所有者元数据位于 YAML 前置元数据 (owner: [email protected]) 或页面顶部的 "Owner:" 行中。基于“口头传承”的所有权（最后编辑该页面的人员）被视为缺失。
4. “过时”默认定义为 12 个月。可通过 kb_ingester.py 的 --stale-days 参数覆盖。某些合规体系（FDA, ISO 13485）要求更短的审核周期；请使用 --profile regulated 和 --stale-days 365。
5. 用户要求的不是个人 PKM。Karpathy 风格的个人“第二大脑”工作应归入 engineering/llm-wiki。

反模式

• 在没有所有者的情况下批量生成 SOP。 没有所有者的文档半衰期仅为 6 个月。除非每个 SOP 都分配给了具体的人员，否则拒绝批量生成 30 份 SOP。

• 使用...

• 将 runbook_validator.py 视为勾选框。 该验证器仅能检测结构缺失，无法检测内容错误。一份 Runbook 即使得分为 100 分，仍可能向操作员提供错误指令。

• 默认将孤立页面（orphan pages）视为垃圾。 部分孤立页面是仅通过搜索才能找到的参考页，并非所有孤立页面都应归档。清理列表是*优先级队列*，而非删除列表。

• 混淆 Knowledge-ops 与 process-mapper。 Process-mapper 记录的是阶段之间的工作*流*（BPMN、周期时间、瓶颈）。Knowledge-ops 记录的是操作员执行工作时消耗的*交付物*（SOP、Runbook、术语表）。两者可同时应用于同一流程。

• 任由术语漂移（glossary drift）累积。 三年内出现两个“CSM”定义，五年内就会变成七个。一旦 kb_ingester.py 的输出中出现术语漂移，应立即修复。

• 在受监管的工作负载下跳过受监管配置文件（regulated profile）。 如果流程涉及 PHI、与 SOX 相关的财务控制或 ISO 13485 设备 QMS，请使用 --profile regulated。受监管的 SOP 缺失版本控制将被视为审计缺陷。

• 凭记忆手写 5W2H 章节。 建立 5W2H 框架是因为操作员经常忘记“How-much（多少/程度）”。请使用生成器，然后编辑输出结果。

区别于

• engineering/llm-wiki —— Karpathy 风格的个人 PKM 第二大脑，由一个人将资料摄入到自己的互联知识库中。Knowledge-ops 是*组织级*的：多作者、多读者、文档有明确负责人、有正式评审周期以及合规覆盖。

• engineering-team/runbook-generator —— 用于调试生产系统（日志、告警、k8s、值班）的系统运维 Runbook。Knowledge-ops Runbook 是用于业务流程的*操作员* Runbook（如：事件沟通级联、供应商离职办理、员工入职）。受众是同行操作员，而非追踪日志的工程师。

• **project-management/*** —— Jira / Confluence 的交付跟踪、Sprint 票据工作流、项目状态报告。Knowledge-ops 是这些 Confluence 页面中的*内容*，而非对谁编辑了页面的*跟踪*。

• business-operations/process-mapper（兄弟项目） —— BPMN 流程*设计*：阶段分布、工作等待点、哪个阶段是瓶颈。Knowledge-ops 是流程*文档化*：即告诉操作员如何执行 mapper 所描述流程的 SOP 和 Runbook 交付物。

• business-operations/internal-comms（兄弟项目） —— 广播公告、全员会议消息、变更管理沟通。Knowledge-ops 是持久的参考交付物；internal-comms 是广播。

• **ra-qm-team/* —— 正式的监管合规撰写（ISO 13485 QMS、MDR 技术文件、21 CFR Part 820）。Knowledge-ops 借鉴了监管清单，但不能替代公告机构（notified-body）的审计。

在调用工具之前，编排器（或 /cs:grill-bizops）需引导用户逐一回答以下问题，每次仅限一个，并提供建议答案 + 权威引用。严禁打包提问。采用深度优先引导 —— 在问题 1-3 确定之前，不得开启问题 4。

1. “这份 SOP / Runbook 的指定负责人是谁？他们是否知道自己是负责人？”**
建议答案：一名具体的人（而非“团队”），且对方已书面同意。
权威引用：Gawande 2009 (*The Checklist Manifesto*) —— 没有负责人的清单在 12 个月内就会失效。所有权即是纪律。

2. “这份文档上次评审是什么时候？评审频率是多少？”
建议答案：已评审...
过去 12 个月内（若使用 --profile regulated 则为 90 天）；频率记录在 frontmatter 中。
标准依据：ISO 9001:2015 §7.5.3 —— 受控文档需要评审周期元数据。ITIL v4 在服务运行手册（runbooks）中也强调了这一点。

3. “对于每个运行手册步骤：可观测的成功信号是什么 —— 即，什么样的具体输出能证明该步骤已生效？”
建议：提供具体的观测值（如“/healthz 返回 HTTP 200”、“Slack 线程被标记为 done 反应”、“Salesforce 机会状态变更为 Closed-Won”），而非“服务已启动”或“运行正常”等模糊描述。
标准依据：Beyer 等人 2018 (*Site Reliability Workbook*, 第 8 章) —— 可观测信号是运行手册的核心。模糊的成功标准是事故期间误用运行手册的主要原因。

4. “对于每个可能失败的运行手册步骤，回滚路径是什么？”
建议：每个会改变状态的步骤必须具备回滚路径，或明确标注“无法回滚 —— 请升级至 X”。
标准依据：AWS Well-Architected Framework（卓越运营支柱）—— “在未定义‘回滚’含义之前，你无法运行一个不可逆的流程”。

5. “此文档存储在哪里，还有哪些文档链接到它？”
建议：存储在权威 Wiki 中，且至少有 2 个相关文档的入站链接。孤立的 SOP 等同于无法被找到的 SOP。
标准依据：Atlassian Team Playbook 关于文档健康度的定义 —— 孤立率 > 20% 是 Wiki 碎片化问题的领先指标。

6. “此流程涉及哪些监管要求 —— SOC 2, HIPAA, ISO 13485, GDPR, SOX，还是无？”
建议：给出明确回答。若为“无”，请通过检查流程涉及的数据类别进行确认。
标准依据：FDA 21 CFR Part 211.100（书面程序；偏差）—— 受监管的 SOP 需要版本控制、变更历史和签核。忽略此步骤将导致审计缺陷。

7. “文档中是否仅记录了‘理想路径’（happy path），还是也记录了 2-3 种最常见的失败模式？”
建议：每个流程的前两种主要失败模式都应记录，并附带相应的恢复子程序。
标准依据：Fowler 2016 (*Production-Ready Microservices*) —— 仅涵盖理想路径的运维文档导致了 60% 以上的事故处理时间浪费。

在确认上述 7 项后，依次调用 kb_ingester.py $\rightarrow$ runbook_validator.py $\rightarrow$ sop_generator.py。