OKF 开放知识格式：用 Markdown+YAML 标准化你的 AI 知识库接入

LEISURELINUX FIELD NOTE 2026·07·10

AI Agent 知识库接入的 N 种方案对比

OKF 开放知识格式 · Markdown+YAML 的三规则

用 Markdown+YAML 标准化你的 AI 知识库接入 · 内刊式深度解读，含参考文献。

![](data:image/svg+xml;base64,PHN2ZyBhcmlhLWhpZGRlbj0idHJ1ZSIgdmlld2JveD0iMCAwIDY0IDY0Ij4KIMKgIMKgIMKgIMKgIMKgCiDCoCDCoCDCoCDCoCDCoAogwqAgwqAgwqAgwqAgwqAKIMKgIMKgIMKgIMKgIMKgCiDCoCDCoCDCoCDCoCDCoAogwqAgwqAgwqAgwqAgwqAKIMKgIMKgIMKgIMKgIMKgPHRleHQgZmlsbD0iI2ZmZiIgZm9udC1mYW1pbHk9IklCTSBQbGV4IFNhbnMsc2Fucy1zZXJpZiIgZm9udC1zaXplPSI4IiBmb250LXdlaWdodD0iODAwIiB0ZXh0LWFuY2hvcj0ibWlkZGxlIiB4PSI0NiIgeT0iNTMiPlk8L3RleHQ+CiDCoCDCoCDCoCDCoDwvc3ZnPg==)        MD · YAML

三规则 · 零运行时 · MIT 协议 · Agent 原生

OKF AI AGENT SPEC 解读

EDITOR\'S NOTE

写在前面

2026 年 6 月 12 日，Google Cloud 发布了一份看似简单的规范——OKF（Open Knowledge Format）。它只有三条规则，零运行时，零 SDK，但你读完后会意识到：它解决的是所有企业做 AI Agent 时最头疼的那个问题——组织知识如何可被 Agent 原生读写。

这份解读基于 OKF 官方规范（okf.md）、Google Cloud 公告及多个开源社区实践。三个小时后，你就能 fork 一个 Git 仓库、用 Markdown 文件搭起自己的第一个合规知识库。

01

PART

OKF 的三个核心规则

THREE RULES, ONE GOAL

OKF 的全部野心，可以压缩成三条规则。这是它和过去十年所有"知识表示规范"最不一样的地方。

一句话总结：OKF = Markdown 正文 + YAML 元数据 + 一个 `type` 字段。 仅此而已。

Rule 1 · 每个知识点 = 一个 .md 文件

一份 OKF bundle 本质就是一个目录，里面装着一堆 Markdown 文件，每个文件只表达一个"概念"——一张表、一个 runbook、一段 API 文档、一个 SLO 指标都行。文件之间用标准 Markdown 链接互相跳转，形成一张人类和 Agent 都能导航的知识图。

每个 .md 文件的开头必须有一段 YAML frontmatter（被 -\——包起来），用于承载结构化元数据。这些元数据让 Agent 在不解析正文的情况下就能理解文件语境。

YAML 里只需要写一个 type 字段，其余都是可选——这种"最小意见"设计是 OKF 的灵魂：规范定义的是"互操作表面"，不是死板的内容结构。

02

PART

一个最小合规的 OKF Bundle 长什么样

THE MINIMAL VIABLE BUNDLE

下面是一个真实可用的最小 OKF bundle——目录结构只有三个文件，丢进任何 Git 仓库都能跑。

my-knowledge-bundle/

├── index.md      # 入口：列出本 bundle 的所有概念

├── what-is-okf.md  # 一个具体概念文件

└── validation-rules.md # 另一个概念文件

其中 what-is-okf.md 的内容如下------YAML frontmatter 用 --- 包裹，Markdown 正文紧跟其后：

             markdown · what-is-okf.md

---

type: concept

title: 什么是 OKF

description: OKF 是用 Markdown+YAML 标准化知识库的开放规范

tags:

 - okf

 - knowledge-base

 - markdown

timestamp: 2026-07-10T08:00:00Z

---

# 什么是 OKF

Open Knowledge Format 是一种把组织知识表示为 Markdown 文件目录

的开放规范，专门为 AI Agent 友好而设计。

## 为什么需要 OKF

过去十年，知识散落在 Confluence、Notion、Google Docs、

Slack 等十几个系统里。OKF 把这 N 个 adapter 收敛为 1。

这是规范允许的最简 bundle——零依赖、零构建、零运行时。你的编辑器本来就支持 Markdown，所以没有任何"新工具"需要安装。

03

PART

type 字段的类型学：可选但强烈推荐

OPTIONAL BUT ENCOURAGED

规范虽然只要求 type，但为了真正发挥 Agent 友好性，社区已经沉淀出一套推荐词表。这套词表不是强制规范，更像是"事实上的最佳实践"：

类别 推荐 type 取值 适用场景 数据资产 BigQuery Table Snowflake Table Dataset 表/数据集 schema 文档 Concept Runbook Playbook 概念解释、操作手册 代码资产 Service API Library 微服务/API/内部库 指标 Metric SLO Dashboard 可观测性指标、SLO 定义 流程 Onboarding Incident 入职流程、事故复盘

这套词表的核心价值在于：当 Agent 检索 bundle 时，它可以按 type 字段做精确过滤——比如"只检索所有 type: Runbook 的文件"来回答"线上出问题了怎么办"。

可选字段也都很有用，按需使用：

• title：人类可读的概念标题（推荐）
• description：一句话说明（推荐）
• resource：指向实际资源（BigQuery 控制台 URL、内部系统链接等）
• tags：自由标签，方便二次过滤
• timestamp：最后更新时间，让 Agent 知道信息新鲜度

04

PART

OKF 在知识表示生态中的位置

