AllWorkin / Articles / 2026.06.12

Google 发布 OKF:Agent 知识库终于有通用格式了(附 3 步搭第一个 Bundle)

Google 发布开放知识格式 OKF v0.1:Markdown + YAML frontmatter + 目录约定,把 LLM Wiki、AGENTS.md 等模式标准化,方便 Agent 读写和跨工具交换。这篇讲它解决什么问题、和 STATE.md/Skill 怎么对应,以及 3 步在代码仓库里搭第一个 Knowledge Bundle。

2026.06.12约 7 分钟#Agent#Gemini#Claude#Cursor

资料来源: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(以及它的边界)

值得关注的点:

  1. v0.1 草案,字段还会长,但「只强制 type」的设计很克制——先跑起来,别等完美 schema。
  2. Producer / Consumer 分离:今天人用 Obsidian 写,明天 Agent 读;后天换 Cursor 也不用翻译层。
  3. 和 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 更好维护。


参考链接

AI工具实战派

觉得有用?每周的新笔记先发公众号。

每周的实战笔记先发在这里。扫码关注,新文章第一时间推给你。

关注 / 加入社群 →