Google 开源 OKF：先搞清楚它有什么用，再谈它是什么-开发者社区

OKF 很轻，轻到一页规范。轻，才有机会被很多人说。它不保证知识正确，不做完整治理，也不会让 Agent 突然变聪明。它做的是更底一层的事：给该被共享的上下文一个不绑平台的家。

你让智能体算「周活怎么从事件流来」，它常会表演式检索一轮：翻元数据目录、扫 Wiki、抠几段代码注释，再拼出一个听着挺完整的答案。模型未必不会推理，麻烦在于那些碎片根本不是同一种写法。目录绑着专有 API，Wiki 有自己的页面结构，共享盘里躺着过期表，准口径还锁在几个老人脑子里。厂商再造一套知识图，Agent 团队再写一套上下文装配，知识却卡在最先产生它的那个界面里，搬不走。

2026 年 6 月，Google Cloud 发布了 Open Knowledge Format，简称 OKF。中文里常说它是「人和 Agent 共读的知识规范」。这话没错，但容易让人先问「格式长什么样」，却跳过更实在的一句：它想改的是知识怎么生产和消费，不是再卖你一个知识服务。

所以这篇先讲作用，再讲定义、结构和消费方式。读完你该能判断：值不值得用，以及用在哪一层。

先说作用：它要当知识交换的中间语

别先背字段。把 OKF 看成中间语更准：谁都能写，谁都能读，中间少做一次翻译。

组织里智能体真正缺的，往往不是更强的基础模型，而是稳得住的内部上下文。表是什么意思、指标在业务上怎么定、两套系统正确的关联怎么走、旧 API 何时弃用、事故先翻哪本手册——这些东西决定答案能不能落地。它们现在散在互不兼容的表面上：元数据目录、第三方 Wiki、共享网盘、代码注释、笔记本单元格，还有口头传承。

浪费是双向的。做 Agent 的人每次重做上下文装配；做目录的人反复发明差不多的数据模型；知识本身很难跨产品、跨组织流动。你以为缺一个更聪明的检索服务，Google 的判断是：缺格式。格式可以不绑账号、不绑 SDK、不绑某朵云；能进 Git，能用编辑器打开，也能被 Agent 当文件读进上下文。

作用可以分几层看。

同一份知识同时给人用、给机器用。不是人看 HTML、机器另吃一套 JSON，而是同一个 Markdown：人可以cat，模型可以直接吞。少一层翻译，就少一层漂移——你改了给人看的说明，机器还读着旧结构，双轨知识库里这事太常见。

生产端和消费端拆开。人手写的包，智能体能读；元数据导出流水线吐出的包，可以丢进可视化器；一个模型综合出来的包，另一个模型还能接着查。格式是合同，两端工具能换。你不必先押宝某家 Agent 框架才敢沉淀知识，也不必换模型供应商就重做知识库。

组织知识重新回到版本控制习惯里。Diff、review、归因、回滚，开发者本来就会，现在直接作用在知识文件上。知识不再只活在「某次聊天里被检索到过」的幽灵状态，而变成可审计的仓库资产。Karpathy 那句很刺耳也很实在：模型不怕烦，不会忘了改交叉引用，一次能碰十几个文件。个人 Wiki 常常死于维护负担，模型偏偏擅长这类记账。OKF 想做的，是把各团队土法炼钢的 Markdown 知识库，收成可以互换的约定。

跨系统交换也便宜一点。数据团队从 BigQuery 导出一包概念文档，平台用自己的检索吃进去，安全用静态页审阅，业务 Agent 用同一包回答「这个指标能不能上周报」。交换单位不是专有 API 的响应体，而是一棵目录：clone、挂载、本地 grep 都行。

它不替你写好全部业务知识，只给你一种可携带、可共读、可交换的载体，让「上下文装配」少一点每个项目从头发明。

信息图：知识碎片汇入统一知识包，人与智能体同读

知识碎片汇入统一知识包，人与智能体同读

作用落到场景：它到底替你省哪一类工作

「中间语」说着正确，还是要落到你会碰到的痛点。

做数据智能体的人，最烦「表有了，语义没有」。列名能扫到，业务含义、关联路径、新鲜度 SLA、弃用说明却散在别处。常见用法是：富集型智能体先走元数据，再按权威文档补引用、补模式、补关联，落成一包可浏览的概念页。人审一遍口径，以后 Agent 从这包读，而不是每次重爬目录 API。

