Open Knowledge Format (OKF) 全面使用指南

一句话：把「知识目录」变成一堆普通的 Markdown 文件，让人和 AI Agent 用完全相同的方式生产、审查、消费它。

01项目是什么

仓库由三部分组成，重要性依次递减——格式是贡献，Agent 和可视化只是让它摸得着的两端。

仓库自带 4 个可直接浏览的成品 bundle：bundles/ga4/（GA4 电商）、bundles/stackoverflow/、bundles/crypto_bitcoin/、bundles/acme_retail/（演示 Attested Computation 完整家族）。

为什么用 Markdown 而不是元数据服务？

• 人和 Agent 都能直接读：cat 一下就能看；LLM 可以原样塞进上下文
• 天然进 git：PR、逐行 diff、blame、评审流程全部免费获得——知识运营变成普通软件工程活动
• 零锁定：bundle 就是一个目录，tar 包、静态服务器、Obsidian/Notion/MkDocs 都能直接用
• 结构化与非结构化刻意混合：frontmatter 放可查询的少数字段，正文放人和 LLM 真正读的散文、Schema、SQL
• 信任、来源、新鲜度是一等公民（v0.2 新增）：机器维护的语料库也能回答「这从哪来、可不可信、还新鲜吗」
• 渐进披露：自动生成的 index.md 让 Agent 逐层浏览，而不是把整个 bundle 塞进上下文

02OKF 格式核心概念

2.1 Bundle 结构

bundle/
  index.md                # 可选：目录清单（渐进披露）
  log.md                  # 可选：按日期倒序的更新日志
  <concept>.md            # 一个概念 = 一个 .md 文件
  <子目录>/               # 按领域自由组织
    index.md
    <concept>.md

保留文件名只有两个：index.md 和 log.md。分发方式：git 仓库（推荐）、tar/zip、或大仓库的子目录。

2.2 概念文档 = frontmatter + 正文

唯一必填字段是 type，只带 type 的概念即完全合规。推荐字段：title、description（一句话，会被 index.md 原样引用）、resource（底层资产 URI）、tags。

---
type: BigQuery Table
title: Customer Orders
description: One row per completed customer order across all channels.
resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
tags: [sales, orders, revenue]
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-05-28T14:30:00Z }
---

# Schema

| Column        | Type      | Description                              |
|---------------|-----------|------------------------------------------|
| `order_id`    | STRING    | Globally unique order identifier.        |
| `customer_id` | STRING    | Foreign key into [customers](customers.md). |

# Common query patterns

```sql
SELECT * FROM orders WHERE total_usd > 100
```

约定俗成的正文标题：# Schema（字段结构）、# Examples / # Common query patterns（示例）、# Computation（见 2.5）。

2.3 信任、来源、生命周期（v0.2 的重点）

信任层级由 verified 推导：无 verified → unverified；仅被 process: / 工具确认 → machine-confirmed；被 human:<id> 确认 → human-reviewed。Actor 命名约定：Agent 用 <producer>/<version>、人用 human:<id>、自动流程用 process:<id>——信任分级靠 human: 前缀判断，人工确认必须用这个前缀。

逐条断言溯源：正文论断用脚注关联 sources[].id。用稳定 id 而非 sources[0] 位置索引，因为 Agent 会不断重写文档，位置索引在重排后会静默错配：

The `events_` table is sharded daily as `events_YYYYMMDD`.[^ga4-schema]

[^ga4-schema]: GA4 BigQuery Export schema

2.4 链接与图状结构

概念之间用普通 Markdown 链接互指，构成超越目录树的有向图。绝对形式（相对 bundle 根，移动文档时稳定）与相对形式均可；本仓库的 Agent 实际写文件相对路径（如 ../references/metrics/daily_active_users.md），保证 GitHub 直接渲染时链接可用。关系类型（joins-with、depends-on…）由周围散文表达，链接本身不携带类型。消费者必须容忍死链——死链可能只是「尚未写出的知识」。

references/ 子目录是命名约定：把外部材料、运行说明、代码镜像为 bundle 内一等概念（如 references/attesters/revenue.py）。

2.5 Attested Computation（可证明计算）

v0.2 最有特色的类型：不只记录一个值是什么，还记录官方认可的算它的方法，让消费者能机械地确认「Agent 跑的是被批准的计算，而不是即兴发挥」。

verified 与 attestation 的区别：前者确认定义仍符合政策（文档级、慢、落盘）；后者确认某次运行按官方方式产生值（每次调用、运行时、不落盘）。定义过期也能干净通过 attestation；定义刚确认过也每次运行仍需 attestation——所以两者都要。

03Reference Agent 工作原理

Agent 基于 Google ADK + Gemini（默认 gemini-flash-latest），分两个独立 pass 运行，最后统一重生成索引。

3.1 Web pass 的爬虫硬限制（工具内强制，Agent 无法逾越）

