图解谷歌OKF（Open Knowledge Format）仓库，理解开放知识格式的落地路径

先说一个动作：Google Cloud 最近放出了 Open Knowledge Format（OKF）的规范，同时扔出了一个叫 knowledge-catalog 的仓库。里面东西很全——规格文件、参考实现（Agent）、跑得通的样例配方、已经生成好的知识包（bundle）、一个用来查看的 HTML 页面，还有跟自家 Knowledge Catalog 产品对接的演示。不过当前版本还标着 OKF v0.1 — Draft，说明这东西还在打磨状态。

这篇就来拆一拆这个仓库，看看 OKF 到底是怎样的一个落地样本。先透个底：整个链条其实并不复杂——核心是 SPEC.md，这是规格的起点；然后有一套参考写入端的代码、一些已经生成的样例产物、一个消费端的查看器，以及适配 Google Knowledge Catalog 的集成示范。每一步都有现成的东西可以参考。

OKF 定的是知识包结构、概念文档和最小字段约束

这张图就是 OKF 的最小交换约定。

翻开 SPEC.md 其实会发现，OKF 定义的核心概念是

——一个分发单元。简单说，一包知识就是一棵目录树，里面放的是 Markdown 格式的概念文档。每个非保留的概念文档都必须带 YAML 头部元数据，type 是必填字段；文件的路径本身就是概念 ID。另外，index.md 和 log.md 是保留文件名，有特殊含义。

对消费端的要求写得也比较"宽厚"：遇到未知的 type、额外的字段、失效的链接，或者缺少 index.md，都要尽量宽容，不能因为一点意外就直接拒收。这背后的逻辑很清楚——

：知识怎么打包、怎么交换、怎么被别的系统读进去。关于知识平台怎么建、语义层怎么统一，都不在这份规范的范围之内。仓库的设计也遵循这个边界，先把交换层钉死，再补上写入端、消费端、产品接入的样板。

这张图把角色拆开来看：输入源提供上下文，写入动作通常由智能体执行；消费端不只有 viewer 查看器，也可以是智能体或其他 AI 应用。

这里有个容易混淆的地方：

。写入端指的是把源系统里的知识整理并写成 OKF 知识包的那一侧。真正执行写入动作的，往往是某个"知识补全智能体"。而 BigQuery、网页资料这些其实只是"输入源"。消费端则是任何会读取、遍历和利用这包文件的系统——不限于 viewer，也可以是别的智能体、RAG 系统、搜索索引，或者像 Knowledge Catalog 这样的目录产品。AI 在两端都参与，只是写入和消费的角色不同。

不少人会问：BigQuery 是不是 OKF 的标配？不是。它只是这个仓库里 reference_agent 实现的唯一内置数据源。OKF 本身是厂商中立的格式，不绑定任何特定的智能体、框架或服务。

谷歌在示例仓库里铺了四层落地样板

第一层是规范：先把交换约定写死

仓库里的 SPEC.md 写得很克制。它没有去发明一套大而全的类型体系，也没有绑定任何服务、数据库或用户界面——只把写入端和消费端之间最小的交换约定定了下来。

约定其实很短：写入端要写对——非保留的 .md 文档必须有可解析的头部元数据，type 不能为空；消费端要宽读——遇到未知字段、未知 type、断链、缺少 index.md，都不能直接判死。一句话总结就是

。OKF 从一开始就没有往"重平台规范"的方向走，它先解决的是互操作问题。

一句话说，SPEC.md 要求的是：写入端从严，读取端尽量宽读。

第二层是 reference_agent：谷歌给出了一套 Agent 应用示例

reference_agent 是一套样板 Agent。它定位是"概念验证版"应用，主要由两个功能组成：

• enrich 演示怎么把源数据和网页资料写成 OKF 知识包。
• visualize 演示怎么把这包文件消费成一个可交互的单文件查看器。

所以这一层给出的并不是 OKF 本体，而是一套覆盖写入和消费的 Agent 应用示例。从模块分工上看也不复杂：

• sources/bigquery.py 负责读 BigQuery 元数据。
• agent.py 拆成了 BigQuery 智能体和网页摄取智能体。
• runner.py 串起写入流程，并负责重建 index.md。
• viewer/generator.py 负责把知识包转成 viz.html。
• cli.py 提供 enrich 和 visualize 两个入口。

这张图把 reference_agent 拆成两条线：enrich 负责写入，visualize 负责消费；两边都围绕同一个 OKF 知识包。

写入侧还可以再拆成两段：

1. BigQuery 轮（BQ pass）
   ：先只用 BigQuery 元数据，为每个概念生成一份 OKF 文档。

2. 网页轮（web pass）
   ：再拿显式给定的种子网址去抓权威页面，在页面预算、域名白名单和深度限制内，决定是补现有文档、单独生成 references/，还是直接跳过。

这张图只压缩了 reference_agent 的写入侧：enrich 负责把源数据和网页资料整理成 OKF 知识包。

再强调一次：

