OKF 很轻轻到一页规范。轻才有机会被很多人说。它不保证知识正确不做完整治理也不会让 Agent 突然变聪明。它做的是更底一层的事给该被共享的上下文一个不绑平台的家。你让智能体算「周活怎么从事件流来」它常会表演式检索一轮翻元数据目录、扫 Wiki、抠几段代码注释再拼出一个听着挺完整的答案。模型未必不会推理麻烦在于那些碎片根本不是同一种写法。目录绑着专有 APIWiki 有自己的页面结构共享盘里躺着过期表准口径还锁在几个老人脑子里。厂商再造一套知识图Agent 团队再写一套上下文装配知识却卡在最先产生它的那个界面里搬不走。2026 年 6 月Google Cloud 发布了 Open Knowledge Format简称 OKF。中文里常说它是「人和 Agent 共读的知识规范」。这话没错但容易让人先问「格式长什么样」却跳过更实在的一句它想改的是知识怎么生产和消费不是再卖你一个知识服务。所以这篇先讲作用再讲定义、结构和消费方式。读完你该能判断值不值得用以及用在哪一层。先说作用它要当知识交换的中间语别先背字段。把 OKF 看成中间语更准谁都能写谁都能读中间少做一次翻译。组织里智能体真正缺的往往不是更强的基础模型而是稳得住的内部上下文。表是什么意思、指标在业务上怎么定、两套系统正确的关联怎么走、旧 API 何时弃用、事故先翻哪本手册——这些东西决定答案能不能落地。它们现在散在互不兼容的表面上元数据目录、第三方 Wiki、共享网盘、代码注释、笔记本单元格还有口头传承。浪费是双向的。做 Agent 的人每次重做上下文装配做目录的人反复发明差不多的数据模型知识本身很难跨产品、跨组织流动。你以为缺一个更聪明的检索服务Google 的判断是缺格式。格式可以不绑账号、不绑 SDK、不绑某朵云能进 Git能用编辑器打开也能被 Agent 当文件读进上下文。作用可以分几层看。同一份知识同时给人用、给机器用。不是人看 HTML、机器另吃一套 JSON而是同一个 Markdown人可以cat模型可以直接吞。少一层翻译就少一层漂移——你改了给人看的说明机器还读着旧结构双轨知识库里这事太常见。生产端和消费端拆开。人手写的包智能体能读元数据导出流水线吐出的包可以丢进可视化器一个模型综合出来的包另一个模型还能接着查。格式是合同两端工具能换。你不必先押宝某家 Agent 框架才敢沉淀知识也不必换模型供应商就重做知识库。组织知识重新回到版本控制习惯里。Diff、review、归因、回滚开发者本来就会现在直接作用在知识文件上。知识不再只活在「某次聊天里被检索到过」的幽灵状态而变成可审计的仓库资产。Karpathy 那句很刺耳也很实在模型不怕烦不会忘了改交叉引用一次能碰十几个文件。个人 Wiki 常常死于维护负担模型偏偏擅长这类记账。OKF 想做的是把各团队土法炼钢的 Markdown 知识库收成可以互换的约定。跨系统交换也便宜一点。数据团队从 BigQuery 导出一包概念文档平台用自己的检索吃进去安全用静态页审阅业务 Agent 用同一包回答「这个指标能不能上周报」。交换单位不是专有 API 的响应体而是一棵目录clone、挂载、本地 grep 都行。它不替你写好全部业务知识只给你一种可携带、可共读、可交换的载体让「上下文装配」少一点每个项目从头发明。信息图知识碎片汇入统一知识包人与智能体同读知识碎片汇入统一知识包人与智能体同读作用落到场景它到底替你省哪一类工作「中间语」说着正确还是要落到你会碰到的痛点。做数据智能体的人最烦「表有了语义没有」。列名能扫到业务含义、关联路径、新鲜度 SLA、弃用说明却散在别处。常见用法是富集型智能体先走元数据再按权威文档补引用、补模式、补关联落成一包可浏览的概念页。人审一遍口径以后 Agent 从这包读而不是每次重爬目录 API。做平台和知识工程的人最烦「每个 Agent 自己攒上下文」。今天 Collibra明天内部 Wiki后天 Confluence 导出。OKF 可以当汇合点各源各自写 producer统一吐 OKF消费侧只维护一套 reader。原系统仍可当权威源OKF 更像可版本化、可离线分发的交换层。做编码智能体的人会觉得它和AGENTS.md、仓库百科是亲戚但分工不同。AGENTS.md适合短而硬的操作规程仓库百科适合解释模块负责哪条链路。OKF 更偏数据与系统周边的元知识和策展说明表、指标、手册、API、引用材料都可以是概念。它不替代指令文件给的是需要长期积累、还可能跨团队交换的那类知识一个互操作面。做知识治理的人更关心知识能不能离开某个产品存活。专有目录好用一旦绑死账号、SDK 和计费迁移成本会反噬。OKF 把自己放在格式而不是平台——价值来自多少人说同一种语言不是谁拥有服务器。别指望它自动保证口径正确也别指望它替你做权限模型更不会把 Avro、OpenAPI 吞进去重做一遍。它管的是怎么装、怎么传、怎么共读内容对不对还得靠生产纪律、引用和人审。后面读定义时预期别抬太高。再说定义OKF 到底是什么作用清楚了定义反而好讲。OKFOpen Knowledge Format是一套开放的知识表示规范面向人和智能体。它描述的是环绕数据与系统的元数据、上下文和经过整理的说明不是要取代业务库也不是要取代领域 schema。当前是 v0.1 Draft刻意做得很薄一棵 Markdown 目录文件头用 YAML frontmatter 放少量可查询字段。没有中央 schema 注册中心没有强制运行时也不要求「必须装某个 SDK 才能读」。Google 的说法是把近年反复出现的「LLM Wiki」模式收成可移植、可互操作的格式。用过 Obsidian、Notion、Hugo或见过仓库里一堆index.md/log.md给 Agent 导航的人形状会眼熟。以前各家看起来像却没约定每个文档至少带什么、哪些文件名保留、链接怎么解释。OKF 把互操作所需的最小约定钉死其它内容模型留给生产者。术语上分发单位叫 Knowledge Bundle知识包一棵自包含、有层次的知识文档集合。基本单元叫 Concept概念一个知识点一个 Markdown 文件可以是表、API也可以是指标、业务流程。概念 ID 是路径去掉.md——tables/orders.md就是tables/orders。身份跟着路径走所以更推荐从包根写绝对链接子目录挪动时少断。光听术语不够先看一棵最小可读的包。人和 Agent 打开仓库时大致就是这种目录sales-knowledge/ ├── index.md # 包根目录先看有什么 ├── log.md # 可选变更日志 ├── tables/ │ ├── index.md │ ├── orders.md # 概念客户订单表 │ └── customers.md # 概念客户表 └── playbooks/ ├── index.md └── freshness-alert.md # 概念新鲜度告警处置手册index.md和log.md是保留名不能当概念文档其余.md都是概念。目录怎么分层由生产者定规范不强制叫tables/或playbooks/——上面只是常见写法。信息图知识包目录树与保留文件名标注知识包目录树与保留文件名标注每个概念文件两部分YAML frontmatter Markdown 正文。硬性要求很少非保留文件要有可解析 frontmatter且必须有非空type。推荐字段大致是title、description、resource、tags、timestamp。resource指向底层资产 URI抽象概念可以没有。生产者可加扩展键消费者应尽量保留未知键别因为多字段就拒收。一张「客户订单」表写成概念页完整示范如下字段与结构对齐官方 SPEC 示例--- type: BigQuery Table title: Customer Orders description: One row per completed customer order across all channels. resource: https://console.cloud.google.com/bigquery?pacmedsalestorders tags: [sales, orders, revenue] timestamp: 2026-05-28T14:30:00Z --- # Schema | Column | Type | Description | |---|---|---| | order_id | STRING | Globally unique order identifier. | | customer_id | STRING | Foreign key into [customers](/tables/customers.md). | | total_usd | NUMERIC | Order total in US dollars. | | placed_at | TIMESTAMP | When the customer submitted the order. | # Joins Joined with [customers](/tables/customers.md) on customer_id. # Citations [1] [BigQuery table schema](https://console.cloud.google.com/bigquery?pacmedsalestorders)读的时候可以按三块拆最上是机器好过滤的元数据type必填其余推荐中间是人和模型一起看的结构化正文底部 Citations 把论断钉回外部证据。包内链接写成/tables/customers.md这种从包根出发的路径挪目录时更稳。信息图概念文件解剖题头字段与正文分区概念文件解剖题头字段与正文分区不是所有概念都绑一张表。事故手册可以没有resource类型写成 Playbook正文写触发条件与步骤并用链接指回相关表--- type: Playbook title: Incident response — data freshness alert description: Steps to triage a freshness alert on the orders pipeline. tags: [oncall, incident] timestamp: 2026-04-12T09:00:00Z --- # Trigger A freshness alert fires when orders lags more than 30 minutes behind its expected SLA. See the [orders table](/tables/orders.md). # Steps - Check the ingestion job dashboard. - Confirm whether upstream producers stalled. - Page the on-call owner listed in the orders concept page.渐进披露靠index.md。它没有 frontmatter只列举「这里有什么」让人和 Agent 先扫目录再下钻。包根或子目录都能放例如# Tables * [Customer Orders](orders.md) - One row per completed customer order. * [Customers](customers.md) - Customer master records used by orders joins. # Playbooks * [Freshness alert](../playbooks/freshness-alert.md) - Triage lagging orders pipeline.log.md按日期倒序记变更方便回答「这包最近改过什么」# Directory Update Log ## 2026-05-22 * **Update**: Added join notes on [Customer Orders](/tables/orders.md). * **Creation**: Established [Freshness alert](/playbooks/freshness-alert.md). ## 2026-05-15 * **Initialization**: Created foundational directory structure.概念之间用普通 Markdown 链接。链接本身不带「依赖 / 关联 / 父子」类型标签语义写在周围句子里。做图谱时多半把链接当成有向边。断链被明确允许目标还不存在可能只是还没写完不算格式错误。Agent 半生成、包在长、重构做到一半都是常态规范选择先可用。符合 v0.1 的条件很短每个非保留 Markdown 有可解析 frontmatter每个 frontmatter 有非空type若有index.md/log.md就按对应结构来。缺可选字段、未知类型、未知扩展键、断链、缺索引消费者都不该拒收。规范能装进一页纸才有机会当中间语学得会、写得出、换得动。流程图从源系统到知识包再到人与智能体消费从源系统到知识包再到人与智能体消费定义背后的几条设计原则为什么看起来这么简单却坚持不做成另一个平台大致是这几条。尽量少规定。每个概念只强制type。有哪些类型、正文怎么分节、还加哪些字段留给生产者。它钉的是互操作表面不是内容本体。想「一次定全世界 taxonomy」的人可能不过瘾但对生态更友好领域可以有自己的类型习惯消费者容忍未知类型就行。生产与消费独立。谁写、谁读不绑死。手写、流水线、模型综合可以并存浏览、检索、Agent 推理也可以并存。参考实现里的 BigQuery 富集 Agent、静态 HTML 图谱都只是一种写法/读法不是规范本身。是格式不是平台。不绑云、库、模型供应商、Agent 框架读写分发都不要求专有账号。Google 更新了 Cloud Knowledge Catalog 去 ingest OKF那只是生态里的一个消费者不是格式前提。价值来自说话的人够不够多——这话既是愿景也是风险v0.1 还早治理和外部提案怎么进规范都会决定它能不能真火起来。边界也清楚不规定固定概念类型 taxonomy不规定存储与查询基础设施不取代 Avro、Protobuf、OpenAPI——只引用不吞并。权限、审批、血缘仍在生产者和周边系统手里。OKF 只管「装进文件的那一层」说同一种话。从示范里能带走的东西对照目录树和两份概念页几件事会变硬。路径即 ID包内引用优先从根路径写。机器要过滤和预览的进 frontmatter叙述与证据进正文。今天只有 Schema明天补 Joins后天补 Citations都不破坏符合性。目录打成 tarball 或丢进 Git别人 clone 就能读。导航先看index.md再下钻概念页要沿革看log.md。官方同时开源参考实现和示例包也是这个道理。规范再短也需要看得见的符合实例。仓库里有公开数据集方向的示例 bundleGA4 电商、Stack Overflow、Bitcoin 等还有把任意包渲成单文件交互图谱的可视化器。它们不是证明 Google 工具最好而是降低试错成本先看一包长什么样再决定自己的 producer 怎么写。知识包怎么被消费写成什么样说完了还得说怎么读、怎么用。分两层规范嵌在结构里的消费约定以及你把 Agent / 产品接上去时的落地方式。前者能当官方意图讲后者是工程接法别写成 Google 下发的运行时协议。规范里已经写明的消费方式OKF 没有单独的 Agent SDK也没有逐步任务状态机。它把消费嵌进文件结构人或智能体面对同一棵目录、同一类 Markdown。入口是文件不是专有 API。工程师可以cat概念页LLM 可以把同一文件原样读进上下文。官方列举的消费形态包括静态文件服务、Obsidian / Notion / MkDocs、把文件载入上下文的模型、搜索索引以及仓库自带的图谱可视化器。会读 Markdown就具备消费能力。导航靠渐进披露先index.md再下钻概念页。任意目录可放index.md枚举「这里有什么」让人或 Agent 打开单篇前先建立地图。这是规范里最接近阅读策略的一条别默认整包灌进上下文一层层看目录再打开需要的概念。某层没有index.md时消费者也可以根据目录和 frontmatter 现场合成索引——规范允许。筛选靠 frontmatter细节靠正文。必填的type给消费者做路由、过滤、展示title/description服务搜索摘要与预览tags、resource、timestamp是推荐键。常见读法先扫头部判断要不要读、这篇是表还是手册需要执行细节再读 Schema、步骤、示例。机器查头部叙述与证据看正文。关系靠 Markdown 链接遍历。/tables/customers.md就是下一步该打开的节点。关系含义写在周围句子里不是链接协议上的类型字段。做图谱时通常把链接当成有向边。断链不是错误目标可能还没写完消费者应继续别整包拒收。变更沿革可看log.md。回答「这包最近改过什么」、决定要不要重索引时按日期倒序的日志比盲扫全部文件直接。它是可选文件一旦存在就是消费侧的时间线入口。消费必须宽容。缺可选字段、未知type、未知扩展键、断链、缺索引都不应拒收。官方默认包会半生成、会生长、会重构——消费者要能读「不完美但可用」的包。串起来就是一条短链打开包根 → 读index.md或合成目录→ 用type/ 描述 / 标签缩小范围 → 打开概念页读正文 → 沿链接补全相关概念 → 需要时看log.md或跳转resource。人和 Agent 走同一条链差别在于 Agent 通常还需要你在外侧告诉它包根在哪什么任务必须先读这包。流程图从索引渐进下钻到概念页并沿链接遍历从索引渐进下钻到概念页并沿链接遍历官方样板消费者长什么样仓库没规定你必须用某框架但给了可对照的消费样板。可视化器是 reference consumer。对任意 OKF 包跑visualize生成单文件 HTML概念做成力导向图节点按type着色边来自正文交叉链接点选可看 frontmatter 与渲染正文包内链接改成站内跳转并带搜索与类型过滤。它证明消费等于解析目录与 Markdown不是调用专有知识 API。目录产品也能 ingest。Google Cloud Knowledge Catalog 已能吃进 OKF再供给自家 Agent。这是「先把文件编译进平台再让 Agent 查」的官方路径之一——文件仍是交换格式平台是可选服务层。参考富集 Agent 主要站在生产侧从 BigQuery 等源写出/enrichment 概念页示范如何生产 OKF不是消费协议本身。产销可以是不同程序甚至不同组织格式是中间的合同。接到你自己的 Agent 时怎么落地规范停在文件约定。要把消费跑进日常 Agent还需要你们自己的接法。下面按投入从低到高都和上面的官方消费链兼容但是工程选择不是 SPEC 条文。直接读文件。给 Agent 读目录/读文件的工具把知识包挂进工作区在系统提示或项目指令里写明包根并约定涉及口径、表语义、关联、手册类问题先读包根index.md再按链接下钻避免跳过索引整库盲扫。这最贴近官方说的「LLM 原样读文件」。先索引再回源读原文。扫一遍 frontmatter按type/tags/ 标题建轻量索引Agent 先拿候选概念 ID 与description最终仍打开对应.md原文作答。索引加速发现原文少一层摘要失真。先 ingest再经服务查询。把包导入 Knowledge Catalog、自建搜索或图谱Agent 通过平台 API / MCP 取知识。包很大、需要权限和统一检索时更合适Git 里的目录仍宜当可审计真相源平台当加速层。无论哪条接法消费纪律最好写进团队约定别指望模型自己悟关键结论以概念页加 Citations 为准与上游冲突时升级给人未知type当普通概念处理别报错退出。OKF 保证的是读得懂、换得动信不信、何时问人仍是产品治理。它和你已经在用的东西是什么关系有人会问这不就是 Obsidian 库吗不就是仓库里的 docs不就是 LLM Wiki相近关键差别是「被规定过」。Obsidian、个人 Wiki、AGENTS.md族、元数据即代码仓库都在用 Markdown、目录和交叉链接。各自好用却默认不为彼此合作而设计字段含义不同索引约定不同保留文件名不同。OKF 把互操作所需的最小规则钉下来让不同生产者写出来的包有机会被不同消费者直接吃掉少写一层适配器。和传统数据目录比OKF 更像交换格式不是治理中台。目录产品仍可以很重权限、审批、血缘、质量规则继续做OKF 提供导出/导入/给 Agent 读的轻路径。和 RAG 比它更偏先编译成活知识再按需读而不是每次提问都从原始碎片重拼——这点和 Karpathy 对 LLM Wiki 的论述一致综合过程应沉淀成可积累的页面别蒸发在聊天记录里。和 MCP、工具协议比层次不同。MCP 更关心 Agent 怎么连工具、怎么拿实时能力OKF 更关心长期依赖的组织知识怎么落盘、怎么交换。两者可以叠工具查实时状态OKF 包提供稳定语义与手册。别指望一个格式解决所有 Agent 基础设施问题。若要采用实务上怎么起步落地时按作用倒推别一上来对着字段表开工。先盘点智能体反复问却答不稳的到底是哪类知识表语义、指标口径、关联路径、事故手册、API 弃用说明——选一类最痛的做最小包。 再选生产者人手写几页也成立有元数据系统就写导出有文档站点就写爬取富集。参考 Agent 只是样板。 然后定你们自己的消费路径提示词里写包根并先读index.md或 ingest 进检索/目录后再供给 Agent——这些是工程选择不是官方强制步骤。消费端越早存在包越不容易变成又一个没人维护的 docs 目录。 最后才谈扩展字段和类型命名。类型字符串没有中央注册尽量写得自解释团队内保持稳定消费者要对未知类型保持宽容。维护节奏也很要紧。允许断链和半成品不等于鼓励长期腐烂。log.md、Git history、定期巡检过时断言、孤儿页、缺引用仍然需要。人适合当审稿人和选题人模型适合做交叉引用与批量改页。这个分工成立活知识才成立否则你只是换了一种更时髦的文档坟场格式。还有一句现实的格式成不成功看生态。v0.1 是起点Google 欢迎外部 producer / consumer 和扩展提案。个人现在就可以用它组织自己的数据与系统知识包企业更适合先在一个域内试点「导出 OKF → Agent 只读这包」再决定要不要推成组织标准。别一上来追求全公司 taxonomy 完美——那正好违背「尽量少规定」。结语中文里那句「人和 Agent 共读的知识规范」共读是作用规范是定义。顺序反了容易只看见 Markdown 和 YAML看不见它想撬的事让组织知识从破碎的专有表面里出来变成可版本化、可交换、两端可替换的中间语。OKF 很轻轻到一页规范。轻才有机会被很多人说。它不保证知识正确不做完整治理也不会让 Agent 突然变聪明。它做的是更底一层的事给该被共享的上下文一个不绑平台的家。若你正在为智能体反复组装同一类内部知识不妨先写十个概念页链起来丢进 Git让人和 Agent 都从index.md往下读。用过之后再决定要不要写成团队约定。有没有第二个人、第二个 Agent 愿意用同一种方式打开同一棵目录比公告重要得多。