プラグインシステムの概要
N.E.K.O. のプラグインシステムは、プロセス隔離と非同期 IPC に基づいた Python ベースのプラグインフレームワークです。シンプルな機能から複雑なプロトコルブリッジまで、さまざまなユースケースに対応する 3 つの開発パラダイム — Plugin、Extension、Adapter — をサポートしています。
アーキテクチャ
┌────────────────────────────────────────────────────┐
│ Main Process (Host) │
│ ┌──────────────────────────────────────────────┐ │
│ │ Plugin Host (core/) │ │
│ │ - プラグインライフサイクル管理 │ │
│ │ - バスシステム（メモリ、イベント、メッセージ）│ │
│ │ - Extension インジェクション │ │
│ │ - ZMQ IPC トランスポート │ │
│ └──────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────┐ │
│ │ Plugin Server (server/) │ │
│ │ - HTTP API エンドポイント (FastAPI) │ │
│ │ - プラグインレジストリ │ │
│ │ - メッセージキュー │ │
│ └──────────────────────────────────────────────┘ │
└────────────────────┬───────────────────────────────┘
│ ZMQ IPC
┌──────────────┼──────────────┬────────────────┐
▼ ▼ ▼ ▼
Plugin A Plugin B Extension C Adapter D
(プロセス) (プロセス) (インジェクト) (プロセス)3 つの開発パラダイム
| パラダイム | インポート元 | ユースケース | 実行方法 |
|---|---|---|---|
| Plugin | plugin.sdk.plugin | 独立した機能（検索、リマインダーなど） | 別プロセス |
| Extension | plugin.sdk.extension | 既存プラグインへのルート/フックの追加 | ホストプラグインプロセスにインジェクト |
| Adapter | plugin.sdk.adapter | 外部プロトコル（MCP、NoneBot）を内部プラグイン呼び出しにブリッジ | ゲートウェイパイプライン付き別プロセス |
どれを使うべきか？
- 「新しいスタンドアロン機能を追加したい」 → Plugin を使用
- 「既存プラグインに追加コマンドを拡張したい」 → Extension を使用
- 「MCP/NoneBot/外部プロトコルの呼び出しを受け付けてプラグインにルーティングしたい」 → Adapter を使用
99% の開発者は Plugin だけで十分です。まずはそこから始めましょう。
主な機能
- プロセス隔離 — 各プラグインは別プロセスで実行され、クラッシュしてもホストに影響しません
- 非同期サポート — 同期・非同期の両方のエントリーポイントに対応
- Result 型 — 型安全なエラーハンドリングのための
Ok/Err（通常フローで例外を使用しない） - フックシステム — AOP のための
@before_entry、@after_entry、@around_entry、@replace_entry - プラグイン間呼び出し — プラグイン間通信のための
self.plugins.call_entry("other_plugin:entry_id") - メモリクライアント — ホストメモリシステムにアクセスするための
self.memory - システム情報 — ホストシステムのメタデータを照会するための
self.system_info - プラグインストア — 永続的なキーバリューストレージのための
PluginStore - バスシステム — イベントの pub/sub のための
self.bus - 動的エントリー — 実行時にエントリーポイントを登録/解除
- 静的 UI — プラグインディレクトリから Web UI を配信
- ライフサイクルフック —
startup、shutdown、reload、freeze、unfreeze、config_change - タイマータスク —
@timer_intervalによる定期実行 - メッセージハンドラー — ホストシステムからのメッセージに反応
プラグインディレクトリ構造
plugin/plugins/
└── my_plugin/
├── __init__.py # プラグインコード（エントリーポイント）
├── plugin.toml # プラグイン設定
├── config.json # オプション：カスタム設定
├── data/ # オプション：ランタイムデータディレクトリ
└── static/ # オプション：Web UI ファイル