你的AI知识库为什么总答非所问?详解Google发布的 OKF —— 给 Agent喂知识的标准格式

数据在数据库里、知识在 Notion 里、上下文在 Agent 的 session 里——三个孤岛，互不打通。 Google Cloud 6 月悄悄推的OKF（Open Knowledge Format），就是给"知识"立的 USB-C 接口：让任何 Agent、任何组织、任何工具，用同一种格式交换已沉淀的领域知识。它不性感（仍是 Markdown），但它解决了 Agent 时代最被忽略的一个真问题。

一、先把 OKF 讲成人话

一句话：OKF 是一套为 AI Agent 量身定做的知识文件格式。

它要做的事只有一件：让"已经被人类沉淀好的领域知识"——指标怎么算、字段啥意思、表跟表怎么 join、出问题按什么 runbook 处理—— 能被任何 Agent 拿来直接用，不需要每次重新解析 PDF/Notion/Confluence 私有 API。

📦 像快递的纸箱标准——顺丰、京东、菜鸟包裹形状不一，如果大家都用同一种"纸箱规格 + 贴标签位置"，流水线就能自动分拣运输。 OKF 就是给知识定的纸箱规格：一个 .md 文件 = 一个概念，YAML frontmatter = 贴在箱子上的标签（type/title/tags…），Markdown 链接 = 跟其它箱子的关联条码。

OKF = 一个目录的 Markdown 文件 + YAML frontmatter + 一小套约定。没有运行时，没有 SDK，没有中心注册表。

📁 一个 OKF Bundle 的目录骨架。黄色=保留文件（index.md / log.md），紫色=概念文件。

二、它能做什么：3 个真跑通的官方案例

Google 在自家 GitHub 仓GoogleCloudPlatform/knowledge-catalog里直接git clone出 3 个 production-grade bundle，全部由enrichment-agent参考实现跑通—— 不是 demo、不是 mock，是真把 BigQuery public dataset 转成 OKF bundle：

Bitcoin 区块链（5 节点）：1 个 dataset + 4 张强耦合的表，13 条交叉链接—— 跨表 FK 不用 schema 约束，prose 里手工[block](blocks.md)就够了。

GA4 e-commerce（11 节点）：1 张 events 表 + 8 个 metrics 指标 reference——关键巧思：把"指标"作为独立概念，每个 metric 一个 .md 文件，可被 Agent 单独引用。

Stack Overflow（49 节点）：1 dataset + 16 张表 + 32 个枚举型 reference—— 把"votes 表里的魔法数字 2/3/5/6 是什么意思"集中收纳成 32 个独立概念。

一句话总结这 3 个 case 的设计意图：它们是"OKF 三种压力测试"——紧凑型（BTC）/ 中等带指标（GA4）/ 复杂带枚举（SO）。 Google 用这三个样本告诉你：不管你的数据多复杂，OKF 都能装。

如果感觉还是有点懵，下面这个是我录屏的一个案例，真实可交互的 viewer：

已关注

关注

重播分享赞

视频详情

三、5 分钟跑通：从空目录到可点击的 Bundle

不想读 451 行规范？最快的上手路径：直接装 CLI，写第一个 concept，浏览器打开，就这么简单。

# 1. 装 CLIcurl -fsSL https://openknowledge.sh/install | bash# 2. 创建一个 bundleopenknowledge new ./my-bundle && cd my-bundle# 3. 写第一个概念（每个 .md = 一个概念）cat > tables/orders.md <<'EOF'---type: BigQuery Tabletitle: Ordersdescription: One row per completed customer order.resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orderstags: [sales, orders]timestamp: 2026-06-23T00:00:00Z---# Schema| order_id | STRING | Unique order id |EOF# 4. 校验 + 导出openknowledge validate .openknowledge to html --out ./site .open ./site/index.html   # 双击就能用

想让 Agent 读你的 bundle？加一个 MCP server，Claude/Codex 就能按需 traverse：

npx -y okfy-ai init stripe https://docs.stripe.com/checkoutclaude mcp add --transport stdio stripe-okf \  -- npx -y okfy-ai serve stripe --mcp --auto-refresh

四、OKF vs RAG vs LLM Wiki：三种"给 Agent 喂知识"的方式

最常见的误解："OKF 是来抢 RAG 饭碗的"——错。它们是流水线上的三道工序，互相补位：

OKF 是源头：把领域知识结构化、可发现、可流通（git 仓库）。

RAG 是检索层：把 OKF 或 LLM Wiki 切成 chunks → 向量库，Agent 按相似度取回。

LLM Wiki 是草稿本：人随手记的笔记，没有规范。

最佳实践：OKF 沉淀结构化知识（指标定义、表关系、runbook）→ 导出到向量库供 RAG 检索（FAQ 类文档）→ Agent 同时挂 OKF（MCP）+ 向量库（RAG），按场景各取所需。

五、如何构建"最佳 Agent 知识库"？5 条建议

建议 1：先想清楚"知识的所有者"是谁

OKF 是协作格式不是单人 wiki—— 写 metric 定义的是数据分析师，写 runbook 的是 oncall 工程师，写 schema 注释的是 DBA。需要"知识 PR"流程：跟代码 PR 一样，diff / review / 合并。没有这条流程，再好的格式也会变成"一人写、众人看、无人维护"的 Wiki 坟场。

建议 2：frontmatter 写满 4 个字段，body 写满 3 段

4 个必填 frontmatter：type（唯一强制） +title+description+tags。description最重要——Agent 路由靠它；写好它就是"给这个概念的电梯演讲"。

3 段推荐 body：概述（1-2 段自然语言） + 关键信息（schema/query/定义） + Citations（1-2 个外部权威源）。 Google 的event_count.md全篇只 9 行，但每个字段都有——这叫密度高。别追求篇幅，密度比长度更重要。

建议 3：把"指标 / 枚举 / 关系"作为独立 concept，别塞 frontmatter

GA4 8 个指标为什么不写成events_.md的 frontmatter 字段？因为独立 concept 才能被 Agent 单独 traverse、单独引用、单独维护。 SO 36 个 vote 类型同理——独立 .md 才能加 citations（历史变更）、加 tags、加链接。

判断标准：这个信息会被谁独立查询？ 如果答案是"会"——拆成独立 concept。

建议 4：建立"知识 PR 流程"——和代码 PR 一样严格

每次改 bundle 走 PR，需要 1 个 review 人 + CI 跑okf-validate；

每周扫一遍timestamp > 90 days的 concept，标"待 review"；

Citation 链接每月跑一次 404 检测（Agent 可自动做）；

废弃不删——加deprecated: true+ 指向替代 concept，跟代码 deprecation 一个套路。

建议 5：跟 RAG / LLM Wiki 并存，不要二选一

OKF 兜底"权威定义"（指标怎么算、字段啥意思、关系怎么连）， RAG 兜底"文档检索"（FAQ、博客、合同条款）， LLM Wiki 兜底"个人草稿"（meeting notes、待整理灵感）。 Agent 同时挂这三个工具，按场景动态选——结构化查 OKF、非结构化查 RAG、个人备忘查 Wiki。

一句话结尾：OKF 不性感（仍是 Markdown），但当所有数据在数据库、所有知识在 Notion、所有上下文在 Agent session 里时—— OKF 给了你一个 30 年后还能 cat 的备份，还能被任何 Agent 即插即用。