okf

开放知识格式（OKF）

OKF 是 Google 推出的开放、厂商中立规范（v0.2），用于描述 AI Agent 所需的上下文，并以 bundle 表示。Bundle 是一个目录，包含多个 markdown 文件，每个文件表示一个 概念（表、数据集、指标、运行手册、操作手册、API、连接路径），并与其所描述的代码一同纳入版本控制。只有 markdown、文件和 YAML frontmatter。该格式就是约定，因此任何生产者都可以编写 bundle，任何使用者（Agent、查看器、搜索索引）都可以读取它，无需 SDK，也不会被锁定。

可通过两种方式使用此技能：按需运行命令，或在整理 Agent 将要读取的知识时隐式应用。完整的规范性规范见 spec.md；各命令的步骤见 commands.md；可复制粘贴的入门模板见 templates.md。

选择 OKF 方法

对于每个 OKF 请求，都应选择最符合用户预期结果的最精简方法。在 OKF Studio 通用聊天中，调用 okf_capability_catalog 检查当前启用的版本化目录，并调用 okf_capability_resource 加载选定的方法。在 Studio 之外，直接读取对应的能力文件。在首次进度更新中说明所选能力。在加载其资源之前，不得声称已使用某种方法。

用户意图	要加载的方法
回答范围明确的 bundle 问题，或追踪已知链接	okf-inspect
选择证据、检查路径，或诊断检索失败	okf-retrieve
规划新的 bundle，其目标位置或概念映射尚未确定	okf-create
向现有知识添加事实、引文或关系	okf-enrich
在不更改文件的情况下审查合规性或知识健康状况	okf-audit
修复可复现的验证或健康问题	okf-repair
根据范围明确的外部证据核对 bundle 中的说法	okf-research
在进行更改前查找直接和下游影响	okf-change-impact
规划版本化的架构、约定、布局或标识变更	okf-migrate
将已接受的证据和已知目标位置转化为新概念	okf-author，然后是 writing
在不改变含义的情况下改进现有文本	okf-revise，然后是 writing

所有方法始终可供查找，但详细说明仅按需加载。一次性加载所有方法会浪费上下文，并混合彼此不兼容的边界。例如，inspect 只读，revise 禁止更改知识，enrich 允许添加有来源依据的内容，而 repair 则要求存在可复现的问题。如果一个请求涉及多个阶段，应按顺序运行各方法，并遵守每种方法的停止条件和产物约定。

执行界面

将能力文件视为可移植的方法，而非必须在 OKF Studio 中运行的要求。

• 在 OKF Studio 中，使用命名为 okf_* 和 studio_stage_* 的工具。如果工作界面有用，请输出所选方法要求的结构化产物。
• 在 Studio 之外，将清点、读取、搜索和遍历操作映射到宿主的文件系统与搜索工具；运行随附的验证器以检查规范符合性和连通性；对于获准的编辑，使用宿主常规的差异比较与审查流程。不要虚构 Studio 工具结果、回执 ID、健康问题 ID 或包指纹。
• 默认情况下，结构化产物仅限 Studio 使用。 在 Studio 之外，除非调用方明确要求产物 JSON，否则应以简洁的散文、Markdown 或常规差异形式返回相同的证据和决策。
• 授权由宿主工作流决定。 Studio 会将写入操作保留在经审查的暂存区中。在其他环境中，应遵循用户要求的编辑范围和宿主的常规审批规则；方法中的 Studio 暂存表述不会撤销明确的文件编辑请求。

唯一规则

当**每份概念文档都包含带有非空 type 字段的 YAML 前置元数据时，**该包即符合规范。 这就是唯一的硬性要求，v0.2 已明确说明这一点。其他所有内容都是建议采用的结构，消费者必须容忍其缺失。坚持这一原则，任何人制作的包都能被任何人的 Agent 读取。完整的符合规范标准和消费者容忍约定见 spec.md。

