Google Open Knowledge Format 完整指南：面向 AI Agent 的开放知识格式

Google 发布 Open Knowledge Format（OKF），以 Markdown 与 YAML Frontmatter 统一保存和交换面向人类与 AI Agent 的知识。本文详解 Knowledge Bundle、Concept、来源追踪、可信度、时效性、生命周期与计算验证机制，并给出 Obsidian 和软件项目中的实践方法。

发布于 2026年8月12日下载 Markdown

Open Knowledge Format v0.2

Open Knowledge Format（OKF）是 Google 提出的一套开放知识格式规范。它使用最常见的 Markdown + YAML Frontmatter 保存知识，让同一套知识既能被人阅读，也能被 Codex、Claude Code 等 AI Agent，以及 Obsidian、Git、MCP、RAG 等不同系统消费。OKF 与 Karpathy 提出的 LLM Wiki 思想非常接近，但两者解决的问题不同：

LLM Wiki 更关注“Agent 如何持续维护知识”，OKF 更关注“这些知识应该按照什么格式保存和交换”。

当每个人、每个团队都使用自己的 Markdown 结构时，Agent 需要先理解不同项目的目录、字段、链接和来源约定。OKF 的作用，就是给这些知识建立一套尽可能轻量、开放且统一的格式。

简单来说，它就是一套 Markdown + YAML 的格式规范。

基础结构：Knowledge Bundle、Concept 与渐进式披露

OKF 把一组相关知识文件称为 Knowledge Bundle，可以理解为“知识包”。一个 Knowledge Bundle 本质上就是一个目录树：

knowledge/
├── index.md                          ← 整个知识包的导航目录
├── log.md                            ← 重要更新记录
│
├── concepts/
│   ├── index.md
│   ├── agent-memory.md
│   └── context-engineering.md
│
├── tools/
│   ├── index.md
│   ├── codex.md
│   └── claude-code.md
│
└── references/
    └── index.md

知识包中最基本的单位叫 Concept。虽然 Concept 直译是“概念”，实际可以理解为一个知识条目。

一个 Concept 就是一个 Markdown 文件，它可以描述任何知识：技术概念、研究笔记、软件服务、API、数据库表、业务流程、指标或公司 Policy。例如：

knowledge/
└── concepts/
    └── agent-memory.md

这个文件的 Concept ID 就是：concepts/agent-memory。也就是说，文件在 Knowledge Bundle 中的路径，本身就是它的 Concept ID。

YAML Frontmatter

每个普通 Concept 都必须是 Markdown 文件，并在顶部包含 YAML Frontmatter。 OKF v0.2 唯一始终强制要求的字段只有：

---
type: Research Topic
---

type 表示这个文件描述的是什么类型的知识。例如可以使用 Research Topic、AI Tool、API Endpoint、Metric、Policy 等。OKF 不规定固定的 type 列表，但同一个知识库应该尽量保持自己的类型命名一致。实际使用时通常还会加入：

---
type: Research Topic
title: Agent Memory
description: AI Agent 长期保存和重新利用知识的机制。
tags: [ai-agent, memory]
---

其中 title 是标题，description 是一句话摘要，tags 用于横向分类。description 对 Agent 尤其重要，因为 Agent 可以先读取元数据，判断文件是否与当前任务有关，再决定是否加载完整正文。

这就是 Progressive Disclosure（渐进式披露）：index.md → title / description → 相关 Concept → 完整正文 → 继续沿链接读取 目标不是把整个知识库一次性塞进 Context Window，而是按需逐层加载。

index.md：知识导航

index.md 是 OKF 的保留文件，主要负责告诉人和 Agent：这个目录里有什么知识？ Bundle 根目录的 index.md 可以声明 OKF 版本：

---
okf_version: "0.2"
---

# AI Agent

* [Agent Memory](concepts/agent-memory.md) - Agent 长期保存和重新利用知识的机制。
* [Context Engineering](concepts/context-engineering.md) - 控制 Agent 当前应该加载哪些上下文。

# Tools

* [Codex](tools/codex.md) - OpenAI 的 AI Agent。
* [Claude Code](tools/claude-code.md) - Anthropic 的命令行 AI Agent。

子目录也可以继续设置自己的 index.md，形成分层导航。Concept 之间推荐使用普通 Markdown Link：

