knowledge-ops

knowledge-ops

面向运营负责人 / 知识管理者 / 内部 TPM 等角色，用于编写公司 SOP 和内部操作手册、验证 5W2H 完整性，以及生成知识库卫生报告。

用途

运营组织发展三年后，知识资料往往杂乱无章：600 个 Notion 页面、200 份 Confluence 操作手册、三个 Obsidian 知识库、一个 Drive/SOPs/ 文件夹，以及一个 Slack #ops-questions 频道——之所以存在这个频道，是因为没人能找到规范文档。常见的问题包括：

1. 没有负责人 — 40% 的 SOP 写的是“团队”而不是具体人员。文档过时后，没人负责。
2. 没有最近审核日期 — 一份多年前编写的供应商退出 SOP 仍引用着一款一年前就已停用的采购工具。
3. 成功信号模糊 — 操作手册第 4 步写着“确认服务正常”。新操作人员不知道这具体意味着什么。
4. 没有回滚方案 — 事件沟通级联操作手册会告诉你如何发送警报，却没说警报有误时如何撤回。
5. 孤立页面 — 知识库中有一半没有任何入站链接。没人能通过导航找到它们；它们之所以还存在，只是因为有人知道网址。
6. 术语表不一致 — “CSM”在三份文档中指客户成功经理，在另外五份中却指客户解决方案经理。新员工要过六个月才会弄清楚。
7. 只有理想流程的 SOP — 文档涵盖了一切顺利时会发生什么，却没有说明 30% 的异常情况下该怎么办。

这项技能回答的是运营人员真正想问的问题：“我应该先修复哪 20 份文档？每份具体有什么问题？”——依靠确定性逻辑，而不是直觉。

使用场景

• 为跨职能公司流程编写新的 SOP（采购申请、供应商退出、事件沟通级联、员工入职、费用报销、客户升级处理手册、安全事件沟通、系统访问权限配置）。
• 在现有内部操作手册投入使用前进行验证（每个步骤都必须注明负责人、预期时长、可观察的成功信号、可观察的失败信号、回滚方案和升级联系对象）。
• 导入多文档知识库导出文件（Notion 压缩包、Confluence 空间导出、Obsidian 知识库、Drive/SOPs/ 目录），找出其中的问题：孤立页面、过期页面（超过 12 个月未编辑）、术语表不一致、未指定负责人的页面，以及交叉链接图。
• 为新入职的运营人员生成他们第 1 周需要阅读的 SOP 和运营手册页面。
• Wiki 清理冲刺 — 每季度进行知识卫生整理，由组织决定归档、重写或合并哪 30 份文档。

工作流

四步确定性流程（符合运维团队的实际工作流，而非抽象流程）：

1. 摄取知识库。 对现有 wiki 导出内容运行 kb_ingester.py --input <vault-dir>。输出为 Markdown 健康报告，包含孤立页面、过时页面、术语表偏差、缺少负责人的页面、交叉链接图和按优先级排列的清理列表。报告会列出优先修复的前 20 篇文档，通常包括高流量的过时文档和与合规相关的缺少负责人的文档。将此列表带入清理冲刺。
2. 验证现有运行手册。 对清理列表中的每份运行手册（或任何即将投入轮值的新运行手册），运行 runbook_validator.py --input <runbook.md>。验证器会根据六项检查为每个步骤评分（指定负责人、预计时长、可观察的成功信号、可观察的失败信号、回滚路径、升级联系人），并生成逐步红黄绿指示、0–100 的总体有效性评分，以及必须修复的问题列表。评分低于 60 的运行手册不适合在事件处理中使用。
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，确认孤立页面数量下降且术语表偏差已解决。重要指标是**“无法找到的文档”（孤立页面）和“不安全的运行手册”**（有效性评分低于 60），而不是页面数量。

脚本

