DeepSeek Harness の自動クリーンアップと ctx.effect()

前の章DeepSeek Harness ローカルプラグインのロードログを一行出力するだけで終わりますが、実際のプラグインはリスナー、ツール、タイマーを登録します。

この章では、プラグインのアンロード時にこれらのリソースを誰がクリーンアップするのかという問題を解決します。

登録は ctx に任せ、クリーンアップも ctx に任せます。


自動クリーンアップの仕組み

ctx を介して登録されたもの——イベントリスナー、ツール、タイマー——は、プラグインのアンロード時にすべて自動的にクリーンアップされます。

removeListener や clearInterval を手動で呼び出す必要はありません。

フレームワークが自動クリーンアップできるのは、ctx を介したすべての登録がプラグインの Fiber スコープに記録されているためです。

アンロード時、フレームワークは登録順の逆順でそれらを解除します。


どの操作が自動的に追跡されるか

以下の操作はすべて自動的に追跡およびクリーンアップされます。

登録操作アンロード時の動作
ctx.on(event, handler)イベントリスナーの自動解除
ctx.tools.register(tool)ツール登録の自動解除
ctx.llm.registerAdapter(names, adapter)LLM アダプター登録の自動解除
ctx.effect(() => cleanup)返された disposer クリーンアップ関数の実行

注册与卸载的自动清理时序


ctx.effect():手動リソースをフレームワークに委ねる

上記のリストに含まれないリソースもあります。例えばネットワーク接続などです。

ctx.effect() を使って、それをどうクリーンアップするかをフレームワークに伝えます。

ctx.effect はコールバックを受け取ります。コールバック内でリソースを作成し、クリーンアップ関数(disposer)を返します。

この disposer はプラグインのアンロード時に実行されます。

disposer(クリーンアップ関数)は ctx.effect コールバックの戻り値です。

それは「今回作成したリソースをどう破棄するか」を表します。

プラグインのアンロード時、フレームワークがそれを呼び出します。

以下はハートビートタイマーの例です:

例

// ファイルパス: scratch-plugin/src/heartbeat.ts
import type { Context } from '@deepseek-ai/cordis'

export function apply(ctx: Context) {
  ctx.effect(() => {
    // タイマーを作成: 5秒ごとに heartbeat を出力する
    const timer = setInterval(() => {
      console.log('heartbeat')
    }, 5000)

    // 返されたクリーンアップ関数はプラグインのアンロード時に実行される
    // つまり: アンロード処理で手動 clearInterval する必要はない
    return () => clearInterval(timer)
  })
}

アンロード時に何もする必要がない場合は、disposer を書かなくても構いません。

ただし、タイマーや接続などのリソースを作成した場合は、必ず対応するクリーンアップ関数を返さなければなりません。


実行順序の詳細

プラグインのアンロード時、disposer は登録順の逆順に呼び出しが開始されます。

複数の非同期 disposer は並行して実行され、1つずつ完了することは保証されません。

順序に依存関係のあるクリーンアップ手順は、同じ ctx.effect() が返す disposer の中に必ず入れ、その disposer が直列に待機するようにしなければなりません。

ヒント:このルールは、先に登録されたリソースは後にクリーンアップされ、後から登録されたリソースは先にクリーンアップされることを意味します。


まとめとセルフテスト

ctx を介して登録されたリソースはアンロード時に自動クリーンアップされます。手動リソースには ctx.effect() を使って disposer を提供します。

  • 1. ctx を介して登録したタイマーは手動で clearInterval する必要がありますか?

  • 2. ctx.effect(() => disposer) の disposer はいつ実行されますか?

  • 3. 順序に依存するクリーンアップを同じ effect に入れるのはなぜですか?

その他の拡張