mirror of
https://github.com/langbot-app/LangBot.git
synced 2026-11-05 07:12:02 +08:00
Add 'docs/' from commit '51dddcb3f891d60bc38645e88b2dbd515344da81'
git-subtree-dir: docs git-subtree-mainline:0582d1b3d4git-subtree-split:51dddcb3f8
This commit is contained in:
RockChinQ
@@ -0,0 +1,149 @@
|
||||
---
|
||||
title: "Debugging Plugin Runtime, CLI, SDK"
|
||||
---
|
||||
|
||||
<Info>
|
||||
Plugin Runtime, CLI, SDK are open sourced at: https://github.com/langbot-app/langbot-plugin-sdk
|
||||
</Info>
|
||||
|
||||
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
|
||||
langbot-projects
|
||||
├── LangBot
|
||||
├── langbot-plugin-sdk
|
||||
```
|
||||
|
||||
Enter the LangBot directory and install dependencies:
|
||||
|
||||
```bash
|
||||
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`.
|
||||
|
||||
<img
|
||||
width="600"
|
||||
src="/images/zh/develop/confirm_venv.png"
|
||||
/>
|
||||
|
||||
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
|
||||
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.
|
||||
- `--ws-debug-port`: Debug port to listen on, default is `5401`.
|
||||
- `--ws-control-port`: Control port to listen on (for LangBot main program connection), default is `5400`.
|
||||
- `-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`.
|
||||
|
||||
```yaml
|
||||
plugin:
|
||||
runtime_ws_url: ws://localhost:5400/control/ws
|
||||
```
|
||||
|
||||
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. 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
|
||||
|
||||
This codebase contains the following:
|
||||
|
||||
- `langbot_plugin.api`: Plugin-related entities and API definitions.
|
||||
- `langbot_plugin.assets`: Plugin templates.
|
||||
- `langbot_plugin.cli`: Plugin development CLI tools.
|
||||
- `langbot_plugin.entities`: Plugin system-related entities not defined in API.
|
||||
- `langbot_plugin.runtime`: Plugin runtime and underlying communication (stdio and websocket) implementation.
|
||||
|
||||
## `lbp` CLI Tool
|
||||
|
||||
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).
|
||||
Reference in New Issue
Block a user