v0.2 在此基础上新增的内容。 v0.1 回答“Agent 需要了解什么？”v0.2 新增了“它应该相信这些内容吗？这些内容仍然正确吗？”四类可选字段均不会导致包不符合规范：sources（知识的来源及可信度信号）、generated 和 verified（由谁编写、由谁确认，信任级别也据此计算）、status 和 stale_after（生命周期），以及 Attested Computation 类型（一种获准由 Agent 运行、但绝不能由 Agent 编写的计算）。有两项内容相较于 v0.1 发生了变化：timestamp 变为 generated: { by, at }，而正文中的 # Citations 章节变为前置元数据中的 sources。根据文档说明的回退机制，v0.1 包仍可使用，因此迁移值得进行，但并不紧急；migrate 命令中提供了具体流程。

命令

调用方式为 /okf <command> [target]。每条命令详见 commands.md。

命令	功能
init	创建一个捆绑包。创建目录、声明 okf_version 的根目录 index.md，以及首批概念文件夹。
add	编写一份概念文档。选择描述性的 type，填写建议的 frontmatter，记录 sources 和 generated，并使用 # Schema 和 # Examples 编写正文。
attest	将经认可的计算定义为一个 Attested Computation 概念，以便 Agent 可以运行它并检查结果，但不能重写它。
migrate	将捆绑包从 v0.1 迁移到 v0.2。进行两处机械式重命名，然后判断参与者以及哪些内容不能声称已验证。
enrich	将来源（BigQuery 数据集、OpenAPI 规范、wiki、网站、文档字符串）转化为概念：先将其完整范围枚举到清单中，再爬取权威文档，补充架构、联接路径和引用，最后进行实体处理，为来源提及但从未解释的每个承载重要信息的名称创建其自身关联的概念。
link	使用相对 Markdown 链接连接概念，并在周边文字中说明关系。
index	生成或刷新 index.md 列表，让 Agent 能通过渐进式披露进行导航。
log	追加一条带日期的 log.md 条目（Creation、Update、Deprecation），最新条目置顶。仅追加，每条一行，便于并行生成方无冲突地合并。
validate	运行一致性检查。使用 node okf-validate.mjs <bundle>，或按照 commands.md 中的手动检查清单操作。
health	检查一致性、连通性、导航、来源、时效性、重复情况和覆盖度信号，不写入任何内容。
retrieve	为问题选择连贯的证据，并保留路径、遗漏、提供方、指纹和弃答决策。
export	将现有来源转换为符合规范的捆绑包：目录、元数据转储、架构导出、文档站点、网站或外部 URL（/okf export <url>）。映射完整范围，覆盖每个章节，为每个命名实体创建其自身的概念，然后通过创建门槛——而非仅生成首页快照。承担生成方角色。
consume	阅读捆绑包以回答问题。从 index.md 开始，跟随链接，并容忍缺失内容。

隐式模式

只要是在塑造供 Agent 后续阅读的知识，就无需等待他人要求，直接应用 OKF：

• 如果你正在记录 Agent 会查阅的数据资产（表、视图、数据集、指标、维度）或流程（运行手册、操作手册、事件指南），就将其写成带有 type 的概念，而不是零散的文字说明。
• 如果你正在导出或转换供 Agent 使用的元数据、目录、架构或文档字符串，就生成一个包，而不是 JSON 块或 Wiki 转储。
• 如果你正在编写 Agent 需要的弃用通知、联接路径或业务含义定义，那么它就是一个概念。为它创建文件并指定 type。
• 如果你正在编辑现有的 OKF 包，就要随时确保其符合规范：更新概念的 generated（包括 by 和 at，因为当前操作方可能与上次编写该概念的人不同），在 log.md 中追加一条记录（放在今天的标题下，占一行，绝不修改过去的记录），重新生成受影响的 index.md，并在创建关系时添加链接。generated.at 标记的是最近一次有意义的更改，因此，不改变含义的机械转换（例如转换链接格式、调整标点）应更新日志，但保留 generated 不变；改写文字则应刷新它。模型变更意味着操作方变更：如果不同的模型编写了新句子，应在 by 中记录该模型，而不是沿用旧的署名。如果你对带有 verified 事件的概念做了实质性修改，该验证就不再涵盖概念当前的内容；应移除它，而不是让它为无人核验过的文本背书。这就是“知识经过触碰和转换”的情形；如果跳过这些记录工作，知识包就会在不知不觉中逐渐失效。

限制。 OKF 适用于供 Agent 阅读的知识，不适用于仅供人阅读的文字。README、博客文章或面向人的设计文档都不是知识包。如果无法确定某项内容是否面向 Agent，请先询问，再进行转换。

