okf

OKF — Open Knowledge Format

Open Knowledge Format（OKF） 是 Google Cloud Data 团队提出的一项开放规范，旨在将 LLM-Wiki 模式正式化为一种可移植、可互操作的格式。知识以目录中的 YAML frontmatter Markdown 文件形式存储（即一个“bundle”）。任何生产者都可以编写，任何 Agent 都可以使用——无需专有 SDK、特殊运行时，也不会被锁定。

核心理念：就是 Markdown。就是文件。就是 YAML frontmatter。

何时使用此技能

• 需要创建供 AI Agent 解析的结构化知识文档——表结构、API 规范、指标定义、运行手册、弃用通知
• 希望获得可经受工具变更的可移植知识 bundle（不依赖供应商目录）
• 正在构建多 Agent 上下文层，让不同系统使用相同的组织知识（关联路径、业务 KPI、事件指南）
• 希望将知识原子相互链接，构建比父子层级更丰富的关系图
• 需要将知识发布或分发为 tarball、git 仓库或文件系统挂载
• 希望让 LLM-wiki 输出与 OKF v0.1 标准正式对齐

何时不使用此技能

• 原始网页来源采集和知识库级 Wiki 维护 → llm-wiki
• Obsidian 知识库自动化（插件开发、CLI、URI 交接）→ obsidian
• 从代码/文档构建持久提交的知识图谱 → graphify
• 抓取网页以提供知识文档内容 → scrapling
• 使用独立的 okf-memory/okf-agent-memory Go CLI/MCP，或搭建其 OKF v0.2 项目记忆布局 → okf-agent-memory

OKF 结构

bundle 目录

knowledge-bundle/
├── tables/
│   ├── orders.md
│   └── customers.md
├── metrics/
│   └── wau.md
├── runbooks/
│   └── outage-response.md
└── concepts/
    └── revenue-calculation.md

每个文件都是一个知识原子——一份带有 YAML frontmatter 的 Markdown 文档。 目录本身就是可分发单元（tarball / git / 文件系统挂载）。

Frontmatter 架构（OKF v0.1）

---
type: <string>          # (required) kind of atom: "BigQuery Table", "API Endpoint",
                        #   "Concept", "Runbook", "Metric Definition", "Data Source", …
title: <string>         # (required) human-readable name
description: <string>   # (required) one-sentence summary the agent can quote verbatim
resource: <url>         # (optional) URL to the described resource
tags: [<tag>, …]        # (optional) list for filtering / discovery
timestamp: <ISO 8601>   # (optional) last-updated datetime, e.g. 2026-06-21T10:00:00Z
---

只有 type、title 和 description 是严格必需字段。 如果原子关联到实时系统或 URL，请添加 resource。 timestamp 可供使用方 Agent 检查内容是否为最新。

Markdown 正文部分

部分	用途
# Overview	自由形式的上下文——动机、所有权、注意事项
# Schema	列、字段或参数的结构说明（建议使用表格格式）
# Examples	具体用法示例，主要使用代码块
# Joins / # Relations	指向相关原子的交叉链接
# Citations	支持文档所述内容的外部来源

各部分均为可选；仅包含与原子类型相关的部分。

操作说明

步骤 1 — 初始化 bundle

# Create the bundle root
mkdir my-knowledge-bundle && cd my-knowledge-bundle

# Scaffold a directory layout
mkdir -p tables metrics runbooks concepts api

对于现有项目，可将 bundle 放在代码旁边或单独的仓库中：

my-project/
├── src/
├── docs/
└── knowledge/          ← OKF bundle lives here
    ├── tables/
    └── metrics/

步骤 2 — 编写知识原子

表原子示例

---
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-06-21T10:00:00Z
---

# Overview

Primary fact table for order analytics. Owned by the Data Engineering team.
Refreshed hourly from the Kafka `orders` topic.

# 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 after discounts.           |
| `placed_at`   | TIMESTAMP | When the customer submitted the order (UTC).         |
| `channel`     | STRING    | `web` \| `mobile` \| `api` \| `partner`.             |

# Joins

- Join to [customers](/tables/customers.md) on `customer_id` for user attributes.
- Join to [products](/tables/products.md) via [order_items](/tables/order_items.md).

