LangBot ドキュメント

日本語

简体中文
English

日本語

简体中文
English

Appearance

プラグイン開発チュートリアル ​

アーキテクチャの基礎 ​

バージョン4.0では、高セキュリティで柔軟性の高い本番環境グレードのプラグインシステムを導入し、開発者に豊富なAPIと使いやすいサポートツールを提供しています。

Plugin Runtimeは、プラグインのライフサイクルを管理し、LangBotとプラグイン間の相互作用を調整するために使用されます。stdioとwebsocketの2つの動作モードがあります。LangBotがユーザーによって直接起動される場合(コンテナ内で実行されていない場合)、stdioモードを使用します。これは個人ユーザーや軽量環境で一般的です。LangBotがコンテナ内で実行される場合、websocketモードを使用します。これは本番環境専用に設計されています。

Plugin Runtimeは、インストールされた各プラグインを自動的に起動し、stdioを通じて相互作用します。プラグイン開発シナリオでは、開発者はlbpコマンドラインツールを使用してプラグインを起動し、WebSocketを介して実行中のRuntimeに接続してデバッグできます。

プラグイン構造 ​

プラグインのディレクトリ構造は次のようになります:

bash
➜  HelloPlugin > tree
.
├── assets
│   └── icon.svg  # プラグインアイコン、プラグインマーケットプレイスページに表示
├── components  # プラグインコンポーネントディレクトリ、さまざまなコンポーネントコードとマニフェストファイルを保存
│   ├── __init__.py
│   ├── commands
│   │   ├── __init__.py
│   │   ├── info.py
│   │   └── info.yaml
│   ├── event_listener
│   │   ├── __init__.py
│   │   ├── default.py
│   │   └── default.yaml
│   └── tools
│       ├── __init__.py
│       ├── get_weather_alerts.py
│       └── get_weather_alerts.yaml
├── main.py  # プラグインメインプログラム、プラグインライフサイクルをリッスン
├── manifest.yaml  # プラグインマニフェストファイル、プラグインメタデータを記述
├── README.md  # プラグインドキュメントファイル、プラグイン機能と使用方法を記述、プラグインマーケットプレイスページに表示
└── requirements.txt  # プラグイン依存関係ファイル

main.pyのプラグインクラスは各プラグインの共通コードで、プラグイン起動時に初期化され、コンテキスト情報(設定など)が渡されます。ここでプラグインの初期化とシャットダウンロジックを実装できます。プラグインクラスはlangbot_plugin.api.definition.plugin.BasePluginを継承し、LangBotグローバルAPIを提供します。

各コンポーネントはプラグインのコア機能モジュールであり、必要に応じて追加および削除できます。異なるコンポーネントは異なる状況で呼び出され、後でプラグイン機能を簡単に拡張できます。各コンポーネントはlangbot_plugin.api.definition.componentsパッケージ下のさまざまなコンポーネント基底クラスから直接継承し、plugin: BasePluginオブジェクトを含み、プラグインのAPIを直接呼び出すことができます。

INFO

このチュートリアルを続けて読んで、プラグイン開発プロセスを理解してください。

CLIのインストール ​

Python 3.10以上がインストールされており、uvパッケージマネージャーがインストールされていることを確認してください。

任意の空のディレクトリで次のコマンドを実行して、LangBot CLIとSDKをインストールします:

bash
pip install -U langbot_plugin

プラグインディレクトリの初期化 ​

プラグイン名がHelloPluginであると仮定して、任意のディレクトリにHelloPluginディレクトリを作成し、そのディレクトリに入り、コマンドを実行してプラグインを初期化します:

bash
lbp init

プロンプトに従ってAuthor、Descriptionなどの情報を入力します。

INFO

lbp init HelloPluginコマンドを使用して、サブディレクトリHelloPluginでプラグインを初期化することもできます。

この操作により、プラグインの初期ファイルが生成されます。お気に入りのエディターでHelloPluginディレクトリを開き、プラグインコードの記述を開始できます。

INFO

lbpコマンドで「command not found」エラーが発生した場合、PATH環境変数が適切に設定されていない可能性があります。 lbpコマンドの代わりにpython -m langbot_plugin.cli.__init__を使用できます。

例えば:

bash
python -m langbot_plugin.cli.__init__ init HelloPlugin
cd HelloPlugin

デバッグモードの開始 ​

まずLangBotをデプロイして起動し、Plugin Runtimeが実行されてポート5401をリッスンしていることを確認する必要があります。

INFO

Runtimeには2つの起動モードがあります:

  • Stdioモード: 起動パラメータ--standalone-runtimeなしでソースコードを使用してLangBotを起動すると、LangBotは自動的にPlugin Runtimeをサブプロセスとして起動し、stdio(標準入出力ストリーム)を通じてPlugin Runtimeと通信します。この場合、RuntimeはLangBotルートディレクトリのdata/pluginsディレクトリからプラグインをロードし、LangBotホストのポート5401をデバッグポートとしてリッスンします。

  • WebSocketモード:

    • 本番環境: 公式のdocker-compose.yamlを使用してLangBotを起動すると、Plugin Runtimeは別のコンテナで実行され、起動パラメータ--standalone-runtimeのためにLangBotはWebSocketモードでPlugin Runtimeと通信します。Runtimeコンテナの5401ポートはデフォルトでホストの5401ポートにマッピングされます。
    • 開発環境: 起動パラメータ--standalone-runtimeを使用してソースコードでLangBotを起動すると、LangBotはdata/config.yamlで設定されたplugin.runtime_ws_urlアドレス(ポートは通常5400)に従って既に起動されているPlugin Runtimeに接続します。スタンドアロンのPlugin Runtimeを自分で起動する必要があります。Plugin Runtimeの開発を参照してください。

stdioまたはwebsocketモードのいずれの場合でも、Plugin Runtimeはそのホストのポート5401をプラグインデバッグ接続のデバッグポートとしてリッスンします。

プラグインを開発する際は、開発設定方法に従ってLangBotを起動することをお勧めします。これによりPlugin RuntimeがStdioモードで起動され、プラグイン開発が容易になります。

プラグインディレクトリの.env.exampleファイルを.envにコピーし、DEBUG_RUNTIME_WS_URLをPlugin RuntimeのWebSocketアドレスに確認または変更します。

bash
cp .env.example .env

プラグインデバッグを開始すると、プラグインの出力が表示されます:

bash
lbp run

そして、LangBotのWebUIでこのプラグインがロードされたことを確認できます。

次のステップ ​

このチュートリアルでは、プラグイン機能を段階的に完成させる方法を案内します。

  • プラグイン情報の変更: プラグインは基本的なプラグイン情報で作成されました。プラグイン情報を完成させてください。
  • コンポーネントの追加: プラグインコンポーネントはプラグインのコア機能ユニットです。必要に応じてコンポーネントを追加できます。