Google OKF：面向 AI 知识资产的 Markdown 交换格式

2026 年 6 月，Google Cloud 发布了 Open Knowledge Format（OKF）。OKF 试图规范一类已经广泛存在、但彼此不兼容的做法：把表结构、指标口径、API 约定、运行手册和业务规则写入 Markdown 文件，由人和 Agent 共同维护。

OKF 不提供知识库产品、向量数据库或 Agent runtime。它定义的是知识交换格式：目录化的 Markdown 文件、少量 YAML frontmatter、普通 Markdown 链接，以及对来源、验证状态、过期时间和受控计算的约定。人工、元数据导出程序和 LLM 都可以生产 OKF；搜索索引、网页阅读器、RAG 管道、MCP Server 和 Agent 都可以消费它。

本文依据 Google 的发布文章和 OKF 规范整理。发布文章介绍的是 v0.1；仓库中的现行规范已更新到 v0.2。v0.2 保留了目录和链接模型，并补充了面向 Agent 维护知识库的 provenance、trust、lifecycle 和 attestation 字段。下文以 v0.2 为准，同时说明与 v0.1 的关系。

Agent 缺少的是可用且可迁移的上下文

企业知识通常分散在数据目录、Wiki、代码注释、指标平台、工单、共享盘，以及少数熟悉系统的员工经验中。以一个分析问题为例：

“本周活跃用户应该怎样计算？”

要回答这个问题，Agent 需要知道事件表的位置、用户 ID 口径、去重规则、时区、过滤条件、可用表、指标负责人，以及 SQL 是否符合财务或分析团队确认的定义。这些信息可能分别存在于数据目录、dbt 模型、业务文档和历史 SQL 中。

常见处理方式主要有两种：

1. 检索原始资料。 将 Wiki、文档和代码切分后写入搜索或向量索引，回答时再拼接上下文。
2. 维护产品专用目录。 数据目录、语义层、知识图谱和 Agent 平台各自维护 API、对象模型和权限模型。

检索原始资料时，命中文本通常没有明确表达来源、当前性和审核状态。产品专用目录则难以迁移到其他系统。每接入一个新的 Agent，团队都可能要重新实现导出、转换、索引和上下文组装。

OKF 的范围较窄：先把知识表示为可由 Git 管理、可由普通编辑器打开、可被其他系统导入的文件集合。检索、执行、权限和界面仍由具体系统负责。

现有方案解决了哪一层问题

为 Agent 提供正确上下文，通常需要解决四个问题：从哪里取得知识、如何将其转成可检索数据、回答时如何选择上下文、以及如何判断内容是否仍然可信。现有方案各自覆盖其中一部分。

实际系统通常组合使用这些方案。例如客服 Agent 通过 API 查询订单状态，通过 RAG 召回退款政策，通过规则引擎控制可执行操作。问题不在于缺少检索或存储产品，而在于知识从源系统进入这些组件时，常常丢失或重新定义了身份、来源、审核状态、有效期和关系。不同团队又会为同一类文件设计不同 frontmatter、目录和导出程序。

OKF 试图补足的是这一层公共约定。它不替换向量检索、知识图谱或数据目录，而是为表、指标、API、政策和运行手册提供可被这些系统共同读取的源文件格式。一个消费者可以把 OKF Bundle 建入向量索引，另一个消费者可以从其中抽取图谱边，第三个消费者可以按 status 和 verified 过滤；三者不必各自定义原始知识的结构。

Bundle、Concept 与文件路径

OKF 的 Knowledge Bundle 是可独立分发的目录树。目录中每个普通 .md 文件表示一个 Concept，即一条独立知识。Concept 可以描述表、数据集、API 等具体资源，也可以描述指标、业务规则或故障处理手册等抽象对象。

Concept ID 使用文件相对 Bundle 根目录的路径，并去掉 .md 后缀：

analytics/
  index.md
  tables/
    orders.md
    customers.md
  metrics/
    weekly-active-users.md
  playbooks/
    late-data.md

上例中，tables/orders.md 的 Concept ID 是 tables/orders。目录用于导航；Concept 之间的普通 Markdown 链接用于表达关联、依赖和引用。因此，一个 Bundle 同时具备目录层级和链接图。

