open-knowledge-format ai-agents claude-code markdown developer-tools knowledge-graph

开放知识格式：用于人工智能编程智能体的便携式内存

开放知识格式将编码智能体所学的内容存储为链接式的Markdown文件。它与CLAUDE.md和MCP有何不同，以及如何立即开始使用它。

发布者：REACTAPP.TOP加入本站 2026年10月28日阅读约 11 分钟2417 词

来源: Google Just Quietly Released the Missing Piece for AI Agents. It’s Called OKF.

开放知识格式是一种标准，旨在让智能体记忆具备可移植性、版本控制功能，并能被开发者工具链中的所有工具读取。

每天重新开始带来的问题

任何使用人工智能编码智能体的人都会遇到同样的困境。当前会话结束后，第二天智能体就什么都不记得了。它必须重新进行身份验证流程，再次猜测三年前做出的架构决策背后的原因，还要重新阅读那五个文件，才能重建前一天花一小时才解释清楚的上下文。

常见的解决办法是创建 CLAUDE.md 或 AGENTS.md 文件，即在每次会话开始时读取的上下文文档。但这些工具相当粗糙：每次运行时都会把所有相关内容一并加载，无论其是否重要；它们是为单个平台上的单个智能体设计的，且灵活性较差。此外，它们还会将“始终编写测试”之类的行为指令与“订单表通过 customer_id 与客户表关联”之类的事实混在一起，很快就会变得杂乱无章。

2026年6月12日，Google Cloud 发布了一项旨在填补这一缺口的规范，名为开放知识格式，简称 OKF。这是目前解决智能体记忆问题最为清晰的方案。

当前知识的存储位置

假设某个智能体需要回答如何从事件流中计算每周活跃用户数，那么答案至少分散在四个地方：

+-----------------------+--------------------------------------------+
| WHERE IT LIVES        | WHAT'S THERE                               |
+-----------------------+--------------------------------------------+
| Metadata catalogs     | Table schemas (but vendor-locked APIs)     |
| Wiki / Notion         | Runbooks, metric definitions               |
| Code comments         | Docstrings, inline notes                   |
| People's heads        | Join paths, deprecation warnings           |
+-----------------------+--------------------------------------------+

这里没有任何内容会随代码一同更新，也没有任何东西能在新的上下文窗口出现后仍然存在。每个智能体构建工具都需重新解决同样的上下文组装问题，而每个目录供应商也会自行设计架构。

OKF认为，所缺少的并非另一个平台，而是一种格式。

这种格式是什么

开放知识格式的0.1版本是一种基于Apache 2.0许可的开放、对供应商中立的规范。知识以markdown文件的形式存储在目录中，每个文件都包含YAML格式的元数据。这听起来很简单，因为它确实很简单，这也是有意为之。

没有模式注册表，没有运行时引擎，也不需要特定的 SDK。任何能够使用 cat 命令读取文件的工具都可以处理它，任何能够使用 git clone 命令克隆代码库的工具都可以分发它。整个规范仅占一页，且只有一个必填字段，其余均为可选，由生成方自行决定。

包的结构

包其实只是一个文件夹，而文件的路径则决定了该文件所代表的概念身份。

.okf/
+-- index.md                      <- progressive entry point
+-- log.md                        <- dated change history, newest first
+-- services/
|   +-- index.md
|   +-- auth-api.md               <- one concept = one file
|   +-- payments-service.md
+-- datasets/
|   +-- index.md
|   +-- orders-db.md
+-- metrics/
|   +-- index.md
|   +-- weekly-active-users.md
+-- decisions/
    +-- index.md
    +-- why-we-use-postgres.md

每个包中都预定了两个文件名：

index.md用于实现渐进式展示。智能体通过逐级读取索引来浏览包的内容，只有在任务需要时才会向下深入。这种分阶段加载的方式有助于降低Claude Skills的令牌消耗。
log.md记录了带有ISO日期的变更历史，最新条目显示在最上方。无论是人类还是维护该包的智能体，只要概念有变化都会在其中添加记录。

