okf-open-knowledge-format

开放知识格式（OKF）

OKF 是一种供应商中立的开放规范（v0.2，由 Google Cloud 发布），用于将知识表示为由 Markdown 文件和 YAML frontmatter 组成的目录。无需 SDK——只要能使用 cat 查看文件，就能读取 OKF。

它将“LLM Wiki”模式（Karpathy 的 gist）规范为一种可互操作的格式：不同生产者编写的 Wiki 可供不同 Agent 使用，无需转换。

v0.2 新增：来源追踪（sources）、可信度信号（generated、verified）、生命周期管理（status、stale_after），以及经认证的计算——一种用于经认可、可验证计算的新概念类型。

完整规范请参阅：

• references/spec-v02.md — 当前版本（v0.2）
• references/spec-v01.md — 旧版（v0.1）

设计原则

1. 尽量减少主观规定 — 只有 type 是必填项。规范定义的是互操作层，而非内容模型。
2. 生产者与使用者相互独立 — 编写者和读取者彼此解耦。人类编写的知识包可供 Agent 使用；LLM 生成的知识包可供人类浏览。
3. 格式，而非平台 — 不依赖云、SDK 或供应商。其价值取决于有多少参与方采用这种格式。
4. 信任是一等要素 — v0.2 支持通过 frontmatter 查询来源、验证情况和时效性。

---

关键术语

术语	定义
知识包	由 .md 文件组成的目录树。分发单元（git 仓库、tarball 或子目录）。
概念	一个 Markdown 文件 = 一个知识单元（表、指标、操作手册、API 等）
概念 ID	知识包内的文件路径，去掉 .md 后缀。例如：tables/users.md → ID tables/users
Frontmatter	文件顶部由 --- 分隔的 YAML 块。
正文	frontmatter 之后的所有内容。标准 Markdown。
链接	表示概念之间关系的标准 Markdown 链接。
来源	概念所依据的材料，记录在 sources frontmatter 字段中。
来源信息	概念所依据的来源集合。
行为主体	身份字符串：Agent 使用 <producer>/<version>，人员使用 human:<id>，自动化流程使用 process:<id>。
信任等级	根据 verified 推导出的级别：未经验证、机器确认或人工审核。
经认证的计算	一种概念（type: Attested Computation），用于承载经认可的数值计算方法。

---

速查 — Frontmatter 字段

核心字段（适用于所有概念）

字段	必填？	说明
type	是	概念类型（自由格式字符串，例如 BigQuery Table、Metric、Playbook、Attested Computation）
title	推荐	便于人类阅读的显示名称
description	推荐	一句话摘要
resource	推荐	标识底层资产的 URI（抽象概念可省略）
tags	可选	用于跨领域分类的 YAML 列表

信任与生命周期字段（v0.2）

字段	说明
generated	{ by: <actor>, at: <ISO8601> } — 创建此内容的人员或工具，以及创建时间
verified	{ by: <actor>, at: <ISO8601> } 列表 — 确认内容正确的人员或工具
status	draft | stable | deprecated — 默认值：stable
stale_after	ISO 8601 日期时间 — 内容从该时刻起视为过时

来源字段（v0.2）

字段	说明
sources	来源条目列表（见下文）
usage_window	{ from, to } — usage_count 信号的时间范围

每个 sources 条目：

• resource（必填）：URL、相对于 bundle 的路径或范围描述符
• id：用于脚注归属的稳定键
• title：便于阅读的标签
• author：生成该来源的主体
• usage_count：使用次数（活跃度信号）
• last_modified：来源上次更改的时间

经验证计算字段（v0.2）

对于 type: Attested Computation 的概念：

字段	说明
runtime	必填。运行方式：bigquery、postgres、dbt、python、Looker
parameters	{ name, type, required } 列表 — 由 Agent 填写的类型化空位
computation	计算文件的路径（若未内联在正文中）
executor	{ resource, receipt: [...] } — 如何运行以及要捕获哪些证据
attester	{ resource } — 用于验证回执的确定性代码

保留文件名

文件	用途	是否有 frontmatter？
index.md	用于渐进式披露的目录列表	否*
log.md	更改历史，最新记录在前	否