Bundle 可以作为 Git 仓库、压缩包，或较大仓库中的子目录分发。规范推荐 Git，因为提交历史、责任人和 diff 有助于审核知识变更；但 Git 不是格式要求。

index.md 与 log.md

每一级目录有两个保留文件名：

其他 .md 文件都是 Concept。不能将 index.md 和 log.md 作为普通概念文档使用。

index.md 并非必需。人或 Agent 可以先读取索引，再按需打开少量文件，而不用把整个知识库放进上下文。log.md 也可选。Git 历史记录了文件变更，面向读者的更新摘要则便于了解近期语义变化。

Concept 文档与 frontmatter

每份 Concept 都是 UTF-8 Markdown，由文件开头的 YAML frontmatter 和其后的 Markdown body 组成：

---
type: BigQuery Table
title: Customer Orders
description: 所有渠道中已完成订单，每行对应一笔订单。
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
---

# Schema

| 字段          | 类型      | 含义                                            |
| ------------- | --------- | ----------------------------------------------- |
| `order_id`    | STRING    | 全局唯一订单标识。                              |
| `customer_id` | STRING    | 关联 [customers](/tables/customers.md) 的外键。 |
| `placed_at`   | TIMESTAMP | 用户提交订单的时间。                            |

# Joins

通过 `customer_id` 与 [customers](/tables/customers.md) 关联。

frontmatter 存放适合过滤、路由和预览的结构化信息。body 保留 Markdown 的表达能力，适合记录字段说明、示例、决策依据和运行步骤。OKF 不要求把所有领域知识收敛为固定 JSON Schema。

唯一必填字段是 type

v0.2 的合规性要求很少：每个非保留 Markdown 文件必须包含可解析的 frontmatter，且其中必须有非空 type。

type 是描述 Concept 种类的短字符串。规范列出的例子包括 BigQuery Table、API Endpoint、Metric、Playbook、Reference 和 Attested Computation。OKF 没有中央类型注册表。生产者应选用清晰稳定的类型名；消费者必须容忍未知类型，并按通用 Concept 处理。

格式只约束互操作所需的最小表面，不接管领域模型。数据平台可以使用 dbt Model、Looker Explore，研发知识库可以使用 Service、ADR、Runbook。消费者不能因为不认识某个类型而拒绝整个 Bundle。

推荐字段和扩展字段

规范推荐以下字段，但均非强制：

生产者可以加入其他字段。消费者应在读写往返时保留未知字段，且不能因为未知字段拒绝文档。团队因此可以逐步加入数据分级、责任人或访问策略等约定，无需等待 OKF 修改规范。

body 没有必需章节。# Schema、# Examples 和 # Computation 具有约定含义，适用时应优先使用，方便人和程序定位内容。

链接与路径规则

OKF 使用 Markdown 链接表示 Concept 关系，支持两种路径：

• 以 / 开头的 Bundle 相对路径，例如 [customers](/tables/customers.md)。规范推荐这种形式，因为移动链接源文档后，目标路径不受源目录影响。
• 标准相对路径，例如 [相邻概念](./other.md)。

链接不携带 depends_on、joins_with 等关系类型。关系含义由周围文本表达。图消费者通常将链接作为有向、无类型边处理。这一选择降低了图谱语义的精确性，但保留了 Markdown 的可读性和编辑便利性。

消费者必须容忍断链。链接目标不存在不构成格式错误，它可能表示尚未补齐的知识。例如，Agent 发现某表引用了不存在的指标定义时，可以创建待办，而不应使整个 Bundle 导入失败。

resource、sources[].resource、computation、executor.resource 和 attester.resource 等路径型字段均支持绝对 URL、以 / 开头的 Bundle 相对路径和普通相对路径。references/ 是建议的目录名，适合存放外部资料镜像、执行说明和校验程序，但不是必需目录。

v0.2 如何表达来源、信任和当前性

早期 Markdown 知识库可读，但 Agent 难以判断内容的依据、审核状态和有效期。OKF v0.2 增加了一组可选 frontmatter 字段，使这些状态可以被程序读取。

