AiSpect コアモジュール解析
aispect-core は、AiSpect フレームワーク全体の基礎であり、中心となるハブです。その主な役割は、大規模モデル Agent の開発標準を定義し、フレームワークとアプリケーション間のインターフェースの規約を確立し、統一されたランタイムプロキシ実行環境 (Runtime Engine) を提供することです。AI プロキシのスキャン、登録、インターセプト、ルーティング、およびコア例外処理メカニズムはすべてこのモジュールに集約されます。
1. 設計原則
aispect-core は、以下の設計原則を堅持しています。
- 純粋な Java ライブラリ: Spring、Quarkus、または特定の IoC コンテナに依存しません。
- ログ依存関係ゼロ: モジュール内では
slf4jなどのログ実装の導入や出力を固く禁じ、強く型付けされた戻り値の規約と例外のみを介して通信します。 - コンパイラのようなランタイム体験: 「部分的な成功コンパイル」のセマンティクス (
AiScanResult) をサポートし、プロセスを中断するか、例外をラップして返すかは呼び出しスタックに委ねます。
2. 論理アーキテクチャとパッケージの分割
論理アーキテクチャの観点から、aispect-core は明確に区分された 4 つのサブパッケージ/モジュールに分割されます。純粋さを保証するために、これら 4 つのモジュールは物理コードパッケージで高度に分離されています。
2.1 com.aispect.api (インターフェース規約層)
これはフレームワークのトップレベルの規約であり、ライフサイクルインターセプト、コンテキスト、および呼び出し操作などのコアインターフェースを定義します。
AiScanResultとAgentInvocationCache: 起動フェーズで外部に提供されるコア資産として、インターセプトされたメソッドとプロキシ間のマッピング関係、および例外の収集を保持します。AiClientとAiOperations: 前者は基盤となる大規模モデルとの通信の抽象化 (ストリーミング推論を含む) を提供し、後者はビジネス開発者に公開される統一された操作パネルです。AiInvocationContext: プロキシのライフサイクル全体を通じて実行されるコンテキスト環境オブジェクト。- Agent ライフサイクルインターフェース:
AiAgentFilter、AiPreProcessor、AiPostProcessor、およびAiGraphBehaviorOrchestratorなど、さまざまなステージのコールバック仕様を定義します。
2.2 com.aispect.common (基本ツールと例外階層)
レイヤー間で共有される例外階層とツールを提供し、同様に厳格な「純粋さ」を維持します。
- 例外階層:
AiSpectExceptionをトップレベルの基本クラスとして、スキャンフェーズ専用のAiScanException(例外のリストを含む) と、ランタイムエラーのためのAiAgentExecutionExceptionが含まれます。
2.3 com.aispect.agent (実行プロキシメタデータ)
開発者がコードを通じて AI とやり取りするためのコアアノテーションとスケルトンの抽象化。
- コアアノテーション:
@AiUnitAgent: ステージ固有のインターセプト拡張のために、通常のビジネスメソッドに配置されます。@AiGraphAgent: ワークフロー全体を開始するために、クラスまたはメインプロセスインターフェースに配置されます。@AiNode: 大規模モデルによってスケジュール可能な基盤となる機能。belongToを介して、周囲のグラフプロキシコンテキストにバインドする必要があります。同じメソッド上の異なるノードは、相互に排他的な実行ステージを持つ必要があります。
- スケルトン実装: 定型コードを大幅に削減するために、
AbstractUnitAgentとAbstractGraphAgentを提供します。
2.4 com.aispect.core (内部実行エンジン)
アセンブリフェーズでのスキャンと、ランタイムでの AOP ルーティングを担当します。純粋に内部で動作し、外部には公開されません。
AiComponentScanner: アセンブリフェーズ中にアノテーション設定を反復処理します。「部分的な成功」のセマンティクスに従い、設定エラー (関連するアノテーションの欠落やステージの競合など) を発見しても短絡せずに、例外を完全に収集し、最終的な決定を外部レイヤーに委ねます。AgentInterceptor(動的プロキシ): JDK Dynamic Proxy に基づいてビジネスコードにランタイム拡張を注入し、プロキシオブジェクトのタイプに基づいてUnitEngineまたは関連するGraphオーケストレーターに正しくルーティングします。動作中は完全にサイレントであり、すべての設定の欠陥やネットワークエラーを Exception にエスカレーションして報告します。