概念文档一览

一个概念由 frontmatter 和 Markdown 正文组成。它的标识是去掉 .md 后的路径，因此 tables/orders.md 就是概念 tables/orders。

• Frontmatter。 必填项是 type。建议按优先级依次填写：title、description（一句话）、resource（底层资产的规范 URI）、tags（YAML 列表）。接下来是 v0.2 中新增的字段族，均为可选：sources（列表，每项至少需要 resource；若正文引用了该项，则还需提供 id；若已知，还需提供 author、usage_count、last_modified 这些可信度信号）；generated: { by, at }（记录撰写者和时间，取代 v0.1 的 timestamp）；verified（由真实人员确认的 { by, at } 列表，或单个不带列表标记的映射）；status（draft|stable|deprecated，缺省时表示 stable）；以及 stale_after（绝对日期，格式为 YYYY-MM-DD）。生成方可以添加任何其他键，使用方应保留未知键，而非拒绝它们。
• 参与者。 每个身份字段（generated.by、verified[].by、sources[].author）都使用同一约定：Agent 或工具使用 <producer>/<version>，人员使用 human:<id>，自动化流程使用 process:<id>。使用方根据 human: 前缀计算信任级别，因此 Agent 生成的内容绝不能使用该前缀。只有遵循这一规则，信任层才有意义。
• 正文。 优先使用结构化 Markdown（标题、列表、表格、围栏代码），而非自由形式的散文。适用时使用常见标题 # Schema、# Examples 和 # Computation。用脚注和 sources 条目的 id 为每条主张标注来源（...sharded daily.[^ga4-schema]）；标签是连接键，不是正文。对于每条事实，请从扩展集合中选择最准确的表达形式（见下一节）。
• 保留文件名，不能用作概念。index.md 是目录列表，不包含 frontmatter；但 bundle 根目录的 index.md 例外，可以声明 okf_version。log.md 是只追加的带日期变更历史；不得编辑过去的条目，修正内容应以新条目取代。
• 链接。 两种形式都属于有效的 OKF：bundle 绝对路径（/tables/customers.md，规范建议使用，因为即使链接文件移动，这种形式仍然有效）和相对路径（customers.md、../tables/customers.md）。不过默认仍使用相对路径：GitHub 会将绝对路径解析到仓库根目录，导致 404；Google 的参考可视化工具不会据此建立任何边；Google 也正是出于这个原因，将自己的示例 bundle 全部改成了相对路径。链接文件移动时，相对链接会失效，因此每次移动后都要重新运行验证器；验证器会报告这两种失败情况。链接表达了一种关系，其含义取决于周围的正文，而不在链接本身。
• 外部材料。 引入的网页或文档应成为 references/<slug>.md 下的普通概念，并设置 type: Reference，同时将其 URL 填入 resource。要吸收其内容，而不只是记录 URL：将实质内容提取到正文中，使该概念离线时也能独立存在——resource 用于记录来源，以便重新核查，而不是替代知识。依赖实时链接的摘要只是一个空壳（见 /okf export）。

选择最清晰的 Markdown 形式

“优先使用结构化 Markdown”不仅适用于标题和表格。对于具有内在结构的事实，扩展 Markdown 形式比散文更便于机器读取（Agent 解析边列表或公式，而不是描述它们的段落），而且在实际阅读这些资料包的平台（GitHub、OKF 查看器）上能呈现丰富的格式。如果某个使用方无法渲染这些形式，源内容仍会以普通 Markdown 呈现，因此不会损失可移植性。