做平台和知识工程的人，最烦「每个 Agent 自己攒上下文」。今天 Collibra，明天内部 Wiki，后天 Confluence 导出。OKF 可以当汇合点：各源各自写 producer，统一吐 OKF；消费侧只维护一套 reader。原系统仍可当权威源，OKF 更像可版本化、可离线分发的交换层。

做编码智能体的人会觉得它和AGENTS.md、仓库百科是亲戚，但分工不同。AGENTS.md适合短而硬的操作规程；仓库百科适合解释模块负责哪条链路。OKF 更偏数据与系统周边的元知识和策展说明：表、指标、手册、API、引用材料都可以是概念。它不替代指令文件，给的是需要长期积累、还可能跨团队交换的那类知识一个互操作面。

做知识治理的人更关心：知识能不能离开某个产品存活。专有目录好用，一旦绑死账号、SDK 和计费，迁移成本会反噬。OKF 把自己放在格式而不是平台——价值来自多少人说同一种语言，不是谁拥有服务器。

别指望它自动保证口径正确，也别指望它替你做权限模型，更不会把 Avro、OpenAPI 吞进去重做一遍。它管的是怎么装、怎么传、怎么共读；内容对不对，还得靠生产纪律、引用和人审。后面读定义时，预期别抬太高。

再说定义：OKF 到底是什么

作用清楚了，定义反而好讲。

OKF（Open Knowledge Format）是一套开放的知识表示规范，面向人和智能体。它描述的是环绕数据与系统的元数据、上下文和经过整理的说明，不是要取代业务库，也不是要取代领域 schema。当前是 v0.1 Draft，刻意做得很薄：一棵 Markdown 目录，文件头用 YAML frontmatter 放少量可查询字段。没有中央 schema 注册中心，没有强制运行时，也不要求「必须装某个 SDK 才能读」。

Google 的说法是：把近年反复出现的「LLM Wiki」模式，收成可移植、可互操作的格式。用过 Obsidian、Notion、Hugo，或见过仓库里一堆index.md/log.md给 Agent 导航的人，形状会眼熟。以前各家看起来像，却没约定每个文档至少带什么、哪些文件名保留、链接怎么解释。OKF 把互操作所需的最小约定钉死，其它内容模型留给生产者。

术语上，分发单位叫 Knowledge Bundle（知识包）：一棵自包含、有层次的知识文档集合。基本单元叫 Concept（概念）：一个知识点一个 Markdown 文件，可以是表、API，也可以是指标、业务流程。概念 ID 是路径去掉.md——tables/orders.md就是tables/orders。身份跟着路径走，所以更推荐从包根写绝对链接，子目录挪动时少断。

光听术语不够，先看一棵最小可读的包。人和 Agent 打开仓库时，大致就是这种目录：

sales-knowledge/ ├── index.md # 包根目录：先看有什么 ├── log.md # 可选：变更日志 ├── tables/ │ ├── index.md │ ├── orders.md # 概念：客户订单表 │ └── customers.md # 概念：客户表 └── playbooks/ ├── index.md └── freshness-alert.md # 概念：新鲜度告警处置手册

index.md和log.md是保留名，不能当概念文档；其余.md都是概念。目录怎么分层由生产者定，规范不强制叫tables/或playbooks/——上面只是常见写法。

信息图：知识包目录树与保留文件名标注

知识包目录树与保留文件名标注

每个概念文件两部分：YAML frontmatter + Markdown 正文。硬性要求很少：非保留文件要有可解析 frontmatter，且必须有非空type。推荐字段大致是title、description、resource、tags、timestamp。resource指向底层资产 URI；抽象概念可以没有。生产者可加扩展键，消费者应尽量保留未知键，别因为多字段就拒收。

一张「客户订单」表写成概念页，完整示范如下（字段与结构对齐官方 SPEC 示例）：

