okf-knowledge-base

Open Knowledge Format (OKF)

OKF v0.2 は、エージェントが読み取れる知識のためのポータブルな形式です。Markdown ファイル、YAML フロントマター、標準リンクで構成されます。/open-knowledge スキルはツールの使用方法を定め、このスキルは OKF のセマンティクスを扱います。

基本ルール

• バンドルは .md ファイルのディレクトリツリーです。予約されていない各ファイルは 1 つの概念を表し、.md を除いたパスがその ID になります。
• 各概念には、解析可能なフロントマターと、空でない文字列の type が必要です。常に必須となるフィールドはほかにありません。
• type はオープンな語彙です。コンシューマーは見慣れないタイプやメタデータも受け入れる必要があります。
• ポータブルな関係性には標準の Markdown リンクを使用します。リンク切れやインデックスの欠如は許容されます。
• index.md と log.md はすべての階層で予約されています。ファイル名は小文字にしてください。
• index.md には通常フロントマターを記述しません。okf_version: "0.2" を宣言できるのはルートのインデックスだけです。
• log.md は新しい順に記述します。エントリーの見出しは ISO 日付で始めます — ## YYYY-MM-DD: Summary（日付の後の要約は任意です。## YYYY-MM-DD のように日付だけでも同様に適合します）。
• OKF コンシューマーが読み取るのは .md であり、.mdx ではありません。

作成時の判断

• 各概念は、有用なリンク先または引用先として最小限の内容にします。安定した説明的なタイプを選び、Document は一般的な代替としてのみ使用します。
• 事実、関係性、リソース、出典、検証、履歴を捏造しないでください。誤った構造を作るより、知識が欠けている状態のほうが適切です。
• title、description、resource、tags は、実質的な情報を加える場合にのみ使用します。
• 出所情報は sources に記録します。主張単位の引用は、対応する sources[].id と Markdown の脚注で結び付けます。
• 作成者情報と検証情報は分けてください。generated は誰がコンテンツを作成したかを示し、verified は誰が確認したかを示します。該当する場合は、正確に小文字の human: および process: プレフィックスを使用します。
• すべての出所情報のタイムスタンプは、UTC オフセットを明示した ISO 8601 形式の日時で記述します（stale_after: 2026-12-31T00:00:00Z）。日付だけ、またはオフセットのない時刻は使用しないでください。これは generated.at、verified[].at、stale_after、sources[].last_modified、および usage_window の両方の境界に適用されます。log.md のエントリー見出しは別扱いで、通常の YYYY-MM-DD 形式の日付のままにします。
• status: deprecated と期限切れの stale_after 値は、検証エラーではなく信頼性に関するシグナルとして扱います。
• type: Attested Computation の場合は、宣言されたランタイムとパラメーターに従ってください。承認済みの計算を書き換えないでください。

バンドルの読み取りと保守

• 最も近い index.md から始め、フロントマターを確認してから、関連するリンクだけをたどります。
• 現行の検証済みソースを優先しますが、不明なタイプや不完全なリンクも許容します。
• バンドルが前提と矛盾する場合はバンドルを信頼し、情報が欠けている、または一貫していない場合は、その旨を伝えます。
• 長期的に有用な発見は、該当する概念と作成者が記述した列挙に書き戻します。
• バンドルでログを使用している場合は、長期的に有用な変更の後に、事実に基づく日付入りの log.md エントリーを追加します。
• レガシーの timestamp と本文内の引用は読み取りますが、概念を更新する際は v0.2 の generated.at と sources を優先します。移行時に出所情報を決して捏造しないでください。

OpenKnowledge の okf プラグイン

オプションのプロジェクトプラグインは、書き込みを妨げることなく、継続的なポータビリティのフィードバックを提供します。

• 書き込み時の警告とプロジェクト監査により、構造、フロントマター、予約ファイル、リンク、.mdx の使用状況が確認されます。
• .ok/okf/*.schema.json には、正確なフィールド仕様が含まれています。推測するのではなく、生成済みのこれらのファイルを読み取ってください。編集してはいけません。
• 決定論的なリント結果により適合性が確認されます。それでも、メタデータが正確で有用かどうかはエージェントが判断する必要があります。
• オプションのインデックス生成機能は index.md ファイルを維持します。生成されたインデックスは機械が管理するため、OpenKnowledge が内容を置き換えるので、決して編集しないでください。
• log.md は生成するものではなく、作成者が記述するものです。

プラグインはデフォルトで無効になっており、各ルールを無効にできます。このプラグインの価値は、OpenKnowledge ネイティブのコンテンツが別の OKF コンシューマーに誤って解釈される場合に、早期警告を提供することです。