0. What is OKF?

OKF と知識バンドルをゼロから理解する。なぜ「形式」がエージェントとの協働に必要なのか

OKF とは何か

このページは okf-seedling を初めて使う人、および「エージェントに知識を読ませたいけれど、どこから手をつければいいか分からない」人向けの入門です。10 分で全体像と用語の基礎が身につきます。

ゴール

  • OKF(Open Knowledge Format)が何を解決するのかを理解する
  • このツールが生み出す「知識バンドル」の構造を頭に描ける
  • 登場する用語(フロントマター、コンセプト、レジストリ等)をひと通り押さえる
  • 次のページ(1→2→3)を読むための地図を得る

OKF とは

OKF は「知識を構造化して、人間にもエージェントにも読める形で扱うためのフォーマット」です。

通常、ドキュメントは「人間が読む」ために書かれます。しかし LLM やエージェントのような機械が読むとき、人間向けの文章だけでは不足することがあります。

  • どこからどこまでが 1 つの概念か分からない
  • 作成日・担当・有効期限など「メタ情報」が本文に埋もれている
  • 更新されても、古い情報と新情報の区別がつかない

OKF はこれらを 1 ファイル 1 概念 の単位で区切り、先頭に フロントマター(YAML) でメタ情報を添えることで解決します。

このツールが生み出すもの

okf-seedling は「書く」だけさせて、後は自動で二つの成果物を出します。単一の source(.qmd)から、人間用と機械用の 2 系統を同時に作る点が核心です。

flowchart LR
    Q["concepts/*.qmd<br>人間が書く(1 概念 1 ファイル)"] --> L["quarto render"]
    L --> H["_site/<br>人間用 HTML<br>(LP・チュートリアル・閲覧用)"]
    L --> O["okf/<br>機械用 OKF バンドル<br>(index.md / log.md / concepts/*.md)"]
    O --> V["validate-okf リンター<br>(準拠 + 品質警告)"]

  • 人間用 HTML … ブラウザで読むサイト(GitHub Pages / Cloudflare Pages に公開)
  • 機械用 OKF バンドル … エージェントが読む前提の Markdown。フロントマター付き
  • リンター … バンドルの妥当性・鮮度を自動チェック

なぜ「形式」が必要か(エージェントとの関係)

エージェントがドキュメントを読むとき、検索→抽出→推論という流れで知識を使います。このとき:

  • フロントマターが辞書: type・対象・作成日・有効期限を機械が一発で解釈できる
  • 1 概念 1 ファイル: 検索で「ちょうど 1 つ分」の知識を引ける(チャンク設計が安定)
  • 参照・関係の明示: 「この指標は、この計算定義に基づく」のようなつながりを辿れる

これが RAG(検索拡張生成)の精度を左右します。詳しくは OKF × RAG Synergy で扱っています。

用語集

用語 意味
OKF Open Knowledge Format。知識を構造化し、人間とエージェントの両方に読める形で交換するための規格
知識バンドル concept の集合体。okf/ ディレクトリ(index.md / log.md / concepts/*.md)としてまとまる
concept 1 つの知識(API、手順書、指標など)。1 ファイル 1 概念
フロントマター 各 .qmd 先頭の YAML ブロック。type・status・generated などのメタ情報
type concept の種類(APIEndpoint / Playbook / Metric など)。必須フィールド
type レジストリ tools/okf-types.json。型の定義を一元管理し、検証・描画・抽出がすべてここを参照
provenance 誰が・いつ生成・検証したかの記録に対応する generated / verified フィールド
エージェント LLM を中心に、ツールを使ってタスクを実行する機械。知識を読む主体の 1 つ
RAG Retrieval-Augmented Generation。検索結果を根拠に LLM が回答を生成する仕組み
リンター コードやデータの形式・品質を自動チェックするツール。ここでは矛盾・欠落・鮮度を警告する
Quarto プレーンテキスト(.qmd)から HTML などへ変換する出版ツール。okf-seedling の実行基盤

検証(リンター)がやってくれること

okf-seedling は「作る」だけでなく「正しく整っているか」も見ます。node tools/validate-okf.mjs が次のチェックをします。

  • 準拠(エラー = 失敗): frontmatter の有無、必須 type、型ごとの必須フィールド、内部リンクの解決
  • 品質(警告 = 成功のまま報告): 鮮度の期限切れ(stale_after)、title / description の欠落、本文が空、未登録 type、推奨見出しの不足

コードのリンター(ESLint 等)と同じ発想で、情報バンドルを対象にしたリンターがこのツールに組み込まれている、と考えると掴みやすいです。

次に読むもの

  1. 1. Create a Bundle — 実際にバンドルを作って、2 系統出力とリンターを体験
  2. 2. Concept Types — 6 種の型の書き方と拡張方法
  3. 3. Deploy — GitHub Pages / Cloudflare Pages への公開
  4. OKF × RAG Synergy — なぜこの形式がエージェントとの協働に効くかの深掘り

読む順は 0 → 1 → 2 → 3 → Synergy がおすすめです。各ページ 1 つのテーマだけを扱っています。