open-knowledge-format

开放知识格式（OKF）—— v0.1

Google Cloud 于 2026 年 6 月 12 日 发布了 开放知识格式 v0.1——这是一项开放规范，将 LLM-wiki 模式正式化为一种可移植、厂商中立的 AI Agent 知识格式。

**该设计刻意保持精简：**由带有 YAML frontmatter 的 Markdown 文件组成的目录。不需要 schema registry、中央管理机构或必需工具。

“只要你能 cat 文件，就能读取 OKF；只要你能 git clone 仓库，就能发布它。”

核心概念

概念	定义
知识包	由 Markdown 文件组成的独立目录树。分发单位。
概念	一个独立的知识单元——一个 Markdown 文件。可用于描述表、指标、操作手册、API 或任何想法。
概念 ID	去掉 .md 后缀的文件路径（例如，tables/users.md 的 ID 为 tables/users）。
Frontmatter	每个文件顶部包含结构化元数据的 YAML 块。
正文	frontmatter 后的标准 Markdown 内容。
链接	从一个概念指向另一个概念的 Markdown 链接——用于表达关系。

参考文件

参考资料	何时加载	文件
规范摘要	需要完整的 OKF v0.1 规范、一致性标准和字段定义时	references/spec-summary.md
知识包架构	创建或组织 OKF 知识包时——目录布局、索引文件、交叉链接约定	references/bundle-architecture.md
使用案例	需要真实案例、第三方实现和采用模式时	references/use-cases.md

脚本

脚本	用途	何时加载
okf-bundle-validate.py	验证 OKF 知识包目录——检查 frontmatter、必需字段、保留文件名和交叉链接完整性	创建或修改 OKF 知识包并想验证其是否符合规范时

资源文件

资源	用途	路径
概念模板	包含所有推荐 frontmatter 字段和正文部分的 Markdown 模板文件	assets/concept-template.md
示例知识包	最小但完整的 OKF 知识包，展示目录结构、索引文件和相互链接的概念	assets/example-bundle/

知识包结构

path/to/bundle/
├── index.md                      # Optional. Directory listing for progressive disclosure.
├── log.md                        # Optional. Chronological update history.
├── <concept>.md                  # A concept at the bundle root.
└── <subdirectory>/               # Subdirectories organize concepts into groups.
    ├── index.md
    ├── <concept>.md
    └── <subdirectory>/
        └── …

名为 index.md 和 log.md 的文件是保留文件——它们有明确定义的语义，不得用于概念文档。

Frontmatter 字段

---
type: <Type name>                  # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI for the underlying asset>
tags: [<tag>, <tag>, …]            # Optional
timestamp: <ISO 8601 datetime>     # Optional last-modified time
# … other producer-defined key/value pairs
---

必需字段：type——用于标识概念类型的简短字符串。类型不会在中央统一注册。生产者可选择描述性值；消费者应能妥善处理未知类型。

常见正文部分：

标题	用途
# Schema	对资产的列／字段进行结构化描述
# Examples	具体用法示例，通常以代码块呈现
# Citations	支持正文中论述的外部来源

交叉链接

概念之间通过标准 Markdown 链接互相连接：

• **绝对路径（相对于知识包）：**以 / 开头，相对于知识包根目录。推荐使用——文档移动后仍保持稳定。
• **相对路径：**标准 Markdown 相对路径。

从概念 A 指向概念 B 的链接表示二者存在某种关系。具体关系类型（引用、依赖、联接）由周围的文字表达，而非链接语法。

消费者必须能够处理失效链接——目标不存在的链接并非格式错误；它可能表示相关知识尚未编写。

一致性

如果一个内容包符合以下条件，则其符合 OKF v0.1：

1. 每个非保留的 .md 文件都包含可解析的 YAML 前置元数据
2. 每个前置元数据块都包含非空的 type 字段
3. 保留文件名（index.md、log.md）遵循其定义的结构

**使用方不得因以下情况拒绝内容包：**缺少可选前置元数据字段、未知的 type 值、未知的前置元数据键、失效的交叉链接或缺少 index.md 文件。

与其他格式的关系

格式	OKF 的差异
Karpathy 的 LLM Wiki	OKF 规定了互操作界面——必需字段、保留文件名、一致性标准
Obsidian / Notion vaults	OKF 仅规定格式——不包含工具、运行时或 UI。任何编辑器都适用
AGENTS.md / CLAUDE.md	OKF 采用多文件、分层、交叉链接结构——而非单一约定文件
Metadata-as-code 仓库	OKF 标准化文件格式，使不同的生产方和使用方能够互操作
领域架构（Avro、Protobuf、OpenAPI）	OKF 引用这些架构——不会取代或替换它们

快速入门

# 1. Create a bundle directory
mkdir my-knowledge && cd my-knowledge

# 2. Create a concept file
cat > datasets/sales.md << 'EOF'
---
type: BigQuery Dataset
title: Sales
description: All sales-related tables for the retail business.
tags: [sales]
timestamp: 2026-06-18T00:00:00Z
---
The sales dataset contains [orders](/tables/orders.md) and [customers](/tables/customers.md).
EOF

# 3. Add an index for navigation
cat > index.md << 'EOF'
# Knowledge Bundle

* Sales Dataset (`datasets/sales.md`) - Retail sales data in an example OKF bundle
EOF

# 4. Validate your bundle
python3 scripts/okf-bundle-validate.py .

注意事项

• **类型值没有集中注册。**请选择描述性类型（BigQuery Table、Playbook、Metric）。使用方应妥善处理未知类型。
• **文件路径就是身份标识。**重命名文件会更改其概念 ID。请使用稳定路径，或在文档中添加重定向。
• index.md 不使用前置元数据（内容包根目录可选添加 okf_version 除外）。正文是包含链接的 Markdown 列表。
• log.md 的日期标题必须采用 ISO 8601 格式（YYYY-MM-DD）。
• **交叉链接没有类型。**关系语义体现在正文中，而非链接语法中。图构建器会将所有链接视为有向边。
• **OKF 未规定标签浏览格式。**希望聚合标签的生产方应在使用时扫描前置元数据并生成相应内容。
• **OKF v0.1 是草案。**规范将持续演进。次要版本升级会添加向后兼容的功能；主要版本升级可能会更改必需字段。使用方应尽力处理未知版本。