--- type: BigQuery Table title: Customer Orders description: One row per completed customer order across all channels. resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders tags: [sales, orders, revenue] timestamp: 2026-05-28T14:30:00Z --- # Schema | Column | Type | Description | |---|---|---| | order_id | STRING | Globally unique order identifier. | | customer_id | STRING | Foreign key into [customers](/tables/customers.md). | | total_usd | NUMERIC | Order total in US dollars. | | placed_at | TIMESTAMP | When the customer submitted the order. | # Joins Joined with [customers](/tables/customers.md) on `customer_id`. # Citations [1] [BigQuery table schema](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)

读的时候可以按三块拆：最上是机器好过滤的元数据（type必填，其余推荐）；中间是人和模型一起看的结构化正文；底部 Citations 把论断钉回外部证据。包内链接写成/tables/customers.md这种从包根出发的路径，挪目录时更稳。

信息图：概念文件解剖，题头字段与正文分区

概念文件解剖，题头字段与正文分区

不是所有概念都绑一张表。事故手册可以没有resource，类型写成 Playbook，正文写触发条件与步骤，并用链接指回相关表：

--- type: Playbook title: Incident response — data freshness alert description: Steps to triage a freshness alert on the orders pipeline. tags: [oncall, incident] timestamp: 2026-04-12T09:00:00Z --- # Trigger A freshness alert fires when `orders` lags more than 30 minutes behind its expected SLA. See the [orders table](/tables/orders.md). # Steps - Check the ingestion job dashboard. - Confirm whether upstream producers stalled. - Page the on-call owner listed in the orders concept page.

渐进披露靠index.md。它没有 frontmatter，只列举「这里有什么」，让人和 Agent 先扫目录再下钻。包根或子目录都能放，例如：

# Tables * [Customer Orders](orders.md) - One row per completed customer order. * [Customers](customers.md) - Customer master records used by orders joins. # Playbooks * [Freshness alert](../playbooks/freshness-alert.md) - Triage lagging orders pipeline.

log.md按日期倒序记变更，方便回答「这包最近改过什么」：

# Directory Update Log ## 2026-05-22 * **Update**: Added join notes on [Customer Orders](/tables/orders.md). * **Creation**: Established [Freshness alert](/playbooks/freshness-alert.md). ## 2026-05-15 * **Initialization**: Created foundational directory structure.

概念之间用普通 Markdown 链接。链接本身不带「依赖 / 关联 / 父子」类型标签，语义写在周围句子里。做图谱时，多半把链接当成有向边。断链被明确允许：目标还不存在，可能只是还没写完，不算格式错误。Agent 半生成、包在长、重构做到一半，都是常态，规范选择先可用。

符合 v0.1 的条件很短：每个非保留 Markdown 有可解析 frontmatter；每个 frontmatter 有非空type；若有index.md/log.md，就按对应结构来。缺可选字段、未知类型、未知扩展键、断链、缺索引，消费者都不该拒收。规范能装进一页纸，才有机会当中间语：学得会、写得出、换得动。

流程图：从源系统到知识包再到人与智能体消费

从源系统到知识包再到人与智能体消费

定义背后的几条设计原则

为什么看起来这么简单，却坚持不做成另一个平台？大致是这几条。

尽量少规定。每个概念只强制type。有哪些类型、正文怎么分节、还加哪些字段，留给生产者。它钉的是互操作表面，不是内容本体。想「一次定全世界 taxonomy」的人可能不过瘾，但对生态更友好：领域可以有自己的类型习惯，消费者容忍未知类型就行。

生产与消费独立。谁写、谁读，不绑死。手写、流水线、模型综合可以并存；浏览、检索、Agent 推理也可以并存。参考实现里的 BigQuery 富集 Agent、静态 HTML 图谱，都只是一种写法/读法，不是规范本身。

是格式，不是平台。不绑云、库、模型供应商、Agent 框架；读写分发都不要求专有账号。Google 更新了 Cloud Knowledge Catalog 去 ingest OKF，那只是生态里的一个消费者，不是格式前提。价值来自说话的人够不够多——这话既是愿景也是风险：v0.1 还早，治理和外部提案怎么进规范，都会决定它能不能真火起来。

边界也清楚：不规定固定概念类型 taxonomy，不规定存储与查询基础设施，不取代 Avro、Protobuf、OpenAPI——只引用，不吞并。权限、审批、血缘仍在生产者和周边系统手里。OKF 只管「装进文件的那一层」说同一种话。

从示范里能带走的东西

