Keyboard shortcuts

Press ← or → to navigate between chapters

Press ? to show this help

Press Esc to hide this help

ID: ADR-002 タイトル: ファーストパーティ拡張サーフェスはトレイト契約を使用する 日付: 2026-07-04 ステータス: 承認済み 関連:

  • crates/zeroclaw-api/src/model_provider.rs
  • crates/zeroclaw-api/src/channel.rs
  • crates/zeroclaw-api/src/tool.rs
  • crates/zeroclaw-api/src/memory_traits.rs
  • crates/zeroclaw-api/src/observability_traits.rs
  • crates/zeroclaw-api/src/runtime_traits.rs
  • crates/zeroclaw-api/src/peripherals_traits.rs
  • docs/book/src/architecture/crates.md
  • docs/book/src/developing/tool-inventory.md

ADR-002: ファーストパーティの拡張サーフェスはトレイト契約を使用する

これは、正式なADRプロセスが導入される前に行われた決定を遡って記録したものです。この記録には元の決定が行われた正確な日付は含まれていません。上記の日付は、このADRがアーキテクチャドキュメントに追加された日付です。

このレコードは FND-002 §6.3、現在の zeroclaw-api トレイトサーフェス、およびクレートとツール境界のドキュメントから起草されました。古い ADR ファイルから復元されたものではありません。

コンテキスト

ZeroClawには、モデルプロバイダー、メッセージングチャネル、ツール、メモリバックエンド、可観測性シンク、ランタイムアダプター、ハードウェアペリフェラルといった、多数の拡張ファミリーが必要です。各ファミリーはIO、エラー、構成、セキュリティ、ライフサイクルの制約が異なりますが、それぞれが同一のエージェントランタイムに組み込めなければなりません。

明示的な契約がなければ、あらゆる統合がランタイムループに特殊ケースの増加を強いることになります。それは当初は新しい統合を迅速にする一方、後々の保守を困難にします。プロバイダーのルーティングがチャネルに漏れ出し、ツールポリシーがプロバイダーに漏れ出し、チャネル認証がエージェントループに漏れ出し、メモリやロギングの挙動が無関係なクレート間でコピーされることになります。

リポジトリはすでにパブリックな契約レイヤーとして zeroclaw-api を使用しています。アーキテクチャドキュメントではこのクレートをカーネル ABI として説明しており、ランタイムは具象実装ではなくトレイトに依存していると記載しています。

決定

ファーストパーティ拡張ファミリーは、zeroclaw-api 内の明示的な Rust トレイト契約を使用し、そのサーフェス用の既存のファクトリ、レジストリ、コンポジション、またはホスト提供の境界を通じて配線されます。

主要なコントラクトには以下が含まれます:

  • モデルプロバイダークライアント用のModelProvider。
  • Channel は受信および送信メッセージング面用です。
  • エージェントが呼び出し可能な機能のためのTool。
  • 永続化と再呼び出しのためのMemoryとMemoryStrategy。
  • ランタイムテレメトリ用のObserver。
  • ホストランタイム機能向けの RuntimeAdapter。
  • ハードウェアおよびボード面向けの Peripheral。

トレイト、ファクトリ、レジストリ、ポリシー、config、ロギング、または下位レイヤーのヘルパーの境界には、複数の実装がそれを必要とする場合に共有される動作が属します。個々の統合は、単一のプロバイダー、チャネル、ツール、またはバックエンドを動作させるためだけに、ランタイムループにパッチを当てたり、並列の状態を追加したりすべきではありません。

この ADR は、ファーストパーティのインプロセス拡張サーフェスを対象としています。アウトオブプロセスまたは独立して配布される機能に対するプラグイン、WIT、MCP、スキルパッケージの境界を置き換えるものではありません。

結果

肯定的な結果:

  • 新しいファーストパーティ統合は、特注のランタイム変更としてではなく、既存の契約に照らしてレビューできます。
  • ランタイムコードは、ベンダー固有の動作ではなく、オーケストレーション、ポリシー、状態、ライフサイクルに集中し続けることができます。
  • テストでは、すべての統合に対して完全なエンドツーエンドのランタイムを必要とせずに、ファクトリ、レジストリ、またはホスト境界の配線、トレイトの動作、エッジケースを対象にできます。
  • ドキュメントおよびレビューガイダンスは、実装が始まる前に具体的な拡張サーフェスを挙げることができます。

否定的な結果:

  • トレイトの変更は影響範囲が広く、慎重な移行が必要です。
  • 狭すぎるトレイトは、インテグレーションに設定、ログ、またはアドホックなヘルパーパスを通じて振る舞いをトンネルすることを強制します。
  • 広すぎるトレイトは、重要な機能の違いを隠蔽する最大公約数的なAPIになり得る。
  • デフォルトのトレイトメソッドは、ドキュメントとテストでデフォルトを明示しない限り、サポートされていない動作を隠蔽する可能性があります。

フォローアップの決定:

  • ADR-003 は、ファーストパーティの Rust 実装だけでなく、独立して配布される WASM プラグイン機能を管理します。
  • ADR-005 は、バックエンド非依存のメモリストレージ契約と SQLite デフォルトを記録しています。
  • ADR-006とADR-007は、実装でゲートされたチャネルプラグインおよびゲートウェイ抽出に関する決定のために引き続き予約されています。

参照