xinyin025/LangBot
1
0
Fork 0
mirror of https://github.com/langbot-app/LangBot.git synced 2026-10-28 19:35:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(runtime): update standalone development guide

Browse Source
This commit is contained in:
RockChinQ
2026-08-11 21:35:20 +08:00
parent 3ab2a61b12
commit 853d7d4091
4 changed files with 174 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
en/deploy/settings.mdx
+3 -2
View File
@@ -340,8 +340,9 @@ box:
enabled: true
backend: 'local' # 'local' (Docker/nsjail), 'docker', 'nsjail', or 'e2b'. Can be written via BOX__BACKEND.
runtime:
# External WebSocket runtimes also require LANGBOT_BOX_CONTROL_TOKEN in
# both LangBot and Box. Keep the shared secret out of this config file.
# LANGBOT_BOX_CONTROL_TOKEN is optional for OSS external WebSocket
# runtimes. To protect an exposed endpoint, set the same strong secret
# in both LangBot and Box. Keep it out of this config file.
endpoint: '' # External Box Runtime base URL, e.g. 'ws://127.0.0.1:5410'. Leave empty for local auto-managed runtime.
limits:
max_sessions: 64
en/develop/plugin-runtime.mdx
+57 -6
View File
@@ -42,11 +42,9 @@ source .venv/bin/activate
## Start Plugin Runtime
```bash
uv run --no-sync lbp rt
python -m langbot_plugin.cli.__init__ rt
```
Or start it via `python -m langbot_plugin.cli.__init__ rt`.
Plugin Runtime accepts the following parameters:
- `--debug-only`: Do not start plugins in the `data/plugins` directory, only allow loading plugins through debug connections.
@@ -76,10 +74,63 @@ 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 --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.\
In a terminal with LangBot's virtual environment activated, start the main program directly with Python and add `--standalone-runtime` (for example, `python main.py --standalone-runtime`). Calling the current virtual environment's Python directly does not resync dependencies, so it does not overwrite the local langbot-plugin-sdk you just installed with the remote version.\
Restart LangBot, and it will connect to this runtime using WebSocket.
`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` is optional by default. When it is unset on both LangBot and Runtime, the local OSS control connection is established without a token. To protect an exposed port 5400, configure the same high-entropy value of at least 32 characters on both sides; configuring only one side makes the connection fail.
`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` is optional by default. When it is unset on both LangBot and Runtime, the local OSS control connection is established without a token. To protect an exposed port 5400, configure the same high-entropy value of at least 32 characters on both sides. Once the Runtime configures a token, it rejects LangBot clients without the same value; configuring only the LangBot side does not enable authentication on the Runtime.
### Debug a plugin with `lbp run`
Multi-Workspace versions no longer allow a debug plugin to join the Runtime merely by reaching port `5401`. Every Workspace has a separate expiring debug key:
1. Make sure LangBot and Plugin Runtime are running and connected as described above.
2. On the LangBot WebUI Plugins page, open “Debug Info” and copy the debug URL and debug key. This requires resource-management permission in the current Workspace.
3. Add the values to the plugin project's `.env`:
```bash
DEBUG_RUNTIME_WS_URL=ws://localhost:5401/plugin/debug/ws
PLUGIN_DEBUG_KEY=<debug key copied from the WebUI>
```
4. Start the plugin from its project directory:
```bash
python -m langbot_plugin.cli.__init__ run
```
Instead of storing the key in `.env`, you may run `python -m langbot_plugin.cli.__init__ run --plugin-debug-key '<debug key>'`. Keys are scoped to one Workspace and expire after two hours. Fetch a new key after it expires, the Runtime restarts, or you switch Workspaces. A client that configures only `DEBUG_RUNTIME_WS_URL` is rejected.
## Start Box Runtime in standalone mode
Box Runtime follows the same control-connection rules as Plugin Runtime: a token is optional for OSS standalone development, and the connection works when `LANGBOT_BOX_CONTROL_TOKEN` is unset on both sides:
```bash
# Terminal 1: langbot-plugin-sdk directory
python -m langbot_plugin.cli.__init__ box
```
Point LangBot's `data/config.yaml` at the local Box Runtime:
```yaml
box:
enabled: true
backend: local
runtime:
endpoint: ws://127.0.0.1:5410
```
```bash
# Terminal 2: LangBot directory
python main.py --standalone-runtime --standalone-box
```
To protect an exposed port 5410, set the same high-entropy, non-whitespace value of at least 32 characters before starting each process:
```bash
export LANGBOT_BOX_CONTROL_TOKEN='<the exact same high-entropy secret on both sides>'
```
Once Box Runtime configures a token, it rejects LangBot clients without the same value. Configuring only the LangBot side does not enable authentication on Box Runtime; an explicitly configured value shorter than 32 characters is still rejected by both sides. Do not commit the real value to configuration or Git.
## langbot-plugin-sdk Architecture
@@ -95,4 +146,4 @@ This codebase contains the following:
The CLI tool provides Runtime startup, plugin initialization, plugin component management, Marketplace interaction, and other functions.
For detailed program entry points, please see [`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py).
For detailed program entry points, please see [`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py).
ja/develop/plugin-runtime.mdx
+57 -6
View File
@@ -42,11 +42,9 @@ source .venv/bin/activate
## プラグインランタイムの起動
```bash
uv run --no-sync lbp rt
python -m langbot_plugin.cli.__init__ rt
```
または`python -m langbot_plugin.cli.__init__ rt`で起動してください。
プラグインランタイムは以下のパラメーターを受け入れます:
- `--debug-only`: `data/plugins`ディレクトリのプラグインを起動せず、デバッグ接続を通じたプラグインの読み込みのみを許可します。
@@ -76,10 +74,63 @@ plugin:
runtime_ws_url: ws://localhost:5400/control/ws
```
そして、LangBotメインプログラムの起動時に起動パラメーター`--standalone-runtime`を追加します(例: `uv run --no-sync main.py --standalone-runtime`)。このコマンドでは必ず`--no-sync`パラメーターを付けてください。これにより、同期したローカルのlangbot-plugin-sdkがリモート版で上書きされないことが保証されます。\
LangBot の仮想環境を有効にしたターミナルで、Python を直接使用してメインプログラムを起動し、`--standalone-runtime` を追加します（例：`python main.py --standalone-runtime`）。現在の仮想環境の Python を直接呼び出す場合、依存関係は再同期されないため、インストールしたローカルの langbot-plugin-sdk がリモート版で上書きされることはありません。\
LangBotを再起動すると、WebSocketを使用してこのランタイムに接続されます。
`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` は既定では省略可能です。LangBot と Runtime の両方で未設定の場合、ローカル OSS の制御接続はトークンなしで確立されます。公開された 5400 ポートを保護する場合は、両側に同じ 32 文字以上の高エントロピー値を設定してください。片側だけに設定すると接続は失敗します。
`LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN` は既定では省略可能です。LangBot と Runtime の両方で未設定の場合、ローカル OSS の制御接続はトークンなしで確立されます。公開された 5400 ポートを保護する場合は、両側に同じ 32 文字以上の高エントロピー値を設定してください。Runtime 側に token を設定すると、同じ値を送信しない LangBot は拒否されます。LangBot 側だけに設定しても Runtime 側の認証は有効になりません。
### `lbp run` でプラグインをデバッグする
Multi-Workspace 版では、デバッグプラグインは `5401` ポートへ到達できるだけでは Runtime に接続できません。Workspace ごとに、有効期限付きの個別デバッグキーが必要です：
1. 上記の手順で LangBot と Plugin Runtime が起動し、接続済みであることを確認します。
2. LangBot WebUI の「プラグイン」ページで「デバッグ情報」を開き、デバッグ URL とデバッグキーをコピーします。この操作には現在の Workspace のリソース管理権限が必要です。
3. プラグインプロジェクトの `.env` に設定します：
```bash
DEBUG_RUNTIME_WS_URL=ws://localhost:5401/plugin/debug/ws
PLUGIN_DEBUG_KEY=<WebUI からコピーしたデバッグキー>
```
4. プラグインプロジェクトのディレクトリで起動します：
```bash
python -m langbot_plugin.cli.__init__ run
```
`.env` に保存せず、`python -m langbot_plugin.cli.__init__ run --plugin-debug-key '<デバッグキー>'` を使用することもできます。キーは Workspace ごとに分離され、有効期限は 2 時間です。期限切れ、Runtime の再起動、または Workspace の切り替え後は WebUI から再取得してください。`DEBUG_RUNTIME_WS_URL` だけを設定したクライアントは拒否されます。
## Box Runtime を standalone モードで起動する
Box Runtime の制御接続ルールは Plugin Runtime と同じです。OSS standalone 開発では token は省略可能で、両側で `LANGBOT_BOX_CONTROL_TOKEN` が未設定の場合も接続できます：
```bash
# ターミナル 1：langbot-plugin-sdk ディレクトリ
python -m langbot_plugin.cli.__init__ box
```
LangBot の `data/config.yaml` でローカル Box Runtime を指定します：
```yaml
box:
enabled: true
backend: local
runtime:
endpoint: ws://127.0.0.1:5410
```
```bash
# ターミナル 2：LangBot ディレクトリ
python main.py --standalone-runtime --standalone-box
```
公開された 5410 ポートを保護する場合は、両方のプロセスを起動する前に、同じ 32 文字以上で空白を含まない高エントロピー値を設定してください：
```bash
export LANGBOT_BOX_CONTROL_TOKEN='<両側で完全に同じ高エントロピーシークレット>'
```
Box Runtime 側に token を設定すると、同じ値を送信しない LangBot は拒否されます。LangBot 側だけに設定しても Box Runtime 側の認証は有効になりません。明示的に設定した値が 32 文字未満の場合は、引き続き両側で拒否されます。実際の値を設定ファイルや Git にコミットしないでください。
## langbot-plugin-sdkアーキテクチャ
@@ -95,4 +146,4 @@ LangBotを再起動すると、WebSocketを使用してこのランタイムに
CLIツールは、ランタイムの起動、プラグインの初期化、プラグインコンポーネント管理、Marketplaceとのインタラクションなどの機能を提供します。
詳細なプログラムエントリポイントについては、[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)を参照してください。
詳細なプログラムエントリポイントについては、[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)を参照してください。
zh/develop/plugin-runtime.mdx
+57 -6
View File
@@ -42,11 +42,9 @@ source .venv/bin/activate
## 启动插件运行时
```bash
uv run --no-sync lbp rt
python -m langbot_plugin.cli.__init__ rt
```
或通过`python -m langbot_plugin.cli.__init__ rt`启动。
Plugin Runtime 接受以下参数：
- `--debug-only`: 不启动`data/plugins`目录下的插件，仅允许通过调试连接加载插件。
@@ -76,10 +74,63 @@ plugin:
runtime_ws_url: ws://localhost:5400/control/ws
```
并在启动 LangBot 主程序时携带启动参数`--standalone-runtime`（如：`uv run --no-sync main.py --standalone-runtime`）。此命令行中，请务必携带`--no-sync`参数，这将确保您刚刚同步的本地 langbot-plugin-sdk 不会被远程的覆盖。\
并在已激活 LangBot 虚拟环境的终端中，直接使用 Python 启动主程序并携带参数`--standalone-runtime`（如：`python main.py --standalone-runtime`）。直接调用当前虚拟环境的 Python 不会再次同步依赖，因此不会把刚刚安装的本地 langbot-plugin-sdk 覆盖为远程版本。\
重启 LangBot，将会使用 WebSocket 连接到此运行时。
默认情况下无需配置 `LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN`：当 LangBot 与 Runtime 两端都未设置时，OSS 的本地控制连接直接建立。若部署环境需要为 5400 控制端口增加共享密钥，则必须在两端配置同一个至少 32 位的高熵值；只配置一端会导致连接失败。
默认情况下无需配置 `LANGBOT_PLUGIN_RUNTIME_CONTROL_TOKEN`：当 LangBot 与 Runtime 两端都未设置时，OSS 的本地控制连接直接建立。若部署环境需要为 5400 控制端口增加共享密钥，则应在两端配置同一个至少 32 位的高熵值。Runtime 端配置后，未携带相同密钥的 LangBot 会被拒绝；只在 LangBot 端配置并不会启用 Runtime 端的认证。
### 使用 `lbp run` 调试插件
多 Workspace 版本不再允许调试插件仅凭 `5401` 端口接入 Runtime。每个 Workspace 都有独立且会过期的调试密钥：
1. 确认 LangBot 与 Plugin Runtime 已按上文启动并连接成功。
2. 在 LangBot WebUI 的“插件”页面点击“调试信息”，复制调试 URL 和调试密钥。该操作需要当前 Workspace 的资源管理权限。
3. 在插件项目的 `.env` 中配置：
```bash
DEBUG_RUNTIME_WS_URL=ws://localhost:5401/plugin/debug/ws
PLUGIN_DEBUG_KEY=<从 WebUI 复制的调试密钥>
```
4. 在插件项目目录中启动：
```bash
python -m langbot_plugin.cli.__init__ run
```
也可以不写入 `.env`，改用 `python -m langbot_plugin.cli.__init__ run --plugin-debug-key '<调试密钥>'`。调试密钥按 Workspace 隔离且有效期为两小时；密钥过期、Runtime 重启或切换 Workspace 后，请回到 WebUI 重新获取。只配置 `DEBUG_RUNTIME_WS_URL` 会被 Runtime 拒绝。
## 以 standalone 模式启动 Box Runtime
Box Runtime 与 Plugin Runtime 的控制连接规则一致：OSS standalone 开发环境默认不强制配置 token，两端都未设置 `LANGBOT_BOX_CONTROL_TOKEN` 时可以直接连接：
```bash
# 终端 1：langbot-plugin-sdk 目录
python -m langbot_plugin.cli.__init__ box
```
LangBot 的 `data/config.yaml` 使用本地 Box 地址：
```yaml
box:
enabled: true
backend: local
runtime:
endpoint: ws://127.0.0.1:5410
```
```bash
# 终端 2：LangBot 目录
python main.py --standalone-runtime --standalone-box
```
若需要保护暴露的 5410 端口，请在启动两个进程前分别设置完全相同、至少 32 位且不含空白的高熵值：
```bash
export LANGBOT_BOX_CONTROL_TOKEN='<两端完全相同的高熵密钥>'
```
Box Runtime 端一旦配置 token，就会拒绝未携带相同 token 的 LangBot。只在 LangBot 端设置不会启用 Box Runtime 端认证；显式配置但不足 32 位的值仍会被两端拒绝。不要把真实密钥提交到配置文件或 Git。
## langbot-plugin-sdk 架构
@@ -95,4 +146,4 @@ plugin:
CLI 工具提供 Runtime 启动、插件初始化、插件组件管理、Marketplace 交互等功能。
详细的程序入口请查看[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)。
详细的程序入口请查看[`langbot_plugin.cli.__init__`](https://github.com/langbot-app/langbot-plugin-sdk/blob/main/src/langbot_plugin/cli/__init__.py)。