Introducing the Open Knowledge Format

介绍开放知识格式

As foundation models continue to improve, the lack of relevant context often limits what they can do, especially as they are used to build agentic systems. While these models can help you write code, summarize documents, or analyze a dataset, they still need the right information to produce accurate and actionable results. 随着基础模型的不断改进，缺乏相关上下文常常限制它们的能力，尤其是在构建智能体系统时。虽然这些模型可以帮助你编写代码、总结文档或分析数据集，但它们仍然需要正确的信息才能产生准确且可操作的结果。

That’s why today, we’re introducing the Open Knowledge Format (OKF), an open specification that formalizes the LLM-wiki pattern into a portable, interoperable format. This is a vendor-neutral, agent- and human-friendly standard for representing the metadata, context, and curated knowledge that modern AI systems need.因此，今天我们推出开放知识格式（OKF），这是一种开放规范，将LLM-wiki模式形式化为可移植、可互操作的格式。这是一个供应商中立、对智能体和人类友好的标准，用于表示现代AI系统所需的元数据、上下文和精选知识。

As published, OKF v0.1 represents knowledge as a directory of markdown files with YAML frontmatter, with a small set of agreed-upon conventions that let wikis written by different producers be consumed by different agents without translation.根据发布内容，OKF v0.1将知识表示为包含YAML前置元数据的Markdown文件目录，并采用一套约定俗成的小型规则，使不同生产者编写的wiki能够被不同智能体直接使用，无需翻译。

That's it. No complex compression scheme, no new runtime, no required SDK. A bundle of OKF documents is:仅此而已。没有复杂的压缩方案，没有新的运行时，没有必需的SDK。一组OKF文档具有以下特点：

• Just markdown — readable in any editor, renderable on GitHub, indexable by any search tool纯Markdown——可在任何编辑器中阅读，可在GitHub上渲染，可被任何搜索工具索引

• Just files — shippable as a tarball, hostable in any git repo, mountable on any filesystem纯文件——可作为tarball分发，可托管在任何Git仓库中，可挂载到任何文件系统

• Just YAML frontmatter — for the small set of structured fields that need to be queryable: type, title, description, resource, tags, and timestamp纯YAML前置元数据——用于需要可查询的少量结构化字段：类型、标题、描述、资源、标签和时间戳

If you've used Obsidian, Notion, Hugo, or any of the LLM wiki patterns that have emerged over the past year, the shape will feel familiar. OKF formalizes the small set of conventions needed to make these patterns interoperable.如果你使用过Obsidian、Notion、Hugo或过去一年出现的任何LLM wiki模式，你会觉得这种形式很熟悉。OKF将实现这些模式互操作性所需的小型约定集正式化。

Let’s take a look at the problem that OKF can solve for your organization, how it works, how to get started with it, and what’s next.让我们看看OKF能为你的组织解决什么问题、它的工作原理、如何开始使用以及下一步计划。

A fragmented context landscape碎片化的上下文环境

In most organizations, the information that foundation models use is overwhelmingly internal knowledge: the schema of a table, your business’ meaning of a metric, the runbook for an incident, the join paths between two systems, the deprecation notice for an old API, etc.在大多数组织中，基础模型使用的信息绝大多数是内部知识：表的模式、业务指标的含义、事件处理手册、两个系统之间的连接路径、旧API的弃用通知等。

Today, these atoms of knowledge live in a variety of highly fragmented systems:如今，这些知识原子存在于各种高度碎片化的系统中：

• Metadata catalogs with their own APIs拥有自有API的元数据目录

• Wikis, third-party systems, or in shared drivesWiki、第三方系统或共享驱动器

• Code comments, docstrings, or notebook cells代码注释、文档字符串或笔记本单元格

• The heads of a few senior engineers少数资深工程师的头脑

