create-provider-package-with-core

Core を使用したプロバイダーパッケージの作成

@prefactor/core を基盤として、独自のプロバイダーアダプターパッケージを構築します。

基本原則：@prefactor/core はトレーシングのインフラストラクチャを担い、アダプターはプロバイダー固有の API をマッピングします。

トリガーフレーズ

次のようなパターンを含むリクエストで、このスキルを適用します。

• 「新しいプロバイダーパッケージを追加する」
• 「@prefactor/core を使用してプロバイダー X をインストゥルメントする」
• 「自分のフレームワークには Prefactor アダプターがない」
• 「Prefactor 用のカスタム SDK 統合を構築する」

ワークフロー

1. アダプターの境界を定義します。
2. プロジェクト内に小規模なアダプターパッケージを作成します。
3. Core のプリミティブを使ってインストゥルメンテーションを実装します。
4. アプリでトレースの動作を検証します。
5. 本番環境での使用に向けて堅牢化します。

1) アダプターの境界を定義する

• アダプターは薄く保ちます。リクエスト／レスポンスのマッピング、ミドルウェアフック、ペイロードの適応を担います。
• ライフサイクル、コンテキスト、シリアライズ、トランスポートの動作には @prefactor/core を再利用します。
• プロバイダー接頭辞付きのスパンタイプ（<provider>:agent、<provider>:llm、<provider>:tool）を使用します。

2) 小規模なアダプターパッケージを作成する

アプリまたはワークスペース内に、専用のモジュール／パッケージ（例：prefactor-provider-<provider>）を作成します。

• src/index.ts 公開エントリーポイント
• src/<provider>-middleware.ts プロバイダー統合ラッパー
• tests/ トレーシングの動作を網羅
• package.json @prefactor/core への依存関係を指定

次のパッケージ構成を使用します。

• ESM のインポート／エクスポートを使用し、相対インポートには明示的に .js を指定します。
• src/index.ts からは、安定したアダプターのエントリーポイントのみをエクスポートします。

3) Core のプリミティブを使ってインストゥルメンテーションを実装する

• トレーシング、コンテキスト伝播、設定、トランスポートヘルパーには @prefactor/core を依存先として使用します。
• アダプターが init と withSpan のようなヘルパー API を公開する場合は、同じトレーサーソースに関連付けます。アダプターのヘルパーを介さずに Core の withSpan を呼び出す場合は、明示的にトレーサーを渡します。
• プロバイダーの実行パスをコンテキスト内（SpanContext.runAsync(...)）でラップし、親／子スパンの関係を維持します。
• 入力／出力と使用量のメタデータを、利用可能な場合に取得し、切り詰め／秘匿化のための保護策を適用します。
• エラー発生時はスパンに失敗データを記録し、元のエラーを再スローします。
• ストリーミングを行うプロバイダーでは、完了、キャンセル、ストリームエラーの各タイミングでスパンを終了します。

4) アプリでトレースの動作を検証する

統合テストまたはローカルのスモークスクリプトで、次の項目を検証します。

• 親／子スパンの関係
• 成功時とエラー時のスパン終了
• ストリーミングの完了／キャンセル／エラー時の終端パス
• ペイロードの取得とサイズ制限
• プロバイダー接頭辞付きのスパンタイプ

設定済みの Prefactor トランスポートを通じてテレメトリが送信されることを確認します。

5) 本番環境での使用に向けて堅牢化する

ロールアウトの前に、次の項目を確認します。

• インストゥルメンテーションがユーザーのリクエストを決してクラッシュさせない
• スパンが必ず一度だけ終了する
• シークレットが秘匿化され、ペイロードのサイズが制限されている
• エラーを再スローする際に、元のスタックと型が保持される

クイックリファレンス

判断事項	配置場所
再利用可能なトレーシング／コンテキストヘルパー	@prefactor/core
プロバイダーのリクエスト／レスポンスのマッピング	自分のアダプターパッケージ
スパンのライフサイクルロジック	@prefactor/core ＋薄いラッパー呼び出し
プロバイダー専用のミドルウェア／ラッパー	自分のアダプターパッケージ

参考資料

• 実装チェックリストには references/provider-package-checklist.md を使用します。

よくある間違い

• Core を再利用せず、プロバイダーごとにトレーシングのライフサイクルを再実装する。
• プロバイダー接頭辞付きのタイプではなく、汎用的なスパン名を使用する。
• 切り詰め／秘匿化せずに生のペイロードを取得する。
• インストゥルメンテーション後にプロバイダーのエラーを握りつぶす。