OKF：LLM Wiki 知识库的落地实践标准

技术调研做到一定深度，往往会有一种熟悉的感觉：资料搜集了一大堆，关键结论心里也有数，可真要让 AI 帮忙整合出个清晰的知识结构，对方却总是一副“信息太多，我抓不住重点”的样子。

这种情况，本质上不是笔记没写好，而是笔记之间缺乏了一张“地图”。AI 无法判断哪一篇是深入分析方案 A 的缺陷、哪一篇是在对比方案 B 的适用场景。它面对的只是一锅乱炖的文本，而不是一个有序的知识库。

Karpathy 提出的 LLM Wiki 概念——采集、整理、生成可查询的 wiki——指明了方向。但一旦进入实操阶段，一堆实际问题就冒了出来：frontmatter 到底放哪些字段才合适？目录该怎么组织才最高效？AI 应该按什么路径来检索知识？这些关键环节长期缺乏公认标准，大家都在摸着石头过河。

OKF 正是在这个背景下，补上了最关键的一环。

OKF 是什么

OKF 说白了就是 Google Cloud 在 2026 年初推出的一套

。它的核心思想很简单：利用 Markdown 文件来组织知识，让整个知识结构——包括有哪些概念、概念之间的关联、以及 AI 如何精准定位它们——变得机器可读。

这套规范异常轻量，核心原则只有三条：

— 从始至终只强制要求一个必填字段：type。其余字段完全自由定义。

— 虽然 Google 提供了从 BigQuery 自动生成 Bundle 的工具，但你完全可以手写或用任何其他工具生成。规范只是一种约定，不绑死某个特定工具链。

— 一个 OKF Bundle 就是一个文件夹，里面是一堆 .md 文件。用 Git 管理也好，归档成 tarball 也罢，甚至直接拷贝，都行，没有任何专属依赖。

所以 OKF 真正回答的实践问题集中在三点：header 该写什么（type 必填，其余自定）、数据如何组织（index.md + 分类目录 + references）、以及 AI 该怎么找（从 index.md 开始，顺着链接逐层深入）。

OKF 和 PKM 已有实践的对应关系

如果你用过 Obsidian 等笔记工具，看到 OKF 的结构应该会感到熟悉——它们的底层逻辑几乎一致，只是术语有所区别：

OKF 概念	PKM 对应	说明
index.md	MOC（Map of Content）	入口导航页，列出该领域的核心页面
目录分层结构	PARA / 主题文件夹	按领域组织，不是扁平文件列表
frontmatter type	页面类型标签（Concept / Note / Reference）	定义这篇笔记是什么类型的知识
references	双向链接 [[wikilink]]	概念之间的关联
type: Reference	Literature Note	引用来源

OKF 把这些分散的做法系统化、标准化了，并配套了工具链。但如果你已经在用 Obsidian 做日常知识管理，完全可以理解为：你早就用自己的方式践行 OKF 的思路了，只是没有意识到这和 Google 提出的正式规范是同一件事。

一个关键分类：Skill 和 OKF 各司其职

在 AI Agent 的语境里，Skill 和 OKF 经常被混为一谈，但它们解决的是完全不同的问题：

• Skill
  = 程序性知识，回答「怎么做」

• OKF
  = Declarative 知识，回答「是什么」以及「知识在哪里」

一个典型的技术调研场景中：OKF 负责告诉 AI「方法 A 是什么、适用场景是什么、和方法 B 的核心差异是什么」；而 Skill 负责「用方法 A 写一段示例代码、用 pip 安装这个包」。两者缺一不可，而且分工明确。

这与 CoALA 框架也是一一对应的：

• 程序性记忆
  ：怎么做（Skill）

• 语义记忆
  ：是什么、在哪里（OKF）

• 情景记忆
  ：发生了什么（Chat History / Daily Notes）

OKF vs RAG：不是替代，是分工

	RAG	OKF
本质	检索技术	知识表示格式
知识组织	非结构化 Chunk，向量索引	结构化图谱，预先定义关联
查询方式	语义相似度搜索	精确路由（读索引 → 读概念 → 读详情）
维护成本	低，追加文档即可	高，需要同步更新
适用场景	变化频繁的非结构化知识	相对稳定、有明确 Schema 的领域

可以理解成：

——你输入「Vue 响应式原理」，它返回一堆含有这些词的网页。——你翻开《Vue 权威指南》的目录，直接定位到「响应式原理」那一章。

更合理的组合方式是：

enrichment_agent 工具链

OKF 官方提供了一套参考实现工具 enrichment_agent，基于 Google ADK（Agent Development Kit）构建，包含两个 AI Agent：

Agent	能力
build_bq_agent	读取 BigQuery 表结构，自动生成 metrics + joins
build_web_agent	抓取官方文档，生成对应的 reference 文档

背后默认调用的是 gemini-flash-latest，这意味着整个生成过程是高度 AI 密集型的，而不是简单的硬编码规则。

生成完 Markdown 文件后，writer.py 会把所有内容整合进 viz.html——一个自包含的交互图谱，用 Cytoscape.js 渲染节点关系，点击节点就能看到完整的文档内容。

最终交付两个核心产物：

（方便版本控制和阅读）+ （JSON 结构，大模型可以直接读取用于推理）。

viz.html 图谱：实际效果

OKF 官方提供的 viz.html 用 Cytoscape.js 渲染成了一个交互式知识图谱。以 GA4 Bundle 为例：

点击任意节点，右侧面板会立刻展示该概念的完整文档，包括其 frontmatter 元数据和 Markdown 正文：

它还支持按节点类型过滤、快速搜索、以及查看每个节点的「Cited by」反向引用：

这里有一个值得注意的细节：

Bundle 结构：知识如何分层组织

一个 OKF Bundle 本质上就是一个目录，承载着某个知识领域的所有完整文档：

ga4/
├── index.md                 # 入口（MOC 导航页）
├── datasets/
│   └── ga4_obfuscated_sample_ecommerce.md
├── tables/
│   └── events_.md
└── references/
    ├── metrics/
    │   ├── event_count.md
    │   └── user_count.md
    └── joins/
        └── events___ads_clickstats.md

每个 .md 文件的结构都是

：

---
type: BigQuery Table
title: Events table
description: 包含 Google Analytics 事件导出数据
resource: https://bigquery.googleapis.com/...
tags: [events, Google Analytics, BigQuery]
---

body 则分层写入：Overview → Schema → Metrics → Joins → Citations。

对个人知识库的启发

OKF 最大的价值，不是让你再引入一套新系统，而是促使你重新审视并精进已有的几个关键实践：

— MOC 的本质是，它告诉 AI 或其他人某个领域的知识从何开始、核心是哪几篇文档。一个写得好 MOC 页面，应该让接触者在三分钟内就能搞清该领域的整体框架。

— OKF 只强制要求一个 type，这并非随意设计。类型标签是机器理解一篇笔记「是什么」的最直接且高效的路径。

— 引用关系不应是单向的。A 引用了 B，那么 B 应该能列出自己「被谁引用」。OKF 的 viz.html 在每个节点详情里标注了「Cited by」；Obsidian 的反向链接面板本质上也是同一功能——但很多人可能还没有真正认真使用过它。

— OKF Bundle 的结构更适合相对稳定的领域，但现实中的知识库是持续生长的。定期 review、果断淘汰过时内容、及时合并重复概念——这些维护动作比单纯追求新增内容要重要得多。

：https://github.com/GoogleCloudPlatform/knowledge-catalog