langrq的blog
← 返回
AIAgent知识管理
AI 观察

卡帕西强推的 LLM Wiki，终于有了通用格式——谷歌发布 OKF

文章要点

解读 Google Cloud 2026 年 6 月发布的 Open Knowledge Format（OKF v0.1）——把 Andrej Karpathy 的 LLM Wiki 模式写成可互操作标准；含结构说明、上手步骤与和 CLAUDE.md / llms.txt 的对比。

2026 年 6 月 12 日，Google Cloud 正式发布 Open Knowledge Format（OKF，开放知识格式） v0.1——一份约 450 行的开源规范，把过去半年里各路团队各自摸索的「LLM 可读 Wiki」模式，写成了可交换、可版本化、厂商中立的通用格式。

Google 在 官方博客 里直接点名 Andrej Karpathy 的 LLM Wiki gist：「LLM 不会厌烦，不会忘记更新交叉引用，一次性能改 15 个文件。」 让人放弃维护个人 Wiki 的那些 bookkeeping，恰恰是 LLM 擅长的事。

卡帕西 2026 年 4 月提出的三层架构——raw/ 原始资料、wiki/ 由 LLM 维护的 Markdown、CLAUDE.md 定义 schema——已经在社区里催生出大量实践。OKF 做的不是再发明一种 Wiki，而是给这个模式补上 互操作层：你的 Wiki、Karpathy 的 Wiki、数据团队的 catalog export，终于可以用同一套规则对话。

下面是我读完 规范全文 和参考实现后的重排解读，不是翻译稿。

一分钟版

要点内容
是什么用「Markdown 目录 + YAML frontmatter」表示组织知识的开放规范
解决什么Agent 需要的上下文散落在 catalog、Wiki、代码注释、老员工脑子里——OKF 是交换介质，不是又一个 SaaS
硬性要求每个概念文档 frontmatter 里 必须有 type 字段，其余几乎全开放
和 Karpathy 的关系正式化 LLM Wiki 模式；Google 称 OKF 为 knowledge 的 lingua franca（通用语）
怎么分发Git 仓库（推荐）、tarball、zip，或更大 repo 里的子目录
Google 附赠BigQuery enrichment agent、静态 HTML 可视化器、三套样例 bundle
现状v0.1 起点，不是终局；Cloud Knowledge Catalog 已支持 ingest OKF

问题：Agent 缺的不是模型，是上下文

Foundation model 越来越强，但 「没有相关上下文」 仍是 Agent 答不准、做不对的主因。组织里真正有用的知识——某张表的 schema、某个指标的业务定义、事故 runbook、两个系统之间的 join 路径、旧 API 的弃用说明——今天分散在：

  • 各 vendor 的 metadata catalog（各自 API、各自 schema）
  • Confluence / Notion / 共享盘
  • 代码注释、docstring、Notebook 单元格
  • 少数 senior 工程师的脑子里

Agent 要回答「怎么从事件流算 weekly active users？」，得从这些 互不相容的表面 现场拼装答案。每个做 Agent 的团队都在重复造「上下文组装」的轮子；每份知识都锁在产生它的系统里。

Karpathy 的解法很朴素：别每次 query 都重新 RAG 一遍原始文档，让 LLM 当 compiler，维护一份持久、结构化、互相链接的 Markdown Wiki。 Obsidian vault 接 coding agent、AGENTS.md / CLAUDE.md、repo 里的 index.md + log.md——同一模式反复出现，只是 没有约定字段、文件名语义、链接规则，Wiki 之间无法协作。

OKF 的定位因此很清晰：缺的是 format，不是又一个 knowledge service。

OKF 长什么样：一屏能看完的设计

一个 Knowledge Bundle 就是一棵 Markdown 文件目录。每个 Concept（概念） 对应 一个 .md 文件——可以是 BigQuery 表、数据集、指标、Playbook、API，或任何你想沉淀的知识。文件路径即概念 ID（去掉 .md 后缀）。

