OKF（Open Knowledge Format）是 Google 提出的开放规范，用于把 LLM-wiki 模式形式化为可移植、可互操作的格式。v0.1 定义了基础格式（markdown + YAML frontmatter），v0.2 加入了信任信号（provenance、verification、freshness、attestation），让机器生成的 bundle 可以被依赖。但跨团队共享仍然是个问题：每个 bundle 用独立 git repo 虽然可移植，但无法与它描述的数据一起被搜索，无法用统一身份和合规策略治理，也不在数据团队已有的技术元数据（schema、lineage、ownership）旁边。下游 agent 必须知道每个 bundle 的位置，bundle 多了就撑不住。

解决方案是把 OKF bundle 映射到 Google Cloud 的 Knowledge Catalog——一个面向 agent 的上下文引擎。Knowledge Catalog 为 BigQuery、Cloud Storage、操作数据库和应用中的数据提供统一的受治理索引，每条 entry 携带 schema、lineage、ownership 和 tags，还能用 typed aspects 扩展。搜索和跨项目查找由同一套 IAM 控制，agent 只能看到自己有权限的内容。发布 bundle 需要一次性配置和一次推送，sample code 在 Knowledge Catalog 仓库里，setup 调用 gcloud dataplex，推送委托给 kcmd（同仓库的 Metadata-as-Code CLI）。

setup 注册三种资源：EntryGroup 存放 bundle，EntryType（okf-bundle）定义概念，AspectType（okf）承载 OKF 信号字段。推送时每个概念生成一个 Entry，带 overview Aspect（markdown 正文）和 okf Aspect（结构化信号）。index.md 和 log.md 也发布为 Entry，保持目录结构可浏览。

okf AspectType 定义了 13 个字段，覆盖 OKF v0.2 全部规格：okf_type、generated、sources、verified、status、stale_after、usage_window、runtime、parameters、computation、executor、attester、extra。每个字段都有展示名、描述和必填索引。顶层标量字段（okf_type、status、stale_after 等）可直接用于 Knowledge Catalog 搜索谓词，例如 aspect:acme-analytics.us-central1.okf.okf_type=Metric 能返回所有 OKF Metric。record 字段的标量子字段（如 generated.by、usage_window.from）也可用于谓词。数组字段（sources、verified、parameters）的子字段不能服务端搜索，agent 需要在 entries.get(view=ALL) 后客户端过滤。datetime 字段的搜索谓词要用裸日期（如 stale_after=2026-12-31）或范围比较，不能用完整 RFC3339 时间戳。

推送流程：kcmd push 从 git 读取 bundle，把每个概念写入目标 EntryGroup。index.md 也变成 Entry，概念挂在对应的 index 下，目录结构保留为可浏览层级。bundle 需要符合 Documents Layout：文件在 catalog/ 子目录下，根目录有 catalog.yaml。sample code 的 setup.ts 会用 –entry-group 参数生成 catalog.yaml。示例 Acme Retail bundle 有 9 个叶概念、6 个目录，加上 index 和 log，共推送 17 个 Entry，Dataplex 自动创建一个附属 Entry，实际列表 18 行。

推送完成后，每个概念 markdown 文件都是 Knowledge Catalog Entry，全项目或全组织可搜索（取决于 IAM 配置）。例如 revenue-ytd Attested Computation 在控制台显示其 SQL、executor、attester、验证历史和完整正文。分析师搜“revenue”能同时找到业务定义和对应的 BigQuery 表，在统一权限模型下。已使用 LookupContext 的 agent 只需把 OKF entry 名加入 resources 列表即可获取上下文。

核心价值：一是跨组织可发现性——agent 通过 searchEntries 和 LookupContext 自动发现 bundle 概念，无需额外克隆或解析 frontmatter；二是治理——bundle Entry 继承 EntryGroup 的 IAM，一次调用返回的内容严格受调用者权限限制，没有并行权限模型。LookupContext 返回预格式化的 YAML 块，包含 catalogEntry、类型、描述、tags 和 overview（markdown 正文），但不渲染自定义 Aspect，需要结构化信号时用 entries.get(view=ALL)。

Agent 遍历 bundle 的典型三步流程：searchEntries 获取候选 Entry 名，LookupContext 获取正文（每次最多 10 个），entries.get 获取结构化信号。引用其他概念时，对目标 Entry 名再次 LookupContext。治理方面，读角色用 roles/dataplex.catalogViewer（允许 entries.get、LookupContext、searchEntries），写角色用 roles/dataplex.catalogEditor（允许 entries.create、entries.patch）。每个 bundle 拥有团队一个 EntryGroup，IAM 级联到 Entry。注意 LookupContext 只解析单 location 内的 entry 名，不跟随正文内链接；bundle EntryGroup 应与数据放在同一 location 以一次调用获取。

生命周期：kcmd push 是幂等 upsert，重复推送安全但每次都会写所有 Entry。删除概念需显式 kcmd delete，或 cleanup.ts 删除整个 EntryGroup（但保留共享的 AspectType 和 EntryType）。生产环境可在 CI 中每次 commit 触发 push，使用带 catalogEditor 角色的服务账号。