docs(develop): verify against code; add --standalone-box and box config keys

This commit is contained in:
RockChinQ
2026-06-07 08:57:34 -04:00
parent 3dec4a6925
commit 2b0c43df98
3 changed files with 6 additions and 6 deletions
+2 -2
View File
@@ -26,7 +26,7 @@ LangBot/
├── main.py # Entrypoint shim -> langbot.__main__.main()
├── pyproject.toml # Python project + deps (uv), pins langbot-plugin==<x.y.z>
├── src/langbot/
│ ├── __main__.py # Real entrypoint, CLI args (e.g. --standalone-runtime)
│ ├── __main__.py # Real entrypoint, CLI args (--standalone-runtime / --standalone-box / --debug)
│ ├── pkg/ # Core backend package
│ │ ├── api/ # HTTP API controllers + services (Quart)
│ │ ├── core/ # App bootstrap, stages, task manager
@@ -92,7 +92,7 @@ Each plugin runs in its own process, with its lifecycle managed by the plugin ru
- **Backend ↔ Plugin Runtime**:
- When LangBot is **started directly** (not in a container), the backend **spawns** the runtime itself and talks over **stdio** (lightweight/personal use). stdio **cannot auto-reconnect** — after a disconnect you must restart LangBot; a common failure is an **orphan runtime process** from a previous backend still holding `5400`/`5401` — kill it and restart.
- When LangBot runs in a **container**, it connects to a standalone runtime over **WebSocket** (production). Control port defaults to `5400`, debug port to `5401`. Config: `plugin.runtime_ws_url` in `data/config.yaml` (e.g. `ws://langbot_plugin_runtime:5400/control/ws`).
- **Backend ↔ Box Runtime**: The Box subsystem connects to the Box runtime over a control channel (default port `5410`), which executes sandboxed code in Docker / nsjail / E2B.
- **Backend ↔ Box Runtime**: The Box subsystem connects to the Box runtime over a control channel (default port `5410`), which executes sandboxed code in Docker / nsjail / E2B. Config (`box:` section of `data/config.yaml`): `box.enabled` (master switch), `box.backend` (`'local'`/`'docker'`/`'nsjail'`/`'e2b'`), `box.runtime.endpoint` (external Box runtime URL, e.g. `ws://127.0.0.1:5410`; empty = local auto-managed). As with the plugin runtime, set that endpoint and start with `--standalone-box` to connect to an external Box runtime.
- The full guide for debugging the runtime, CLI and SDK is in [Debugging Plugin Runtime, CLI, SDK](/en/develop/plugin-runtime); detailed flags and architecture are in the `langbot-plugin-sdk` repo's `AGENTS.md`.
## Development Environment Setup
+2 -2
View File
@@ -26,7 +26,7 @@ LangBot/
├── main.py # エントリーシム -> langbot.__main__.main()
├── pyproject.toml # Python プロジェクト + 依存(uv)、langbot-plugin==<x.y.z> を固定
├── src/langbot/
│ ├── __main__.py # 実際のエントリーポイント、CLI 引数(例:--standalone-runtime)
│ ├── __main__.py # 実際のエントリーポイント、CLI 引数(--standalone-runtime / --standalone-box / --debug)
│ ├── pkg/ # コアバックエンドパッケージ
│ │ ├── api/ # HTTP API コントローラ + サービス(Quart)
│ │ ├── core/ # アプリ起動、ステージ、タスクマネージャ
@@ -92,7 +92,7 @@ LangBot/
- **バックエンド ↔ プラグインランタイム**:
- LangBot を**直接起動**した場合(コンテナ外)、バックエンドが自らランタイムを**起動**し、**stdio** で通信します(軽量/個人向け)。stdio は**自動再接続できません**——切断後は LangBot の再起動が必要です。よくある障害は、前のバックエンドが残した**孤児ランタイムプロセス**が `5400`/`5401` を占有しているケースで、それを kill して再起動します。
- LangBot を**コンテナ**で実行する場合、**WebSocket** で独立したランタイムに接続します(本番向け)。制御ポートは既定 `5400`、デバッグポートは `5401`。設定:`data/config.yaml` の `plugin.runtime_ws_url`(例:`ws://langbot_plugin_runtime:5400/control/ws`)。
- **バックエンド ↔ Box ランタイム**:Box サブシステムは制御チャネル(既定ポート `5410`)で Box ランタイムに接続し、ランタイムが Docker / nsjail / E2B でサンドボックスコードを実行します。
- **バックエンド ↔ Box ランタイム**:Box サブシステムは制御チャネル(既定ポート `5410`)で Box ランタイムに接続し、ランタイムが Docker / nsjail / E2B でサンドボックスコードを実行します。設定(`data/config.yaml` の `box:` セクション):`box.enabled`(マスタースイッチ)、`box.backend`(`'local'`/`'docker'`/`'nsjail'`/`'e2b'`)、`box.runtime.endpoint`(外部 Box ランタイムの URL、例:`ws://127.0.0.1:5410`、空なら ローカル自動管理)。プラグインランタイムと同様、このエンドポイントを設定し `--standalone-box` で起動すると外部 Box ランタイムに接続できます。
- ランタイム・CLI・SDK のデバッグ方法の詳細は[「プラグインランタイム、CLI、SDK のデバッグ」](/ja/develop/plugin-runtime)を参照。詳細なフラグとアーキテクチャは `langbot-plugin-sdk` リポジトリの `AGENTS.md` にあります。
## 開発環境のセットアップ
+2 -2
View File
@@ -26,7 +26,7 @@ LangBot/
├── main.py # 入口垫片 -> langbot.__main__.main()
├── pyproject.toml # Python 项目与依赖(uv),固定 langbot-plugin==<x.y.z>
├── src/langbot/
│ ├── __main__.py # 真正的入口,定义 CLI 参数(如 --standalone-runtime)
│ ├── __main__.py # 真正的入口,定义 CLI 参数(--standalone-runtime / --standalone-box / --debug)
│ ├── pkg/ # 核心后端包
│ │ ├── api/ # HTTP API 控制器 + 服务(Quart)
│ │ ├── core/ # 应用引导、启动阶段(stages)、任务管理器
@@ -91,7 +91,7 @@ LangBot 后端的核心包 `src/langbot/pkg/` 按职责拆分为若干子模块
- **后端 ↔ 插件运行时**:
- 用户**直接启动** LangBot(非容器)时,后端自己**拉起**运行时并通过 **stdio** 通信(轻量/个人场景)。stdio **不能自动重连**——断开后需重启 LangBot;常见故障是上一个后端遗留的**孤儿运行时进程**仍占用 `5400`/`5401`,杀掉后重启即可。
- LangBot 运行在**容器**中时,通过 **WebSocket** 连接到独立的运行时(生产场景)。控制端口默认 `5400`,调试端口默认 `5401`。相关配置:`data/config.yaml` 的 `plugin.runtime_ws_url`(如 `ws://langbot_plugin_runtime:5400/control/ws`)。
- **后端 ↔ Box 运行时**:Box 子系统通过控制通道连接到 Box 运行时(默认端口 `5410`),运行时在 Docker / nsjail / E2B 中执行沙箱代码。
- **后端 ↔ Box 运行时**:Box 子系统通过控制通道连接到 Box 运行时(默认端口 `5410`),运行时在 Docker / nsjail / E2B 中执行沙箱代码。相关配置(`data/config.yaml` 的 `box:` 段):`box.enabled`(总开关)、`box.backend`(`'local'`/`'docker'`/`'nsjail'`/`'e2b'`)、`box.runtime.endpoint`(外部 Box 运行时地址,如 `ws://127.0.0.1:5410`,留空则本地自动托管)。与插件运行时类似,配置该地址并以 `--standalone-box` 启动即可连接外部 Box 运行时。
- 调试运行时、CLI 与 SDK 的完整方法见[《调试插件运行时、CLI、SDK》](/zh/develop/plugin-runtime),详细参数与架构在 `langbot-plugin-sdk` 仓库的 `AGENTS.md` 中。
## 开发环境配置