字段可选不代表状态缺失没有含义。未填写相关字段的文档依然合规，消费者也能明确知道该文档没有提供相应信号。

sources：来源和主张归因

sources 记录 Concept 所依据的材料。每条来源的 resource 必填，可以是绝对 URL、Bundle 内路径、references/ 中的材料，也可以是不能直接跳转的范围描述，例如 “BigQuery 项目 X 中的全部查询”。

sources:
  - id: revenue-policy
    resource: https://wiki.example.com/finance/revenue-recognition
    title: 收入确认政策
    author: team:finance-fpa
    last_modified: 2026-06-18
  - id: executive-dashboard
    resource: dashboards/executive-revenue
    title: 收入驾驶舱
    author: team:finance-fpa
    usage_count: 5000
    last_modified: 2026-06-28
usage_window: { from: 2026-06-01, to: 2026-06-30 }

sources[].id 是可选字段，但正文引用来源时应提供稳定 ID。正文用 Markdown 脚注将具体主张关联到该 ID：

收入按财年内已确认记录的 `amount` 求和。[^revenue-policy]

[^revenue-policy]: 收入确认政策

脚注标签是 sources[].id 的连接键。消费者应按 ID 解析归因，不应依赖脚注中的自由文本。即使 Agent 重排来源列表，主张与来源的关联也不会变化。

来源可以包含三类客观信号：

• author：来源由谁或什么生成；
• usage_count：在 usage_window 内被使用、访问或执行的次数；
• last_modified：来源本身最后修改的日期。

规范没有定义统一的可信度分数。不同组织对作者、使用量和新鲜度的权重不同，固定分数难以迁移，也会随时间失效。usage_count 只应作为活跃度和趋势信号，不应用于精确比较仪表盘阅读次数和定时任务执行次数。

generated 与 verified

generated 记录当前内容最后一次实质性变更的生产者和时间：

generated: { by: catalog-agent/1.4.2, at: 2026-08-06T09:30:00Z }

generated.by 在 generated 对象出现时必填，generated.at 使用 ISO 8601 时间。规范为 actor 建议了统一写法：

• Agent 或工具：<producer>/<version>，例如 catalog-agent/1.4.2；
• 人：human:<id>，例如 human:alice；
• 自动流程：process:<id>，例如 process:finance-nightly。

verified 记录内容是否已由某个参与者根据来源或底层资源确认。它可以保留多条事件，例如人工审核和自动校验：

verified:
  - { by: human:finance-owner, at: 2026-08-05T15:00:00Z }
  - { by: process:finance-nightly, at: 2026-08-06T02:00:00Z }

规范也接受单个 mapping：verified: { by: human:finance-owner, at: ... }。消费者必须把它作为单元素列表处理。

消费者可以从 verified 推导信任层级：

这些字段是建议性信号，不是访问控制。人工审核过的定义仍可能过期；自动校验通过的定义也可能不适用于某个业务问题。

status 与 stale_after

status 可取 draft、stable 或 deprecated，缺失时默认 stable：

status: deprecated
stale_after: 2026-09-30

draft 表示内容尚未审阅或可能不完整。deprecated 表示保留历史和链接，但不再是当前定义。stale_after 是绝对日期。当 today >= stale_after 时，文档处于 stale 状态。规范使用绝对日期而非 “读取后 30 天” 这类 TTL，消费者只需比较日期，不需要确定 TTL 的起算点。

Agent 选择上下文时，应结合 status、stale_after、generated.at、最新的 verified.at 和来源的 last_modified。不宜将 stale 文档直接排除，因为历史指标解释、旧系统修复和迁移仍可能需要它。任务允许时，可以保留这类内容，并将 stale 状态明确传给模型和用户。

Attested Computation 如何约束敏感计算

v0.2 新增的 Attested Computation 用于描述经批准的计算及其运行校验方式。它解决的问题是：如何确认某次数字确实由批准的计算产生。

假设 Agent 需要回答 “2025 财年收入是多少”。即使它检索到了正确的指标文档，也可能改写 SQL、遗漏参数、替换为相近的表，或在复述时更改查询结果。将 SQL 放在 Markdown 文档中无法约束实际运行。

