okf-seedling

OKF v0.2 準拠の知識バンドルを作成する Quarto テンプレートツール

okf-seedling

ドキュメントを エージェントに読める形で整え、公開する Quarto テンプレートツールです。

LLM やエージェントに知識を読ませたいのに、検索がズレて回答がハズレる — それは文章が悪いのではなく、知識が「形式」に沿って整理されていないからです。

  • Why: 人間向けの文章のままでは、エージェントは概念の区切り・メタ情報・鮮度を正しく読めない
  • What: OKF(Open Knowledge Format)は知識を「1 概念 1 ファイル + フロントマター」に構造化する形式
  • How: .qmd を書くだけで、人間用 HTML と 機械用 OKF バンドル、さらにリンターチェックまでが同時に生まれる

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

  • エージェントにも人間にも読める .qmd をソースに
  • quarto use template 一発でバンドル雛形を生成
  • レンダリングで 人間用HTML と 機械用OKFバンドル を二系統出力
  • リンターツールとして準拠チェック + 鮮度・欠落の品質警告
  • GitHub Pages / Cloudflare Pages に並行デプロイ

OKF バンドルとは

エージェントにも人間にも読める形で、ドキュメント群をひとまとめにした知識パッケージです。 okf/ ディレクトリ(index.md / log.md / concepts/*.md)に機械可読な Markdown として自動生成され、 人間向けの HTML と 同じ source(.qmd) から同時に出力されます。

  • concept 単位で構造化 … API / Playbook / Metric / Attested Computation を 1 ファイル 1 概念で記述
  • frontmatter が辞書 … type・対象・作成日などのメタ情報を機械が解釈
  • sha 差分追跡 … バンドル全体の更新差分を機械が検知できる

Create

quarto use template watanabe3tipapa/okf-seedling で新しい知識バンドルを生成。詳細

Author

6 種の concept 型(API / Playbook / Metric / Attested Computation)を type レジストリで拡張可能。詳細

Deploy

GitHub Pages と Cloudflare Pages に並行デプロイ。frontmatter は HTML にも出力され、Playwright による知識蓄積にも対応。詳細

OKF × RAG Synergy

OKF(Open Knowledge Format)と RAG は競合ではなく、OKF バンドルが RAG の精度を左右する RAG-ready な知識基盤になる補完関係です。実バンドル例でシナジーを分解します。解説を読む

まず読んでほしい

OKF や知識バンドルが初めての方は、この順で読んでください。

  1. 0. What is OKF — OKF・バンドル・用語の基礎(10 分)
  2. 1. Create a Bundle — 実際に作ってみる
  3. 2. Concept Types — 6 種の型の書き方
  4. 3. Deploy — 公開する
  5. OKF × RAG Synergy — なぜエージェントに効くのか

Concept 型

Type 説明
API Overview API 全体の概要(認証・バージョン・エラー)
API Endpoint 1 エンドポイントの仕様
API Schema 入出力の型・JSON スキーマ
Playbook 手順書・対処手順
Metric 指標の定義
Attested Computation 検証可能な計算定義

Get Started

quarto use template watanabe3tipapa/okf-seedling
quarto render
node tools/validate-okf.mjs