事实	写成	而不是
拓扑：连接、沿袭、管道流、状态	```mermaid 代码围栏（erDiagram、flowchart、sequenceDiagram）；边就是数据	描述箭头的散文段落
正式定义：指标公式、阈值、时间窗口	TeX，行内使用 $…$，独立成行使用 $$…$$	在散文中用伪数学描述（“计数除以时间窗口”）
术语含义：词汇表、枚举值、状态码	定义列表（Term 后接 : definition）	形如“X - 表示 Y”的项目符号
带状态的核对清单：推出或迁移进度	任务列表（- [x] / - [ ]）	“步骤 1 到 3 已完成”之类的散文
将一项声明归因于一个来源	脚注标签使用 sources 条目的 id（[^ga4-schema]）	括号中的 URL，或没有对应条目的裸 [^1]
逐字段事实：架构、参数	Markdown 表格（已是惯例）	键值形式的散文

用散文表达含义和推理；事实有具体结构时，就选用这些形式。templates.md 中的示例展示了每种形式的具体用法。

验证

对资料包目录运行随附的检查器：

node okf-validate.mjs path/to/bundle

对于硬性要求（概念缺少 frontmatter 或 type 为空），检查器会报错（退出码为 1）；对于软性建议，则会发出警告，但不会导致资料包验证失败，因为使用方能够容忍这些问题。v0.2 新增的内容都不会导致错误，因为它们全是可选项；检查器会将其作为建议进行检查，并且只有在根索引声明 "0.2" 的资料包上使用 --strict 时，才会启用相应的门槛。该门槛涵盖遗留的 timestamp 和 # Citations、缺少 resource 的 sources 条目、缺少 by 的 generated、超出范围的 status，以及缺少 runtime 或计算内容的 Attested Computation。v0.1 资料包无论是否启用严格模式，都能通过验证。检查器还会在警告中报告资料包的图连通性，包括孤立节点（没有指向其他概念的概念链接，也没有来自其他概念的概念链接的概念）和失效的概念链接（目标不是概念的链接，包括指向保留文件 index.md 的链接）。传入 --strict 可将这些问题转为失败：这是生产者门槛，因为 Agent 遍历资料包时无法到达孤立节点或跨越失效链接，所以这些情况从结构上就意味着上下文缺失。编辑描述后传入 --drift：它会将索引中的每条条目与其链接概念的 description 进行比较，并找出仍在宣传旧声明的条目。脚本通过验证并不代表所有地方的渲染结果都一致；实际使用方对 actor 前缀和链接形式的处理可能与规范不同，commands.md 中的差异列表说明了哪些地方需要再次核查。脚本所依据的审查清单见 commands.md。

验证检查的是符合规范，而不是覆盖程度。 一个只有五十页网站中少量内容的简略存根也能顺利通过验证，因为唯一规则针对的是每个文件的 type，而不是资料包是否完整收录了来源内容。从来源生成资料包（export、enrich）时，默认运行是必要条件，但还不够——请运行 okf-validate --strict，并遵循 commands.md 中的创建门槛：覆盖所有发现的章节、概念具备实际深度、将每个承载关键信息的名称拆解为独立且带链接的概念（资料包应在门槛规定的位置结束，而不是在来源自身的解释结束时结束）、构建没有孤立节点或失效链接的连通图，并将任何爬取边界记录在 log.md 中。默认运行 okf-validate 通过验证，并不等于导出工作已经完成。

此技能中的文件

• spec.md。OKF v0.2 的完整规范性参考（符合性、字段、来源与信任、参与者、链接、经证明的计算、版本控制、与 v0.1 的变更、非目标、设计原则）。
• commands.md。逐一介绍各命令的端到端流程、涉及的文件和验证清单。
• templates.md。概念、根目录 index.md、子目录 index.md 和 log.md 模板，以及 BigQuery 表、指标、运行手册和外部引用的完整示例。
• writing.md。适用于撰写和修订的读者任务、行文、结构、修订和事实保留通用规范。
• capabilities/。由上方路由器选用的窄范围检查、检索、创建、丰富、审计、修复、研究、变更影响、迁移、撰写和修订方法。
• okf-validate.mjs。零依赖的符合性检查器。

来源

Open Knowledge Format 由 Google Cloud 发布。规范：GoogleCloudPlatform/knowledge-catalog。公告：Open Knowledge Format 如何改进数据共享。同一代码库还提供了参考生产者（一个丰富 Agent）、单文件 HTML 可视化工具（作为参考消费者）以及四个可浏览的示例包；spec.md 中列出了它们。GA4、Stack Overflow 和 Bitcoin 已重新生成 v0.2 版本，acme_retail 则是新示例，涵盖了 v0.2 的所有功能，包括可信度信号、已弃用指标和由 BigQuery 支持的经证明计算。OKF v0.2 仍是一项早期标准，旨在向后兼容地扩展，并明确将证明运行时协议、证明者 ABI、证明缓存和语义层模板推迟到后续修订，因此请重新查阅规范，不要自行臆造。