OKF 将经批准的计算建模为独立 Concept：

---
type: Attested Computation
title: 按财年计算已确认收入
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: references/skills/run-bigquery.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: references/attesters/revenue.py
generated: { by: metric-agent/2.0.0, at: 2026-08-01T08:00:00Z }
verified: { by: human:finance-owner, at: 2026-08-02T14:00:00Z }
stale_after: 2026-12-31
sources:
  - id: revenue-policy
    resource: https://wiki.example.com/finance/revenue-recognition
    title: 收入确认政策
---

# Computation

```sql
SELECT SUM(amount) AS revenue
FROM finance.recognized_revenue
WHERE fiscal_year = @year
```

该类型在通用字段之外定义了以下契约字段：

指标说明无需包含全部 SQL，可以链接到独立计算 Concept：

# Definition

财年收入由[按财年计算已确认收入](../computations/revenue.md)产生。

同一计算可以被指标、仪表盘和报表复用，也可独立维护验证状态和过期时间。

参数边界和执行过程

规范要求 Agent 只能为已声明的 parameters 提供值，不能改写 computation。参数绑定和可执行产物生成由消费者或 executor 完成。attester 根据计算定义和参数独立推导预期执行产物，再与 receipt 中的 executed_sql 或 compiled_sql 比较。

典型消费过程如下：

1. 通过 type: Attested Computation 或指标文档链接发现计算；
2. 读取 frontmatter 契约和内联或外部计算；
3. 仅填写已声明的参数；
4. 按 executor 执行并获取符合 receipt 约定的运行证据；
5. 在确定性环境中运行 attester，校验实际计算、参数绑定和展示结果；
6. 根据 attestation、stale_after 和 trust tier 展示结果、提示风险或拒绝输出。

verified 与 attestation 的职责不同：

• verified 确认定义仍符合政策或来源。它通常较慢，记录在 Bundle 中；
• attestation 确认一次运行是否按批准定义产生结果。它发生在运行时，receipt 不写回 Bundle。

旧定义仍可能被正确执行并通过 attestation。刚经人工审核的定义，也仍需要对每次敏感查询进行 attestation。

OKF 的职责边界

OKF 是知识表示和交换格式，不是完整的平台：

OKF 可以与 RAG、知识图谱、数据目录、MCP 和 Agent Skill 组合使用：

• RAG 可以对 OKF 文件和 frontmatter 建立混合索引；
• 知识图谱可以从目录和 Markdown 链接生成节点与边；
• 数据目录可以将表、血缘和使用信息导出为 OKF；
• MCP Server 可以将 Bundle 暴露为 search_concepts、read_concept、run_attested_computation 等工具；
• Agent Skill 可以说明如何按某个 runtime 读取、执行和验证 Attested Computation。

OKF 与 AI Native Agent 知识库的区别

这里的知识库指为 Agent 补充模型参数中没有、或需要随业务变化而更新的信息。例如客服 Agent 的知识库会包含商品规则、服务政策、退款条件、常见问题、工单处理流程和升级路径。Agent 在回答用户问题前，从中检索相关内容，以减少依赖通用预训练知识带来的错误，并让回答符合当前业务口径。

这类知识库通常由文档、FAQ、网页、表格或数据库记录构成。系统会对原始材料切分、嵌入并写入向量索引，再在每次请求时召回相关片段，拼接到模型上下文中。它解决的是”当前问题应补充哪些事实”。

OKF 解决的是更靠前的一层：这些知识在进入索引前，应以什么结构保存和交换。它不规定使用哪种 embedding 模型、向量数据库、分块策略或重排序算法。它规定一份知识文档如何表达类型、底层资源、来源、验证状态、过期时间和与其他知识的链接，使不同检索服务和 Agent 可以读取同一份知识资产。

客服 Agent 可以将服务政策、退款规则和升级流程整理成 OKF Concept，再由检索系统构建向量索引。用户询问退款条件时，检索系统先按问题召回相关 Concept 或片段，随后将正文、来源、验证状态和过期时间提供给模型。此时 OKF 不是 RAG 的替代品，而是 RAG 上游的知识表示层。

