OKF（Open Knowledge Format）学习笔记

日期：2026-06-16 · 主题：OKF 官方规范、Agent 生成知识包、校验与可视化工程实践

1. OKF 的官方定位

OKF 是一种开放的、对人类和 Agent 友好的知识表示格式，用于表示围绕数据和系统的元数据、上下文和经过整理的洞察。

官方强调 OKF 的形态非常小：一个由 Markdown 文件组成的目录树，每个概念文档顶部带有 YAML 元数据块。
a directory of markdown files with YAML frontmatter

因此，OKF 不是数据库、不是查询引擎、不是知识图谱系统，也不是某个工具链本身。它首先是一种文件格式和组织约定。

2. 官方目标与非目标

Readable人类不依赖专门工具也能阅读。
ParseableAgent 不依赖专用 SDK 也能解析。
Diffable可以在 Git 等版本控制系统中比较差异。
Portable可以跨工具、组织和时间迁移。

官方目标

  1. 定义一种 enrichment agents 可以写入的通用格式。
  2. 指导 consumption agents 如何读取和遍历知识。
  3. 促进知识在系统和组织之间交换。
  4. 标准化少量必须存在的字段，使内容可以被有意义地消费。

官方非目标

  • 不定义固定的 concept type 分类体系。
  • 不规定存储、服务或查询基础设施。
  • 不替代 OpenAPI、Protobuf、Avro、数据库 schema 等领域专用格式。

3. 核心术语

术语中文理解关键点
Knowledge Bundle知识包自包含、层级化的知识文档集合，是分发单位。
Concept概念Bundle 内的单个知识单元，由一个 Markdown document 表示。
Concept ID概念标识由 concept 文件路径去掉 .md 后缀得到。
Frontmatter顶部 YAML 元数据块由 --- 包围，位于 Markdown 文件顶部。
Body正文frontmatter 后面的 Markdown 内容。
Link概念链接标准 Markdown 链接，用于表达 concept 之间的关系。
Citation来源引用指向外部来源，用于支持正文中的声明。

4. Bundle 结构

path/to/bundle/
├── index.md
├── log.md
├── <concept>.md
└── <subdirectory>/
    ├── index.md
    ├── <concept>.md
    └── <subdirectory>/
        └── …

Bundle 可以被分发为 Git repository、tarball、zip archive，或 larger repository 中的 subdirectory。

保留文件名

文件名作用
index.mdDirectory listing，用于目录索引和 progressive disclosure。
log.mdUpdate history，用于记录更新历史。
官方规则：index.md 和 log.md 不能作为 concept document；其他 .md 文件都是 concept documents。

5. Concept Document 结构

每个 concept document 是 UTF-8 Markdown 文件，由 YAML frontmatter 和 Markdown body 两部分组成。

---
type: <Type name>                  # REQUIRED
title: <Optional display name>
description: <Optional one-line summary>
resource: <Optional canonical URI for the underlying asset>
tags: [<tag>, <tag>, …]            # Optional
timestamp: <ISO 8601 datetime>     # Optional last-modified time
# … other producer-defined key/value pairs
---
字段官方性质说明
type必需标识 concept 种类。
title推荐人类可读展示名。
description推荐一句话摘要，用于索引、搜索片段和预览。
resource推荐底层资产的 canonical URI。
tags推荐用于横向分类的短字符串列表。
timestamp推荐最后一次有意义修改的 ISO 8601 时间。

6. type 字段

type 是 OKF 中最重要的字段之一。它是一个短字符串，用于识别 concept 的种类。Consumer 可以用它做路由、过滤和展示。

BigQuery TableBigQuery DatasetAPI EndpointMetricPlaybookReference

这些是官方示例值，不是封闭枚举。type 字段必需，但 type 值没有官方中央注册表。

7. 官方示例

绑定具体资源的 Concept

---
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]
timestamp: 2026-05-28T14:30:00Z
---

# Schema

| Column        | Type      | Description                              |
|---------------|-----------|------------------------------------------|
| `order_id`    | STRING    | Globally unique order identifier.        |
| `customer_id` | STRING    | Foreign key into [customers](/tables/customers.md). |
| `total_usd`   | NUMERIC   | Order total in US dollars.               |
| `placed_at`   | TIMESTAMP | When the customer submitted the order.   |

# Joins

Joined with [customers](/tables/customers.md) on `customer_id`.

# Citations

[1] [BigQuery table schema](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)

不绑定具体资源的 Concept

---
type: Playbook
title: Incident response — data freshness alert
description: Steps to triage a freshness alert on the orders pipeline.
tags: [oncall, incident]
timestamp: 2026-04-12T09:00:00Z
---

# Trigger

A freshness alert fires when `orders` lags more than 30 minutes behind
its expected SLA. See the [orders table](/tables/orders.md).

# Steps

