Plugin SDK v0.9 移行ガイド

旧 inbound link のため historical path name を維持しています。現在は current migration checklist です。一部 API は削除済みですが、push_message v1 compatibility argument は current source で変換され deprecation warning を出します。filename から正確な removal release を推測しないでください。

概要

以前の API	状態	移行先
type = "script" / script plugin	削除済み、互換レイヤーなし	通常の plugin パッケージと NekoPluginBase
plugin._types.result	削除済み	plugin.sdk.plugin から Result、Ok、Err、SdkError などを import
Bus の where_* とリスト集合演算	削除済み	get()、filter() / where()、sort()、limit()、watch() を合成
get_message_plane_all	削除済み	bounded な await self.bus.messages.get(...) を使用
Bus の incremental/local fast path	削除済み	標準の bounded/replayable read/watch パイプライン
高レベル self.memory / SDK MemoryClient	削除済み	self.bus.memory.get(...) は最近のメモリ上の user-context record の読み取りにのみ使用。永続メモリの semantic recall に対応する plugin SDK API はありません
Extension package type、[plugin.host]、plugin.sdk.extension	削除済み、互換レイヤーなし	Router を所有する通常 Plugin に統合するか、独立した Plugin に変換
push_message v1 フィールド	deprecated だが current source では変換される	parts、visibility、ai_behavior を使い、正確な removal release に依存しない

パッケージ種別

script plugin には互換 shim がありません。manifest とエントリークラスを標準 Plugin に変更します。

[plugin]
type = "plugin"

from plugin.sdk.plugin import NekoPluginBase, neko_plugin, plugin_entry, Ok

@neko_plugin
class MyPlugin(NekoPluginBase):
    @plugin_entry(id="run")
    async def run(self, **_):
        return Ok({"status": "done"})

Extension に互換 shim はありません。type = "extension" と [plugin.host] を削除し、Router module を旧 host に移して self.include_router(router) を呼ぶか、通常の NekoPluginBase package に変換します。plugin.sdk.extension import は plugin.sdk.plugin の対応する public symbol に置き換えてください。PluginRouter は通常 Plugin 内部のコード整理にだけ残ります。

Result の import

公開 Result スタックは 1 つだけです。

# 以前
from plugin._types.result import Result, Ok, Err

# 移行後
from plugin.sdk.plugin import Result, Ok, Err, SdkError

削除されたモジュールの互換 alias を追加しないでください。

Bus クエリと watcher

Bus は host state の read/watch facade であり、publish 可能な汎用イベントバスではありません。名前空間を 1 つ選び、結果件数を制限します。

events = await self.bus.events.get(plugin_id=self.plugin_id, max_count=50)
events = (
    events
    .filter(priority_min=1)
    .filter(type="TASK_FINISHED")
    .sort(by="timestamp", reverse=True)
    .limit(20)
)

watcher = events.watch(self.ctx)

@watcher.subscribe(on="add")  # "add"、"del"、"change" のみ
def on_added(delta):
    for event in delta.added:
        self.logger.info(f"event: {event.type}")

watcher.start()

callable の filter(predicate)、where(predicate)、sort(key=callable) は local snapshot 処理には使えますが replay できません。watch() より前では使わず、watcher chain には structured filter(field=value, ...) と sort(by=...) を使います。watch() を使えるのは messages、events、lifecycle だけで、conversations と memory は read-only snapshot です。

削除済み helper は where_in、where_eq、where_contains、where_regex、where_gt、where_ge、where_lt、where_le と BusList の共通部分/差分演算です。条件は filter(...) または where(predicate) に書き換え、2 つの snapshot を結合する必要がある場合は record key を使って通常の Python で明示的に処理します。

get_message_plane_all は Message Plane の messages store を page 単位で読み、max_items 上限を持つ API でした。incremental な after_seq transport path が削除されたため、1 対 1 の代替 API はありません。bounded な await self.bus.messages.get(max_count=..., ...) に移行し、必要に応じて structured filter、sort(by=...)、limit() を使います。

削除された Bus fast path は、BusList fast_mode、incremental reload cursor、local message cache、revision/delta shortcut などの高速化分岐です。watch() に必要な replay plan と trace は残っており、get() / structured filter(field=value) / sort(by=...) / limit() が replayable chain を構成します。これらは旧 push_message(fast_mode=...) とは別物です。後者は deprecated v1 compatibility surface に属します。v2 は標準の per-message host delivery path を使うため、旧 batching/backpressure 最適化を実際に外す際は high-volume producer を再 benchmark してください。

Memory

旧 SDK MemoryClient は異なる 2 つの概念を混在させていました。現在サポートされる代替機能は、host の最近の user-context snapshot の読み取りです。

# 1 bucket の最近の record
records = await self.bus.memory.get(bucket_id="default", limit=20)

これらは件数制限付きでメモリ上にのみ保持されるユーザー発話イベントで、TTL は 1 時間です。キャラクターの永続的な facts、reflections、persona ではありません。self.bus.memory による record の読み取りと型付き record は残ります。削除されたのは高レベルの self.memory property と SDK/runtime の MemoryClient facade です。ctx.query_memory(...) は互換性のため残っていますが、非推奨の placeholder endpoint を呼ぶだけで semantic recall は行いません。現在、公開 plugin SDK に構造化された永続メモリ recall API はありません。

push_message v2

新規コードでは canonical schema だけを使います。

self.push_message(
    source="my_plugin",
    visibility=["chat"],
    ai_behavior="blind",
    parts=[{"type": "text", "text": "タスクが完了しました"}],
)

同じ変更内で移行できない call に対して、稼働中の plugin source へ marker だけを一括挿入するのは避けてください。plugin maintainer の変更と競合しやすいため、まず issue または PR で warning を追跡します。自分が管理する plugin source では、次のような局所コメントを使用できます。

# TODO(plugin-api-v0.9): v0.9 までに push_message v1 field を置換する。追跡: <issue-or-PR>。

v1 の message_type、description、content、binary_data、binary_url、mime、delivery、reply、unsafe、fast_mode は互換専用です。静的 check と runtime warning が対象呼び出しを示します。v0.9 より前に移行してください。完全な対応表は push_message v2 の説明を参照してください。

検証

uv run neko-plugin check <plugin_id-or-path> --strict

旧 push_message warning は抑制せず、すべて移行対象として扱ってください。