3.2 立 reference 的四道门

页面要立为 references/<slug> 新概念，须同时满足：①主题可被主概念点名引用；②非 bundle 级元页面（slug 含 overview / quickstart / faq 等直接跳过）；③通过「引用测试」（能写出 See the [X reference](…) for …）；④复用测试（≥2 个概念会引用它）。

强制的结构化抽取则绕过四道门：页面上的聚合指标、维度、join 路径必须捕获——指标写 references/metrics/<slug>.md（拥有 SQL 公式），join 写 references/joins/<a>__<b>.md（双下划线、按字母排序），且立了引用就必须回链：相关表的 # Metrics / # Joins 章节必须链接它，会话结束前校验无孤儿 reference。

3.3 防幻觉守卫（代码级）

tools/bundle_tools.py 的 write_concept_doc 内置三层防御：缺 type 等必需键拒写；web pass 中新 # Schema 丢失 BQ pass 从真实元数据填充的字段 → 拒写并列出缺失字段；新 sources 条目数少于现存 → 拒写。提示词同时约定：「拒写不代表失败——读回旧文档、原样保留全部内容、只做增量，然后重试。」

04快速上手

python3.13 -m venv .venv
.venv/bin/pip install \
  --index-url https://pypi.org/simple/ \
  -e .[dev]

gcloud auth application-default login
gcloud config set project <billing-project>

# Gemini 二选一：
export GEMINI_API_KEY=...
# 或 Vertex AI：
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=<id>
export GOOGLE_CLOUD_LOCATION=<region>

最小运行

.venv/bin/python -m reference_agent enrich \
    --source bq \
    --dataset <project>.<dataset> \
    --web-seed-file <path/to/seeds.txt> \
    --out ./bundles/<name>

不提供 seed 或加 --no-web → 只跑 BQ pass。公共数据集可读，但查询按字节计费到你的项目。

05六大使用场景与示例

.venv/bin/python -m reference_agent enrich \
    --source bq \
    --dataset bigquery-public-data.ga4_obfuscated_sample_ecommerce \
    --web-seed-file samples/ga4_merch_store/seeds.txt \
    --out ./bundles/ga4

.venv/bin/python -m reference_agent enrich \
    --source bq --dataset my-company.sales \
    --no-web --out ./bundles/sales

.venv/bin/python -m reference_agent enrich \
    --source bq --dataset bigquery-public-data.crypto_bitcoin \
    --concept tables/transactions \
    --out ./bundles/crypto_bitcoin

.venv/bin/python -m reference_agent visualize --bundle ./bundles/crypto_bitcoin
# 写出 bundles/crypto_bitcoin/viz.html

# 自定义输出与标题：
.venv/bin/python -m reference_agent visualize \
    --bundle ./bundles/crypto_bitcoin --out /tmp/btc.html --name "Bitcoin OKF"

06CLI 完整参考

enrich

visualize

07一份 OKF 文档的完整生命周期

1. 生产：BQ pass 用元数据写初稿（真实 Schema、SQL 模式、交叉链接）→ Web pass 用官方文档增补语义（指标公式、join 路径、枚举值），全程守卫防缩水
2. 组织：regenerate_indexes 生成各级目录；可选手工维护 log.md
3. 审查：人用 human:<id> 补 verified；信任层级从 unverified 升到 human-reviewed
4. 演进：内容变化时 generated.at 刷新；过时定义设 status: deprecated（保留供链接与历史）；有时效的知识设 stale_after
5. 分发：git 推送 / tar 包 / 静态服务器 / kcmd 推到 Knowledge Catalog
6. 消费：LLM 逐层读 index.md → 按需加载概念；或开 viz.html 交互探索；确定性代码扫 frontmatter 建索引；运行 Attested Computation 时由 attester 背书

08测试与开发

.venv/bin/pytest    # 7 个测试文件：BQ source、bundle 工具、文档解析、
                    # index、viewer、web fetcher、web 工具

09设计决策与注意事项

• v0.1 → v0.2 两个刻意破坏性变更：timestamp 被 generated.at 取代；正文 # Citations 列表被 frontmatter sources 取代。旧 bundle 可被 v0.2 消费者降级读取。
• 宽容是规范的一部分：type 值不注册；消费者必须容忍未知类型、未知键、缺任何可选家族、死链、缺 index.md——都不能拒绝 bundle。
• 未来方向（规范 §12 列为 deferred）：receipt/verdict 完整运行时协议、attester ABI 与沙箱、attestation 缓存、语义层模板（Looker/dbt，届时比较从 SQL 等价转为模型+绑定等价）。
• 实践提示：description 保持一句话——它会被原样进 index.md；seed 文件选「权威文档页」而非营销页，Agent 会跟随 cookbook / metric / reference 类链接；大表数据集迭代期务必 --concept + 适度 --web-max-pages。