*例外：bundle 根目录的 index.md 可以包含 okf_version: "0.2" frontmatter。

常用正文标题

标题	使用时机
# Schema	数据资产——描述列/字段
# Examples	展示具体用法（代码块、查询）
# Computation	经验证计算——经认可的代码/查询

---

主体约定

记录身份的字段（generated.by、verified[].by、sources[].author）使用：

• Agent 使用 <producer>/<version>：reference_agent/gemini-2.5-pro
• 人员使用 human:<id>：human:ahormati
• 自动化流程使用 process:<id>：process:finance-nightly

信任层级根据 human: 前缀推导：人工验证 > 机器确认 > 未验证。

---

信任层级

使用者根据 verified 字段推导信任级别：

条件	信任层级
没有 verified 键	未验证
verified 仅由非 human: 主体验证	机器确认
verified 由 human:<id> 主体验证	人工审核

信任层级是参考信号，而非访问控制。

---

创建 Bundle

当用户希望从头创建 OKF bundle 时：

1. 确定范围和结构

询问：我们要捕获哪些知识？（表、指标、API、操作手册等） 将内容组织成适合该领域的目录树。

2. 创建概念文档

每个概念对应一个 .md 文件。最简合规示例：

---
type: Metric
---

# Monthly Recurring Revenue (MRR)

Sum of all active subscriptions normalized to a monthly amount.

包含来源信息和信任信息的完整 v0.2 示例：

---
type: Metric
title: Monthly Recurring Revenue
description: Sum of all active subscription revenue normalized to monthly.
tags: [revenue, saas, kpi]
status: stable
generated: { by: human:ftelles, at: 2026-08-25T10:00:00Z }
verified: { by: human:finance-lead, at: 2026-08-25T14:00:00Z }
stale_after: 2026-12-31T00:00:00Z
sources:
  - id: stripe-docs
    resource: https://stripe.com/docs/billing/subscriptions
    title: Stripe Subscription Billing
    author: team:stripe-docs
    last_modified: 2026-06-01T00:00:00Z
---

# Monthly Recurring Revenue (MRR)

## Definition

Sum of all active subscriptions normalized to a monthly amount.[^stripe-docs]
Excludes one-time fees and overages.

## Formula

`MRR = Σ(active_subscription_monthly_value)`

## Related

- [Churn Rate](./churn.md) uses MRR as denominator
- [ARR](./arr.md) = MRR × 12

[^stripe-docs]: Stripe Subscription Billing

如需查看不同领域的更多示例，请参阅 references/examples.md。

3. 交叉链接概念

使用标准 Markdown 链接。两种形式：

• 绝对路径（相对于 bundle，以 / 开头）：[customers](/tables/customers.md) — 推荐（文件移动后仍保持稳定）
• 相对路径：[churn](./churn.md)

链接用于声明关系。关系的类型由周围的正文表达，而非链接语法。允许存在失效链接——它们表示尚未写入的知识。

4. 使用脚注添加来源信息（v0.2）

当声明引用外部来源时，在 frontmatter 中使用 sources，并在正文中添加脚注：

sources:
  - id: ga4-schema
    resource: https://developers.google.com/analytics/bigquery/export-schema
    title: GA4 BigQuery Export schema

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

[^ga4-schema]: GA4 BigQuery Export schema

5. 生成 index.md

可放置在任意目录中，以支持渐进式披露。无需 frontmatter。格式：

# Metrics

- [MRR](./mrr.md) - Monthly recurring revenue
- [Churn](./churn.md) - Monthly churn rate
- [NPS](./nps.md) - Net Promoter Score

条目应包含所链接概念的 frontmatter 中的描述。

6. 生成 log.md（可选）

按时间顺序记录更改历史，最新记录在前；日期标题使用 ISO 8601 格式：

# Update Log

## 2026-08-25
- **Creation**: Added MRR, Churn, and NPS metrics.
- **Creation**: Established directory structure.

## 2026-08-20
- **Initialization**: Bundle created.

7. 声明版本（可选）

bundle 根目录的 index.md 可以包含 frontmatter，以声明规范版本：