Text
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 body：

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`.

概念之间用普通 Markdown 链接连成 知识图——关系比目录树的父子层级更丰富。可选的 index.md 做渐进式披露（先浏览目录再深入）；可选的 log.md 按日期记录变更历史。

三条设计原则，Google 写得很直白：

  1. Minimally opinionated——只强制 type；类型枚举不 centrally 注册，消费者遇到未知 type 要 gracefully 降级处理。
  2. Producer / consumer 解耦——人写的 bundle 可被 Agent 读；pipeline 生成的 bundle 可被可视化器浏览；一个 LLM 合成的 bundle 可被另一个 LLM 查询。
  3. Format, not platform——不绑定云、数据库、模型或 Agent 框架；读写得靠 cat 和 git clone，不需要专有 SDK。

和 Karpathy LLM Wiki 的对应关系

层Karpathy 模式OKF v0.1
原始输入raw/ 不可变资料OKF 不规定；仍可在 bundle 外用 raw/
结构化知识wiki/ 里 LLM 维护的 MarkdownBundle 目录树 + 概念文档
运行契约CLAUDE.md / AGENTS.md schema规范里的 frontmatter、index.md、log.md 约定
互操作团队内部约定版本化 spec，跨团队 / vendor 可消费

Karpathy gist 的核心洞察——编译 vs 再发现：RAG 每次 query 重新检索原始文档；Wiki 模式让 LLM 处理一次、维护持久 artifact，链接和交叉引用随时间变厚。OKF 把「artifact 长什么样」钉死了最小公约数，但没碰「谁维护、用什么 Agent、存在哪」——那些仍是你的 CLAUDE.md 该管的事。

怎么用 OKF：从手写到自动化

路径 A：从零手写一个最小 bundle

适合先把团队里 10～20 个高频概念（核心表、关键指标、oncall playbook）沉淀下来。

  1. 建目录，按业务域分子文件夹（如 tables/、metrics/、playbooks/）。
  2. 每个概念一个 .md，frontmatter 至少写 type；建议补上 title、description、tags。
  3. 用 bundle 相对路径链接（推荐以 / 开头，如 [customers](/tables/customers.md)），稳定且便于 Agent 遍历。
  4. 根目录加 index.md，列出各子目录和重点概念；可选在 frontmatter 声明 okf_version: "0.1"。
  5. 放进 Git，和代码同仓或独立 repo——diff、review、回滚天然可用。

Conformance 检查清单（v0.1）：

  • 除 index.md、log.md 外，每个 .md 都有可解析的 YAML frontmatter。
  • 每个 frontmatter 有非空 type。
  • 若存在 index.md / log.md，结构符合规范 §6、§7。

缺 optional 字段、未知 type、断链——消费者不应因此拒收 bundle；这是刻意设计的宽松模型，方便 Agent 半自动生成、人类半 curated。

路径 B：用 Google 参考实现从 BigQuery 生成

仓库：GoogleCloudPlatform/knowledge-catalog

Enrichment Agent 两阶段跑：

  1. BQ pass——扫描 dataset，为每张表/视图起草 OKF 概念文档（schema、描述等来自 BigQuery metadata）。
  2. Web pass（可 --no-web 跳过）——LLM 当 crawler，从 --web-seed 种子 URL 抓取权威文档， enrich 现有概念或 mint references/ 下的引用文档；有 --web-max-pages 和域名白名单硬限制。

样例 bundle（GA4 电商、Stack Overflow、Bitcoin 公开数据集）就在 bundles/ 里，可直接 clone 当模板。

Visualizer——把任意 OKF bundle 渲染成 单文件交互式 HTML 图，无后端、可静态托管，适合给非技术同事浏览知识图。

路径 C：在 Google Cloud 里消费

Google 同步更新了 Cloud Knowledge Catalog，可 ingest OKF bundle 并 serve 给自家 Agent——若你已在 GCP 数据栈里，这是一条 hosted 消费路径；但 OKF 本身不依赖 GCP。

路径 D：接进你自己的 Agent

消费侧没有魔法 SDK：

  1. Agent 启动时读 bundle 根 index.md，做 progressive disclosure。
  2. 按任务需要 read_file 跟进链接的概念文档。
  3. 用 frontmatter 的 type / tags 做路由或过滤（例如只加载 Playbook 和 Metric）。
  4. 写回时更新 timestamp、追加 log.md 条目——和 Karpathy 模式一样，让 LLM 承担 Wiki 维护的脏活。

和相近格式的对比

格式范围可移植性必填字段
CLAUDE.md / AGENTS.md单 repo、单工具工具特定无
Karpathy LLM Wiki团队内部约定而已无
OKF v0.1组织级、多团队、多 vendor版本化 spec仅 type
llms.txt站点级爬虫上下文非 Agent 知识库格式N/A

OKF 不取代 Avro、Protobuf、OpenAPI 等领域 schema——它 引用 它们，并在 Markdown body 里用 # Schema、# Examples、# Citations 等约定段落承载人类和 Agent 都能读的上下文。

为什么现在值得试

  1. 成本极低——就是 Markdown + Git；Obsidian、MkDocs、GitHub 渲染现成可用。
  2. 和 Agent 工作流同构——coding agent 本来就在读 repo 里的 md；OKF 只是把「该有什么字段、链接怎么写」说清楚了。
  3. v0.1 故意留余地——Google 明确这是起点；社区 issue、PR、alternative implementation 都欢迎。
  4. 卡帕西设想的规模化——个人 Wiki 可以升级成 组织可交换的知识包；A 团队 enrichment 的 bundle，B 团队的 Agent 可以直接消费。

若你已经在用 LLM 维护项目 Wiki 或数据 catalog notes，最小行动是：给现有 Markdown 概念页补上 type，统一交叉引用为 /path/to/concept.md，根目录加 index.md——你就已经走在 OKF Conformance 路上了。

资源链接

一句话：卡帕西把 LLM 变成 Wiki 维护者；Google 把 Wiki 变成可交换格式。OKF 不是又一个知识 SaaS——它是 Agent 时代组织上下文的 Markdown 通用语。

评论

加载评论中...