Agent Memory 与 [Context Engineering](/concepts/context-engineering.md) 密切相关。

这样 Markdown 文件成为节点，Markdown Link 则自然形成知识之间的连接。

log.md：更新记录

log.md 记录 Knowledge Bundle 或某个目录的重要变化：

# Knowledge Update Log

## 2026-08-10

* **Creation**: 新增 [Agent Memory](concepts/agent-memory.md)。
* **Update**: 更新 [Context Engineering](concepts/context-engineering.md) 的来源资料。

## 2026-08-09

* **Initialization**: 创建初始知识包。

日期使用 YYYY-MM-DD，最新记录放在最上面。

OKF v0.2 的五个核心机制

基础的 Markdown、YAML、index.md 和链接解决的是“如何建立统一知识格式”。但当大量知识开始由 Agent 自动生成和维护以后，还需要回答五个更重要的问题：

机制	中文理解	核心字段	解决的问题
Provenance	来源追踪	`sources` + Citation	这条知识从哪里来？
Trust	可信度	`generated`、`verified`	谁生成的？谁验证过？
Freshness	时效性	`stale_after`	现在是否可能已经过时？
Lifecycle	生命周期	`status`	是草稿、正式版本还是已废弃？
Attestation	计算过程验证	`runtime`、`parameters`、`executor`、`attester`	结果是否按照规定方法计算？

Provenance：来源追踪

Provenance 解决的是：这条知识依据了什么资料？ 核心字段是 sources：

sources:
  - id: okf-spec
    resource: https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
    title: Open Knowledge Format v0.2 Specification

resource 指向原始资料，id 则给这个 Source 一个稳定标识。如果还需要说明正文中的某一句话具体来自哪个 Source，可以使用 Citation，也就是 Markdown 脚注：

OKF 中，文件路径就是知识条目的 Concept ID。[^okf-spec]

[^okf-spec]: Open Knowledge Format v0.2 Specification

这里的 [^okf-spec] 对应 YAML 中的：sources[].id: okf-spec。因此可以形成：结论 → Citation → Source → 原始资料。 Source 还可以记录 author、usage_count、last_modified 等信息，为 Consumer 判断来源可靠性提供客观信号。

Trust：生成与验证

知道来源之后，还需要知道：这条知识是谁生成的？有没有真正被验证？ 核心字段是：

generated:
  by: research-agent/1.0
  at: "2026-08-10T10:00:00+08:00"

verified:
  - by: human:jason
    at: "2026-08-10T11:00:00+08:00"

generated 表示当前内容由谁生成，以及最后一次发生有意义修改的时间。 verified 表示谁真正对照 Source 或真实资源检查过内容。

常见 Actor 表示方式：

research-agent/1.0：Agent 或工具
human:jason：人工审核
process:schema-check：自动化程序

Consumer 可以根据 verified 推导：没有验证 → unverified，只有机器验证 → machine-confirmed，存在 human:* → human-reviewed。因此 OKF 不需要直接写 trust: high 之类的主观评分。

Freshness：时效性

Freshness 解决的是：这条知识以前是正确的，现在还值得继续使用吗？

核心字段：

stale_after: "2026-12-31"

它表示：从这个日期开始，这条知识应该重新检查。几个容易混淆的时间字段：

字段	含义
`sources[].last_modified`	原始 Source 最后修改时间
`generated.at`	当前 Concept 最后发生有意义修改的时间
`stale_after`	从什么时候开始应该重新检查

Lifecycle：生命周期

Lifecycle 回答：这条知识现在处于什么状态？ 核心字段：

status: stable

标准状态有三个：

draft：草稿，尚未准备好正式使用
stable：当前正式版本
deprecated：已经废弃，但为了历史记录和旧链接继续保留

Freshness 与 Lifecycle 是两个不同维度。例如：

status: stable
stale_after: "2026-12-31"

意思是：它现在仍然是正式版本，但到年底以后需要重新检查。

Attestation：计算过程验证

Attestation 主要用于数据库、BI、财务指标等重要计算场景。它解决的是：Agent 给出的数字，是否真的按照经过批准的方法计算出来？ 例如公司规定 Revenue 必须使用固定 SQL，就可以建立一种特殊 Concept：

---
type: Attested Computation
title: Revenue for Fiscal Year