，不绑定特定的智能体、框架、模型或服务。而在 reference_agent 这套应用示例里，写入侧是 reference_agent enrich --source bq + web pass，消费侧是 reference_agent visualize。你在自己的项目里落地，完全可以换成基于 Codex、Claude Code 或其他智能体框架的写入端和消费端——前提只有一个：最后写出来、读进去的知识包，还得守住同一份 OKF 约定。reference_agent 不是 OKF 本体，而是谷歌先交出来的"最短可跑"应用示例。

第三层是 bundles 和复现配方 samples

这一层就是仓库里已经生成出来的样例产物 bundles/，samples/ 只是复跑这些样板时附带的一层配方。

仓库直接挂了三组公开样例：GA4 Google Merchandise Store、Stack Overflow、Bitcoin public datasets。每组都对应一份样例说明和一份已经生成好的知识包。拿一组来看结构：

samples//
├─ README.md     # 跑哪个外部数据集、用什么 enrich 命令
└─ seeds.txt     # web pass 的种子网址

bundles//
├─ datasets/
├─ tables/
├─ references/
├─ index.md
└─ viz.html

这里的重点不在配方本身，而在

。前者是可复现的说明，后者才是 OKF 真正要交换和消费的东西。samples/ 里选用的 GA4、Stack Overflow、Bitcoin 也只是示例源。从 OKF 的设计边界来看，如果你自己实现写入端，完全可以换成 API 文档、数据库模式、产品帮助中心，或者内部的任何知识页面。

至于查看器 viewer，它本身也没做成一个重磅产品。src/reference_agent/viewer/generator.py 生成的是一个单文件、自包含的 HTML 页面，包括图结构、头部元数据、渲染后的 Markdown、反向链接、搜索、类型筛选。它就是 reference_agent 这套应用里的概念验证版消费端，用来证明：知识包一旦生成，就已经能被浏览、跳转和消费。

这就是 viz.html 的实际样子：左侧把知识包渲染成概念图谱，右侧直接展开当前文档的头部元数据、正文、模式和示例查询。

第四层：通过 mdcode 把知识包接进 Knowledge Catalog（可选）

这一层讲的是怎么消费 OKF 知识包的另一种场景。你可以先把 Knowledge Catalog 理解成 Google Cloud / Dataplex 里的一种"目录型消费端"。关键在于：它不直接读知识包，而是要先过一层 mdcode 桥接。

到这里其实可以把消费端分成两类：

• 直接消费知识包
  ：像 viz.html、智能体、RAG、搜索索引这种，本身就认 OKF 的目录结构、Markdown、头部元数据和链接——不需要桥接层。

• 映射后再消费
  ：像 Knowledge Catalog 这种有自己的对象模型的产品，不直接吃"裸知识包文件夹"，中间要先过一层桥接或映射。

第四层就是这条桥：先把知识包映射成目录模型，再通过 kcmd push 发布到 Knowledge Catalog。

mdcode demo 展示的就是第二种情况。catalog/ 里预放了一套 GA4 知识包，setup.ts 创建 Dataplex EntryGroup 并写出 catalog.yaml，再把知识包里的 Markdown 文档映射成 Dataplex 的 entry / aspect 模型。具体过程是：每个 .md 对应一个 entry，entry 名镜像文件路径，正文进入 dataplex-types.global.overview；头部元数据里的自定义 type: 如果不是合法的 Dataplex 类型引用，就回退到 dataplex-types.global.generic。

所以这条链真正闭合时，走的是：

OKF 知识包 → mdcode 目录快照 → kcmd push → Dataplex EntryGroup / aspects

如果你的消费端能直接读知识包，第四层可以跳过；只有消费端不直接认知识包，或者你真的要接目录产品、治理系统和现有目录系统时，才需要走这层适配。

总结：怎么落地？

在自己项目里落地或者搭配其他 Agent 使用，别急着搭平台，也别先搞什么大一统知识体系。最短路径就两段：

。

如果放到 Codex、Claude Code 这类智能体环境里，一个更务实的方向是把 OKF 做成一组 skill：写入 skill 负责按约定生成概念文档、补头部元数据、维护 index.md 和链接；读取 skill 负责遍历知识包、按类型筛选、追踪反向链接，再把相关概念装进上下文。这样 OKF 就不只是"文件夹格式"，而会变成智能体可以反复调用的一套知识读写动作。

先写出最小知识包，再决定是不是要接桥接层；平台接入应该放在最后，不该放在最前。

1. 先挑一个边界清楚的知识子域和数据源——数据库、API 文档、帮助中心、内部知识页都可以。
2. 再决定写入端怎么来。想复用现成样板，就从 reference_agent enrich --source bq 这条链起步；如果你的源不是 BigQuery，就保留同样的知识包约定，自己补数据源适配器，或者在 Codex / Claude Code 里封装成 OKF 写入 skill。
3. 先把一包最小可用的知识包写出来。重点不是写满，而是先把头部元数据、链接、index.md 和类型约定跑通。
4. 先用 viz.html、智能体、RAG 或搜索去直接消费它，检查这包文件能不能读、能不能跳、能不能查。
5. 如果消费端能直接读知识包，到这里就够了；只有消费端不直接认知识包，或者你必须接目录产品、治理系统和现有目录系统时，再加桥接层——比如 mdcode 或者自己的适配器。