From 0afe8821620c9cbf11a3d8a11b04604c0d6fd0c2 Mon Sep 17 00:00:00 2001 From: Junyan Qin Date: Wed, 25 Feb 2026 13:07:33 +0800 Subject: [PATCH] Update plugin-runtime documentation to clarify directory structure, installation steps, and local modifications for LangBot and langbot-plugin-sdk. --- en/develop/plugin-runtime.mdx | 38 ++++++++++++++++++++++++++------ ja/develop/plugin-runtime.mdx | 41 ++++++++++++++++++++++++++++------- zh/develop/plugin-runtime.mdx | 33 ++++++++++++++++++++++------ 3 files changed, 90 insertions(+), 22 deletions(-) diff --git a/en/develop/plugin-runtime.mdx b/en/develop/plugin-runtime.mdx index bef150759..cb26db359 100644 --- a/en/develop/plugin-runtime.mdx +++ b/en/develop/plugin-runtime.mdx @@ -6,34 +6,46 @@ title: "Debugging Plugin Runtime, CLI, SDK" Plugin Runtime, CLI, SDK are open sourced at: https://github.com/langbot-app/langbot-plugin-sdk -Clone the plugin runtime source code: +Since LangBot depends on entities defined in langbot-plugin-sdk, we recommend opening VS Code in a new directory, placing both LangBot and langbot-plugin-sdk (git clone https://github.com/langbot-app/langbot-plugin-sdk) as subdirectories within it. The directory structure should look like: ```bash -git clone https://github.com/langbot-app/langbot-plugin-sdk +langbot-projects +├── LangBot +├── langbot-plugin-sdk ``` -Enter the plugin runtime directory and install dependencies: +Enter the LangBot directory and install dependencies: ```bash -cd langbot-plugin-sdk +cd LangBot uv sync --dev ``` At this point, uv will automatically create a virtual environment (.venv) for you. If your editor asks whether to use this virtual environment, please select `Yes`. + + +If the prompt does not appear, please manually set the Python interpreter path to the interpreter in the venv from the bottom-right corner. + +Then open the terminal at the bottom of VS Code, which will automatically activate the venv. + Or you can manually activate this virtual environment: ```bash +# Please modify the command according to your .venv path source .venv/bin/activate ``` ## Start Plugin Runtime ```bash -lbp rt +uv run --no-sync lbp rt ``` -Please ensure that the `lbp` command is the `lbp` executable in the virtual environment of this directory, or start it via `python -m langbot_plugin.cli.__init__ rt`. +Or start it via `python -m langbot_plugin.cli.__init__ rt`. Plugin Runtime accepts the following parameters: @@ -43,6 +55,18 @@ Plugin Runtime accepts the following parameters: - `-s`: Use `stdio` to accept control connections. **Use only in production environment**. - `--skip-deps-check`: To ensure that all plugin dependencies are installed, the Runtime will check and install all installed plugin dependencies on every startup. Use this parameter to disable this check. +### Make LangBot Use Your Locally Modified langbot-plugin-sdk + +If you have modified things like message entities or plugin data definitions, you need to update them in the LangBot environment to ensure data format compatibility during runtime. + +In a **terminal with the LangBot directory's virtual environment (.venv) activated**, switch to the langbot-plugin-sdk directory and run: + +```bash +uv pip install . +``` + +This will install your modified langbot-plugin-sdk into LangBot's environment. + ### Make LangBot Connect to This Runtime Configure `plugin.runtime_ws_url` to `ws://localhost:5400/control/ws` in LangBot's `data/config.yaml`. @@ -52,7 +76,7 @@ plugin: runtime_ws_url: ws://localhost:5400/control/ws ``` -And add the startup parameter `--standalone-runtime` when starting the LangBot main program (e.g., `uv run main.py --standalone-runtime`).\ +And add the startup parameter `--standalone-runtime` when starting the LangBot main program (e.g., `uv run --no-sync main.py --standalone-runtime`). Make sure to include the `--no-sync` parameter in this command, which ensures that the local langbot-plugin-sdk you just synced will not be overwritten by the remote version.\ Restart LangBot, and it will connect to this runtime using WebSocket. ## langbot-plugin-sdk Architecture diff --git a/ja/develop/plugin-runtime.mdx b/ja/develop/plugin-runtime.mdx index c60903242..172741910 100644 --- a/ja/develop/plugin-runtime.mdx +++ b/ja/develop/plugin-runtime.mdx @@ -6,34 +6,46 @@ title: "プラグインランタイム、CLI、SDKのデバッグ" プラグインランタイム、CLI、SDKはこちらでオープンソース化されています: https://github.com/langbot-app/langbot-plugin-sdk -プラグインランタイムのソースコードをクローンします: +LangBotはlangbot-plugin-sdkで定義されたエンティティに依存するため、新しいディレクトリでVS Codeを開き、LangBotとlangbot-plugin-sdk（git clone https://github.com/langbot-app/langbot-plugin-sdk）をサブディレクトリとして配置することをお勧めします。ディレクトリ構造は以下の通りです： ```bash -git clone https://github.com/langbot-app/langbot-plugin-sdk +langbot-projects +├── LangBot +├── langbot-plugin-sdk ``` -プラグインランタイムディレクトリに移動し、依存関係をインストールします: +LangBotディレクトリに移動し、依存関係をインストールします： ```bash -cd langbot-plugin-sdk +cd LangBot uv sync --dev ``` この時点で、uvは自動的に仮想環境(.venv)を作成します。エディターがこの仮想環境を使用するかどうかを尋ねる場合は、`Yes`を選択してください。 -または、この仮想環境を手動でアクティブ化できます: + + +プロンプトが表示されない場合は、右下隅からPythonインタープリターのパスをvenv内のインタープリターに手動で設定してください。 + +次に、VS Code下部のターミナルを開きます。これにより自動的にvenvがアクティブ化されます。 + +または、この仮想環境を手動でアクティブ化できます： ```bash +# .venvのパスに応じてコマンドを変更してください source .venv/bin/activate ``` ## プラグインランタイムの起動 ```bash -lbp rt +uv run --no-sync lbp rt ``` -`lbp`コマンドがこのディレクトリの仮想環境の`lbp`実行可能ファイルであることを確認するか、`python -m langbot_plugin.cli.__init__ rt`で起動してください。 +または`python -m langbot_plugin.cli.__init__ rt`で起動してください。 プラグインランタイムは以下のパラメーターを受け入れます: @@ -43,6 +55,18 @@ lbp rt - `-s`: `stdio`を使用して制御接続を受け入れます。**本番環境でのみ使用してください**。 - `--skip-deps-check`: すべてのプラグイン依存関係がインストールされていることを確認するため、ランタイムは起動時に毎回すべてのインストール済みプラグインの依存関係をチェックしてインストールします。このパラメーターを使用してこのチェックを無効にします。 +### LangBotでローカル修正したlangbot-plugin-sdkを使用する + +メッセージエンティティやプラグインデータ定義などを変更した場合、実行時のデータ形式の互換性を確保するために、LangBot環境に更新する必要があります。 + +**LangBotディレクトリの仮想環境（.venv）がアクティブ化されたターミナル**で、langbot-plugin-sdkディレクトリに移動し、以下を実行します： + +```bash +uv pip install . +``` + +これにより、修正したlangbot-plugin-sdkがLangBotの環境にインストールされます。 + ### LangBotをこのランタイムに接続する LangBotの`data/config.yaml`で`plugin.runtime_ws_url`を`ws://localhost:5400/control/ws`に設定します。 @@ -52,7 +76,8 @@ plugin: runtime_ws_url: ws://localhost:5400/control/ws ``` -そして、LangBotメインプログラムの起動時に起動パラメーター`--standalone-runtime`を追加します(例: `uv run main.py --standalone-runtime`)。 LangBotを再起動すると、WebSocketを使用してこのランタイムに接続されます。 +そして、LangBotメインプログラムの起動時に起動パラメーター`--standalone-runtime`を追加します(例: `uv run --no-sync main.py --standalone-runtime`)。このコマンドでは必ず`--no-sync`パラメーターを付けてください。これにより、同期したローカルのlangbot-plugin-sdkがリモート版で上書きされないことが保証されます。\ +LangBotを再起動すると、WebSocketを使用してこのランタイムに接続されます。 ## langbot-plugin-sdkアーキテクチャ diff --git a/zh/develop/plugin-runtime.mdx b/zh/develop/plugin-runtime.mdx index 710f12993..99664c5a3 100644 --- a/zh/develop/plugin-runtime.mdx +++ b/zh/develop/plugin-runtime.mdx @@ -6,16 +6,18 @@ title: "调试插件运行时、CLI、SDK" 插件运行时、CLI、SDK 开源在: https://github.com/langbot-app/langbot-plugin-sdk -Clone 插件运行时源码： +由于 LangBot 需要依赖 langbot-plugin-sdk 中定义的实体，我们推荐您在一个新建目录下打开 VS Code，将 LangBot 和 langbot-plugin-sdk（git clone https://github.com/langbot-app/langbot-plugin-sdk） 作为子目录放入其中，目录结构如下： ```bash -git clone https://github.com/langbot-app/langbot-plugin-sdk +langbot-projects +├── LangBot +├── langbot-plugin-sdk ``` -进入插件运行时目录，安装依赖： +进入 LangBot 目录，安装依赖： ```bash -cd langbot-plugin-sdk +cd LangBot uv sync --dev ``` @@ -26,19 +28,24 @@ uv sync --dev src="/images/zh/develop/confirm_venv.png" /> +若未弹出，请手动在右下角设置 Python 解释器路径为该 venv 中的解释器。 + +然后打开 VS Code 底部的终端，这将自动激活 venv。 + 或者请您手动激活此虚拟环境： ```bash +# 请自行根据.venv路径来修改命令 source .venv/bin/activate ``` ## 启动插件运行时 ```bash -lbp rt +uv run --no-sync lbp rt ``` -请确保`lbp`命令是该目录下的虚拟环境中的`lbp`可执行文件，或通过`python -m langbot_plugin.cli.__init__ rt`启动。 +或通过`python -m langbot_plugin.cli.__init__ rt`启动。 Plugin Runtime 接受以下参数： @@ -48,6 +55,18 @@ Plugin Runtime 接受以下参数： - `-s`: 使用`stdio`接受控制连接。**仅在生产环境使用**。 - `--skip-deps-check`: 为了确保插件依赖均已安装，Runtime 会在每次启动时检查并安装所有已安装插件的依赖。携带此参数可禁用此检查。 +### 使 LangBot 使用您本地修改过的 langbot-plugin-sdk + +若您修改了诸如消息实体、插件数据定义等内容，需要将其更新到 LangBot 环境，以确保运行期间数据格式兼容。 + +请在**确保已激活 LangBot 目录下的虚拟环境（.venv）的终端**中，切换目录到 langbot-plugin-sdk 目录下，执行： + +```bash +uv pip install . +``` + +这将把您修改后的 langbot-plugin-sdk 安装到 LangBot 的环境。 + ### 使 LangBot 连接到此运行时 在 LangBot 的`data/config.yaml`中配置`plugin.runtime_ws_url`为`ws://localhost:5400/control/ws`。 @@ -57,7 +76,7 @@ plugin: runtime_ws_url: ws://localhost:5400/control/ws ``` -并在启动 LangBot 主程序时携带启动参数`--standalone-runtime`（如：`uv run main.py --standalone-runtime`）。\ +并在启动 LangBot 主程序时携带启动参数`--standalone-runtime`（如：`uv run --no-sync main.py --standalone-runtime`）。此命令行中，请务必携带`--no-sync`参数，这将确保您刚刚同步的本地 langbot-plugin-sdk 不会被远程的覆盖。\ 重启 LangBot，将会使用 WebSocket 连接到此运行时。 ## langbot-plugin-sdk 架构