runtime: bigquery

parameters:
  - name: year
    type: integer
    required: true

executor:
  resource: /references/run-bigquery.md
  receipt: [job_id, executed_sql, result]

attester:
  resource: /references/revenue-check.py
---

# Computation

```sql
SELECT SUM(net_amount)
FROM finance.orders
WHERE fiscal_year = @year
```

runtime 表示执行环境； parameters 表示 Agent 可以提供的参数； executor 定义如何执行，并返回实际执行记录，也就是 Receipt（执行凭证）； attester 是确定性检查程序，用来检查 Receipt，并判断实际执行是否符合批准的计算约束。

Agent 可以提供：year = 2026。但不应该擅自修改 SQL。这种机制主要用于财务数据、利润率、业务指标等高要求场景，普通个人知识笔记通常不需要。

完整 OKF v0.2 Concept 模板

下面是一份为了展示字段关系而设计的完整模板。

它使用 Attested Computation 作为类型，因此能够同时展示普通 Concept 字段和计算验证字段。实际使用时不需要机械填写所有字段，没有明确用途的字段应该直接省略。

---
# 唯一始终强制要求的字段
type: Attested Computation

# 推荐字段
title: Example Concept
description: 用一句话说明这条知识是什么，以及为什么值得读取。
resource: https://example.com/canonical-resource
tags: [example, research]

# ===== 生命周期与时效性 =====
# draft | stable | deprecated
status: stable
# 从这个日期开始应重新检查
stale_after: "2026-12-31"

# ===== 内容生成信息 =====
generated:
  by: research-agent/1.0
  at: "2026-08-10T10:00:00+08:00"

# ===== 验证信息 =====
verified:
  - by: process:auto-check
    at: "2026-08-10T10:30:00+08:00"

  - by: human:jason
    at: "2026-08-10T11:00:00+08:00"

# ===== 来源追踪 =====
sources:
  - id: official-docs
    resource: https://example.com/docs
    title: Official Documentation
    author: process:official-docs
    usage_count: 1200
    last_modified: "2026-08-01"

  - id: internal-policy
    resource: /references/internal-policy.md
    title: Internal Policy
    last_modified: "2026-07-20"

# usage_count 所对应的统计时间窗口
usage_window:
  from: "2026-07-01"
  to: "2026-07-31"

# ===== Attested Computation =====

# 执行环境
runtime: bigquery

# Agent 可以提供的参数
parameters:
  - name: year
    type: integer
    required: true

# 如果计算代码保存在独立文件中，可以使用 computation 指向它
# computation: /references/computations/revenue.sql

# 如何执行
executor:
  resource: /references/executors/run-bigquery.md
  receipt:
    - job_id
    - executed_sql
    - result

# 如何验证执行结果
attester:
  resource: /references/attesters/revenue-check.py
---

# Definition

这里保存真正的知识正文。

某一个需要来源支持的结论。[^official-docs]

# Relationships

参见 [Another Concept](/concepts/another-concept.md)。

# Computation

```sql
SELECT SUM(net_amount)
FROM finance.orders
WHERE fiscal_year = @year
```

[^official-docs]: Official Documentation

对于普通个人知识笔记，通常没有必要使用 Attested Computation。

一个更实际的普通 Concept 基线通常只需要：

---
type: Research Topic
title: Agent Memory
description: AI Agent 长期保存和重新利用知识的机制。
tags: [ai-agent, memory]

generated:
  by: research-agent/1.0
  at: "2026-08-10T10:00:00+08:00"

sources:
  - id: official-docs
    resource: https://example.com/docs
    title: Official Documentation
---

真正重要的知识，再根据需求加入 verified、status 和 stale_after。

实际使用场景

Obsidian 个人知识库

不需要把整个 Obsidian Vault 全部强制改造成 OKF。

Daily Note、Inbox、Canvas、模板和临时草稿可以继续使用原来的结构，只把真正需要被 Agent 长期复用的知识整理成独立 Knowledge Bundle。