对照目录树和两份概念页，几件事会变硬。

路径即 ID，包内引用优先从根路径写。机器要过滤和预览的进 frontmatter，叙述与证据进正文。今天只有 Schema，明天补 Joins，后天补 Citations，都不破坏符合性。目录打成 tarball 或丢进 Git，别人 clone 就能读。导航先看index.md，再下钻概念页；要沿革看log.md。

官方同时开源参考实现和示例包，也是这个道理。规范再短，也需要看得见的符合实例。仓库里有公开数据集方向的示例 bundle（GA4 电商、Stack Overflow、Bitcoin 等），还有把任意包渲成单文件交互图谱的可视化器。它们不是证明 Google 工具最好，而是降低试错成本：先看一包长什么样，再决定自己的 producer 怎么写。

知识包怎么被消费

写成什么样说完了，还得说怎么读、怎么用。分两层：规范嵌在结构里的消费约定；以及你把 Agent / 产品接上去时的落地方式。前者能当官方意图讲，后者是工程接法，别写成 Google 下发的运行时协议。

规范里已经写明的消费方式

OKF 没有单独的 Agent SDK，也没有逐步任务状态机。它把消费嵌进文件结构：人或智能体面对同一棵目录、同一类 Markdown。

入口是文件，不是专有 API。工程师可以cat概念页，LLM 可以把同一文件原样读进上下文。官方列举的消费形态包括静态文件服务、Obsidian / Notion / MkDocs、把文件载入上下文的模型、搜索索引，以及仓库自带的图谱可视化器。会读 Markdown，就具备消费能力。

导航靠渐进披露：先index.md，再下钻概念页。任意目录可放index.md，枚举「这里有什么」，让人或 Agent 打开单篇前先建立地图。这是规范里最接近阅读策略的一条：别默认整包灌进上下文，一层层看目录，再打开需要的概念。某层没有index.md时，消费者也可以根据目录和 frontmatter 现场合成索引——规范允许。

筛选靠 frontmatter，细节靠正文。必填的type给消费者做路由、过滤、展示；title/description服务搜索摘要与预览；tags、resource、timestamp是推荐键。常见读法：先扫头部判断要不要读、这篇是表还是手册；需要执行细节再读 Schema、步骤、示例。机器查头部，叙述与证据看正文。

关系靠 Markdown 链接遍历。/tables/customers.md就是下一步该打开的节点。关系含义写在周围句子里，不是链接协议上的类型字段。做图谱时，通常把链接当成有向边。断链不是错误：目标可能还没写完，消费者应继续，别整包拒收。

变更沿革可看log.md。回答「这包最近改过什么」、决定要不要重索引时，按日期倒序的日志比盲扫全部文件直接。它是可选文件，一旦存在，就是消费侧的时间线入口。

消费必须宽容。缺可选字段、未知type、未知扩展键、断链、缺索引，都不应拒收。官方默认包会半生成、会生长、会重构——消费者要能读「不完美但可用」的包。

串起来就是一条短链：打开包根 → 读index.md（或合成目录）→ 用type/ 描述 / 标签缩小范围 → 打开概念页读正文 → 沿链接补全相关概念 → 需要时看log.md或跳转resource。

人和 Agent 走同一条链；差别在于 Agent 通常还需要你在外侧告诉它：包根在哪，什么任务必须先读这包。

流程图：从索引渐进下钻到概念页并沿链接遍历

从索引渐进下钻到概念页并沿链接遍历

官方样板消费者长什么样

仓库没规定你必须用某框架，但给了可对照的消费样板。

可视化器是 reference consumer。对任意 OKF 包跑visualize，生成单文件 HTML：概念做成力导向图，节点按type着色，边来自正文交叉链接；点选可看 frontmatter 与渲染正文，包内链接改成站内跳转，并带搜索与类型过滤。它证明：消费等于解析目录与 Markdown，不是调用专有知识 API。

目录产品也能 ingest。Google Cloud Knowledge Catalog 已能吃进 OKF，再供给自家 Agent。这是「先把文件编译进平台，再让 Agent 查」的官方路径之一——文件仍是交换格式，平台是可选服务层。

参考富集 Agent 主要站在生产侧：从 BigQuery 等源写出/enrichment 概念页，示范如何生产 OKF，不是消费协议本身。产销可以是不同程序，甚至不同组织；格式是中间的合同。

