用途
synthesis-okf 用于验证、转换和编写符合 Google 开放知识格式（Open Knowledge Format，简称 OKF v0.1）的内容。OKF 是一种正式化的知识库规范，采用目录树组织 Markdown 文件，每个文件带有 YAML 前置元数据（frontmatter）。该技能填补了 Google 参考仓库未提供的一致性校验器和转换器空白，并附带一套经过多个真实仓库转换验证的操作流程。
主要能力
该技能提供四个核心工具：
-
okf_validate.py：一致性校验器，检查 OKF 的硬性规则，包括每个非保留的 .md 文件须有可解析的 YAML 前置元数据、前置元数据中须有非空的 type 字段、保留文件名（index.md、log.md）须遵循既定结构。支持
--summary输出类型分布、--check-links报告断链（仅作信息提示，不算违规）。 -
okf_convert.py：幂等的前置元数据回填工具，可为现有 Markdown 语料补充 OKF 前置元数据，且不覆盖已有字段。支持按目录映射 type、从 H1 推导标题、从 git 提交时间推导时间戳、将 README.md 重命名为 index.md 并按规范重新生成索引。
-
okf_consistency.py：基于配置的仓库内部一致性检查器，读取
.agents/knowledge-base.yaml及其 taxonomy 配置，报告重复元数据、日期冲突、状态冲突、缺失必填字段、不符合规范的标签等问题。 -
转换流程：一套完整的操作步骤，包括基线校验、编写描述文件、转换、校验至零错误、仓库一致性检查、编译器配置排除 index.md 和 log.md、审查差异并提交。
使用方式
校验命令：python3 scripts/okf_validate.py <bundle_dir> [--summary] [--check-links] [--quiet]
转换命令：python3 scripts/okf_convert.py <bundle_dir> --type-map instructions=Instruction,runbooks=Runbook,datasets=Dataset,contexts=Context --descriptions <repo>-descriptions.yaml [--dry-run]
一致性检查命令：python3 scripts/okf_consistency.py <repo_root> [<repo-relative-doc> ...] [--strict]
建议先使用 --dry-run 预览变更，再实际执行。描述文件需手工编写，因为自动提取不可靠。
适用场景
适用于需要将现有 Markdown 知识库转换为 OKF 格式、需要校验 OKF 合规性、或需要维护知识库内部一致性的场景。该流程已在多个真实仓库上验证，包括 26 篇文档的公开仓库和 72 篇文档的个人知识库。
限制
OKF 规范中只有三条硬性规则，其余均为软性指导，校验器不应因缺少可选字段或断链而拒绝知识库。type 值完全自由格式，无中心注册表。转换时需注意文件名含空格会导致生成的链接失效，应改为连字符命名。空的知识库目录视为天然合规，无需转换。