这一区分会影响知识库的建设方式。若只把文档切块写入向量库，原始资料的来源、审核人、版本、链接关系和过期状态常需由每个系统重新定义。OKF 将这些信息留在可审查的源文件中。索引可以重建，embedding 模型可以更换，服务可以迁移，知识的结构、来源和状态仍可保留。

不过，不需要为所有检索材料建立复杂的 OKF Bundle。变化快、风险低的临时公告或短期 FAQ 可以直接进入现有检索管道。涉及业务口径、合规政策、跨系统关联或需要 Agent 执行计算的知识，更适合使用 OKF 记录来源、审核和当前性。对于客服 Agent，这些字段可以帮助系统在召回后区分已审核的现行政策、待确认草稿和已废弃规则。

OKF 的优点、限制与适用范围

OKF 的价值来自其刻意收窄的范围。它只要求目录、Markdown、YAML frontmatter、链接和少量保留文件名，因此可以被现有编辑器、Git、静态站点、搜索系统和 Agent 直接处理。

这些优点有明确前提。OKF 不会自动让检索结果更相关，也不会验证来源是否真实、内容是否正确。verified 和 status 只是生产者提供的信号，消费者仍要决定信任策略。Attested Computation 只定义计算的描述和校验入口，实际 executor、attester、运行权限和沙箱必须由平台实现。

OKF 也有一些成本和限制：

• 格式仍处于早期阶段。 当前规范是 v0.2，生态中的 producer、consumer 和兼容性实践仍在形成。采用时需要自行维护版本兼容策略。
• 最小 Schema 带来一致性风险。 只有 type 是必填字段。不同团队可能为相同对象使用不同类型名和扩展字段，需要在组织内部另行约定词表和校验规则。
• Markdown 不适合所有内容。 大型表格、复杂图形、多媒体、细粒度评论和多人实时协作，通常需要其他存储或编辑系统。OKF 可以引用这些资源，但不取代它们。
• 链接图缺少标准关系类型。 Markdown 链接只表示存在关系，depends_on、joins_with 或数据血缘等具体语义仍在正文中表达。需要严格关系查询时，消费者要增加领域 Schema 或同步到知识图谱。
• 文件路径是身份。 重命名或移动文件会改变 Concept ID，并可能影响 Bundle 内链接和外部引用。团队需要将路径稳定性纳入变更流程。
• 来源与审核需要持续维护。 若没有 Owner、复核流程和过期策略，frontmatter 会像普通文档一样过时。格式不能替代内容治理。
• 不提供访问控制。 Bundle 内的 verified、status 和 resource 不等同于权限。数据读取、工具执行和密钥访问仍需 IAM、工具网关和审计系统控制。

适用范围可以按知识的复用范围和风险判断。跨多个 Agent、检索服务或团队使用的领域知识，特别是业务政策、指标定义、服务接口、数据资产说明和运行手册，适合整理为 OKF Bundle。它们需要稳定身份、来源、审核记录和关系导航。仅服务于单个检索应用、变化很快且风险较低的临时通知、活动文案或短期 FAQ，可以直接进入现有采集和索引流程。高结构化且要求严格关系推理的数据，也可以继续以语义层或知识图谱为主，再将面向人和 Agent 的说明导出为 OKF。

在 AI Native 系统中落地 OKF

OKF 不适合作为一次性文档迁移项目。它更适合进入知识生产、审核、消费和反馈的日常流程。

按发布边界组织 Bundle

可按独立发布、独立授权和变更节奏相近的领域划分 Bundle：

knowledge/
  commerce-analytics/
  finance-metrics/
  order-domain/
  developer-platform/
  incident-response/

Bundle 不必等同于组织部门。更实用的判断是：Concept 是否来自相近的源系统，是否遵循同一权限等级，是否需要同时提供给同一类 Agent。

团队还应约定常用 type 和对应正文结构：

这样做不要求建立全局本体，只是减少同一团队内的写法分歧。

从权威系统生成初稿

表结构、OpenAPI、dbt manifest、告警规则和服务目录等结构化来源可以由确定性导出器生成初始 Concept。导出器至少应写入 type、title、resource、generated 和对应的 sources。

