跳转至

Open Knowledge Format（OKF）

概述

Open Knowledge Format（OKF） 是由 Google Cloud 数据分析、商业智能与数据库团队（作者为 Sam McVeety 和 Amir Hormati）于 2026 年 6 月 12 日发布的开放规范，当前版本为 v0.1。它将 Andrej Karpathy 最早提出的"LLM-wiki"模式正式化，定义为一种可移植、可互操作的格式，用于表示 AI 智能体与人类共享的元数据、上下文及精选知识。

OKF 旨在解决上下文碎片化问题：AI 智能体目前必须从分散、互不兼容的来源——元数据目录、内部 Wiki、代码注释、部落知识——拼凑上下文，导致跨团队与跨智能体部署时工作重复、结果不一致。OKF 明确定位为格式，而非平台：无需任何专有账号、运行时、压缩方案或 SDK。Google 表示欢迎外部贡献、替代实现以及在 Google 产品之外的采用，且该规范采用版本化设计，支持向后兼容扩展。

核心概念与架构

结构

OKF 包（bundle）是一个由带 YAML frontmatter 的 Markdown 文件组成的目录，以可导航的层级结构组织：

sales/
├── index.md
├── datasets/
│   ├── index.md
│   └── orders_db.md
├── tables/
│   ├── index.md
│   ├── orders.md
│   └── customers.md
└── metrics/
    ├── index.md
    └── weekly_active_users.md

文档格式

每份文档由少量结构化 YAML frontmatter 字段与自由格式的 Markdown 正文组成。示例：

---
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
---
# Schema
| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Globally unique order identifier. |
| `customer_id` | STRING | FK to [customers](/tables/customers.md). |

# Joins
Joined with [customers](/tables/customers.md) on `customer_id`.

核心组件

  • Frontmatter 字段：type 是唯一必填字段；title、description、resource、tags 和 timestamp 是常见可选字段，生产方可自由添加自定义字段。
  • 图结构：文档之间的普通 Markdown 链接构成可导航的知识图谱（例如，某张表的文档链接到其关联的客户表）。
  • index.md：每个目录的可选入口文件，支持渐进式展开——智能体先读取高层次索引，再深入详细文件。
  • log.md：某一知识领域的可选时序历史文件。

设计原则

  • 意见最小化——只有 type 字段是必需的；其余均由生产方自行约定。
  • 生产方与消费方解耦——格式本身即契约；写入侧与读取侧的工具可独立演进。
  • 格式，而非平台——不绑定任何云服务、数据库、模型厂商或智能体框架；从不要求专有账号或 SDK。

核心特性

特性 说明
纯 Markdown 可在任意编辑器中阅读，在 GitHub 上渲染，可被标准搜索工具索引
纯文件 可打包为 tarball 发布，可托管在 git 仓库，可挂载到任意文件系统
纯 YAML frontmatter 少量结构化、可查询字段
交叉链接 标准 Markdown 链接在文档间建立知识图谱关系
人机双读 同一文件同时服务于人类读者和智能体，无需转换

应用场景

OKF 专为捕获以下"知识原子"而设计：

  • 表与数据集的 Schema
  • 业务指标定义
  • 事故处理手册（runbook）
  • 系统间的关联路径
  • API 弃用公告

典型工作流：智能体（或人类）在回答"如何从事件流中计算每周活跃用户数？"这类问题时，可遍历 OKF 包的指标、表与关联定义图，无需每次从头推导上下文。

参考实现

Google 随规范一同发布了三个参考实现，均位于 GoogleCloudPlatform/knowledge-catalog 仓库：

实现 说明
增强智能体（Enrichment Agent） 遍历 BigQuery 数据集，起草 OKF 文档并补充引用来源
静态 HTML 可视化工具 将 OKF 包转换为交互式图视图；自包含，无需后端
示例包 GA4 电商、Stack Overflow 和 Bitcoin 公共数据集

OKF 同时也是 Google Cloud Knowledge Catalog 的摄取格式，该产品使用 OKF 向 Google 智能体提供精选知识。

优势

  • 希望将版本可控、git 原生知识与代码并存的团队
  • 希望避免智能体上下文与元数据厂商锁定的组织
  • 用单一制品桥接人类文档（Wiki）与智能体可消费上下文
  • 需要跨产品、跨组织、跨智能体框架迁移的可移植知识库

局限

  • v0.1，发布于 2026 年 6 月 12 日——版本极早；生态工具、校验器及 Google 以外的采用尚未建立
  • 尚无正式治理机构（例如，尚未捐赠给基金会，不同于 AGENTS.md → AAIF 的路径）
  • 未发布任何关于检索质量或智能体性能提升的量化基准测试数据
  • 意见最小化意味着大型组织内部的一致性依赖于内部约定，而非规范本身

与其他规范的关系

规范 侧重点 与 OKF 的关系
AGENTS.md 仓库/项目的持久化、常驻智能体指令 相同的"Markdown + 结构化元数据"理念，应用于行为指令而非知识/元数据
Agent Skills / SKILLS.md 按需触发的工作流 互补的按需规范；OKF 用于参考知识，而非可执行流程
上下文工程——卸载（写出）策略 将信息保存到活跃上下文窗口之外，供按需检索 OKF 是"卸载"模式的标准化基底——一个结构化、可链接的文件树，智能体可按需即时读取
智能体记忆——语义记忆 智能体积累的持久化事实与知识 OKF 包是语义记忆内容（Schema、定义、实体关系）的可移植存储格式

最佳实践

挑战 / 领域 说明 解决方案 / 建议
避免上下文碎片化 知识分散于目录、Wiki、代码注释各处 整合到随代码版本化的 OKF 包中
智能体与人类双重受众 面向人类编写的文档智能体难以解析，反之亦然 使用 OKF 的 Markdown + 最小化 frontmatter，让单一文件同时服务两类受众
知识图谱导航 智能体需要高效定位相关实体（表、指标、关联） 通过文档间的普通 Markdown 链接构建可遍历图；添加 index.md 文件支持渐进式展开
保持知识时效性 静态文档随系统演进而过时 使用增强智能体（如参考实现中的 Enrichment Agent）遍历实时系统，起草并更新带引用的 OKF 文档

参见

参考资料