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 コールバックの戻り値です。
それは「今回作成したリソースをどう破棄するか」を表します。
プラグインのアンロード時、フレームワークがそれを呼び出します。
以下はハートビートタイマーの例です:
例
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 に入れるのはなぜですか?