---
okf_version: "0.2"
---

# My Knowledge Bundle

- [Tables](./tables/) - Database tables
- [Metrics](./metrics/) - Business KPIs

8. 分发

可通过以下方式分发一个 bundle：

• git 仓库（推荐——保留历史记录、归属信息和差异）
• tarball 或 zip 归档
• 更大型仓库中的子目录

9. 验证符合性

以下三条规则必须全部通过：

1. 每个非保留的 .md 文件都具有可解析的 YAML frontmatter
2. 每个 frontmatter 都有非空的 type 字段
3. 存在时，保留文件（index.md、log.md）遵循其定义的结构

---

创建经证明的计算（v0.2）

经证明的计算不仅承载值的含义，还承载经过认可的计算方式。需要可验证、可复现的计算时，请使用它们。

适用场景

• 合规要求提供审计跟踪的财务指标
• 必须在各报告中一致计算的 KPI
• 任何需要确认“经过认可的操作是否已运行”的计算

结构

---
type: Attested Computation
title: Revenue for fiscal year
description: Recognized revenue for a fiscal year, per Finance's definition.
status: stable
runtime: bigquery
parameters:
  - { name: year, type: integer, required: true }
executor:
  resource: references/skills/run-on-bq.md
  receipt: [job_id, executed_sql, result]
attester:
  resource: references/attesters/revenue.py
generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
stale_after: 2026-09-23T00:00:00Z
sources:
  - id: rev-policy
    resource: https://wiki.acme/finance/revenue-recognition
    title: Revenue recognition policy
---

# Computation

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

The computation binds only the declared `parameters`, per the recognition
policy.[^rev-policy]

[^rev-policy]: Revenue recognition policy

关键规则

1. Agent 只填写参数——Agent 为已声明的 parameters 提供值，绝不编辑计算本身
2. 计算可以内联，也可以外置——内联时使用 # Computation 标题；使用外部文件时则使用 computation: 字段
3. 执行器生成回执——供证明者检查的证据
4. 证明者是确定性的——不使用大模型，只用代码验证回执

链接到计算

其他概念可以链接到经证明的计算：

---
type: Metric
title: Revenue
---

# Definition

Recognized revenue for a fiscal year, computed by 
[the revenue computation](../computations/revenue.md).

---

验证 Bundle

首选：okflint（如可用）

okflint 是专用于 OKF bundle 的 Python linter，包含 3 个层级（OKF 核心、配置文件、卫生检查）的 18 条规则。如果已安装，始终优先使用它，而非内置 bash 脚本。

**Agent 行为：**验证前，检查是否已安装 okflint（command -v okflint）。如果未安装，请询问用户：

“尚未安装 okflint（专用于 OKF 的 linter，包含 18 条规则、支持通过清单设置 profiles 和 wikilinks）。是否要安装？选项：

1. uv tool install okflint（推荐，隔离安装）
2. pip install okflint
3. 不安装，继续操作（使用内置 bash 脚本进行基本验证）”

如果用户同意安装：

# Option 1: uv (recommended — installs isolated, no venv needed)
uv tool install okflint

# Option 2: pip (installs in current environment)
pip install okflint

# Verify installation
okflint --version

安装后（或已安装时）：

# Full validation with manifest (if okf-base.yaml exists)
if [ -f okf-base.yaml ]; then
  okflint validate --manifest okf-base.yaml ./bundle/
else
  # Core OKF validation only (no manifest needed)
  okflint validate ./bundle/
fi

okflint 相较于内置脚本的优势：

• 由清单驱动的 profiles（强制执行自定义必填字段、状态词汇表和每种类型的约束）
• 可针对完整的 Obsidian 知识库解析 Wikilink
• JSON 输出（--json），便于 CI 流水线解析
• 检测失效的 Markdown 链接和含义不明确的 Wikilink
• 退出代码：0 = 通过，1 = 符合性失败，2 = 清单无效

后备方案：内置 bash 脚本

未安装 okflint 时，使用 scripts/validate.sh 检查 3 条核心符合性规则和 v0.2 字段。

收到验证请求时，请检查 3 条符合性规则。报告：

