DeepSeek Harness 依存駆動ロード、自動リロードとネストコンテキスト
前回までで Fiber 状態機械について学びました。今回は、状態機械がどのようにサービス依存によって駆動されるかを見ていきます。
なぜ依存するサービスが消えると、プラグインは自動的にアンロードされるのでしょうか?サービスが復旧すると、なぜ自動的にリロードされるのでしょうか?
依存駆動ロード
inject を宣言したプラグインは、必要なサービスがすべて準備完了になるのを待ってから、LOADING に入り apply を実行します。
このメカニズムは、サービス依存を使ってロード順序を表現するため、起動順序を手動で調整する必要はありません。
例
// このプラグインが tools と llm の2つのサービスに依存することを宣言
export const inject = ['tools', 'llm']
export function apply(ctx: Context) {
// ここでは ctx.tools と ctx.llm がすでに準備完了なので、安全に使用できます
}
依存するサービスが消えた場合(例えば提供元が置き換えられた場合)、プラグインは自動的にアンロードされ、ACTIVE から直接 DISPOSED へ移行します。
サービスが復旧すると、プラグインは再ロードされ、PENDING → LOADING → ACTIVE をもう一度経由します。
公式ドキュメントの原文:依存するサービスが消えた場合(例えば提供元が置き換えられた場合)、プラグインは自動的にアンロードされ(ACTIVE → DISPOSED)、サービス復旧後に再ロードされます。
自動リロードの保証
自動リロードが安全なのは、ctx を通じて行われたすべての登録がアンロード時に取り消されるからです。
旧インスタンスのリスナー、ツール、アダプターは残らず、新しいインスタンスが再登録します。
これにより、プラグインが存在しないサービスを呼び出すのを防ぎ、重複リスニングや重複登録も防ぎます。
ネストコンテキスト:ctx.plugin()
ctx.plugin() は、現在のプラグインの内部に子プラグインを登録するために使用します。
子プラグインは子 Fiber を作成します。これは親コンテキストを継承しますが、独立したライフサイクルを持ちます。
子 Fiber は親プラグインと一緒にアンロードされます。
例
export function apply(ctx: Context) {
// 子プラグインを登録する。childPlugin は関数、オブジェクト、または Service のサブクラスにできる
ctx.plugin(childPlugin)
// 子プラグインは自身の Fiber を持ち、親プラグインと一緒にアンロードされる
}
ネストコンテキストはプラグインの組み合わせでよく見られます。「集約」プラグインが複数の小プラグインをまとめ、それらのライフサイクルを一元管理します。
手動での早期終了:fiber.dispose()
ほとんどの場合、プラグインはコンテキストの破棄に伴ってアンロードされますが、実行中にプラグインインスタンスを手動で早期終了する必要がある場合もあります。
ctx.plugin() が返す Fiber オブジェクトはdispose()メソッドを提供します。
例
import type { Context } from '@deepseek-ai/cordis'
// 型宣言:context とプラグイン関数(例示)
declare const ctx: Context
declare function myPlugin(ctx: Context): void
// プラグインインスタンスを作成し、その Fiber を取得する
const fiber = ctx.plugin(myPlugin)
// 後で手動で終了する必要がある場合に dispose を呼び出す
// 注意:dispose は Promise を返すため、await で非同期クリーンアップの完了を待つ必要がある
await fiber.dispose()
dispose は3つのことを保証します:
| 保証 | 説明 |
|---|---|
| すべての登録が削除される | そのプラグインが持つリスナー、ツール、アダプターなどの登録がすべて取り消される |
| 子プラグインの再帰的アンロード | ctx.plugin() で作成された子 Fiber も一緒にクリーンアップされる |
| 非同期クリーンアップの完了を待つ | 返される Promise は、すべての非同期ディスポーザーの処理が終了した後に解決される |
言い換えれば、await fiber.dispose() が返った時点で、このプラグインはそのサブツリーも含めて完全に停止しています。
まとめとセルフチェック
依存駆動ロードにより、プラグインはサービスが準備完了のときだけ起動し、サービスが消えると自動アンロード、復旧すると自動リロードされます。ctx.plugin() は再帰的にアンロード可能な子 Fiber を作成します。
セルフチェックしてみましょう:
- inject で宣言されたサービスが準備完了でない場合、プラグインはどの状態で停止しますか?
- ctx.plugin() で作成された子 Fiber と親 Fiber はどのような関係ですか?
- await fiber.dispose() が返ったとき、どのようなことが完了していることが保証されますか?