LLM 可以补充字段摘要、示例、关联文档和关联路径。这些补充必须保留可追溯来源，不能将模型推断写成权威事实。

一条可审计的生产流水线通常包括：

1. 从权威 API 或代码仓库导出基础字段；
2. 为每个对象创建或更新对应 Concept；
3. 让 Agent 在指定的权威材料范围内补充 body 与 sources；
4. 对 source link、frontmatter、重复 Concept 和断链运行确定性检查；
5. 对高风险类型创建变更请求，由 Owner 写入 verified: human:<id>；
6. 合并后更新目录索引和搜索索引。

generated.by 应记录实际使用的生成器和版本。生成器出现系统性摘要错误时，团队可以据此定位并重建受影响批次。

为 Agent 提供渐进式读取工具

将整个 Bundle 拼入 system prompt 不具备可扩展性。更合适的方式是提供只读工具，以 index.md 和 frontmatter 作为导航面：

list_bundle(path)                -> 当前目录的 index 或合成目录
search_concepts(query, filters)  -> ID、title、description、type、trust、freshness
read_concept(id)                 -> frontmatter、body、出站链接
read_sources(id)                 -> sources 与逐条归因

当 Agent 回答 “订单收入如何计算” 时，可以先搜索 Metric 和 Attested Computation，再读取命中的指标定义、计算契约和少量关联表说明。index.md 支持在没有向量检索时按目录浏览。搜索服务也可以先按 type、tags、status、信任等级和过期时间过滤，再读取正文。

检索策略应由确定性代码实现：

• 默认优先 status: stable 且未过期的内容；
• 涉及财务、生产变更、权限和合规的任务，要求 human-reviewed，或进入人工审批；
• stale 或 draft 内容可作为背景材料，但应将状态传给模型和用户；
• deprecated 内容只用于历史追溯或迁移，不作为默认操作依据。

仅在 prompt 中写 “优先选择可信资料” 不足以执行这些约束，因为模型可能忽略或误解字段。

通过工具网关执行 Attested Computation

高风险指标、报表和生产操作需要区分解释知识和执行动作。MCP Server、内部工具网关或 Agent runtime 可以按 Attested Computation 暴露受限工具：

get_metric_value(
  computation_id: string,
  parameters: object
) -> { result, receipt, attestation, freshness, trust }

调用链至少应保证：

1. 参数 schema 来自 parameters，拒绝未声明参数；
2. executor 从 Bundle 指向的已批准实现读取运行说明；
3. receipt 保存实际执行内容、运行 ID 和原始结果；
4. attester 在独立的确定性环境中校验 receipt；
5. 返回给模型的结果包含 attestation verdict、验证时间和 stale 状态；
6. 工具网关、身份系统和数据权限系统继续控制执行权限，OKF 字段不替代这些机制。

这样可以避免 Agent 读到正确收入定义后，临时编写另一段 SQL 并直接展示数字。OKF 单独使用无法阻止该行为；需要将 executor 和 attester 接入工具网关。

将 Bundle 纳入代码审查和持续校验

当 Agent 使用知识做决策、生成 SQL 或执行操作时，知识文件也需要版本、审核和回滚能力。CI 可以检查：

• 每个 Concept 是否具有可解析的 frontmatter 和非空 type；
• index.md、log.md 是否被误写成 Concept；
• sources 中必填的 resource 是否存在，脚注 ID 是否能对应来源；
• stale_after 是否格式合法，敏感 Concept 是否过期后仍被标记为可自动执行；
• Attested Computation 的 runtime、参数、executor、attester 和计算位置是否完整；
• attester 是否覆盖成功和失败 receipt；
• 面向生产操作的变更是否经过指定 Owner 审核；
• 索引是否在变更后重建，检索结果是否保留 Bundle commit SHA。

对于自动生成的批量变更，还应限制可写目录、单次修改数量和可访问源系统。允许 Agent 维护知识库，不等于允许它绕过审核覆盖所有业务定义。

将运行反馈转为可审核的变更