scripts/sop_generator.py — 读取描述 SOP 的 JSON 元数据文件（流程负责人、触发事件、受众角色、频率、法规要求、输入、输出、步骤大纲），并生成完整的 5W2H 结构化 SOP，格式为 Markdown（或规范化 JSON）。--profile 标志用于调整输出：ops（通用内部运营）、support（客户支持操作手册风格）、finance（侧重控制与对账）、hr（标记敏感数据）、it（侧重系统与访问权限）、regulated（添加版本控制、签核矩阵、审计跟踪）。法规要求（SOC2、HIPAA、ISO13485、GDPR、SOX）会附加相应的合规性前言。--sample 会打印一个完整的供应商离职 SOP 示例。仅使用标准库。

scripts/runbook_validator.py — 读取操作手册（Markdown 文件或 JSON），并根据六项必需属性验证每个步骤：（1）明确的负责人（不能是“团队”或“运营”），（2）预期时长（具体数字 + 单位），（3）可观察的成功信号（例如，“从 /healthz 收到 HTTP 200”——而不是“服务正常运行”），（4）可观察的失败信号，（5）回滚路径（或明确说明“此步骤无法回滚，请升级给 X”），（6）升级联系对象（明确姓名或明确的值班轮值）。输出每个步骤的红黄绿状态（GREEN/AMBER/RED）、总体有效性评分 0-100，以及必须修复的问题列表。判定标准：≥ 80 = SAFE-TO-USE，60-79 = USE-WITH-CAUTION，< 60 = NOT-SAFE。--sample 会打印一份故意写得有问题的事件沟通操作手册，以演示故障检测。仅使用标准库。

scripts/kb_ingester.py — 遍历包含 Markdown 文件的目录（Notion 导出、Confluence 空间导出、Obsidian 知识库、Drive/SOPs/ 目录）。提取：（a）交叉链接映射（通过 Markdown [link](path) 语法，记录页面之间的引用关系），（b）术语表候选项（在 3 份或更多文档中反复出现、但没有统一标准定义页面的专有名词和缩写），（c）孤立页面（知识库中没有任何页面链接到该页面），（d）术语表漂移（同一术语在不同文档中的定义或用法不一致，例如“CSM”在两处有不同的展开形式），（e）过时页面（超过 12 个月未编辑，通过文件系统 mtime 或 YAML last_reviewed frontmatter 检测），（f）缺少负责人的页面（frontmatter 中没有 owner: 字段）。生成一份知识库健康状况 Markdown 报告，其中包含按 staleness × inbound-link-count 排序的优先级前 20 项清理列表（优先处理访问量高的过时文档）。--sample 会在 tmpdir 中创建一个包含 8 个页面的小型合成知识库，并对其运行完整流程。仅使用标准库。

快速示例

# Builds a synthetic 8-page vault and emits a KB health report (orphans, stale pages, glossary drift, top-20 cleanup list)
cd business-operations/skills/knowledge-ops && python3 scripts/kb_ingester.py --sample

参考资料

• references/5w2h_sop_canon.md — Kaoru Ishikawa 的 5W2H 方法、Toyota 标准作业规范、Atul Gawande 的检查清单宣言、Atlassian Confluence 的 SOP 指南、ISO 9001 SOP 要求、ITIL v4 服务运营、FDA 21 CFR Part 211。共引用 8 个来源，涵盖 SOP 编写规范。
• 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 — 汇总了 8 种反模式，来源包括 Notion/Confluence 企业 Wiki 研究、Mozilla SUMO 知识库经验、Stack Overflow 社区管理研究、Atlassian Team Playbook、MIT TIK 组织 Wiki 研究、Cynthia Lee 关于术语表漂移的论述，以及 Adam Wiggins 关于“文档腐化”的论述。

假设