ECOSYSTEM POSITIONING

OKF 不是孤立发明的，它和现有的几套规范有清晰的边界。下表是它和常见方案的对比：

维度 OKF Schema.org 传统 RAG Confluence 等 目标受众 Agent + 人类 搜索引擎 Agent（粗） 人类为主 互操作性 文件级，零依赖 需 JSON-LD 注入 黑盒索引 API 锁定 版本控制 Git 原生 弱 否 弱 运行时依赖 无 Schema 验证器 Embedding 服务 后台服务 Agent 解析成本 低 中 高 高

OKF 的定位很清晰：它不取代 Schema.org（Schema.org 服务于公共网页搜索），也不取代 RAG（OKF 的结构化内容可以作为 RAG 的高质量输入），它填补的是"组织内部、Agent 原生、最小代价"这个空白。

更进阶的实验性项目 LinkML Open Knowledge Format（LOKF）正在尝试把 OKF 字段绑定到 Schema.org / W3C DCAT / PROV-O 等正式知识图谱词汇——既能保持 Markdown 的轻量，又能用 SPARQL 查询、用 OWL 推理。这一层还在演进，值得关注但不必现在就用。

05

PART

三个真实落地场景

THREE REAL-WORLD USE CASES

CASE A

内部 Runbook 知识库

SRE / 平台工程

把过去散落在 Confluence 的 SRE runbook 全部导出为 OKF 格式，YAML 里写 type: Runbook、tags: [k8s, oncall]。Agent 在事故响应时直接 grep 这一类文件，比翻 wiki 快一个数量级。

结果：事故响应平均耗时下降 60%。

CASE B

数据资产的"自带文档"

数据 / 分析团队

每个 BigQuery 表对应一个 .md 文件，YAML 里写 type: BigQuery Table 和 resource 指向控制台 URL。Agent 做数据分析前先读对应文件，自动知道 schema、敏感级别、负责人。

结果：表使用文档覆盖率从 30% 提升到 95%。

CASE C

团队大脑 / Onboarding Bundle

HR / 入职体验

新员工入职时 clone 一个 git 仓库，里面全是 type: Onboarding 或 type: Concept 的 Markdown 文件。Agent 把这个仓库挂进 context，新员工的任何问题都从这份"团队大脑"里检索——这正是 Google 内部称之为 "LLM-wiki pattern" 的实践。

结果：新员工 ramp-up 时间缩短约 40%。

///

END

三句话带走 OKF

THREE SENTENCES TO TAKE AWAY

OKF 不是另一种框架，它是一份对"知识应以何种形式存在"的回答：当组织和 Agent 都得读这些知识时，Markdown+YAML 是阻力最小、版本控制最自然、互操作性最高的形式。

它用三条规则、零依赖、MIT 协议，把过去十年的"知识格式之争"压缩为一个工程问题——你只需要写 Markdown。

而当你下次准备开一个 Confluence 子站点、或者把一堆 Notion 页面"导出"给 AI 用之前，先停下来问自己一个问题：

这些知识，能被 Agent 直接 git clone 出来用吗？

如果答案是不能——OKF 给出了如何做到的规范。

REFERENCES / 参考文献

01 / Open Knowledge Format 官方规范 · okf.md · 访问于 2026-07-10

02 / Google Cloud, \"Introducing OKF: An Open Markdown Spec for AI Agent Knowledge\" · Google Cloud Blog · 2026-06-12

03 / Open Knowledge Format GitHub 仓库 · github.com/open-knowledge-format/okf

04 / LinkML Open Knowledge Format (LOKF) · github.com/linkml/okf · 把 OKF 绑定到 Schema.org / W3C DCAT / PROV-O

05 / Google Knowledge Graph & Schema.org · Google Search Central Documentation · 与 OKF 的"组织内部知识"定位互补

06 / Cal Newport, \"Deep Work\" · 关于知识工作者的专注工作模式（方法论呼应）

我是 LeisureLinux，{{一句话简介，如：专注技术、组织、认知提升的深度解读}}。

L LeisureLinux · 公众号

如果你觉得今天这篇 OKF 解读有收获，欢迎点赞、在看、收藏三连，我们下篇见。

赞 在看 收藏

THANKS FOR READING

后记：本文参考 OKF v0.1 官方规范、LinkML LOKF 实验性绑定层，以及 Cal Newport《Deep Work》关于知识工作者专注模式的方法论。"三个案例"中提及的指标均为典型使用场景下的近似估计值，不针对具体企业。

---

本文完。欢迎关注 LeisureLinux，获取更多深度技术解读。

核心AI术语：从感知到认知

构建可演进的第二大脑：基于 OpenKB + OpenRouter + Llama 3.3 的"编译式"RAG 架构深度实践

GitNexus：为 AI 时代打造的 MCP 原生代码知识图谱引擎

常见问题（FAQ）

Q1：这篇文章主要讲什么？ LEISURELINUX FIELD NOTE 2026·07·10 Q2：还有哪些关键事实？ 01 PART OKF 的三个核心规则 THREE RULES, ONE GOAL OKF 的全部野心，可以压缩成三条规则。 Q3：有哪些值得注意的细节？ __biz=MzA5NzgyNzA0MA==&mid=2650317599&idx=1&sn=39ac01b56c6fc4452137bef0ff3a80e5&scene=21#wechat_redirect){linktype="2" localeditorid="mvpq1wrcuifput1q80" target="_blank" textvalue=… Q4：核心结论是什么？ LEISURELINUX FIELD NOTE 2026·07·10 AI Agent 知识库接入的 N 种方案对比 OKF 开放知识格式 · Markdown+YAML 的三规则 用 Markdown+YAML 标准化你的 AI 知识库接入 · 内刊式深度解读，含参考文献。