When an AI agent needs to answer "How do I compute weekly active users from our event stream?" it has to assemble the answer from these scattered, mutually incompatible surfaces. Every vendor offers its own catalog, its own SDK, its own knowledge-graph schema, and none of the knowledge is easily portable across products or organizations.当AI代理需要回答“如何从事件流中计算周活跃用户？”时，它必须从这些分散且互不兼容的表面中拼凑答案。每个供应商都提供自己的目录、自己的SDK、自己的知识图谱模式，而这些知识都无法轻松地在产品或组织之间移植。

The result: Every agent builder is solving the same context-assembly problem from scratch, every catalog vendor is reinventing the same data models, and the knowledge itself is locked behind whichever surface created it.结果是：每个代理构建者都在从头解决相同的上下文组装问题，每个目录供应商都在重新发明相同的数据模型，而知识本身则被锁定在创建它的表面之后。

Knowledge as a living wiki知识作为活的Wiki

Developer teams are changing how they build AI agents. Instead of using models to search the same documents for the same facts over and over, you can give your agents a shared markdown library that grows more useful over time. This lets your agents take on the drudgery of reading and updating their own files, while your team curates the content and manages it like code. 开发团队正在改变构建AI代理的方式。与其让模型一遍又一遍地搜索相同的文档以获取相同的事实，你可以为代理提供一个共享的Markdown库，该库会随着时间的推移变得越来越有用。这可以让你的代理承担阅读和更新自己文件的繁琐工作，而你的团队则负责策划内容并像管理代码一样管理它。

Andrej Karpathy, the prominent AI researcher and educator, articulates this idea most crisply in his LLM Wiki gist. "LLMs don't get bored, don't forget to update a cross-reference, and can touch 15 files in one pass," he writes. The bookkeeping that causes humans to abandon personal wikis is exactly what LLMs are good at.著名AI研究员和教育家Andrej Karpathy在他的LLM Wiki要点中最清晰地阐述了这一想法。他写道：“LLM不会感到无聊，不会忘记更新交叉引用，并且可以一次性处理15个文件。”导致人类放弃个人Wiki的簿记工作正是LLM所擅长的。

Similar knowledge-as-Wiki pattern keeps reappearing under different names: Obsidian vaults wired to coding agents, the AGENTS.md / CLAUDE.md family of convention files, repos full of index.md and log.md artifacts that agents consult before doing real work, and "metadata as code" repositories inside data teams. 类似的“知识即Wiki”模式以不同的名称不断出现：连接到编码代理的Obsidian库、AGENTS.md / CLAUDE.md系列约定文件、包含index.md和log.md工件的仓库（代理在执行实际工作前会查阅这些文件），以及数据团队内部的“元数据即代码”仓库。

The pattern is compelling and powerful, but each instance is bespoke. Karpathy's wiki and your team's wiki and a vendor's catalog export may all look alike (markdown, frontmatter, cross-links), but none of them are intentionally designed to cooperate. There is no agreed-upon answer to what fields every document should carry, or what filenames mean what. As a result, the knowledge encoded in wikis remains siloed within the original teams, leading to redundant effort whenever a new agent is built.这种模式引人注目且强大，但每个实例都是定制的。Karpathy的Wiki、你团队的Wiki以及供应商的目录导出可能看起来都很相似（Markdown、前置元数据、交叉链接），但它们都没有被有意设计为相互协作。对于每个文档应携带哪些字段，或文件名代表什么，没有统一的答案。因此，Wiki中编码的知识仍然孤立在原始团队中，导致每次构建新代理时都需要重复劳动。

What's missing is a format, not another service缺少的是一种格式，而不是另一种服务

The answer to this problem isn’t another knowledge service. You need a format, a way to represent knowledge that:这个问题的答案不是另一种知识服务。你需要一种格式，一种表示知识的方式，它应该：

• Anyone can produce, without an SDK任何人都可以生成，无需SDK

• Anyone can consume, without an integration任何人都可以消费，无需集成

• Survives moving between systems, organizations, and tools在系统、组织和工具之间迁移时依然存活

• Lives in version control alongside the code it describes与其描述的代码一起存在于版本控制中

