KnowledgeUnit プロトコル

KnowledgeUnit プロトコルは、AI 生成ナレッジを表現するための標準フォーマットを定義します。すべてのナレッジユニットは、明確に定義されたスキーマ、型識別子、バージョニング契約を持つ JSON-LD ドキュメントです。

JSON-LD フォーマット

すべての KnowledgeUnit は2つの必須コンテキストフィールドを持つ JSON-LD ドキュメントです：

{
  "@context": "https://openknowledgepulse.org/schema/v1",
  "@type": "Trace",
  "id": "kp:trace:a1b2c3d4",
  ...
}

@context -- スキーマ名前空間 URI。すべての v1.x ドキュメントは https://openknowledgepulse.org/schema/v1 コンテキストを共有します。新しいメジャーバージョンは新しいコンテキスト URI を導入します（例：.../v2）。
@type -- 型識別子。Trace、Pattern、SOP のいずれか。

KnowledgeUnit タイプ

プロトコルは3つのナレッジユニットタイプを定義し、それぞれ固有の ID プレフィックスを持ちます：

タイプ	ID プレフィックス	説明
Trace	`kp:trace:`	単一のエージェントインタラクションの記録。何が起こり、何が試され、結果はどうだったか。トレースはパターンが抽出される原材料です。
Pattern	`kp:pattern:`	複数のトレースから蒸留された繰り返し発生する解決策やアプローチ。「X が発生したら Y を行う」のような再利用可能なナレッジをキャプチャします。
SOP	`kp:sop:`	標準作業手順書。パターンから組み立てられた、キュレーション済みのステップバイステップワークフロー。システム内で最も忠実度の高いナレッジを表します。

Trace から Pattern、SOP への進行は、キュレーションと信頼度の増加を反映しています：

Trace（生の観察）
  → Pattern（繰り返し発生する解決策）
    → SOP（キュレーション済みワークフロー）

スキーマバージョニング戦略

KnowledgePulse はスキーマにセマンティックバージョニングを使用し、各バージョンレベルに明確なルールを設けています：

パッチバージョン（例：1.0.0 → 1.0.1）

バグ修正とフィールド説明の明確化。
@context URI に変更なし。
新しいフィールドの追加なし、フィールドの削除なし。
既存のコンシューマーは変更なしで動作し続けます。

マイナーバージョン（例：1.0.0 → 1.1.0）

追加のみ -- 新しいオプションフィールドが導入される可能性があります。
@context URI に変更なし（引き続き https://openknowledgepulse.org/schema/v1）。
既存のフィールドが削除されたり、セマンティクスが変更されることはありません。
既存のコンシューマーは動作し続け、新しいフィールドを単に無視します。

メジャーバージョン（例：v1 → v2）

破壊的変更 -- フィールドの削除、名前変更、セマンティクスの変更が行われる可能性があります。
新しい @context URI（例：https://openknowledgepulse.org/schema/v2）。
明示的なマイグレーションが必要です。

後方互換性ルール

2つのルールがクロスバージョンの相互運用性を規定します：

v1 コンシューマーはすべての v1.x ドキュメントをパースできなければならず、未知のフィールドを無視します。v1.0 に対して書かれたコンシューマーは v1.3 ドキュメントをエラーなく受け入れ、認識しないフィールドを単に破棄します。
v2 コンシューマーは v1 ドキュメントを受け入れなければならず、自動マイグレーションを行います。v2 コンシューマーが v1 ドキュメントに遭遇した場合、登録されたマイグレーション関数を適用してドキュメントをその場でアップグレードします。

バージョンネゴシエーション

REST API

クライアントは KP-Schema-Version リクエストヘッダーを使用して優先スキーマバージョンを宣言します：

GET /v1/knowledge/kp:trace:abc123
KP-Schema-Version: 1.2.0

サーバーはリクエストされたバージョン（または最も近い互換バージョン）のナレッジユニットで応答し、解決されたバージョンを返します：

HTTP/1.1 200 OK
KP-Schema-Version: 1.2.0
Content-Type: application/ld+json

サーバーがリクエストされたバージョンを満たせない場合、406 Not Acceptable を返します。

MCP ツール

MCP ツールは schema_version パラメータを受け入れます：

{
  "tool": "knowledgepulse_retrieve",
  "arguments": {
    "id": "kp:trace:abc123",
    "schema_version": "1.2.0"
  }
}

返されるナレッジユニットはリクエストされたスキーマバージョンに準拠します。

マイグレーションシステム

マイグレーション関数は packages/sdk/src/migrations/ に存在し、チェーン可能です。各マイグレーション関数はバージョン N からバージョン N+1 にドキュメントを変換します：

v1 → v2 → v3

v1 ドキュメントを v3 にマイグレートするために、SDK は v1-to-v2 と v2-to-v3 のマイグレーションを自動的にチェーンします。この設計により、各マイグレーションは単一のバージョンステップのみを処理すればよく、ロジックがシンプルでテスト可能になります。

import { migrate } from "@knowledgepulse/sdk";

// v1 ドキュメントを最新バージョンにマイグレート
const upgraded = migrate(v1Document, { targetVersion: "3.0.0" });

マイグレーション関数は純粋関数です。ドキュメントを受け取り、副作用なしに新しいドキュメントを返します。

非推奨ポリシー

新しいメジャーバージョンがリリースされた場合：

旧メジャーバージョンは新バージョンのリリース日から12ヶ月間サポートされ続けます。
非推奨期間中、旧バージョンのレスポンスにはコンシューマーにアップグレードを促す KP-Deprecated: true ヘッダーが含まれます。
12ヶ月の期間後、サーバーは旧バージョンの提供を停止し、410 Gone を返す場合があります。

HTTP/1.1 200 OK
KP-Schema-Version: 1.5.0
KP-Deprecated: true
Content-Type: application/ld+json

クライアントは KP-Deprecated ヘッダーを監視し、それに応じてマイグレーションを計画すべきです。

JSON-LD フォーマット​

KnowledgeUnit タイプ​

スキーマバージョニング戦略​

パッチバージョン（例：1.0.0 → 1.0.1）​

マイナーバージョン（例：1.0.0 → 1.1.0）​

メジャーバージョン（例：v1 → v2）​

後方互換性ルール​

バージョンネゴシエーション​

REST API​

MCP ツール​

マイグレーションシステム​

非推奨ポリシー​