1. Check the [ingestion job dashboard](https://example.com/dash).
2. …

9. OKF Conformance

一个 bundle 符合 OKF v0.1，如果满足三条硬性要求：

  1. 每个非保留 .md 文件都有可解析的 YAML frontmatter。
  2. 每个 frontmatter 都包含非空 type 字段。
  3. index.md 和 log.md 在出现时遵循官方对应结构。
OKF v0.1 hard conformance =
  非保留 .md 有可解析 YAML frontmatter
  frontmatter 有非空 type
  reserved files 出现时结构正确
官方强调：Consumers 应将其他约束视为 soft guidance。缺少可选字段、未知 type、未知额外 key、broken links、缺少 index，都不应导致 consumer 拒绝 bundle。

10. AI/Agent 如何生成 OKF

OKF 设计上支持由人编写，也支持由 Agent 生成。

用户提供源资料和目标
Agent 读取 OKF SPEC
Agent 分析源资料结构
Agent 自动制定 producer plan
必要时确认关键边界
Agent 生成 Knowledge Bundle
运行校验和可视化等项目工具

重要认知：详细生成要求不应主要由用户手写，而应由 Agent 读取官方 SPEC 和源资料后自动分析制定。用户主要提供源资料、目标用途和关键边界。

11. 工程实践素材：校验与可视化

以下工具脚本属于工程实践辅助能力，需要明确它们不是 OKF 协议本体。

文件定位作用
tools/okf_bundle_common.py项目级共享解析模块解析 frontmatter、links、citations、log，统一 validator 和 visualizer 的解析逻辑。
tools/validate_okf_bundle.py项目级 validator按 spec、reference、project 三层检查 bundle。
tools/visualize_okf_bundle.py项目级 visualizer wrapper / extended viewer辅助浏览 concepts、links、body、frontmatter、citations、log 等。

12. 官方协议、官方参考实现、项目增强工具

OKF SPEC
  ↓
Official reference implementation
  ↓
Project tooling
OKF SPEC官方格式规范，定义术语、结构、conformance、links、citations、index、log 等规则。
官方参考实现例如 OKFDocument.validate()。它可能比 SPEC 更严格，但不等同于 SPEC hard conformance。
项目增强工具validator、visualizer、common parser 等，帮助生产、校验和浏览，但不构成协议要求。

一句话总结：SPEC 决定什么叫 OKF；官方参考实现展示一种官方代码实践；项目工具帮助生产、校验和浏览，但不构成协议要求。

13. 官方 visualizer 的实现观察

运行官方 visualizer 后，曾出现 37 concept(s), 0 edge(s) 的输出。

  1. 官方 visualizer 当前只跳过 index.md，没有跳过 log.md，所以会把 log.md 也计入 concept。
  2. 官方 visualizer 当前忽略以 / 开头的 bundle-relative absolute links，所以没有生成 edges。
这是官方 visualizer 当前实现限制，不是 OKF SPEC 的问题；官方 SPEC 明确推荐 bundle-relative absolute links。

14. 最短记忆版

  1. OKF 是开放的、对人类和 Agent 友好的知识表示格式。
  2. OKF 的基本形态是 Markdown 文件目录树 + YAML frontmatter。
  3. Knowledge Bundle 是分发单位，Concept 是 bundle 内的单个知识单元。
  4. OKF v0.1 的硬性合规要求很少：非保留 .md 有 frontmatter、type 非空、reserved files 结构正确。
  5. title、description、resource、tags、timestamp 是推荐字段，不是合规必需项。
  6. Links 是标准 Markdown links，推荐 bundle-relative absolute links，通常表示有方向、无显式类型的关系。
  7. Citations 用来支持正文中的外部来源声明。
  8. OKF 不规定工具、存储、查询系统，也不定义固定 type taxonomy。
  9. AI/Agent 可以生成 OKF bundle，但生成后应通过校验和人工 review。
  10. Validator 和 visualizer 是工程辅助工具，不是 OKF 协议本体。

15. 复习自测

点击按钮查看答案。建议先口头回答，再展开核对。

题目 1：OKF v0.1 的 hard conformance 包含哪些要求？

每个非保留 .md 文件都有可解析 YAML frontmatter；每个 frontmatter 都包含非空 type；index.md 和 log.md 出现时遵循官方结构。
题目 2：type 是官方固定枚举吗？

不是。type 字段是必需的，但 type 值没有中央注册表。Producer 应选择描述性、自解释的 type，consumer 必须优雅处理未知 type。
题目 3：为什么 OKF 推荐 bundle-relative absolute links？

因为它们以 / 开头，相对于 bundle root 解析。当文档在子目录中移动时，这种链接形式更稳定。
题目 4：Validator 和 visualizer 是 OKF 协议要求吗？

不是。它们是工程辅助工具。OKF 官方不要求特定 tooling。Validator 用于辅助检查，visualizer 用于辅助浏览和 review。
题目 5：Concept 与 Knowledge Bundle 的关系是什么？

Knowledge Bundle 是自包含、层级化的知识文档集合，是分发单位；Concept 是 bundle 内的单个知识单元，由一个 Markdown document 表示。
本笔记基于 OKF v0.1 官方规范和本次学习会话整理。