• Is readable by humans and parseable by agents: the same file, no translation layer人类可读且代理可解析：同一个文件，无需转换层

By design, OKF is that format. 按照设计，OKF就是那种格式。

How OKF works: The design in one screenOKF如何工作：一屏设计

An OKF bundle is a directory of markdown files representing concepts: anything you want to capture, including tables, datasets, metrics, playbooks, runbooks, and APIs. Each concept is one file. The file path is the concept's identity:OKF 包是一个 markdown 文件目录，用于表示概念：任何你想捕捉的内容，包括表格、数据集、指标、剧本、运行手册和 API。每个概念对应一个文件。文件路径就是概念的标识：

Each concept document has a small block of YAML front matter for structured fields and a markdown body for everything else:每个概念文档都有一小块 YAML 前置元数据用于结构化字段，以及一个 markdown 正文用于其他所有内容：

Concepts link to each other with normal markdown links, turning the directory into a graph of relationships that is richer than the parent/child links implied by the file system. Bundles can optionally include index.md files (for progressive disclosure as agents navigate the hierarchy) and log.md files (for chronological history of changes).概念之间通过普通的 markdown 链接相互关联，将目录转化为一个关系图，比文件系统隐含的父子链接更丰富。包可以可选地包含 index.md 文件（用于代理在层级中导航时的渐进式展示）和 log.md 文件（用于变更的时间顺序历史记录）。

The full v0.1 specification (including conformance criteria, cross-linking rules, and the small number of reserved filenames) fits on a single page.完整的 v0.1 规范（包括一致性标准、交叉链接规则以及少量保留文件名）仅占一页篇幅。

Three principles behind the design设计背后的三个原则

1. Minimally opinionated. OKF requires exactly one thing of every concept: a type field. Everything else (e.g., what types exist, what other fields to include, what sections the body has) is left to the producer. The spec defines the interoperability surface, not the content model.1. 最小化意见。OKF 对每个概念只要求一件事：一个类型字段。其他所有内容（例如，存在哪些类型、包含哪些其他字段、正文有哪些章节）都留给生产者决定。规范定义的是互操作表面，而非内容模型。

2. Producer/consumer independence. OKF cleanly separates who writes the knowledge from who consumes it. A bundle hand-authored by a human can be consumed by an AI agent. A bundle generated by a metadata export pipeline can be browsed in a visualizer. A bundle synthesized by one LLM can be queried by another. The format is the contract; the tooling at each end is independently swappable.2. 生产者/消费者独立性。OKF 清晰地将知识的编写者与消费者分离。由人类手工编写的包可以被 AI 代理消费。由元数据导出管道生成的包可以在可视化工具中浏览。由一个 LLM 合成的包可以被另一个 LLM 查询。格式是契约；两端的工具可以独立替换。

3. Format, not platform. OKF is not tied to any specific cloud, database, model provider, or agent framework. It will never require a proprietary account or SDK to read, write, or serve. We're publishing it as an open standard because the value of a knowledge format comes from how many parties speak it, not from who owns it.3. 格式，而非平台。OKF 不绑定任何特定的云、数据库、模型提供商或代理框架。它永远不会要求专有账户或 SDK 来读取、写入或提供服务。我们将其作为开放标准发布，因为知识格式的价值在于有多少方使用它，而非谁拥有它。

What we're shipping with the spec我们随规范发布的内容

To make the format concrete, we're publishing reference implementations at both the producer and consumer ends:为了使格式具体化，我们在生产者和消费者两端都发布了参考实现：

• An enrichment agent that walks a BigQuery dataset, drafts an OKF concept document for every table and view, then runs a second LLM pass that crawls authoritative documentation and enriches each concept with citations, schemas, and join paths.一个富化代理，它遍历 BigQuery 数据集，为每个表和视图起草 OKF 概念文档，然后运行第二次 LLM 处理，爬取权威文档并用引用、模式和连接路径富化每个概念。

