Google 的 Open Knowledge Format (OKF): 想把 Agent 需要的组织知识装进文件夹

Google推出OKF，用文件夹形式组织企业知识，让AI Agent更懂业务逻辑。核心内容：1. OKF如何定义知识单元与文件结构2. YAML frontmatter与Markdown body的协作机制3. 通过普通链接建立跨文件知识关系

Google Cloud 本周发了 Open Knowledge Format，简称 OKF。它看起来很朴素：一个目录，里面放 Markdown 文件，每个文件顶部写 YAML frontmatter，再用普通 Markdown 链接把文件连起来。

这个东西值得写，是因为它碰到的痛点很实在。Agent 已经能写 SQL、查文档、调用工具，但在企业里经常卡在另一层：这张表到底能不能用，指标口径是谁定的，订单表和客户表应该怎么连，事故 runbook 放在哪里，某条规则有没有来源。模型不缺语法，缺的是可消费的组织知识。

它是什么

OKF 定义的基本单位叫 Knowledge Bundle。Bundle 就是一个文件夹，可以放在 Git 仓库里，也可以打成 zip 或 tarball。文件夹里每个非保留的 .md 文件叫 concept，表示一个知识单元。

concept 可以是一张 BigQuery 表，一个数据集，一个 API endpoint，一个指标，一个业务流程，一个 incident playbook，也可以是一篇参考资料。文件路径就是它的 ID，比如 tables/orders.md 对应的 concept id 是 tables/orders。

这种设计挺工程化。你不需要先部署服务，也不需要注册 schema registry。只要能读文件，就能读 OKF；只要能 git clone，就能分发 OKF。

技术细节

一个 concept 文件分成两段：YAML frontmatter 和 Markdown body。

frontmatter 里唯一必填字段是 type。它告诉消费者这个 concept 大概是什么，比如 BigQuery Table、Metric、Playbook、Reference。Google 没有做中心化 type registry，生产者自己起名字，消费者遇到未知 type 也应该继续读。

推荐字段有 title、description、resource、tags、timestamp。这里的思路很清楚：frontmatter 只放少量需要过滤、展示、索引的结构化信息。

真正的语义放在 Markdown body 里。比如表的字段说明、示例 SQL、join 方式、使用限制、引用来源，都可以用标题、表格、代码块、普通段落来写。Spec 里给了几个约定标题：# Schema、# Examples、# Citations。这些属于约定，对人和 Agent 都好读。

跨文件关系也很朴素：普通 Markdown 链接。orders.md 里可以链接到 /tables/customers.md，关系类型靠周围文字说明。这个选择降低了写入成本，也让图可视化器可以先把所有链接当作 directed edge。

这里有个取舍。关系语义不会特别强，想做严格的知识图谱查询会嫌它松。但我反而觉得 v0.1 这样挺合理。企业知识刚开始被整理时，最难的是让人愿意写、让 Agent 写出来不容易坏。强 schema 太早压上去，很多团队会直接放弃。

index.md 和 log.md 很关键

OKF 里有两个保留文件名：index.md 和 log.md。

index.md 负责分层导航。Agent 可以先读根目录的 index，看有哪些 dataset、table、metric、playbook，再按任务逐层打开相关文件。不用一口气把整个知识库塞进上下文。

log.md 负责变更历史。比如某个目录下新增了一个表、修改了一个指标口径、废弃了一个 playbook，都可以按日期记下来。Agent 后续读取时，能知道最近发生过什么，不用完全靠全文搜索碰运气。

这套设计明显继承了 LLM Wiki 的味道。Karpathy 那篇 LLM Wiki 讲的也是三层：raw sources、wiki、schema。OKF 做的事，是把这个社区里已经跑起来的模式，变成一个供应商中立的交换格式。

为什么 Google 要做这个

Google 的切入点是数据目录和 Agentic Data Cloud。企业数据系统里有太多上下文放在服务里：Dataplex、BigQuery、Looker、文档站、内部 wiki、工单、Slack 讨论。Agent 要想真的帮人分析数据，只拿到字段名远远不够。

举个很常见的场景。一个销售收入指标，字段名可能叫 revenue，但它到底包不包含退款、税费、折扣、跨境汇率调整，往往在另一个文档里。再往下问，这个指标能不能按周聚合，能不能和用户表 join，历史分区有没有数据质量事故，又会散到更多地方。

传统 RAG 可以检索这些资料，但每次都要重新拼。OKF 的想法是把稳定知识先整理成 wiki，让它持续累积。Agent 查询时读的是整理后的 concept，而不只是 raw docs 的碎片。

