DeepSeek Harness プラグインのライフサイクル:Fiber 状態機械
前の章では、リスナーを登録し、ツールを登録し、さらに書いてきましたctx.effect()。
プラグインは一体、どの時点から「実行」され、どの時点から「アンロード」されるのか、考えたことはありますか?
この章では、Cordis プラグインモデルとライフサイクル状態機械を紹介します。つまりFiber 状態機械。
Fiber とは何か
ロードされた各プラグインは、1つのFiberスコープを持ちます。
Fiber はプラグインインスタンスの実行ユニットと理解できます。プラグインの宣言、ロード、実行からアンロードまでのすべての状態を保持します。
フレームワークは Fiber を通じて、プラグインが現在どの段階にあるのか、そして次に何ができるのかを把握します。
Fiber:Cordis ランタイムにおけるプラグインインスタンスの状態コンテナ。
それはそのプラグインのライフサイクル状態を記録し、アンロード時に登録をクリーンアップする根拠にもなります。
Fiber 状態機械
Fiber の状態は以下の順序で遷移し、プラグインのロードからアンロードまでの一生全体を表します。
メインパスはPENDING → LOADING → ACTIVE → UNLOADING → DISPOSED。
LOADING フェーズで apply が例外をスローした場合、入るのはFAILED。
| 状態 | 意味 | 発生タイミング |
|---|---|---|
| PENDING | 宣言済みだが、必要な依存関係が未準備 | プラグインがコンテキストに追加されたが、inject のサービスがまだ準備できていない |
| LOADING | 依存関係が準備完了し、apply を実行中 | すべての必須サービスが準備完了し、フレームワークが apply(ctx) を呼び出す |
| ACTIVE | プラグイン実行中 | apply が正常に戻り、登録が有効になる |
| FAILED | apply が例外をスロー | apply の実行中にエラーが発生、ロード失敗 |
| UNLOADING | プラグインがアンロード中で、リソースを解放している | 依存関係の消失、dispose、または HMR によるアンロードのトリガー |
| DISPOSED | 完全にアンロード済み | すべてのディスポーザが実行完了 |
用語:inject はプラグインが必要とするサービス依存関係を宣言するフィールドです。フレームワークはこれらのサービスがすべて準備完了するまで apply を実行しません。
依存関係駆動のロード
inject を宣言したプラグインは、すべての必須サービスが準備完了するのを待ってから LOADING に入ります。
依存するサービスが現れない場合、プラグインは PENDING に留まり、apply は実行されません。
実例
// 本プラグインは tools と llm の2つのサービスを必要とすることを宣言する。両方が準備完了になるまで apply は実行されません。
export const inject = ['tools', 'llm']
export function apply(ctx: Context) {
// ここに来た時点では、ctx.tools と ctx.llm は必ず準備ができている
// 可以放心地注册工具、读取模型配置
}
これは、Cordis が手動で起動シーケンスを編成するのではなく、サービス依存関係によってロード順序を表現する方法です。
自動クリーンアップ機構
ctx を通じて行ったすべての登録は、プラグインのアンロード時に自動的に取り消されます。
これは dsh が「自己クリーンアップ」できる根本的な理由であり、ホットリプレースが安全に機能する前提でもあります。
| 登録操作 | アンロード時のクリーンアップ |
|---|---|
| ctx.on(event, handler) | イベントリスナーの自動削除 |
| ctx.tools.register(tool) | ツール登録の自動削除 |
| ctx.llm.registerAdapter(names, adapter) | LLM アダプター登録の自動削除 |
| ctx.effect(() => cleanup) | 返されたディスポーザはアンロード時に実行される |
特に ctx.effect は、ネットワーク接続など、既存の「レジストリ」で追跡できないカスタムリソースを管理するために使用されます。
ディスポーザの呼び出し順序
プラグインのアンロード時、ディスポーザは登録順序の逆順で呼び出しが開始されます。
複数の非同期ディスポーザは並行して実行され、順番に完了することは保証されません。
順序依存のあるクリーンアップ手順は、同じ ctx.effect() が返すディスポーザの中に入れ、そのディスポーザが直列に待機する必要があります。
例えば、A と B の2つのエフェクトを順に登録した場合、アンロード時には最初に B のディスポーザが呼び出され、次に A のディスポーザが呼び出されます。
B のクリーンアップが A のクリーンアップの完了を待つ必要がある場合は、この2つの手順を同じ effect に書く必要があります。
ハンズオン例:状態遷移の観察
公式ドキュメントでは、以下の最小プラグインを使ってロードとアンロードのログを紹介しています。
実例
// console.log でライフサイクルイベントを出力し、apply と effect の順序を観察する
export function apply(ctx: Context) {
// apply が呼び出される:プラグインは LOADING から ACTIVE へ移行する
console.log('サンプル plugin loading')
// エフェクトを登録:返されたクリーンアップ関数はアンマウント時に実行される
ctx.effect(() => {
// エフェクト登録完了(apply はまだ実行中)
console.log('サンプル effect registered')
// 返回 disposer:插件卸载时调用
return () => console.log('サンプル effect cleaned up')
})
}
ロード時の出力:
サンプル plugin loading サンプル effect registered
アンロード時の出力:
サンプル effect cleaned up
apply が最初に実行され、その後 effect の登録が実行され、返されたディスポーザがアンロード段階で呼び出されることがわかります。
まとめとセルフチェック
Fiber 状態機械は、プラグインの宣言から完全なアンロードまでの6つの状態を表します。ディスポーザは登録の逆順で、非同期かつ並行して登録をクリーンアップします。
セルフチェックしてみましょう:
- Fiber にはどの6つの状態がありますか?apply が例外をスローしたときはどの状態に入りますか?
- なぜ ctx.on で登録したリスナーは手動で removeListener する必要がないのでしょうか?
- 順序依存のある2つのクリーンアップ手順は、どう書けば安全ですか?