其余所有文件均为概念文档，其标识方式即为文件路径。概念文档必须具备的唯一前置信息是一个非空的type字段。

---
type: Service
title: "Auth API"
description: "Issues and verifies short-lived access tokens."
resource: https://github.com/acme/auth
tags: [auth, platform]
timestamp: 2026-06-14T10:00:00Z
---

该内容块可包含普通的 Markdown 语法，以及表格。

## Endpoints| Method | Path     | Description               |
|--------|----------|---------------------------|
| POST   | /token   | Exchange creds for a JWT. |
| GET    | /verify  | Validate a token.         |## Why This ExistsSee the decision at [decisions/why-we-separated-auth.md](../decisions/why-we-separated-auth.md).
Joins with [datasets/orders-db.md](../datasets/orders-db.md) for user scoping.

接下来的关键设计步骤是：通过标准的 Markdown 链接将各个概念相互关联。这样一来，这个目录就变成了一个图结构，即一组具有明确关联关系的结构化、可交叉引用的知识体系，而非简单的文档堆叠。

[auth-api.md]
                    /            \
                  links          links
                  /                \
[decisions/why-separated-auth.md]  [datasets/orders-db.md]
                                        |
                                      links
                                        |
                                [datasets/customers-db.md]

能够跟随 Markdown 链接的工具可以遍历该图结构，而拥有文件访问权限的代理则可以对其进行读写操作。

由于只需指定type字段，生产者可自行决定支持哪些类型（服务、数据集、指标、决策规则、运行手册等）、使用哪些可选字段以及包含哪些内容部分。OKF定义的是互操作性标准，而非内容模型。

生产者与消费者

该格式在两端的使用方式相同，因此更换生产者或消费者不会破坏知识结构。

PRODUCERS                       CONSUMERS
---------                       ---------
Human authors       ---->       AI agents
BigQuery pipelines  ---->       HTML visualizers
LLM-generated       ---->       Search indexes
Wiki exports        ---->       Other agents / tools

没有专有账户，没有SDK，也没有中央注册表。其价值源于更广泛的采用率，而非供应商锁定效应。这正符合git、markdown和JSON背后的理念——这些格式之所以能长久使用，正是因為它们无需任何额外条件即可使用。

与CLAUDE.md和MCP的关系

大多数困惑都源于此。OKF并非要取代现有工具，而是填补特定的空白。

+---------------------+---------------------------+---------------------------+
| TOOL                | PURPOSE                   | SCOPE                     |
+---------------------+---------------------------+---------------------------+
| CLAUDE.md           | How the agent behaves     | Per-project, one agent    |
| AGENTS.md           | Repo instructions         | Per-repo, tool-specific   |
| Karpathy LLM wiki   | Agent-maintained notes    | Pattern, not a spec       |
| MCP                 | Live tool access          | Runtime connections        |
| OKF                 | What the team knows       | Cross-project, any agent  |
+---------------------+---------------------------+---------------------------+

一个清晰的思维模型将三个问题区分开来：

CLAUDE.md规定了智能体应如何行事。
OKF记录了团队对该系统的了解情况。
MCP指明了智能体当前可以调用的实时工具。

它们是分层关联的。CLAUDE.md中的某一行可能会要求在执行任何分析任务之前先读取.okf/metrics/文件。OKF数据包则提供CLAUDE.md所指向的结构化知识，而MCP连接则提供OKF文档中描述的实时数据源。

它所借鉴的维基理念

提出“氛围编码”概念、如今更倾向于使用“智能体工程”这一术语的安德烈·卡帕西，发布了一篇关于大语言模型维基的总结文章，获得了5000多颗星。他的观点很简单：当维护工作变得繁琐时，人们就会放弃维基，但智能体不会感到疲倦，也不会忘记交叉引用，更不会难以一次性编辑15个文件。

