GA4：指标与 join 被实体化
只有一张主表，却生成了多个 metric / reference 文档，并从主表链接过去。OKF 的价值显现在“怎么用”，而非仅仅 schema。
把数据资产周围的 schema、指标、join path、runbook 与业务语境， 沉淀成一束人和 agent 都能读写、可 git 管理、可被多方消费的 markdown 文件。
OKF 不是另一个知识服务， 而是一层 format-first 的 agent 知识交换格式。
企业里 agent 要回答一个业务问题，往往得跨 catalog、wiki、代码、notebook 和专家记忆， 把表 schema、指标定义、join path、runbook、业务口径重新拼一遍。 Google 的关键判断不是“再建一个知识平台”，而是把知识交换层下沉为一种文件格式—— 它能被 git、文件系统、静态站点、搜索索引和各种 agent 直接消费，不需要 API、账号、SDK 与迁移。
标准化的面被压到极小：一个 bundle 就是一棵 markdown 目录树，
concept 的身份就是它的文件路径，关系就是普通 markdown 链接，
元数据就是 YAML frontmatter——而规范真正强制的字段只有一个 type。
下面按“为什么是现在 → 格式契约 → 生产线 → 消费端 → catalog 接入 → 样例 → 边界 → 启发”逐层拆开，
并对每个判断保留可核对的源码证据。
OKF 的起点不是模型不会推理，而是 agent 缺少可携带、可验证、可跨工具复用的上下文。
上下文碎片化是真正的起点。 一个 agent 要回答“这张表能不能用来算复购率”，需要的不只是 schema，还有指标口径、 可用的 join、历史 runbook、以及谁在什么语境下定义了这些。这些知识散落在不同系统里， 每次都要重新拼装——OKF 把这一块拎出来作为要解决的问题。
所以 Google 选择 format，而不是又一个 service。 服务意味着 API、认证、SDK、迁移成本；格式则可以被既有工具链直接吃下。 SPEC 的 non-goals 明确排除了“固定 taxonomy”和“规定存储/查询基础设施”—— OKF references 既有 schema（Avro、Protobuf、OpenAPI），而不试图取代它们。
这其实是给 LLM-wiki 实践上规格。 Obsidian、Notion、AGENTS.md 这类 markdown 知识库早就存在，缺的是一套可交换的最小约定。 Google 的战略叙事，是让生产者、消费者和 catalog 供应商共享一种文件级语言，而不是共享同一个产品—— 一个知识交换的 lingua franca。
# OKF references other schemas;
# it does not subsume them.
✗ 定义固定的 concept 类型表
✗ 规定存储 / 服务 / 查询基础设施
✗ 取代 Avro · Protobuf · OpenAPIOKF v0.1 标准化的，只是让一个知识语料“自描述”所需的最小结构约定。其余全部交给生产者。
分发单位是 Knowledge Bundle——一棵 markdown 目录树，可以是 git repo、tarball，
或大仓库里的一个子目录。每个 concept 是一个 markdown 文件，由 YAML frontmatter 和正文组成；
它的 Concept ID 就是去掉 .md 后缀的相对路径——身份绑定到文件系统，不需要额外 registry。
---
type: BigQuery Table # REQUIRED — 唯一强制字段
title: Orders
description: One row per completed order.
resource: https://console.cloud.google…
tags: [sales, orders, revenue]
timestamp: 2026-05-28T14:30:00Z
---
# Schema
| order_id | STRING | 唯一订单号 |
| customer_id | STRING | FK → [customers](/tables/customers.md) |
# Joins
Joined with [customers](/tables/customers.md) on customer_id.my_bundle/
├── index.md # 可选 · 渐进浏览
├── log.md # 可选 · 变更时间线
├── datasets/
│ └── sales.md
└── tables/
├── orders.md
└── customers.md分发单位是一棵 markdown 目录树。知识被降到软件团队已经熟悉的协作原语：clone、diff、review、blame、tarball、静态托管。
概念身份就是 bundle 内相对路径，无需中心 registry；移动、链接、代码审查仍服从文件系统语义。
只强制 type，推荐 title / description / resource / tags / timestamp，其余字段生产者自定义、消费者宽容保留。
普通 markdown 链接是唯一的图边；A→B 断言一种关系，具体类型由周围 prose 承载，而不编码在链接里。
保留文件名：index 支持渐进披露，log 记录局部变更时间线。两者都非必需，消费者可按需即时合成。
conformant 门槛被刻意压低：未知 type、额外字段、断链、缺 index 都不得让消费者拒绝 bundle。为生态早期增长让路。
仓库里的 reference 实现把这套格式落成一条可运行的生产—消费链路；格式本身不要求其中任何一环。
reference enrichment agent 是一个 proof-of-concept 生产者：用 Google ADK + Gemini，把 source metadata 写成 OKF 文档，并靠写入约束保证结构不退化。
生产端被抽象成三件事：列出概念、读取概念 metadata、可选采样行。 BigQuery 只是第一个实现——这把“知识从哪来”做成了可插拔的接口。
它把 dataset 与 table/view 映射为 concepts，并对日期分片表族（events_YYYYMMDD）
做 wildcard family 聚合，提供 schema、partition、clustering、sample rows 等原始事实。
先 BQ pass：逐个 concept 跑 BQ agent 写出基础文档；
再 web pass：当存在 seed URL 时，抓取权威页面，把指标、join path、引用与语义说明补进去。
收尾自动 regenerate 各级 index.md。
最有工程味的部分：agent 不能自由写文件系统，只能通过一个窄工具落盘。 web pass 更新已有文档时，不能删 schema 字段、不能减少 citations， 必须在旧结构上增强——这是让增强保持单调性的反馈控制器。
# web pass 被约束为「只增强，不重写」
keep existing schema fields
keep existing citations
add metrics · joins · references
add business context (cited)
write once, at the very endvisualizer 同样在证明 format-first：它只是一个把 bundle 预解析进单个 HTML 的离线视图——OKF 本身并不要求它存在。
graph = concepts + markdown links。
visualizer 读取所有非 index 的 markdown 文件作为节点，再从正文里的 .md 链接
抽取 directed edges 和 backlinks，用 Cytoscape.js 画图、marked 渲染正文——无需后端。
detail panel 重放 OKF 文档。
选中节点后展示 type、title、description、resource、tags 与 markdown body，
并把内部绝对 .md 链接改写成图内跳转。图谱只是导航，详情面板才是真正阅读知识的地方。
这一端的意义不在于 viewer 本身有多强，而在于它证明了：这种文件束可以被任何人用一段静态代码转成可浏览的知识图谱。
# 输出一个自包含 HTML
parse *.md (≠ index) → nodes
extract [..](.md) links → edges + backlinks
embed graph JSON → <script>
render Cytoscape.js · marked
no server · no build stepDataplex 侧能 ingest OKF，但它不是 OKF 的唯一宿主——这个姿态对一个开源格式很关键。
DocumentsLayout 把文件映射成 entry。
mdcode 的 DocumentsLayout 把每个 .md 映射为 Knowledge Catalog entry：
frontmatter 映射到资源字段，markdown body 映射到 overview aspect。
路径如 references/metrics/event_count.md 会变成同名 entry。
CatalogSnapshot + CatalogSync。 mdcode 用 manifest 选择 source/layout，再通过 pull/push 在本地文件快照和 Dataplex API 之间 同步 entry 与 aspect——一条标准的 metadata-as-code 路径，把 OKF 从 repo artifact 推向服务内可用知识。
但接入也暴露了一个代价：OKF 的自由 type 进入 Dataplex 的 type 系统时会被保守映射。
只有合法的三段式 type ref 会被保留，否则 fallback 到 dataplex-types.global.generic——
ingest 变简单，却牺牲了一部分领域类型语义。（见 §07）
references/metrics/event_count.md
│
▼ DocumentsLayout
entry: event_count
type: <3-part ref> || generic
aspect: overview ← md body
fields: ← frontmatter仓库里的三个样例 bundle 展示了 OKF 能在不同密度上工作——从轻量表族，到把指标和 join 实体化为一等概念。
只有一张主表，却生成了多个 metric / reference 文档，并从主表链接过去。OKF 的价值显现在“怎么用”，而非仅仅 schema。
把帖子类型、投票类型、审核状态、license 等从主表周边抽为 reference，适合解释结构复杂的公共数据集。
更接近传统 catalog：dataset + blocks / transactions / inputs / outputs 四张表。说明 OKF 可以从轻量 schema 起步，不必一次语义化到底。
# Metrics
- [Event Count](../references/metrics/event_count.md) — 事件总数
- [New User Count](../references/metrics/new_user_count.md) — 首访用户数
- [Avg Pageviews](../references/metrics/avg_pageviews.md) — 人均浏览
# Joins
- [Events → Ads Clicks](../references/joins/events___ads_clickstats.md)
join on collected_traffic_source.gclid
# Citations
- developers.google.com/analytics/bigquery/…这正是 §02 那条“markdown links 形成知识图”的具象化：一张表通过普通链接， 指向围绕它的指标与 join——而这些指标本身又是可被独立引用、独立消费的概念。
现在该看的不是“能不能跑”，而是“标准极简”与“工具可用”之间的张力。它更像一份标准提案 + 一个可运行 PoC。
SPEC 最小只要求 type，但 writer 工具实际要求 title / description / timestamp；SPEC 推荐 bundle-relative 绝对链接，generator 的 edge extractor 目前却跳过 /…md、偏好相对链接。链接规范仍需收敛。
web pass 依赖 HTML 抓取、40KB markdown 截断，以及 LLM 判断哪些是权威链接、哪些页面值得写入。适合 PoC，但还不是有强保证的引用管线。guardrails 能降低覆盖真实 schema 的风险，却不能证明外部内容本身正确。
OKF 的自由 type 进入 Dataplex 时，只有合法三段式 type ref 才保留，否则 fallback 到 generic。ingest 简单了，却丢掉一部分领域类型语义。
博客与 README 都明确：reference agent 和 visualizer 是 proof-of-concept。OKF 能不能成立，关键不在工具完整，而在多方生产者和消费者是否写出兼容实现。宽容消费降低了参与成本，但也延后了强一致语义的形成。
抛开 Google Cloud 这一具体宿主，OKF 给出的是一个关于“知识控制点放在哪里”的判断。
OKF 真正的产品判断，是把知识互操作的控制点从服务 API 移到文件格式——牺牲强中心化能力，换来最低集成成本、最高可移植性、以及更容易被 agent 写入的协作面。
当知识是 git 里的 markdown，它就能 diff、review、blame、回滚。生产由受约束的 agent loop 完成，消费由静态工具完成，人始终在环内可改可读。
frontmatter 给机器，正文给人，链接给两者。一束文件同时是人类文档、agent 上下文和 catalog 数据源——这是它区别于任何单一知识平台的地方。