Agent 使用 Bundle 时会发现断链、过期定义、缺少字段说明或 attestation 持续失败等问题。此类发现不应只留在 trace 中。

可以分别处理：

• 对断链、缺失 description、过期日临近等低风险问题，自动创建 issue 或候选变更；
• 对 schema API 可确定同步的新字段，自动更新并写入新的 generated 记录；
• 对指标语义、政策、权限、运行手册步骤和 Attested Computation 的变更，提交给 Owner 审核，并在确认后更新 verified。

Agent 的运行轨迹因此成为知识维护的输入，而不会直接变成事实。

一个最小 Bundle 示例

以下目录可以承载订单分析领域的知识：

commerce-analytics/
  index.md
  tables/
    orders.md
    customers.md
  metrics/
    weekly-active-users.md
  computations/
    weekly-active-users.md
  references/
    skills/run-bigquery.md
    attesters/weekly-active-users.py

Bundle 根目录的 index.md 可以声明目标协议版本，并提供 Agent 导航：

---
okf_version: "0.2"
---

# 数据表

- [订单表](tables/orders.md) - 完成订单及其金额、用户与时间。
- [客户表](tables/customers.md) - 客户主数据与注册信息。

# 指标

- [周活跃用户](metrics/weekly-active-users.md) - 按事件口径计算的周去重活跃用户。

frontmatter 只允许出现在 Bundle 根 index.md。okf_version 也是可选的。消费者不认识声明版本时，应尽力读取，而不应直接拒绝。

指标文档负责解释口径，并链接到受控计算：

---
type: Metric
title: 周活跃用户
description: 在自然周内至少完成一次有效行为的去重用户数。
tags: [engagement, active-users]
status: stable
generated: { by: analytics-catalog/1.4.2, at: 2026-08-06T08:00:00Z }
verified: { by: human:growth-metrics-owner, at: 2026-08-05T16:00:00Z }
stale_after: 2026-11-01
sources:
  - id: metric-policy
    resource: /references/metric-policy.md
    title: 活跃指标口径说明
---

# Definition

自然周按业务时区划分；同一用户在同一周内只计一次。结果由[周活跃用户计算](../computations/weekly-active-users.md)产生。[^metric-policy]

[^metric-policy]: 活跃指标口径说明

生产环境中，SQL 可以保存在版本控制的 .sql 文件中，再通过 computation 字段引用。

仍需由实现方解决的问题

OKF 的格式范围很小，也明确将一些问题留给实现方。

type 和 Markdown 链接不能替代严格的语义层或数据血缘系统。OKF 可以表达 “该指标由哪个计算产生”，但不定义列级血缘、血缘变更传播或统一关系类型。

verified 和来源信号不是安全边界。Agent 是否可以读取 Bundle、访问 URI 或运行计算，仍应由 IAM、工具网关、密钥管理和数据分级策略控制。

Attested Computation 定义了概念接口，但 v0.2 尚未规定 receipt/verdict 的统一 wire format、attester ABI、跨环境可移植性、沙箱和缓存。这些部分需要平台实现，或等待后续协议演进。

Markdown 降低了迁移和编辑成本，但不会自动保证内容质量。没有来源、Owner、过期策略、CI 校验和人工审核时，Bundle 仍会积累过时或互相矛盾的描述。

结语

Google OKF 将知识交换层限制在一组人可读、Agent 可解析、可版本管理的 Markdown 文件中。v0.1 定义目录、Concept、frontmatter、链接、index.md 和 log.md 等基础约定。v0.2 新增 sources、generated、verified、status、stale_after 与 Attested Computation，让知识库能够表达来源、审核、当前性，以及计算是否按批准定义执行。

在 AI Native 系统中，OKF 可以作为知识资产层：权威系统导出基础事实，Agent 补充可读上下文，Git 和 CI 管理变更，检索服务根据当前性和信任状态选择上下文，工具网关通过 Attested Computation 约束敏感执行。权限、检索质量和运行安全仍需要由周边系统提供。

参考资料

• Google Cloud：Introducing the Open Knowledge Format
• GoogleCloudPlatform/knowledge-catalog：OKF v0.2 Specification
• GoogleCloudPlatform/knowledge-catalog