前些日子 Google Cloud 发布了 Open Knowledge Format（开放知识格式：谷歌发布OKF（Open Knowledge Format）规范，它与Karpathy的LLM-wiki是什么关系？），并在GoogleCloudPlatform/knowledge-catalog仓库里一起给出了规范文件、参考写入端（智能体）、样例运行配方、已生成知识包（bundle）、查看器（viz.html），以及接入 Knowledge Catalog 的演示。当前版本还是OKF v0.1 — Draft，说明规范还在完善中。[1][2][3][5][6]
本篇拆解谷歌的示例仓库，看OKF的具体落地内容：SPEC.md是规格起点，后面还有参考写入端、样例产物、消费端查看器，以及接入谷歌 Knowledge Catalog 产品适配示例。[1][2][5][6]
按照OKF的路径，未来的知识就像一包包可携带的知识包，可直接放进项目、智能体或目录系统直接消费。它可以是一棵目录，也可以被打成压缩包分发；它是不同消费端都认同同一份契约。
把 GoogleCloudPlatform/knowledge-catalog/okf/根目录摊平看，大致是这样：
okf/├─ SPEC.md # OKF 最小交换约定├─ README.md # 仓库导航、样例索引和运行说明├─ samples/ # 复跑说明：数据集、种子网址、精确 enrich 命令├─ bundles/ # 已生成的 OKF 知识包和 viz.html├─ src/reference_agent/ # 写入端与查看器实现│ ├─ sources/ # 数据源适配器，当前仓库只内置 BigQuery│ ├─ bundle/ # 文档写入、路径和索引生成│ ├─ web/ # 网页抓取│ ├─ viewer/ # 知识包可视化│ └─ cli.py / runner.py # 执行入口和流程编排├─ tests/ # 数据源、知识包、查看器、web pass 的行为测试└─ pyproject.toml # Python 包入口和依赖
仓库不只写了规格文件SPEC.md，还把交换约定、运行配方、写入端实现、已生成产物和消费端样板一起给出来了。[2]
提示：文中的 BigQuery 是 Google Cloud（很多人也叫 GCP）提供的全托管、无服务器企业级云数据仓库，面向大规模数据分析；用户不用自己管理底层基础设施，就能用标准 SQL 或 Python 查询和分析 PB 级数据。后面出现的
BQ pass里的BQ，就是 BigQuery 的缩写。按 Google Cloud 价格页当前说明，BigQuery 免费层包含每月 10 GiB 存储和 1 TiB 查询处理量。[7][8]
不过在仔细读 SPEC.md之前，最好先把仓库里的三样东西分清。
samples/不是原始知识数据，也不是智能体自动读取的一整套配置，而是仓库附带的复跑说明：本次要跑哪个外部资料（数据集）、用什么 enrich命令，seeds.txt 则给 web pass提供种子网址。程序实际读取的是命令行参数和 seeds.txt，再由reference_agent 去读外部数据源，把结果写进bundles/。
把仓库拆开看，实际链条是样例说明数据源和运行参数 -> reference_agent 执行 -> bundles 落产物。[2]
OKF 定的是知识包结构、概念文档和最小字段约束
这张图对应的是 OKF 的最小交换约定。
看 SPEC.md 中的规范，OKF 定义的是知识包这个分发单元：一包知识就是一棵目录树，里面放 Markdown 概念文档；每个非保留概念文档都要带 YAML 头部元数据，type 必填，文件路径就是概念 ID，index.md 和 log.md是保留文件名。对消费端的要求也写死了：遇到未知type、额外字段、失效链接，或者缺失index.md，都要尽量读取，不能轻易拒收。[3]
这些约束只负责交换层：知识怎么打包、怎么交换、怎么再被别的系统读进去。知识平台怎么建、语义层怎么统一，都不在这份规范里。整个仓库也是按这个边界走的：先把交换层钉住，再补写入端、消费端和产品接入样板。[2][3]
这张图把角色拆开看：输入源提供上下文，写入动作通常由智能体执行；消费端不只viewer 查看器，也可以是智能体或别的 AI 应用。
这里的“写入端”和“消费端”不要按传统前后端去理解。写入端指的是把源系统知识整理并写成 OKF 知识包的一侧，真正执行写入动作的往往是知识补全智能体；BigQuery、网页资料这些更多是输入源。消费端则是任何会读取、遍历和利用这包文件的系统，不只viewer，也可以是智能体、RAG、搜索索引，或者 Knowledge Catalog 这样的目录系统。AI 在两边都参与，只是写入和消费的角色不同。[2][3]
谷歌在示例仓库里铺了四层落地样板
第一层是规范：先把交换约定写死
仓库的 SPEC.md规范写的很克制。它不是发明一套大而全的类型体系，也没有绑定服务、数据库或界面，只把写入端和消费端之间最小的知识包交换约定定下来。[3]
约定其实很短。写入端要写对：非保留 .md文档必须有可解析的头部元数据，type不能为空；消费端要宽读：未知字段、未知 type、断链、缺少index.md，都不能直接判死。OKF 从一开始就没有往重平台规范那边走，它先解决的是互操作。[2][3]
一句话说，SPEC.md要求的是：写入端从严，读取端尽量宽读。
第二层是reference_agent：谷歌给出了一套 agent 应用示例
reference_agent 是样板 Agent，在真实落地或者开发中我们可以直接参考示例代码的实现逻辑。
它的定位是概念验证版应用：
enrich演示怎么把源数据和网页资料写成 OKF 知识包。 visualize演示怎么把这包文件消费成可交互的单文件查看器。
也就是说，谷歌这一层给出的不是 OKF 本体，而是一套覆盖写入和消费的 agent 应用示例。[2]
这张图把 reference_agent拆成两条线：enrich 负责写入，visualize负责消费；两边都围绕同一个 OKF 知识包。
看模块分工也不复杂：[2]
sources/bigquery.py负责读 BigQuery 元数据 agent.py拆成 BigQuery 智能体和网页摄取智能体 runner.py串写入流程并重建 index.mdviewer/generator.py负责把知识包转成 viz.html，cli.py则提供 enrich和visualize两个入口。
注意这里别把
BigQuery理解成 OKF 的通用名词。它不是 OKF 规范的要求，但在当前这份reference_agent实现里，bq也是唯一内置的数据源。[2][3]
写入侧可以拆成两段：
BigQuery 轮（ BQ pass）先只用 BigQuery 元数据，为每个概念生成一份 OKF 文档。网页轮（ web pass）再拿显式给定的种子网址去抓权威页面，在页面预算、域名白名单和深度限制内，决定是补现有文档、单独生成references/，还是直接跳过。[2]
这张图只压缩了 reference_agent的写入侧：enrich 负责把源数据和网页资料整理成 OKF 知识包。
这里要分开看两层。OKF 本身是厂商中立格式，不绑定特定智能体、框架、模型提供方或服务系统；而在reference_agent 这套应用示例里，写入侧是reference_agent enrich --source bq + web pass，消费侧是reference_agent visualize生成单文件查看器。[2]
在自己项目中落地，你可以继续用这套应用，也可以换成基于 Codex、Claude Code，或者别的智能体框架的写入端和消费端；前提只有一个，就是最后写出来、读进去的知识包还守住同一份 OKF 约定。reference_agent 不是 OKF 本体，而是谷歌先交出来的最短可跑应用示例。[2][3]
第三层是bundles 和复现配方 samples
这一层是仓库里已经生成出来的样例产物bundles/，samples/只是复跑这些样板时附带的一层配方。[2]
仓库直接挂了三组公开样例：GA4 Google Merchandise Store、Stack Overflow、Bitcoin public datasets。每组都对应一份样例说明和一份已经生成好的知识包。[2]
拿一组看结构就够了：
samples//├─ README.md # 跑哪个外部数据集、用什么 enrich 命令└─ seeds.txt # web pass 的种子网址bundles//├─ datasets/├─ tables/├─ references/├─ index.md└─ viz.html
重点不在配方本身，而在谷歌把“输入长什么样”和“产物长什么样”一起摆出来了。前者是可复现说明，后者才是 OKF 真正要交换和消费的东西。samples/ 里选用的 GA4、Stack Overflow、Bitcoin 也只是示例源。
从 OKF 的设计边界看，如果你自己实现写入端，完全可以换成 API 文档、数据库模式、产品帮助中心，或者内部知识页面。[2][3]
查看器（viewer）本身也没被做成重产品。src/reference_agent/viewer/generator.py生成的是一个单文件、自包含的 HTML 页面，包括图结构、头部元数据、渲染后的 Markdown、反向链接、搜索、类型筛选。它就是 reference_agent这套应用里的概念验证版消费端，用来证明知识包一旦生成，已经能被浏览、跳转和消费。[2]
这就是 viz.html的实际样子：左侧把知识包渲染成概念图谱，右侧直接展开当前文档的头部元数据、正文、模式和示例查询。
[可选] 第四层：通过 mdcode 把知识包接进 Knowledge Catalog
这一层讲的是怎么消费 OKF 的知识包。你知不知道 Knowledge Catalog 本身并不重要，先把它理解成 Google Cloud / Dataplex 里的一种目录型消费端就够了；关键在于它不直接读知识包，而是要先过一层mdcode 桥接。前面三层已经够你理解 OKF，也够你把知识包写出来并直接消费；这一层只是“接特定产品”的可选分支。[4][5][6]
到这里，其实可以把消费端分成两类：
直接消费知识包：像 viz.html、智能体、RAG、搜索索引这种，本身就认 OKF 的目录、Markdown、头部元数据和链接，不需要桥接层。映射后再消费：像 Knowledge Catalog 这种有自己对象模型的产品，不直接吃“裸知识包文件夹”，中间要先过一层桥接或映射。[2][4][5][6]
第四层是这条桥：先把知识包映射成目录模型，再通过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。[5][6]
所以这条链真正闭合时，走的是：
OKF 知识包 -> mdcode 目录快照 -> kcmd push -> Dataplex EntryGroup / aspects
如果你的消费端能直接读知识包，第四层就可以跳过；只有消费端不直接认知识包，或者你真要接目录产品、治理系统和现有目录系统时，才需要继续走这层适配。[2][4][5][6]
总结：怎么落地？
在我们自己的项目中落地或者搭配其他Agent使用，不要着急搭平台，也别先搞什么大一统知识体系。最短路径就两段：先把知识包做出来，再判断消费端是直接读，还是要桥接后再读。
如果放到 Codex、Claude Code 这类智能体环境里，我更倾向于把 OKF 做成一组 skill：写入 skill 负责按约定生成概念文档、补头部元数据、维护
index.md和链接；读取 skill 负责遍历知识包、按类型筛选、追踪反向链接，再把相关概念装进上下文。这样 OKF 就不只是“文件夹格式”，而会变成智能体可以反复调用的一套知识读写动作。
先写出最小知识包，再决定是不是要接桥接层；平台接入应该放在最后，不该放在最前。
先挑一个边界清楚的知识子域和数据源，数据库、API 文档、帮助中心、内部知识页都可以。 先决定写入端怎么来。想复用现成样板，就从 reference_agent enrich --source bq这条链起；如果你的源不是 BigQuery，就保留同样的知识包约定，自己补数据源适配器，或者在 Codex / Claude Code 里封装成 OKF 写入 skill。[2][3]先把一包最小可用的知识包写出来，重点不是写满，而是先把头部元数据、链接、 index.md和类型约定跑通。先用 viz.html、智能体、RAG 或搜索去直接消费它，检查这包文件能不能读、能不能跳、能不能查。如果消费端能直接读知识包，这里就够了；只有消费端不直接认知识包，或者你必须接目录产品、治理系统和现有目录系统时，再加桥接层，比如 mdcode或自己的适配器。[2][4][5][6]