同样的模式独立地多次出现——在结合了编码智能体的Obsidian中，在满是AGENTS.md文件的仓库中，以及在数十个项目中的index.md和log.md文件中。人们其实都在重复发明同样的东西。OKF的贡献在于明确了每份文档包含哪些字段以及文件名代表什么含义，这样不同的维基甚至BigQuery目录导出的数据也能无需翻译即可协同工作。

两者之间的映射关系分为三层：

KARPATHY LAYER              OKF EQUIVALENT
--------------              --------------
Raw sources (immutable) --> External datasets, docs, APIs
                            (OKF bundles are the compiled layer)

Wiki (LLM-maintained)   --> OKF bundle (*.md + frontmatter)
                            (OKF adds type, resource, tags, timestamp)Schema (CLAUDE.md)      --> Producer/consumer conventions + okf/SPEC.md
                            (org-wide spec replaces per-vault bespoke rules)

Karpathy的方案与OKF都为相同任务预留了index.md和log.md文件，这种一致性并非偶然。

Google随之一同发布的内容

OKF虽然只是一种规范，但Google还发布了三款实用工具：

BigQuery增强工具。该工具针对数据集，为每个表和视图生成OKF概念文档，随后通过第二次LLM处理添加来自文档的引用、架构信息及连接路径。对于数据仓库而言，其输出结果就是已填满内容的.okf/目录。

静态 HTML 可视化工具。它可将任何 OKF 数据包转换为一个独立的 HTML 文件中的交互式图表，无需后端支持，所有内容都留在页面内。概念以节点形式呈现，Markdown 链接则以边形式呈现，点击节点会打开一个类似维基的面板，其中显示渲染后的 Markdown 内容以及标记为“链接至/被引用自”的反向链接。

示例数据包。GitHub 上有三个实际使用公共 BigQuery 数据集的数据包：

+--------------------+----------------------------------+
| BUNDLE             | WHAT IT DOCUMENTS                |
+--------------------+----------------------------------+
| GA4 e-commerce     | Analytics tables and metrics     |
| Stack Overflow     | Public dataset concepts          |
| Bitcoin            | Blockchain dataset structure     |
+--------------------+----------------------------------+

它们既可作为可供复制的初始模板，也可用于证明该格式在不同领域中依然适用。

何时选择 OKF

当知识问题符合以下情况时，OKF 是合适的选择：

每个新的智能体会话中都会重复出现相同的解释。如果总有某个上下文块被不断粘贴到 CLAUDE.md 中，那它就应该存放在 OKF 中。
知识涉及多个项目或团队。CLAUDE.md 仅与一个项目和一个智能体相关，而 OKF 能够将相关内容整合在一起，在不同的代码库、智能体和工具之间传递。
项目文档需要具备版本控制功能。OKF 与它所描述的代码一同存储在 git 中，任何更改都会以差异形式显示，而且通过拉取请求可以将知识更新与代码变更一起提交。

技术栈为 Google Cloud 和 BigQuery。它与 Google 的 Knowledge Catalog 直接集成，能够接收数据包并将其传递给 GCP 的处理节点。

需要知识图谱而非简单的维基结构。Markdown 链接图仅能体现概念间的文本描述关系，无法构建真正的图数据库。

在以下情况下这种选择并不合适：

需要实时数据时，应使用 MCP 技术。
行为规则需要编码处理，这正是 CLAUDE.md 的功能。
项目规模较小，可在单次会话内完成，此时仅使用 CLAUDE.md 即可。

入门指南

其设计理念便是尽可能简化设置流程。

结合 Claude Code 使用

okf-skills 插件包含了三种功能。/okf:okf用于创建和管理插件包，/okf:validate用于检查插件包是否符合标准，而/okf:visualize则用于生成交互式图表。可通过以下命令进行安装：

/plugin marketplace add scaccogatto/okf-skills
/plugin install okf@scaccogatto

任何智能体，包括 Claude Code、Cursor、Codex 以及另外二十多种，都可以使用 npm：

npx skills add scaccogatto/okf-skills

