DeepSeek Harness プラグインのライフサイクル:Fiber 状態機械

前の章では、リスナーを登録し、ツールを登録し、さらに書いてきましたctx.effect()。

プラグインは一体、どの時点から「実行」され、どの時点から「アンロード」されるのか、考えたことはありますか?

この章では、Cordis プラグインモデルとライフサイクル状態機械を紹介します。つまりFiber 状態機械。


Fiber とは何か

ロードされた各プラグインは、1つのFiberスコープを持ちます。

Fiber はプラグインインスタンスの実行ユニットと理解できます。プラグインの宣言、ロード、実行からアンロードまでのすべての状態を保持します。

フレームワークは Fiber を通じて、プラグインが現在どの段階にあるのか、そして次に何ができるのかを把握します。

Fiber:Cordis ランタイムにおけるプラグインインスタンスの状態コンテナ。

それはそのプラグインのライフサイクル状態を記録し、アンロード時に登録をクリーンアップする根拠にもなります。


Fiber 状態機械

Fiber の状態は以下の順序で遷移し、プラグインのロードからアンロードまでの一生全体を表します。

Fiber 状态机

メインパスはPENDING → LOADING → ACTIVE → UNLOADING → DISPOSED。

LOADING フェーズで apply が例外をスローした場合、入るのはFAILED。

状態意味発生タイミング
PENDING宣言済みだが、必要な依存関係が未準備プラグインがコンテキストに追加されたが、inject のサービスがまだ準備できていない
LOADING依存関係が準備完了し、apply を実行中すべての必須サービスが準備完了し、フレームワークが apply(ctx) を呼び出す
ACTIVEプラグイン実行中apply が正常に戻り、登録が有効になる
FAILEDapply が例外をスローapply の実行中にエラーが発生、ロード失敗
UNLOADINGプラグインがアンロード中で、リソースを解放している依存関係の消失、dispose、または HMR によるアンロードのトリガー
DISPOSED完全にアンロード済みすべてのディスポーザが実行完了

用語:inject はプラグインが必要とするサービス依存関係を宣言するフィールドです。フレームワークはこれらのサービスがすべて準備完了するまで apply を実行しません。


依存関係駆動のロード

inject を宣言したプラグインは、すべての必須サービスが準備完了するのを待ってから LOADING に入ります。

依存するサービスが現れない場合、プラグインは PENDING に留まり、apply は実行されません。

実例

// 文件路径:scratch-plugin/src/my-plugin.ts
// 本プラグインは 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 に書く必要があります。


ハンズオン例:状態遷移の観察

公式ドキュメントでは、以下の最小プラグインを使ってロードとアンロードのログを紹介しています。

実例

// 文件路径:scratch-plugin/src/lifecycle-log.ts
// 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つの状態を表します。ディスポーザは登録の逆順で、非同期かつ並行して登録をクリーンアップします。

セルフチェックしてみましょう:

  1. Fiber にはどの6つの状態がありますか?apply が例外をスローしたときはどの状態に入りますか?
  2. なぜ ctx.on で登録したリスナーは手動で removeListener する必要がないのでしょうか?
  3. 順序依存のある2つのクリーンアップ手順は、どう書けば安全ですか?
その他の拡張