资料来源:Google Cloud 官方博客(2026-06-12)+ Open Knowledge Format v0.1 规范
你让 Claude Code 回答「这个表的 user_id 怎么 join?」——它可能翻一遍仓库,可能去猜 schema,可能胡编。
与此同时,同一份知识可能散落在:数据目录 API、Confluence、代码注释、某个 senior 的脑子里,还有你项目根目录的 CLAUDE.md。
每个 Agent 都在重复组装上下文,每套工具各写各的格式。
6 月 12 日,Google 发布了 Open Knowledge Format(OKF,开放知识格式)v0.1:把「LLM Wiki / AGENTS.md / 元数据即代码」这套模式,写进一份厂商中立的开放规范。规范仓库在 GoogleCloudPlatform/knowledge-catalog(截至发稿约 1.4k star)。
这篇我们不写「一文读懂协议」。写我们关心的:对于我们这种用 Cursor / Claude Code / Codex写代码的人,OKF 到底能干嘛、怎么上手。
一、缺的不是又一个知识服务,是一套格式
Google 博客里讲得很直:Agent 缺的是上下文,而眼下上下文极度碎片化——各家 catalog 各搞各的 API,wiki 各搞各的 frontmatter,知识锁在产生它的那个系统里。
之前写过的 《Karpathy 的 LLM Wiki》 思路你大概见过:别让模型每次从原始文档里重新发现知识,编译成 Markdown 维基,持续更新。我之前还写过 《Hermes Agent + LLM Wiki》 那套。
Obsidian vault、CLAUDE.md / AGENTS.md、仓库里的 index.md + log.md——形状都像,但没有统一约定。A 团队写的 bundle,B 团队的 Agent 读不懂字段含义。
OKF 的定位就一句:
Markdown 文件 + YAML frontmatter + 少量约定。 没有新运行时(runtime),没有强制 SDK。
git clone就能搬,cat就能读。
这和我在《Claude Fable 5 十四步》里写的 STATE.md 复利是同一类问题:模型无状态,文件有状态。OKF 把「文件长什么样」标准化了。
二、OKF 长什么样(30 秒版)
一个 Knowledge Bundle(知识包)= 一目录 Markdown 树。每个 Concept(概念)= 一个 .md 文件,可以是表、指标、API、Runbook,或抽象业务规则。
目录示例(来自规范):
sales/
├── index.md
├── datasets/
│ └── orders_db.md
├── tables/
│ ├── orders.md
│ └── customers.md
└── metrics/
└── weekly_active_users.md
每个概念文件头部是 YAML frontmatter,规范只强制一个字段:type(其余 title、tags 等都可选):
---
type: BigQuery Table
title: Orders
description: One row per completed customer order.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, revenue]
timestamp: 2026-05-28T14:30:00Z
---
正文用普通 Markdown:表结构放 # Schema,外部出处放 # Citations,概念之间用 Markdown 链接连成图——不只靠文件夹父子关系。
两个保留文件名(不能拿来做普通概念):
| 文件 | 用途 |
|---|---|
index.md |
目录索引,Agent 逐层展开用 |
log.md |
变更日志,按日期记录谁加了什么 |
说白了:Obsidian + Hugo + LLM Wiki 的交集,Google 写成了 1 页能读完的 SPEC。
三、和你在用的东西怎么对应
| 你现在的做法 | OKF 里叫什么 |
|---|---|
CLAUDE.md / AGENTS.md 项目规则 |
可拆成多个 Concept,或根目录 index.md 指过去 |
| Skill 里的程序性(procedural)记忆 | type: Playbook 的概念文档 |
Claude Fable 5文章里的 STATE.md |
很像 bundle 里的 log.md + Verified facts 段 |
| Karpathy LLM Wiki | 几乎同构,OKF 多了互操作约定 |
| 商业 metadata catalog | 可用 Agent 导出成 OKF bundle,给任意模型读 |
OKF 不取代 Skill 或 MCP——它解决的是知识产物怎么打包、怎么跨工具交换。Producer 可以是人、可以是 enrichment Agent、可以是 BigQuery 导出脚本;Consumer 可以是 Claude Code、Codex、Cursor、或一个静态 HTML 可视化工具(Google 参考实现里带了)。
四、3 步:给代码项目搭第一个 OKF Bundle
不用等 Google Cloud。任何 repo 都能先放一版 okf/ 或 docs/knowledge/。
1、定根目录 + 写 index.md
# Project Knowledge
* [Auth module](/modules/auth.md) - JWT 与 RBAC 约定
* [API conventions](/playbooks/api-conventions.md) - 错误码与分页
* [Tables](/tables/) - 核心表说明(如有)
index.md 不要 frontmatter(规范如此),只做渐进披露——Agent 先扫目录,再决定打开哪页。
2、每个重要概念一个文件,必填 type
例如 modules/auth.md:
---
type: Module
title: Auth
description: JWT 登录 + RBAC;middleware 顺序固定。
tags: [auth, security]
timestamp: 2026-06-12T00:00:00Z
---
# Rules
- 顺序:rate_limit → jwt → rbac(反了会 401)
- 用户 ID 字段是 `auth_users.uid`,不是 `auth_users.id`
# Related
见 [API conventions](/playbooks/api-conventions.md)
3、会话结束写 log.md,会话开始读 bundle
这和 STATE.md 复利一模一样:
- 结束:今天试了什么、验证了什么、哪条规则写进哪个 Concept
- 开始:Claude Code 里
@docs/knowledge/index.md或写进CLAUDE.md:「动手前先读 OKF bundle」
Google 参考流程里还有 enrichment Agent:扫 BigQuery 数据集 → 自动生成每表一个 Concept → 第二遍 LLM 补 citation 和 join 路径,数据团队很爽,纯代码团队手写 5~10 个 Concept 就够起步。
五、我怎么看 OKF(以及它的边界)
值得关注的点:
- v0.1 草案,字段还会长,但「只强制
type」的设计很克制——先跑起来,别等完美 schema。 - Producer / Consumer 分离:今天人用 Obsidian 写,明天 Agent 读;后天换 Cursor 也不用翻译层。
- 和 Claude Fable 5「自我改进」同向:Verified facts、General rules、log——OKF 是把这类结构从「每个团队自创」拉成可交换格式。
别指望它解决的:
- 不会自动替你想清楚知识该怎么分(SCHEMA 还是要人定)
- 不是 RAG 替代品——原始 PDF 仍要有人或 Agent 编译进 Concept
- 不是 Google 专属;但首批 tooling(Knowledge Catalog ingest、BigQuery enrichment)在 GCP 生态里
Karpathy 模式 + Skills + STATE.md,你已经在搭「复利知识系统」了。OKF 多提供一层:你的 bundle 可以和别人的 bundle 对话,Agent 之间可以换上下文。
如果你主力 Claude Code,我的建议是:别另起炉灶。在现有 repo 里加 docs/knowledge/,把 CLAUDE.md 里最长、最常改的几段拆成 Concept,根目录 index.md 链过去——一周就能试出是否比单文件 CLAUDE.md 更好维护。
参考链接
- Google Cloud — Introducing the Open Knowledge Format:https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing/
- OKF v0.1 规范(SPEC):https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
- knowledge-catalog 仓库:https://github.com/GoogleCloudPlatform/knowledge-catalog
- Karpathy — LLM Wiki gist:https://gist.github.com/karpathy