OKF实战：如何将Agent组织知识存入文件夹
Google Cloud 本周推出的 Open Knowledge Format（OKF）初看相当朴素：一个目录，内含 Markdown 文件，顶部是 YAML frontmatter，用标准 Markdown 链接串联文件。这套架构对撰写技术文档的人来说再熟悉不过。
深入剖析后，它捅破了一层关键的窗户纸。现有 Agent 已经能写 SQL、查询文档、调用工具，但真正在企业落地时，往往卡在最基础的一环：这张表能否直接使用？“销售收入”指标的口径由谁定义？订单表与客户表的 join 路径是什么？事故 runbook 文件存放在哪里？模型并不缺少语法，缺的是能被高效消化和引用的组织知识。
OKF 核心定义
OKF 定义了最小单位——Knowledge Bundle，即一个文件夹。它可以被塞进 Git 仓库，也可以打包为 zip 或 tarball。文件夹内除几个保留文件外，每个 .md 文件称为一个 concept，代表一个知识单元。
这个 concept 可以是一张 BigQuery 表、一个数据集、一个 API 端点、一个指标、一个业务流程、一份事故复盘文档或一篇参考资料。文件路径天然成为唯一 ID，例如 tables/orders.md 对应的 concept ID 就是 tables/orders。
这种设计工程气息浓厚。无需先部署服务，无需注册 schema registry。能读文件就能读 OKF，能 git clone 就能分发 OKF。对落地实施者而言，这是最直接的诚意。
技术细节解析
一个 concept 文件分为两部分：YAML frontmatter 与 Markdown body。
frontmatter 中唯一必填字段是 type，告知消费方该 concept 的类别，例如 BigQuery Table、Metric、Playbook、Reference。值得注意，Google 并未设立中心化 type registry，生产者可自行命名，消费方遇到未知 type 也应继续解析。
推荐字段包括 title、description、resource、tags 与 timestamp。思路清晰：frontmatter 只存放用于过滤、展示、索引的结构化信息。
真正的语义与内容全在 Markdown body 中。表的字段说明、示例 SQL、常见 join 方式、使用限制、引用来源，均可通过标题、表格、代码块、普通段落呈现。Spec 中给出了一些约定俗成的标题，如 # Schema、# Examples、# Citations。这些是约定而非强制，但对人类和 Agent 都极友好。
跨文件关系的表达同样朴素——普通 Markdown 链接。orders.md 可直接链接至 /tables/customers.md，关系类型由周围文字说明。这种选择大幅降低了写入成本，也使得图可视化工具能先将所有链接视为有向边处理。
这里存在明显的权衡。关系语义不够强，想做严格的知识图谱查询可能会觉得松散。但 v0.1 版本做到这一步反而更明智。企业知识在初期整理时，最难解决的永远是人愿意写、写出来不易腐坏。过早施加强 schema，很多团队会直接放弃。
index.md 与 log.md 的关键作用
OKF 包含两个保留文件名：index.md 与 log.md。
index.md 负责分层导航。Agent 可先读取根目录的 index，了解有哪些 dataset、table、metric、playbook，再根据任务逐层打开相关文件。这样无需将整个知识库一次性塞入上下文。
log.md 记录变更历史。例如某目录下新增一张表、修改指标口径、废弃某个 playbook，均可按日期记录。Agent 后续读取时能快速感知近期变化，无需依赖全量搜索碰运气。
这套设计明显继承了 LLM Wiki 的思路。Karpathy 的 LLM Wiki 同样提到三层结构：raw sources、wiki、schema。OKF 所做的，正是将社区已验证的模式转化为供应商中立的交换格式。
Google 为何推出 OKF
Google 的切入点聚焦数据目录与 Agentic Data Cloud。企业数据系统中大量上下文散落于 Dataplex、BigQuery、Looker、文档站、内部 wiki、工单系统、Slack 讨论中。Agent 若真想帮人分析数据，仅拿到字段名远远不够。
举一个典型场景：“销售收入”指标，字段名可能仅是 revenue，但它是否包含退款、税费、折扣、跨境汇率调整？这些信息往往藏于另一份文档。再往下追，该指标能否按周聚合？能否与用户表 join？历史分区是否存在数据质量问题？这些信息又散落于更多地方。
传统 RAG 可以检索这些资料，但每次需重新拼装。OKF 的设想是将相对稳定的知识预先整理成 wiki，并持续积累。Agent 查询时读取的是整理后的 concept，而非 raw docs 的碎片。
Google 此次还提供了参考实现。README 指出，enrichment agent 先读取 BigQuery metadata，为数据集、表等概念生成 OKF 文档；然后通过 web pass 抓取权威文档，补充 citation、说明与关系。它甚至能生成自包含的 HTML visualizer，用图展示 bundle 中的 concept 与链接。
更值得关注的是，它将数据目录知识拉回归工程工作流。指标口径更新、join path 修订、verified SQL 加入，均可变成 Git diff、走 PR、被 review。对数据团队而言，这比多一个聊天入口实用得多。
与相邻标准的差异
OKF 容易与 llms.txt、MCP、OpenLineage 混淆，但它们管理不同层级。
llms.txt 更像是站点给 LLM 的入口导航，告知模型重要文档位置。MCP 是 Agent 连接工具、资源与数据源的协议。OpenLineage 记录作业运行时的血缘事件，例如哪个 job 读取了哪些 dataset、产出了哪些 dataset。
OKF 则更接近上下文资产本身。它可以被 llms.txt 指向，可通过 MCP 暴露给 Agent，也能将 OpenLineage 的结果写成 concept 说明或 citation。它聚焦的层级是将组织知识制作成可移动、可审查、可读取的文件包。
落地实践路径
团队若想尝试 OKF，不建议一上来就导出整个公司知识库。稳妥的方法是选一个小域，例如一个 BigQuery dataset、一个核心业务指标域或一个产品线的数据资产。
先定义本地 profile：明确 type 清单、推荐 frontmatter 字段、固定章节模板、citation 规则。例如表必须包含 Schema、Examples、Citations；指标必须说明口径、过滤条件、刷新频率、owner；playbook 必须写明触发条件、处理步骤、升级路径。
然后从现有系统导出第一版。dbt docs、LookML、BigQuery INFORMATION_SCHEMA、DataHub、Dataplex、内部 wiki 均可成为 producer。第一版不必追求完美，先产出高价值的 concept。
接着安排人员审核最关键的内容，尤其是指标口径、权限边界、SQL 示例、业务规则。Agent 生成的内容可以加速整理，但不能作为事实来源。OKF 中的 citation 至关重要，每个关键判断最好都能追溯到原文档、系统链接或 owner。
完成审核后，让 Agent 开始只读消费。例如 SQL Agent 先读取 index.md，再打开相关表和指标 concept，沿链接找到 join path 与示例查询。观察生成质量是否更稳定，错误是否更易定位。待只读消费稳定后，再考虑让 Agent 写回修改建议，并通过 PR 让人审核。
已知边界
OKF v0.1 还很早期。它没有权限模型、查询基础设施、统一 type registry 或强关系语义。不能替代数据治理系统、schema 管理或运行时血缘采集。
权限尤需谨慎：将表说明、示例 SQL、业务规则导出为文件后，传播变得更易。哪些字段能写入 bundle、哪些示例会泄漏业务敏感信息、哪些 concept 只能给特定团队读取，这些必须在外部系统处理。
规模也是问题：几百到几千个 concept，用文件、Git、index、grep、静态 viewer 处理非常舒适。但到了几十万级别，必然需要搜索索引、分片、增量同步与权限过滤。OKF 负责交换形态，不负责大规模 serving。
总结与建议
整体而言，OKF 可以小规模尝试，但不宜立即将其作为平台战略。
它最有价值之处，是将 Agent 所需的组织知识转化为普通文件——普通到可以放进 Git、被人审查、被脚本检查、被不同工具搬运。这个方向完全正确。
但有一处潜在隐患：type 与章节的约定可能随实践分裂。没有 registry 带来灵活性的同时，也会带来映射成本。真正落地时，团队必须编写自己的 OKF profile，否则文件夹很快会退化为另一种松散 wiki。
如果你正在做数据问答、SQL Agent、企业知识库或代码 Agent 项目，不妨将 OKF 作为一个极轻的中间层来试：先从小域导出，让 Agent 读取，观察错误是否减少。不要让格式本身成为新负担——它应助知识流动，减少流程阻碍。