✅ PASS: 12/12 concept files have valid frontmatter with type field
✅ PASS: index.md follows list structure (no frontmatter)
✅ PASS: log.md uses ISO 8601 date headings, newest first

⚠  WARNING: 3 files missing 'description' field (recommended)
⚠  WARNING: 2 broken cross-links (permitted but worth noting)
ℹ  INFO: 5 files with trust fields (generated/verified)
ℹ  INFO: 2 Attested Computation concepts found

基于脚本的检查请参阅 scripts/validate.sh。

错误（符合性失败）

• E1：文件 {path} 没有 YAML frontmatter
• E2：文件 {path} 有 frontmatter，但没有 type 字段（或字段为空）
• E3：保留文件 {path} 的结构不符合预期
• E4：经证明的计算缺少必需的 runtime 字段

警告（非阻塞，规范允许这些情况）

• W1：缺少推荐字段 title 或 description
• W2：{file} 中的跨链接 {link} 失效
• W3：没有 generated 字段（v0.2 推荐）
• W4：目录 {dir} 中没有 index.md
• W5：log.md 中的日期不是 ISO 8601 格式
• W6：sources 条目缺少 resource 字段
• W7：stale_after 日期已过——内容已过时

消费者绝不能因为以下原因拒绝 bundle：缺少可选字段、未知类型值、未知 frontmatter 键、失效链接或缺少索引文件。

---

丰富概念

当用户需要丰富现有 OKF 概念时：

添加架构部分

对于数据资产，添加包含列清单的 # Schema：

# Schema

| Column | Type | Description |
|--------|------|-------------|
| `order_id` | STRING | Unique identifier |
| `customer_id` | STRING | FK to [customers](/tables/customers.md) |

添加示例部分

对于 API、查询或工具，添加 # Examples，并使用围栏代码块展示用法。

添加来源信息（v0.2）

在 frontmatter 中添加 sources，并在正文中添加脚注，为每项声明注明来源：

sources:
  - id: official-docs
    resource: https://example.com/docs
    title: Official Documentation
    author: team:product-docs
    last_modified: 2026-07-15T00:00:00Z

添加信任标记（v0.2）

generated: { by: reference_agent/gemini-2.5-pro, at: 2026-08-25T10:00:00Z }
verified: { by: human:domain-expert, at: 2026-08-25T14:00:00Z }
status: stable
stale_after: 2026-12-31T00:00:00Z

添加交叉链接

将链接融入自然的行文中。不要单独创建“链接”部分，而应在关系有意义的上下文中说明。

补全建议字段

如果缺少 title、description、tags，请添加。尽可能根据正文内容推导其值。

丰富内容工作流参考

官方内容丰富 Agent 遵循以下模式——手动操作时也应用相同逻辑：

1. 从仅含元数据的文档开始（只有 frontmatter 和最简正文）
2. 根据源系统添加架构／结构
3. 根据权威文档添加 sources
4. 根据发现的关系（外键、共享标签、连接路径）融入交叉链接
5. 添加 index.md 文件，以支持渐进式披露
6. 添加 generated，并可选择添加 verified，用于信任跟踪

---

将 v0.1 迁移到 v0.2

需要处理的破坏性变更

1. timestamp → generated.at

   # v0.1
   timestamp: 2026-05-28T22:53:05Z
   
   # v0.2
   generated: { by: human:author, at: 2026-05-28T22:53:05Z }
   

2. # Citations → sources

   # v0.1 body
   # Citations
   [1] https://example.com/docs
   
   # v0.2 frontmatter
   sources:
     - id: docs
       resource: https://example.com/docs
       title: Example Documentation
   

迁移脚本模式

# For each .md file:
# 1. Extract timestamp, convert to generated
# 2. Parse # Citations, convert to sources
# 3. Add footnotes in body for citations

# Consumers MAY fall back to legacy fields when v0.2 fields absent

向后兼容性

v0.2 的使用方 SHOULD：

• 如果缺少 generated，则回退使用 timestamp
• 如果缺少 sources，则解析旧版 # Citations

---

将来源转换为 OKF

详细的转换指南请参阅 references/conversion.md。