# Citations

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

指标定义原子

---
type: Metric Definition
title: Weekly Active Users (WAU)
description: Count of distinct users who triggered at least one qualifying event in the trailing 7-day window.
tags: [kpi, growth, users]
timestamp: 2026-06-21T10:00:00Z
---

# Overview

Owned by the Growth Analytics team. Used in all executive dashboards.

# Definition

```sql
SELECT
  DATE_TRUNC(event_date, WEEK) AS week_start,
  COUNT(DISTINCT user_id)      AS wau
FROM [events](/tables/events.md)
WHERE event_name IN ('session_start', 'purchase', 'share')
  AND event_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
GROUP BY 1
\```

# Relations

- Source table: [events](/tables/events.md)
- Related metric: [Monthly Active Users (MAU)](/metrics/mau.md)

运行手册原子

---
type: Runbook
title: Database Connection Pool Exhaustion
description: Steps to diagnose and recover from connection pool exhaustion on the primary Postgres cluster.
tags: [incident, database, postgres, oncall]
timestamp: 2026-06-21T10:00:00Z
---

# Overview

Triggered when `pg_stat_activity` shows ≥95% pool utilization or `FATAL: remaining connection slots are reserved` errors appear.

# Steps

1. Check active connections: `SELECT count(*) FROM pg_stat_activity;`
2. Identify blocking queries: see [slow-query runbook](/runbooks/slow-queries.md).
3. Kill idle connections older than 5 min if count > threshold.
4. Scale pool via [connection pooler config](/concepts/pgbouncer-config.md).
5. Page DBA on-call if not resolved in 10 min.

# Citations

[1] [PgBouncer docs](https://www.pgbouncer.org/)

步骤 3 — 交叉链接原子

使用相对于 bundle 根目录的绝对链接（推荐——移动后仍然稳定）：

See the [customers table](/tables/customers.md) for join key details.

对于同目录文件，使用相对链接：

See [related concept](./other-concept.md).

设计规则：链接表示关系存在；关系类型（父级、外键、关联、依赖）由周围的文字（而非链接本身）说明。这样可以保持图谱不受类型限制，并让使用方灵活处理。

步骤 4 — 验证 bundle

在使用或分发之前，运行基本的结构检查：

# Check all .md files have required frontmatter fields
python3 -c "
import os, sys
import re

bundle = '.'  # path to bundle root
errors = []

for root, dirs, files in os.walk(bundle):
    for f in files:
        if not f.endswith('.md'):
            continue
        path = os.path.join(root, f)
        text = open(path).read()
        if not text.startswith('---'):
            continue  # skip non-OKF files
        fm_end = text.find('---', 3)
        if fm_end == -1:
            errors.append(f'{path}: unclosed frontmatter')
            continue
        fm = text[3:fm_end]
        for field in ('type:', 'title:', 'description:'):
            if field not in fm:
                errors.append(f'{path}: missing required field {field!r}')

if errors:
    for e in errors: print('ERROR:', e)
    sys.exit(1)
else:
    print('OK — all OKF files valid')
"

步骤 5 — 分发 bundle

# As a tarball
tar -czf my-knowledge-bundle.tar.gz my-knowledge-bundle/

# As a git repo (recommended for versioning + freshness via timestamp)
git init my-knowledge-bundle && cd my-knowledge-bundle
git add . && git commit -m "Initial OKF bundle"
git remote add origin https://github.com/acme/knowledge-bundle.git
git push -u origin main

# As a filesystem mount in a Docker container
# docker run -v $(pwd)/my-knowledge-bundle:/knowledge ...

步骤 6 — 让 AI Agent 使用 bundle

import os, re, yaml

def load_okf_bundle(bundle_path: str) -> list[dict]:
    """Load all OKF atoms from a bundle directory."""
    atoms = []
    for root, _, files in os.walk(bundle_path):
        for f in files:
            if not f.endswith('.md'):
                continue
            path = os.path.join(root, f)
            text = open(path).read()
            if not text.startswith('---'):
                continue
            fm_end = text.find('---', 3)
            if fm_end == -1:
                continue
            try:
                fm = yaml.safe_load(text[3:fm_end])
                body = text[fm_end + 3:].strip()
                atoms.append({
                    'path': os.path.relpath(path, bundle_path),
                    'frontmatter': fm,
                    'body': body
                })
            except Exception:
                pass
    return atoms

# Usage
atoms = load_okf_bundle('./knowledge')
tables = [a for a in atoms if a['frontmatter'].get('type') == 'BigQuery Table']

步骤 7 — 与 llm-wiki 集成

OKF bundle 与仓库的 llm-wiki 技能工作流兼容：

# After running llm-wiki to capture raw sources, promote to OKF-compliant format:
# 1. Add required frontmatter (type, title, description) to each wiki/*.md
# 2. Add resource: field pointing to the source URL
# 3. Organize into typed subdirectories (tables/, metrics/, concepts/, …)
# 4. Run the Step 4 validator

# Use the llm-wiki skill for:
#   - Raw source capture and summarization
#   - Query filing and lint passes
#   - Obsidian/git vault maintenance

# Use OKF for:
#   - Portable, interoperable distribution to other teams/agents
#   - Standard frontmatter that consuming agents can parse without a custom schema

步骤 8 — 安装插件

# Project install
npx skills add https://github.com/akillness/jeo-skills --skill okf

# Global install
npx skills add -g https://github.com/akillness/jeo-skills --skill okf

# Target specific agents
npx skills add -g https://github.com/akillness/jeo-skills --skill okf -a claude-code -a codex -y

此外还提供 scripts/install.sh——一个一键辅助脚本，可验证 pyyaml 依赖，并可选择验证现有 bundle。 完整的字段和部分参考请参阅 references/usage.md。

输出格式

当用户向 okf 请求帮助时，返回一份简洁的简介：

# OKF Routing Brief

## Scope
- Task: create-bundle | author-atom | validate | distribute | consume | migrate-from-llm-wiki
- Atom type: table | metric | runbook | concept | api-endpoint | other

## Recommended next move
- bootstrap-bundle | author-atom | validate | distribute | consume | llm-wiki-promote

## Why
- 2-3 bullets grounded in the user's request

## Route-outs
- `llm-wiki` for raw source capture and vault maintenance
- `obsidian` for Obsidian vault automation
- `graphify` for durable committed knowledge graphs
- `scrapling` for web-content extraction into OKF documents

最佳实践

1. 一个原子，一个概念 — 每个文件只涵盖一张表、一个指标、一个 API 端点、一份运行手册或一个概念；当范围扩展到多个主题时，应拆分文件。
2. description 是 Agent 的标题 — 编写时应确保 Agent 能在回复中原样引用，无需额外上下文。
3. 优先使用绝对链接，而非相对链接 — /tables/customers.md 在文件移动后仍然有效；../tables/customers.md 则会悄然失效。
4. 为每个生产原子添加时间戳 — 消费这些原子的 Agent 可根据 timestamp 跳过过时内容；没有它，就无法检测内容是否新鲜。
5. type 是自由字符串，而非枚举 — "BigQuery Table"、"Kafka Topic"、"REST API"、"Runbook"、"Metric" 均有效；在同一个包中应保持一致，并在根目录的 README.md 中说明约定。
6. 分发前先验证 — 运行第 4 步的检查器；frontmatter 出错会导致下游 Agent 消费失败，且不会发出提示。
7. 使用 Git 跟踪内容新鲜度 — Git 仓库让使用者可以通过提交日期检测内容是否过时，并通过标准的 git pull 获取差异。

参考资料

• OKF 规范：https://github.com/google/open-knowledge-format
• PyTorchKR 讨论（韩语）：https://discuss.pytorch.kr/t/open-knowledge-format-okf-google-ai-feat-llm-wiki/10701
• LLM-Wiki 模式：参见 llm-wiki 技能（../llm-wiki/SKILL.md）
• Obsidian 集成：参见 obsidian 技能（../obsidian/SKILL.md）
• 知识图谱：参见 graphify 技能（../graphify/SKILL.md）
• 将网页抓取到 OKF：参见 scrapling 技能（../scrapling/SKILL.md）
• 本地用法参考：references/usage.md
• 本地安装程序：scripts/install.sh