My-Obsidian-Vault/
├── README.md                         ← Vault 自身说明
├── AGENTS.md                         ← Codex / Claude Code 的操作规则
│
├── inbox/                            ← 尚未整理的信息
├── daily/                            ← Daily Notes
│
├── sources/                          ← 原始文章、论文、GitHub、视频转录
│   ├── articles/
│   ├── papers/
│   └── github/
│
└── knowledge/                        ← OKF Knowledge Bundle
    ├── index.md
    ├── log.md
    │
    ├── concepts/
    │   ├── index.md
    │   ├── ai-agent/
    │   └── knowledge-management/
    │
    ├── tools/
    │   ├── index.md
    │   ├── codex.md
    │   └── claude-code.md
    │
    └── references/

推荐流程：

原始资料 → Agent 研究 → 更新或创建 Concept → 添加 Source / Citation → 更新 index.md → 更新 log.md → Git 保存历史

其中原始资料继续作为 Source of Truth，OKF 保存的是经过整理、关联和综合后的长期知识。

软件项目与 Agent 文档

代码仓库可以建立独立 .okf/：

my-project/
├── AGENTS.md                         ← Agent 行为规范
├── README.md
├── src/
├── tests/
│
└── .okf/                             ← Agent 长期项目知识
    ├── index.md
    ├── log.md
    ├── architecture/
    ├── services/
    ├── decisions/
    ├── APIs/
    └── runbooks/

OKF 不应该重新复制一遍源代码。更适合保存的是：架构为什么这样设计、历史决策、重要业务约束、模块关系、API 的业务含义、不能破坏的规则以及故障处理流程。代码仍然是实现层面的 Source of Truth，OKF 是 Agent 可以长期读取的语义和背景知识。

API 与业务约定

OKF 也不应该取代 OpenAPI。OpenAPI 继续负责参数、Schema、Response、Status Code 等正式接口定义；OKF 保存的是 OpenAPI 很难表达的业务语义和上下文。

project/
├── openapi/
│   └── api.yaml                      ← API 正式 Schema / Source of Truth
│
└── .okf/
    ├── index.md
    ├── APIs/
    │   ├── authentication.md         ← 认证架构和业务约定
    │   └── create-order.md           ← Endpoint 的业务语义和限制
    │
    └── policies/
        └── order-creation.md         ← 正式业务规则

例如 API Concept 可以直接指向真实 OpenAPI：

---
type: API Endpoint
title: Create Order
description: 创建新的 Customer Order，并返回唯一订单 ID。
resource: ../../openapi/api.yaml#/paths/~1orders/post

sources:
  - id: openapi
    resource: ../../openapi/api.yaml
    title: Production OpenAPI Specification

  - id: order-policy
    resource: /policies/order-creation.md
    title: Order Creation Policy
---

正文只保存调用顺序、业务限制、幂等规则、与其他 Endpoint 的关系等真正需要 Agent 理解的上下文。数据库 Schema、业务指标和企业 Policy 也可以采用相同思路；其中需要严格保证计算方式的指标，再进一步使用 Attested Computation。

使用建议与注意事项

实际采用 OKF v0.2 时，不要为了“符合规范”而机械填写所有字段。

可以按照需求逐步增加：

最小实现： type
实际可读知识： type + title + description
可追溯知识： generated + sources + Citation
长期可信知识： verified + status + stale_after
重要业务计算： Attested Computation + executor + receipt + attester

另外需要注意几个原则：

OKF 是格式，不是知识管理软件。 它不能替代 Obsidian、Git、RAG、MCP 或数据库，而是可以和这些系统组合使用。
不要重复真正的 Source of Truth。 源代码、数据库 Schema、OpenAPI、官方文档仍然应该保持为原始事实来源。OKF 更适合保存这些资产背后的语义、关系和长期知识。
警惕知识 Drift。 原始系统已经变化，但 OKF 文档没有同步更新，就会产生“文档和真实系统不一致”的问题。重要知识应该结合 stale_after、自动检查、Git Diff 和人工 Review。
不要一开始过度工程化。 对个人知识库而言，type、title、description、sources 已经能够获得很大价值；只有真正重要的内容才需要逐步增加验证和生命周期机制。

OKF v0.2 真正重要的并不是 YAML 本身，而是它建立了一套面向 Agent 的知识约定：

知识应该能够被定位、被导航、被追溯来源、被判断可信度、被判断是否过期，并且能够脱离某一个 Agent 或平台长期存在。

这也是 OKF 可以与 Obsidian、Git、Codex、Claude Code、MCP、RAG、数据库和其他 Agent 系统组合使用的核心原因。