プラグイン開発入門ガイド

N.E.K.O に新しい機能を加えたいときは、プラグインから始めるのがわかりやすい方法です。プラグインは小さな Python プロジェクトで、plugin.toml に基本情報を記述し、NekoPluginBase のサブクラスで機能を提供します。最初から N.E.K.O 全体の仕組みや内部構造を理解する必要はありません。

最初に見る 2 つのファイル

一般的なプロジェクト構成は CLI が自動で作成します。初めは次の 2 ファイルだけに注目してください：

plugin/plugins/hello_world/
├── plugin.toml   # プラグイン ID、名前、バージョン、Python クラス
└── __init__.py  # プラグインが提供する機能

plugin.toml は、読み込むプラグインと Python クラスを N.E.K.O に伝えます。__init__.py では、@plugin_entry などのデコレーターを使って、ユーザー、Agent、ホストから呼び出せる機能を公開します。

最小限の機能は次のように書けます：

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


@neko_plugin
class HelloWorldPlugin(NekoPluginBase):
    @plugin_entry(id="hello", name="Hello", description="Say hello")
    async def hello(self, name: str = "World", **_):
        return Ok({"message": f"Hello, {name}!"})

実行時エントリーは async def で定義し、Ok(...) または Err(...) を返します。設定、タイマー、ライフサイクル、メッセージ、保存領域、UI は、必要になったときに追加できます。

プラグインが動くまで

plugin.toml → プラグインクラスを読み込む → エントリーを登録する → プロセスを起動する
                                                        ↓
                                       エントリーを呼ぶ → Ok / Err

この流れには 2 種類の「エントリー」があります。plugin.toml の [plugin].entry は N.E.K.O が読み込む Python クラスを指定します。@plugin_entry で宣言する hello などの ID は、起動後に呼び出せる個々の機能を表します。

最初のプラグインを完成させる

1. uv run neko-plugin init <plugin_id> --type plugin --name "<表示名>" でプラグインを作成します。
2. 生成された plugin.toml と __init__.py を開きます。
3. 非同期の @plugin_entry 関数を追加または変更します。
4. uv run neko-plugin check <plugin_id> と生成されたテストを実行します。
5. N.E.K.O のプラグイン画面で一覧を更新してからプラグインを起動し、エントリーを呼び出します。以後の変更では、実行中のプラグインを再読み込みできます。
6. 他のユーザーに配布するときに .neko-plugin パッケージをビルドします。

開発中は、パッケージ内のコードと素材を読み取り専用として扱います。設定には self.config、永続データには self.data_path(...)、再生成可能なキャッシュには self.cache_path(...) を使います。

クイックスタートでは、Hello World プラグインの作成から実行までを順番に説明しています。完了後はプラグイン設定とエントリーとパラメータを読み、その他のページは必要になったときに参照してください。