然后运行这些技能：

/okf:okf produce .okf        # create your first bundle
/okf:validate .okf --strict  # check conformance
/okf:visualize .okf          # generate viz.html

为使内容自动保持最新，让 Claude 在处理任务前先读取 .okf/ 文件并记录所学内容，需将 templates/CLAUDE-okf.md 模板复制到项目的 CLAUDE.md 中。此步骤并非强制要求。

手动编写

创建一个 .okf/ 目录并添加一个 index.md 文件。接着为系统处理的每个重要功能各创建一个概念文件。决策记录的格式如下：

---
type: Decision
title: "Why we use Postgres over MySQL"
description: "JSONB support and row-level security were decisive."
timestamp: 2026-03-01T00:00:00Z
tags: [infrastructure, database]
---

正文如下：

## ContextIn early 2026 we evaluated both options. MySQL's JSON support was insufficient for our metadata schema...## DecisionPostgres 16. See [datasets/primary-db.md](../datasets/primary-db.md) for schema docs.

只需如此即可。任何拥有文件访问权限的代理都能立即读取该文件，同时它也可在 Pull Request 中被查看，并在 Git 中进行差异对比。

整个技术栈

以下是 OKF 在会话中与其他组件的关系：

+--------------------------------------------------+
|              AGENT SESSION                       |
+--------------------------------------------------+
|  CLAUDE.md / AGENTS.md                          |
|  (behavioral rules - how agent acts)            |
+--------------------------------------------------+
|  OKF BUNDLE (.okf/)                             |
|  (curated team knowledge - what we know)        |
|  - index.md: entry points per domain            |
|  - concepts/*.md: services, datasets, decisions |
|  - log.md: change history                       |
+--------------------------------------------------+
|  AUTO-MEMORY (memory.md)                        |
|  (what the agent picked up implicitly)          |
+--------------------------------------------------+
|  MCP CONNECTIONS                                |
|  (live tool access - what the agent can do)     |
+--------------------------------------------------+
|  SKILLS (.claude/skills/)                       |
|  (reusable SOPs - how to do specific tasks)     |
+--------------------------------------------------+

每一层都负责解答自身的问题。它们彼此不重叠，而是相互组合。

v0.1尚未解决的问题

谷歌明确表示v0.1只是一个起点，首要目标是实现互操作性。目前仍有若干设计问题有待解决：

矛盾问题。当两个OKF文档对同一事实存在分歧时，目前还不存在合并机制。
过时信息。由于OKF基于文件存储，当系统升级后文档未被更新，属于流程故障而非格式问题。
类型化关系。当前的规范仅使用普通Markdown链接，而诸如“矛盾”、“扩展”或“取代”等更复杂的关联类型仍在由社区进一步研究。
多维度搜索。部分从业者希望拥有比当前最低规范更多的标签功能。

根据反馈，v0.2版本很可能会解决其中的几个问题，而且规范仓库是公开的，正在接收问题反馈和 pull request。

为何乏味的格式能胜出

那些成为基础设施的格式往往都很枯燥。JSON之所以能胜出，是因为它是最简单且无需额外成本就能使用的格式，而非因为它有多聪明。Markdown也是以同样的方式胜出的。

OKF完全符合这一特征：阅读它无需任何成本，编写它也无需任何成本，而且任何能处理文件的工具都能使用它。其价值会随着使用它的生成者和消费者的增加而提升，不会受制于单一供应商的决定。此外，它还记录了人们通过Karpathy的gist、AGENTS.md的习惯以及手工构建的index.md层级结构所自行总结出的模式，这正是问题真正得到解决的最好证明。

Karpathy的观点是，智能体比人类更能维护维基，因为它们不会感到厌烦。OKF则认为，只有当维基能够被传播时，其价值才会不断提升。将这两个观点结合起来，几年后或许就能形成智能体辅助开发的基础框架。现在趁其尚新就加以构建，将来对你以及你指导的每一个智能体都会有益处。