接到你自己的 Agent 时怎么落地

规范停在文件约定。要把消费跑进日常 Agent，还需要你们自己的接法。下面按投入从低到高，都和上面的官方消费链兼容，但是工程选择，不是 SPEC 条文。

直接读文件。给 Agent 读目录/读文件的工具，把知识包挂进工作区；在系统提示或项目指令里写明包根，并约定：涉及口径、表语义、关联、手册类问题，先读包根index.md，再按链接下钻，避免跳过索引整库盲扫。这最贴近官方说的「LLM 原样读文件」。

先索引，再回源读原文。扫一遍 frontmatter，按type/tags/ 标题建轻量索引；Agent 先拿候选概念 ID 与description，最终仍打开对应.md原文作答。索引加速发现，原文少一层摘要失真。

先 ingest，再经服务查询。把包导入 Knowledge Catalog、自建搜索或图谱，Agent 通过平台 API / MCP 取知识。包很大、需要权限和统一检索时更合适；Git 里的目录仍宜当可审计真相源，平台当加速层。

无论哪条接法，消费纪律最好写进团队约定，别指望模型自己悟：关键结论以概念页加 Citations 为准；与上游冲突时升级给人；未知type当普通概念处理，别报错退出。OKF 保证的是读得懂、换得动；信不信、何时问人，仍是产品治理。

它和你已经在用的东西是什么关系

有人会问：这不就是 Obsidian 库吗？不就是仓库里的 docs？不就是 LLM Wiki？

相近，关键差别是「被规定过」。Obsidian、个人 Wiki、AGENTS.md族、元数据即代码仓库，都在用 Markdown、目录和交叉链接。各自好用，却默认不为彼此合作而设计：字段含义不同，索引约定不同，保留文件名不同。OKF 把互操作所需的最小规则钉下来，让不同生产者写出来的包，有机会被不同消费者直接吃掉，少写一层适配器。

和传统数据目录比，OKF 更像交换格式，不是治理中台。目录产品仍可以很重：权限、审批、血缘、质量规则继续做；OKF 提供导出/导入/给 Agent 读的轻路径。和 RAG 比，它更偏先编译成活知识再按需读，而不是每次提问都从原始碎片重拼——这点和 Karpathy 对 LLM Wiki 的论述一致：综合过程应沉淀成可积累的页面，别蒸发在聊天记录里。

和 MCP、工具协议比，层次不同。MCP 更关心 Agent 怎么连工具、怎么拿实时能力；OKF 更关心长期依赖的组织知识怎么落盘、怎么交换。两者可以叠：工具查实时状态，OKF 包提供稳定语义与手册。别指望一个格式解决所有 Agent 基础设施问题。

若要采用，实务上怎么起步

落地时按作用倒推，别一上来对着字段表开工。

先盘点：智能体反复问却答不稳的，到底是哪类知识？表语义、指标口径、关联路径、事故手册、API 弃用说明——选一类最痛的做最小包。再选生产者：人手写几页也成立；有元数据系统就写导出；有文档站点就写爬取富集。参考 Agent 只是样板。然后定你们自己的消费路径：提示词里写包根并先读index.md，或 ingest 进检索/目录后再供给 Agent——这些是工程选择，不是官方强制步骤。消费端越早存在，包越不容易变成又一个没人维护的 docs 目录。最后才谈扩展字段和类型命名。类型字符串没有中央注册，尽量写得自解释，团队内保持稳定；消费者要对未知类型保持宽容。

维护节奏也很要紧。允许断链和半成品，不等于鼓励长期腐烂。log.md、Git history、定期巡检（过时断言、孤儿页、缺引用）仍然需要。人适合当审稿人和选题人；模型适合做交叉引用与批量改页。这个分工成立，活知识才成立；否则你只是换了一种更时髦的文档坟场格式。

还有一句现实的：格式成不成功看生态。v0.1 是起点，Google 欢迎外部 producer / consumer 和扩展提案。个人现在就可以用它组织自己的数据与系统知识包；企业更适合先在一个域内试点「导出 OKF → Agent 只读这包」，再决定要不要推成组织标准。别一上来追求全公司 taxonomy 完美——那正好违背「尽量少规定」。