• A static HTML visualizer that turns any OKF bundle into an interactive graph view in a single self-contained file; no backend, no install on the viewing side, no data leaves the page.一个静态 HTML 可视化工具，可将任何 OKF 包转换为单个自包含文件中的交互式图形视图；无需后端，查看端无需安装，数据不会离开页面。

• Three ready-to-browse sample bundles: GA4 e-commerce, Stack Overflow, and Bitcoin public datasets, produced by the reference agent and committed to the repo as living examples of conformant OKF.三个可直接浏览的示例包：GA4 电子商务、Stack Overflow 和比特币公共数据集，由参考代理生成并提交到仓库中，作为符合 OKF 的活示例。

These are proofs of concept, deliberately. The agent demonstrates one way to produce OKF; nothing about the format requires a specific agent framework or LLM. The visualizer demonstrates one way to consume it; nothing about the format requires HTML or a graph view. We expect (and want!) the ecosystem of producers and consumers to grow far beyond what we've shipped.这些是概念验证，有意为之。代理演示了一种生成 OKF 的方式；格式本身不要求特定的代理框架或 LLM。可视化工具演示了一种消费方式；格式本身不要求 HTML 或图形视图。我们期望（并希望！）生产者和消费者的生态系统能远远超出我们目前发布的范围。

Where we go from here我们接下来的方向

OKF v0.1 is a starting point, not a finished standard. The format will evolve as more producers and consumers emerge and as we collectively learn what knowledge representations agents actually need in practice.OKF v0.1 是一个起点，而非最终标准。随着更多生产者和消费者的出现，以及我们共同学习代理在实践中实际需要的知识表示，该格式将不断发展。

We're publishing in the open from day one because that's the only way a knowledge format earns its name, whether you're building a knowledge catalog, an enrichment pipeline, a wiki tailored to AI agents, or anything in the AI knowledge domain. 我们从第一天起就公开发布，因为这是知识格式赢得其名称的唯一方式，无论你是在构建知识目录、丰富管道、为AI代理量身定制的维基，还是AI知识领域的任何其他内容。

From here, we encourage you to:从这里开始，我们鼓励你：

• Read the spec (it's short!)阅读规范（它很短！）

• Write a producer for your source system, your database, your documentation site为你的源系统、数据库、文档站点编写生产者

• Write a consumer: a viewer, a search index, an agent that reasons over bundles编写消费者：查看器、搜索索引、对包进行推理的代理

• Try the reference implementation against your own data针对你自己的数据尝试参考实现

• File issues, send PRs, or propose extensions: The spec is versioned and explicitly designed for backward-compatible growth提交问题、发送PR或提出扩展：该规范是版本化的，并明确设计为向后兼容的增长

The repo, the spec, and the sample bundles are available in GitHub. We have also updated Google Cloud’s Knowledge Catalog to be able to ingest Open Knowledge Format and serve it to our agents. You can find the relevant code and examples here.仓库、规范和示例包可在GitHub上获取。我们还更新了Google Cloud的知识目录，使其能够摄取开放知识格式并服务于我们的代理。你可以在此处找到相关代码和示例。

The format itself is the contribution. The tools we've shipped exist to make it real, and to lower the cost of trying it out. Whatever shape your knowledge takes today, OKF is designed to be the lingua franca it can be exchanged for tomorrow. 格式本身即是贡献。我们发布的工具旨在使其成为现实，并降低尝试的成本。无论你的知识今天以何种形式存在，OKF都旨在成为未来可以交换的通用语言。

^{Published by the Google Cloud Data Cloud team. Open Knowledge Format is an open specification; contributions, alternative implementations, and adoption beyond Google products are all explicitly welcomed.}由Google Cloud Data Cloud团队发布。开放知识格式是一个开放规范；明确欢迎贡献、替代实现以及Google产品之外的采用。

^{In addition to the authors, this work came together thanks to key ideas from many others at Google, and we thank them for their contributions.}除了作者之外，这项工作还得益于Google许多其他人的关键想法，我们感谢他们的贡献。