仓名和那句 GitHub 简介(「Google Cloud Knowledge Catalog Tools and Samples」)把里面的东西说小了。真正的主角不是一堆厂商 SDK 样例,而是 OKF,Open Knowledge Format。仓库自己的 okf/README.md 写得很直白:「本仓库主要讲的是 Open Knowledge Format。贡献在于格式本身。」其余的富集 agent 和图谱可视化,都是为了让这个格式在生产端和消费端都摸得着。
OKF 到底是什么
OKF 是一份规范,用来表示「知识」,也就是数据周围的元数据、上下文和经过梳理的洞见,形式是一个装满纯 markdown 文件的目录,每个文件带 YAML frontmatter。没有 schema 注册中心,没有中央权威,不依赖任何运行时。规范里的说法很冲:能 cat 一个文件,你就能读 OKF;能 git clone 一个仓,你就能分发它。
有意思的是谁在做这件事。「Knowledge Catalog」是 Google Cloud 把 Dataplex(它的托管元数据目录产品)改的新名字,所以这个仓挂在一个以 Google 付费服务命名的名下。可 OKF 偏偏刻意保持厂商中立。规范点名 Unity Catalog 和 Collibra 这两个直接竞品,说它们都是合法的生产方,还写明这个格式「不绑定任何特定的 agent、框架、模型供应商或服务系统」。一家云巨头在自家产品名下发布一份反锁定的格式,这层张力值得留意,也是为什么这个仓读起来更像一次标准化尝试,不像一份样例堆。
它为什么上了 trending
star 曲线把故事讲清楚了。仓库 2026-05-04 创建,之后几周一直停在一星附近。6 月中旬突然拉直:6 月 13 日约 700 星,6 月 14 日过 1300,6 月 15 日过 2100,到 6 月 16 日约 2320 星(截至 2026-06 的快照)。这个窗口正好对上落地 agents/ 目录和 OKF 参考 agent 的那批提交(6 月 12 至 13 日的 PR #28、#40、#42)。格式公开的时机,恰逢「agent 该怎么存放和交换知识」变成一个拥挤的问题,而来自 Google Cloud 的一份开放规范,足以快速吸走注意力。
仓里都有什么
- 规范(
okf/SPEC.md),目前是 v0.1 Draft。它把一个 bundle 定义为 markdown 概念文件构成的目录树,保留index.md(目录清单,用于渐进式展开)和log.md(更新历史)两个文件名,并用普通的 markdown 链接在概念之间连边,连成图,不止于树形结构。 - 一个参考富集 agent(
okf/,包名enrichment-agent),基于 Google Agent Development Kit,模型后端用 Gemini。BigQuery 是第一个元数据源,藏在可插拔的Source接口后面。它分两遍跑:BQ 遍仅凭 BigQuery 元数据为每个概念写一份 OKF 文档,然后是可选的 web 遍,由 LLM 通过fetch_url工具爬取种子 URL 来富集文档。 - 三个开箱即看的 bundle,放在
bundles/:GA4 电商数据集、Stack Overflow 公共数据集、Bitcoin 区块与交易,每个都配一份自包含的viz.html图谱查看器,消费端无需后端、无需安装。 - 一个 toolbox(
toolbox/),含「metadata as code」(mdcode),把目录元数据当成源码工件来同步,另有富集 harness。
真正关键的那条 frontmatter 规则
OKF 对一份概念文档「必须声明什么」相当克制。在 §4.1 里,唯一必填的 frontmatter 键是 type(一个短字符串,比如 BigQuery Table 或 Metric)。title、description、resource、tags、timestamp 全是可选,生产方还能随意加额外键。这种极简就是整个设计赌注:一个程序化生产方可以只吐出 {"type": "API Endpoint"}、别的什么都不写,照样合规。
安装并运行参考 agent
格式本身不需要任何工具,但参考 agent 是个普通的 Python 包,从源码安装。在 okf/ 目录下(Python 3.11 以上):
python3.13 -m venv .venv
.venv/bin/pip install -e .[dev]最小富集运行指向一个 BigQuery 数据集和一个输出目录;加 --no-web 跳过 LLM 的 web 遍:
.venv/bin/python -m enrichment_agent enrich \
--source bq \
--dataset <project>.<dataset> \
--no-web也可以用顶层 README 里的按钮在 Cloud Shell 打开仓库。没有发布到 PyPI 的包,也没有 pip install okf;把这个 agent 当成你 clone 下来的参考代码,而不是装上就用的产品。
适合什么,不适合什么
适合:你想要一份可移植、能在 git 里逐行 diff 的知识语料,人和 LLM 都能不靠 SDK 直接读;或者你受够了元数据被锁在某个目录产品的私有 API 后面。因为一个 bundle 就是一堆文件,它天然能和 Obsidian、MkDocs、Notion 以及静态托管拼起来。
不适合:你今天就需要一份冻结稳定的规范(它是 v0.1 Draft,每周都在变);或者你以为这是个开箱即用的 Google Cloud 产品。参考 agent 明确需要 Google Cloud 凭证、BigQuery 和 Gemini 访问权,所以「自动生产」那一半并不厂商中立,尽管格式是。仓库还带一句明确免责:它「不是 Google 官方产品」。
OKF 对比其它 agent 知识格式
OKF 是一种格式,不是一个目录系统,所以最真实的对照是另外几种「用 markdown 表达、供 agent 和 LLM 读取的知识」开放约定,再加上它对位的那个目录系统老玩家。star 数为截至 2026-06。
| 项目 | Star | 许可 | 是什么 | 同一思路? |
|---|---|---|---|---|
| OKF(本仓) | 约 2.3k | Apache-2.0 | markdown + YAML frontmatter 的知识 bundle 格式,附参考 agent | 格式即产品 |
| Agent Skills | 约 151k | (未标注) | 用 markdown + YAML frontmatter 封装 agent 能力 | 同样的 md+frontmatter 形态,载荷不同 |
| llms.txt | 约 2.4k | Apache-2.0 | 一种把站点内容暴露给 LLM 的 markdown 约定 | markdown 给 LLM 读,范围更窄 |
| Unity Catalog | 约 3.4k | Apache-2.0 | 开源数据目录服务(Databricks) | 是个目录系统,不是文件格式 |
前两行的容器是同一个:markdown 加 YAML frontmatter,载荷一边是 skill,一边是数据概念。OKF 伸手去拿同一种形态、没有另造一种新文件类型,这正是这张表里值得记住的地方。
在它之上动手前该知道的坑
- 参考校验器一度比规范更严。 正如贡献者在 issue #62 里指出的,
validate()把REQUIRED_FRONTMATTER_KEYS设成了("type", "title", "description", "timestamp"),而 §4.1 只要求type。一个只有type的极简 bundle,在 PR #64 修掉之前会被自带校验器判不通过。如果你钉在了早期某个 commit,记得核对你的校验器对齐的是规范,而不是那个旧元组。 - v0.1 是个移动靶。 issue 区满是正在进行的规范争论:
okf_version该放哪里(#57)、范围要不要扩到单概念文档之外、提议的 §9 一致性语料(#62)、以及面向 OpenAPI 等来源的生产方提案(#56)。这些都有用,但别把格式当成已冻结。 - 它不是 Google 官方产品,尽管挂着 GoogleCloudPlatform 组织和产品名。支持力度和存续性是社区级的,没有 SLA 兜底。
相关仓库
- anthropics/skills:结构上最近的表亲 Agent Skills,用的是同一套 markdown 加 frontmatter 容器。
- 这个格式所属的更大趋势:LLM 工具生态。
常见问题
Knowledge Catalog 和 Dataplex 是一回事吗? Knowledge Catalog 是 Google Cloud 给原来 Dataplex 起的新名字,即它那套 AI 驱动的数据目录与元数据平台。这个仓装的是围绕该产品的工具、样例和 OKF 规范,但 OKF 本身的设计是可以脱离它独立工作的。
OKF 是 Google 官方产品吗? 不是。仓库自己的免责声明写着它「不是 Google 官方产品」。它挂在 GoogleCloudPlatform 组织下、用 Apache-2.0 许可,但请当成开源参考作品看待,别当成受支持的服务。
OKF 的参考 agent 需要 Google Cloud 和 Gemini 吗? 需要。这个富集 agent 基于 Google Agent Development Kit,模型后端是 Gemini,第一个数据源是 BigQuery,所以跑它需要 Google Cloud 凭证。你产出的格式是可移植的,但自带的生产方不是。
OKF 绑定某个厂商吗? 格式是明确厂商中立的:规范邀请 Unity Catalog、Collibra 这类竞品来生产 OKF,并声明它不绑定任何 agent、框架、模型或服务系统。只有参考 agent 是 Google 专属的。
OKF 文档要求哪些 frontmatter?
只要一个键:type。其余(title、description、resource、tags、timestamp)都可选,生产方还能加自己的键。注意早期版本的参考 validate() 曾错误地多要了几个,已在 PR #64 修复。
OKF 和 Agent Skills 怎么比? 两者都把内容存成带 YAML frontmatter 的 markdown,人和 agent 都能直接读。Agent Skills 封装的是可执行的 agent 能力;OKF 封装的是关于数据的知识与元数据。容器相同,载荷不同。