Google 这次也给了参考实现。README 里写到 enrichment agent 会先读取 BigQuery metadata，为数据集、表等概念生成 OKF 文档；然后通过 web pass 抓取权威文档，把 citation、说明、关系补进去。它还能生成一个自包含 HTML visualizer，用图方式看 bundle 里的 concept 和链接。

我更在意的是它把数据目录知识拉回了工程工作流。指标口径更新、join path 修订、verified SQL 加入，都可以变成 Git diff，可以走 PR，可以被 review。对数据团队来说，这比又多一个聊天入口实际得多。

和几个相邻标准怎么分

OKF 很容易和 llms.txt、MCP、OpenLineage 混在一起看，但它们管的层不一样。

llms.txt 更像站点给 LLM 的入口导航，告诉模型重要文档在哪里。MCP 是 Agent 连接工具、资源和数据源的协议。OpenLineage 记录作业运行时的血缘事件，比如哪个 job 读了哪些 dataset，产出了哪些 dataset。

OKF 更像上下文资产本身。它可以被 llms.txt 指向，也可以通过 MCP 暴露给 Agent，还可以把 OpenLineage 结果写成概念说明或 citation。它关注的层，是把组织知识做成可移动、可审查、可读取的文件包。

落地方式

如果团队想试 OKF，我不建议一上来就把整个公司知识库导出。比较稳的路径是选一个小域，比如一个 BigQuery dataset、一个核心业务指标域，或者一个产品线的数据资产。

先定本地 profile。也就是把 type 清单、推荐 frontmatter 字段、固定章节模板、citation 规则写清楚。比如表必须有 Schema、Examples、Citations；指标必须说明口径、过滤条件、刷新频率、owner；playbook 必须说明触发条件、处理步骤、升级路径。

然后从现有系统导出第一版。dbt docs、LookML、BigQuery INFORMATION_SCHEMA、DataHub、Dataplex、内部 wiki，都可以成为 producer。第一版不用追求完美，先把高价值 concept 做出来。

接着让人审最关键的内容。尤其是指标口径、权限边界、SQL 示例、业务规则。Agent 写出来的东西可以加速整理，但不能把它当成事实来源。OKF 里的 citation 很重要，最好每个关键判断都能追到原文档、系统链接或 owner。

这一步之后，让 Agent 只读消费。比如 SQL Agent 先读 index.md，再打开相关表和指标 concept，沿链接找到 join path 和示例查询。观察生成质量有没有变稳，错误是否更容易定位。等只读消费稳定后，再考虑让 Agent 写回建议修改，并通过 PR 让人审。

边界

OKF v0.1 还很早。它没有权限模型，没有查询基础设施，没有统一 type registry，也没有强关系语义。它不能替代数据治理系统，不能替代 schema 管理，也不能替代运行时血缘采集。

权限尤其要小心。把表说明、示例 SQL、业务规则导出成文件后，传播会变得更容易。哪些字段能写进 bundle，哪些示例会泄漏业务敏感信息，哪些 concept 只能给特定团队读，这些都要在外部系统里处理。

还有规模问题。几百到几千个 concept，用文件、Git、index、grep、静态 viewer 很舒服。到了几十万级别，肯定需要搜索索引、分片、增量同步和权限过滤。OKF 负责交换形态，不负责大规模 serving。

资料来源

Google Cloud Blog 原文：https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing

OKF SPEC v0.1：https://raw.githubusercontent.com/GoogleCloudPlatform/knowledge-catalog/main/okf/SPEC.md

OKF GitHub README：https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf

Karpathy LLM Wiki：https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f

llms.txt：https://llmstxt.org/

MCP 文档：https://modelcontextprotocol.io/docs/getting-started/intro

OpenLineage 文档：https://openlineage.io/docs/

总结

OKF 这件事，我的判断是可以小规模试，别急着押成平台战略。

它最有价值的地方，是把 Agent 需要的组织知识变成普通文件。普通到可以放进 Git，可以被人审，可以被脚本检查，可以被不同工具搬来搬去。这个方向很对。

我也有点担心 type 和章节约定后面会分裂。没有 registry 带来灵活性，也会带来映射成本。真正落地时，团队一定要写自己的 OKF profile，不然文件夹很快会变成另一种松散 wiki。

如果你现在已经在做数据问答、SQL Agent、企业知识库、代码 Agent 项目，我会把 OKF 当成一个很轻的中间层来试：先从一个小域导出，给 Agent 读，再看错误有没有少一点。别让格式本身变成新负担。它应该帮知识流动，减少新流程负担。