快速规则

Notion 导出： 将属性映射到 frontmatter。移除文件名中的 UUID 后缀。将 Notion 链接转换为相对 Markdown 链接。

Obsidian 保管库： 将 [[wikilinks]] 转换为 [title](./file.md)。确保存在 type 字段。将行内 #tags 移至 frontmatter。

CSV／电子表格： 每行代表一个概念。将列映射到 frontmatter 字段。第一列作为文件名。

---

防护规则

1. 绝不编造数据。 如果不确定正确的 type，请先询问。如果没有架构信息，就不要填写。不得编造 URL 或列名。
2. 保留未知字段。 OKF 明确允许扩展。不要删除不认识的字段。
3. 不要强加分类体系。 类型值是自由格式字符串。可以建议描述性值，但绝不要因为 bundle 中包含意料之外的类型而拒绝它。
4. 链接失效没关系。 规范明确允许此类链接——它们表示尚未编写的知识。
5. 默认保持精简。 只生成 type（必填）以及有依据的建议字段。不要填充空值。
6. 先询问，再假设。 如果领域不明确，请询问哪些类型和结构合适。
7. 尊重信任层级。 只有经过人工审核时，才能标记为 verified by human:。不得伪造验证信息。
8. 计算完整性。 绝不要编辑 Attested Computation 概念中的计算内容——只能填写参数。

---

通过 Google Cloud Knowledge Catalog 提供服务

Google Cloud 的 Knowledge Catalog 可原生接入 OKF bundle，并将其提供给 Agent。这是面向企业的方案——可选，但功能强大。

kcmd CLI（元数据即代码）

kcmd 是一个用于 OKF 类本地元数据与 Knowledge Catalog 之间双向同步的工具。可以把它理解为“元数据版 git”。

# Initialize from BigQuery dataset
kcmd init --bigquery-dataset <project>.<dataset>

# Pull current state from catalog
kcmd pull

# Push local changes
kcmd push --dry-run
kcmd push

它也以 MCP 服务 的形式提供，供 Agent 集成：

{
  "mcpServers": {
    "kc-mac": {
      "command": "kcmd",
      "args": ["mcp", "--path", "/path/to/root"]
    }
  }
}

MCP 工具：pull、push、list-entries、lookup-entry、modify-entry。

参考内容丰富 Agent

官方内容丰富 Agent（Python、ADK、Gemini）会根据 BigQuery 元数据自动生成 OKF bundle。采用两阶段架构：

1. BQ 阶段——根据元数据为每个表／视图生成一份 OKF 文档
2. Web 阶段——大模型抓取种子 URL，并针对每个页面决定：
   • (a) 丰富现有概念，添加引用／架构信息
   • (b) 创建新的 references/<slug> 文档
   • (c) 跳过无关内容

控制选项：--web-seed-file、--web-max-pages、--web-allowed-host、--no-web。

可视化工具

参考 Agent 包含一个 visualize 子命令，可将任意 OKF 捆绑包渲染为独立的交互式 HTML 文件：

python -m reference_agent visualize --bundle ./bundles/<name>

功能：

• 概念力导向图，节点按类型着色
• 详情面板，显示 frontmatter 和渲染后的 markdown
• “引用者”反向链接
• 搜索和类型筛选

何时向用户提及此工具： 如果他们正在丰富 BigQuery 数据集，请指引他们使用参考 Agent。如果他们需要集成企业目录，请指引他们使用 kcmd。

---

输出格式

创建捆绑包时，请按以下格式呈现结果：

1. 目录树，显示完整结构
2. 每个文件的内容，放在围栏代码块中
3. 一致性检查，确认捆绑包符合 3 条规则
4. 信任摘要（v0.2），显示已验证／未验证的数量

saas-metrics/
├── index.md
├── log.md
├── metrics/
│   ├── index.md
│   ├── mrr.md
│   ├── churn.md
│   └── nps.md
└── computations/
    └── mrr-calculation.md

然后展示每个文件，并确认：

Bundle is OKF v0.2 conformant ✅
- 4 concept files
- 1 Attested Computation
- 3 human-verified, 1 unverified
- 0 stale concepts