OKF Ops 是一套用于评估、验证和采用开放知识格式（Open Knowledge Format，简称 OKF）的技能。OKF 是一种极简、开放的约定，用于把知识表示为带 YAML frontmatter 的 markdown 文件目录树——即围绕数据与系统的元数据和经过整理的情境。本技能帮助你评估某个仓库是否适合采用、校验某个知识包是否符合规范，并在确实有价值的地方引入 OKF。完整格式规则见 references/okf-spec.md，可直接复制的概念文档模板见 assets/concept-template.md。
一、采用前需要了解的诚实范围 OKF 是 v0.1 草案（由 Google 发布，与平台无关），刻意保持极简：只有一个必填的 frontmatter 字段（type）、保留文件 index.md 和 log.md，以及一个宽松消费（permissive-consumption）契约。有两个值得提前知道的后果：
- 采用成本由仓库本身决定，而非规模决定。已经一致使用 frontmatter 的仓库，往往只需一次机械的 type 推导即可符合规范；而纯粹散文式 markdown 的仓库则需要为每个文件编写 frontmatter——通常不值得，而且这些文件可能本来就不适合作为“概念”。
- 合规性是一种弱保证。“符合 OKF”只意味着达到了结构底线，并不代表内容质量好。应使用评估来按仓库决定是否采用，不要把它变成一刀切的强制要求。 此外，无论 OKF 的发展轨迹如何，这里的工具本身都很有用——assess-okf.py 是一个通用的“这个文档树的 frontmatter 一致性如何？”扫描器。
二、工作流程：评估 → 决定 → 验证
-
评估（只读）——这个仓库是否是好的候选？ 命令示例： python scripts/assess-okf.py docs/ # 人类可读摘要 python scripts/assess-okf.py --json docs/ | jq '.data.readiness_pct' 它会报告：.md 文件总数、已带 frontmatter 的数量、具有非空 type 的数量、现有 frontmatter 键的直方图（展示你已有哪些词汇可供推导 type）、type 值分布、存在的保留文件、需要补充 type 的文件，以及整体就绪度百分比。永不写入。 关键是要看直方图，而不只是百分比。一个“0% 就绪度”但拥有丰富一致键（例如每个文件都有 title/level/tags）的仓库，迁移成本很低——你可以从已有键推导出 type。而一个“0%”且 frontmatter 大多为空的仓库，迁移成本很高。若要在多个仓库间寻找候选，可对每个仓库运行评估并比较。
-
决定——只在收益大于投入时采用
- frontmatter 一致的仓库 → 采用：推导 type、修复任何格式错误的文件，完成。
- 散文与 frontmatter 混合的仓库 → 通常跳过，或只采用一个子集（只指定真正的概念文档；OKF 没有内置的散文豁免——这是已知的僵化之处）。
- 验证——某个知识包是否符合规范？ 命令示例： python scripts/check-okf.py ./bundle # 退出码 0 表示符合，10 表示不符合 python scripts/check-okf.py --json ./bundle | jq '.data[] | select(.severity=="error")' python scripts/check-okf.py --strict ./bundle # 软警告也会导致失败 它仅强制硬性规则（每个非保留 .md 都有可解析的 frontmatter 且 type 非空；保留文件只做轻度合理性检查）。根据 OKF 的宽松消费规则，断链和缺少可选字段属于 INFO，永远不算失败（除非使用 --strict）。一旦仓库采用了 OKF，可将 check-okf.py --strict 接入 CI 门禁（退出码 10 会使构建失败）。
三、工具 两个脚本都遵循 Skill Resource Protocol：stdout 仅输出数据（--json 输出 {"data":…,"meta":{"schema":…}} 封装），框架/进度信息输出到 stderr，--help 带示例，使用语义化退出码。仅依赖标准库；若存在 PyYAML 则使用，否则使用内置的 frontmatter 解析器（会在 stderr 中说明）。
脚本与角色、退出码：
- scripts/assess-okf.py：对文档树进行只读就绪度扫描。退出码：0 已扫描，2 用法错误，3 未找到。
- scripts/check-okf.py：知识包一致性校验器。退出码：0 符合规范，10 不符合规范，4 frontmatter 不可解析，3 未找到，2 用法错误。
四、另见
- references/okf-spec.md——格式：frontmatter 字段、保留文件、合规规则、宽松消费、版本管理。
- assets/concept-template.md——可直接复制的 OKF 概念文档。