1. 知识库采用 Markdown 格式（或可导出为 Markdown——Notion、Confluence、Obsidian 和 Google Docs 均支持）。仅 HTML 或仅 PDF 格式的知识库需要先进行转换；这不在范围内。
2. 用户有权委托他人重写或归档。整理出一份没人会采取行动的清单是白费功夫——运行 ingester 前，先将发现的问题交给一位明确指定的负责人。
3. 负责人元数据存放在 YAML frontmatter 中（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 个月。除非 30 份 SOP 都分别指派给明确指定的人员，否则拒绝批量生成。
• 把 runbook_validator.py 当作勾选清单。 验证器能发现结构缺失，但无法发现内容错误。运行手册即使得分为 100，也仍可能告诉操作人员错误的做法。
• 默认将孤立页面视为垃圾。 有些孤立页面是只能通过搜索找到的参考页面——并非所有孤立页面都应归档。清理清单是优先级队列，不是删除清单。
• 混淆 knowledge-ops 和 process-mapper。 Process-mapper 记录各阶段之间的工作流转（BPMN、周期时间、瓶颈）。Knowledge-ops 记录操作人员执行工作时使用的资料（SOP、运行手册、术语表）。两者都可能适用于同一流程。
• 任由术语表定义不断偏移。 三年内“CSM”有两种定义，五年内就会变成七种。kb_ingester.py 的输出一旦显示术语表定义出现偏移，就应立即修正。
• 在受监管的工作负载下跳过受监管配置。 如果流程涉及 PHI、SOX 相关财务控制，或 ISO 13485 医疗器械 QMS，请使用 --profile regulated。受监管 SOP 缺少版本控制会成为审计发现项。
• 凭记忆手写 5W2H 部分。 设置 5W2H 框架是为了避免操作人员忘记“How-much”。请使用生成器，再编辑输出内容。

与以下内容的区别

• engineering/llm-wiki — Karpathy 风格的个人 PKM 第二大脑，由一人将资料导入自己的互相关联知识库。Knowledge-ops 面向组织：多位作者、许多读者、每份文档均有明确指定的负责人，以及正式审核周期和合规要求。
• engineering-team/runbook-generator — 用于调试生产系统的系统运维运行手册（日志、告警、k8s、值班）。Knowledge-ops 的运行手册是针对业务流程的操作人员运行手册（事件沟通升级流程、供应商离职流程、员工入职流程）。读者是其他操作人员，而不是查看日志的工程师。
• project-management/* — Jira / Confluence 交付跟踪、冲刺工单工作流、项目状态报告。Knowledge-ops 关注的是这些 Confluence 页面中的内容，而不是跟踪由谁编辑这些页面。
• business-operations/process-mapper（同级项目）— BPMN 流程设计：有哪些阶段、工作在哪些环节等待、哪个阶段是瓶颈。Knowledge-ops 关注流程文档：指导操作人员如何执行 mapper 所描述流程的 SOP 和运行手册等资料。
• business-operations/internal-comms（同级项目）— 广播公告、全员大会消息、变更管理沟通。Knowledge-ops 是持久的参考资料；internal-comms 是广播沟通。
• ra-qm-team/* — 正式的法规合规文档编写（ISO 13485 QMS、MDR 技术文件、21 CFR Part 820）。Knowledge-ops 会借鉴法规核对清单，但不能替代公告机构审核。

强制提问库（Matt Pocock 式审问规范）

调用工具前，编排器（或 /cs-grill-bizops）会一次只问一个问题，并提供推荐答案和规范引用。绝不可打包提问。按深度优先顺序进行——第 1-3 题尚未敲定前，不要打开第 4 题。

1. “这份 SOP／运行手册的具名负责人是谁？他们知道自己承担这项责任吗？” 推荐：由一位具体的人负责（而不是“团队”），且他们已书面同意。 规范：Gawande 2009（The Checklist Manifesto）——没有负责人的检查清单会在 12 个月内失效。责任归属就是这项规范的核心。

2. “这份文档上次审核是什么时候？审核周期是多久？” 推荐：最近 12 个月内已审核（若为 --profile regulated，则为 90 天内）；审核周期已写入 frontmatter。 规范：ISO 9001:2015 §7.5.3——受控文档必须包含审核周期元数据。ITIL v4 对服务运营运行手册也有类似要求。

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. “文档是否只记录了正常流程，还是也记录了最常见的 2-3 种故障模式？” 推荐：记录每个流程中最常见的 2 种故障模式，并为其编写各自的恢复子流程。 规范：Fowler 2016（Production-Ready Microservices）——只涵盖正常流程的运维文档，会导致 60% 以上的事故处理时间浪费。

全部 7 项敲定后，依次调用 kb_ingester.py → runbook_validator.py → sop_generator.py。