langbot-plugin 0.4.5__tar.gz → 0.4.7__tar.gz

{langbot_plugin-0.4.5 → langbot_plugin-0.4.7}/.github/workflows/test.yml

@@ -77,3 +77,17 @@ jobs:
             src/langbot_plugin/entities/io \
             src/langbot_plugin/runtime/plugin/logbuffer.py \
             src/langbot_plugin/utils/platform.py
+
+  action-consistency:
+    name: Action Protocol Consistency
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check action enum / proxy / handler consistency
+        run: python scripts/check_action_consistency.py

langbot_plugin-0.4.7/AGENTS.md

@@ -0,0 +1,121 @@
+# AGENTS.md
+
+This file guides code agents working in the `langbot-plugin-sdk` repository. `CLAUDE.md` is a symlink to this file.
+
+Read `ARCHITECTURE.md` before non-trivial SDK, CLI, Plugin Runtime, Box Runtime, protocol, or cross-repo LangBot changes. This file is the working checklist; `ARCHITECTURE.md` is the system map.
+
+## Quick Facts
+
+- Package name: `langbot-plugin`.
+- Python: `>=3.10`.
+- CLI entrypoint: `lbp = langbot_plugin.cli:main`.
+- Main consumers: LangBot main repo and third-party plugins.
+- Runtime license: `src/langbot_plugin/runtime/` is AGPL; the rest is Apache 2.0.
+- LangBot pins this package in its `pyproject.toml`; local cross-repo testing needs a local install into LangBot's venv.
+
+## Essential Commands
+
+```bash
+uv sync --dev
+uv run lbp --help
+uv run lbp ver
+uv run lbp init MyPlugin
+uv run lbp comp Command
+uv run lbp run
+uv run lbp build
+uv run lbp publish
+uv run lbp rt
+uv run lbp box
+```
+
+Focused validation:
+
+```bash
+uv run pytest tests/api -q
+uv run pytest tests/cli -q
+uv run pytest tests/runtime -q
+uv run pytest tests/box -q
+uv run pytest tests/packaging/test_installed_cli_blackbox.py -q
+uv run python scripts/check_action_consistency.py
+```
+
+## Where to Look
+
+- Architecture map: `ARCHITECTURE.md`.
+- CLI entrypoint and flags: `src/langbot_plugin/cli/__init__.py`.
+- Plugin SDK APIs: `src/langbot_plugin/api/`.
+- Plugin Runtime: `src/langbot_plugin/runtime/`.
+- Box Runtime: `src/langbot_plugin/box/`.
+- Action protocol: `src/langbot_plugin/entities/io/` and `src/langbot_plugin/runtime/io/handler.py`.
+- Plugin tutorial: https://docs.langbot.app/zh/plugin/dev/tutor.
+- Runtime/CLI/SDK debugging: https://docs.langbot.app/zh/develop/plugin-runtime.
+- LangBot main repo: `../LangBot/`.
+
+## Cross-Repo LangBot Testing
+
+Use sibling repos:
+
+```text
+langbot-projects/
+├── LangBot/
+└── langbot-plugin-sdk/
+```
+
+When changing shared entities, component contracts, action payloads, Plugin Runtime, or Box Runtime:
+
+```bash
+# from langbot-plugin-sdk, with LangBot's .venv active
+uv pip install .
+
+# from LangBot; keep local SDK installed
+uv run --no-sync main.py
+```
+
+Standalone runtime flows:
+
+```bash
+# Plugin Runtime, default control :5400 and debug :5401
+uv run --no-sync lbp rt
+
+# Box Runtime, default :5410
+uv run --no-sync lbp box
+```
+
+Then configure LangBot as needed:
+
+- Plugin runtime: `plugin.runtime_ws_url: ws://localhost:5400/control/ws`, launch LangBot with `--standalone-runtime`.
+- Box runtime: `box.runtime.endpoint: ws://127.0.0.1:5410`, choose `box.backend`, launch LangBot with `--standalone-box`.
+
+## Change Rules
+
+- Treat action enums and Pydantic models as cross-process API contracts; update callers, handlers, and tests together.
+- Do not duplicate action strings outside the enum definitions.
+- Keep generated plugin templates, component base classes, CLI renderer behavior, and docs consistent when component contracts change.
+- Preserve `uv run --no-sync` guidance for local SDK testing; otherwise LangBot may reinstall the pinned PyPI package.
+- Keep comments/docstrings in English and user-facing labels/descriptions i18n-ready.
+- Commit message format: `<type>(<scope>): <subject>`.
+
+## Runtime Pitfalls
+
+- Direct local LangBot runs often spawn Plugin Runtime over stdio; stdio disconnects cannot auto-reconnect.
+- Orphan Runtime processes holding `5400`/`5401` commonly break `lbp run` debugging.
+- Docker deployments use `langbot_plugin_runtime:5400/control/ws` and `langbot_box:5410` as service hosts.
+- A false Box “no backend” often means Docker socket permission is missing, not that Docker is unavailable.
+- nsjail inside containers needs host cgroup namespace for cgroup v2 limits; do not fake memory limits with `RLIMIT_AS` because it breaks tools that reserve large virtual memory.
+- There is no supported `python -m langbot_plugin.box` entrypoint; use `lbp box`.
+- `CLAUDE.md` is a symlink to this file; edit `AGENTS.md`, not the symlink.
+
+## Principles
+
+- Keep it simple, stupid.
+- Entities should not be multiplied unnecessarily.
+- 八荣八耻
+
+    以瞎猜接口为耻，以认真查询为荣。
+    以模糊执行为耻，以寻求确认为荣。
+    以臆想业务为耻，以人类确认为荣。
+    以创造接口为耻，以复用现有为荣。
+    以跳过验证为耻，以主动测试为荣。
+    以破坏架构为耻，以遵循规范为荣。
+    以假装理解为耻，以诚实无知为荣。
+    以盲目修改为耻，以谨慎重构为荣。

langbot_plugin-0.4.7/ARCHITECTURE.md

@@ -0,0 +1,225 @@
+# Architecture
+
+This document maps the `langbot-plugin-sdk` repository. It explains the durable structure and cross-process contracts. For working rules, commands, and pitfalls, see `AGENTS.md`.
+
+## What This Repository Is
+
+`langbot-plugin-sdk` is the infrastructure package behind LangBot's plugin and sandbox systems. It is published to PyPI as `langbot-plugin` and pinned by the LangBot main repo.
+
+The package has four roles:
+
+- **Plugin SDK**: public APIs and entities imported by plugin authors.
+- **CLI**: `lbp`, used to scaffold, run, debug, build, publish, and launch runtimes.
+- **Plugin Runtime**: `lbp rt`, the host process that manages plugin packages and plugin processes.
+- **Box Runtime**: `lbp box`, the sandbox runtime used by LangBot's Box subsystem.
+
+The runtime code under `src/langbot_plugin/runtime/` is AGPL; the rest of the repo is Apache 2.0.
+
+## Repository Boundary
+
+This repo is coupled to LangBot but owns different things.
+
+- The LangBot main repo owns product behavior, HTTP API, web UI, platform adapters, pipeline execution, model/tool orchestration, persistence, skills integration, and the LangBot-side runtime connectors.
+- This SDK repo owns plugin author APIs, shared message/event/context entities, the action RPC protocol, `lbp`, Plugin Runtime implementation, and Box Runtime implementation.
+- Plugins import this package directly; LangBot also imports it for shared entities and runtime protocols.
+
+If a change alters shared entities, component contracts, action names/payloads, runtime behavior, or Box models, update/test both repos in lockstep.
+
+## Top-Level Layout
+
+```text
+langbot-plugin-sdk/
+├── src/langbot_plugin/
+│   ├── api/                  # Public plugin-author SDK
+│   │   ├── definition/       # BasePlugin, components, manifests
+│   │   ├── entities/         # Contexts, events, builtin platform/provider models
+│   │   └── proxies/          # APIs exposed to plugin code
+│   ├── cli/                  # `lbp` entrypoint and subcommands
+│   ├── runtime/              # Plugin Runtime (`lbp rt`)
+│   ├── box/                  # Box Runtime (`lbp box`)
+│   ├── entities/io/          # Action RPC request/response/error/action models
+│   ├── assets/               # Scaffolding templates and page SDK asset
+│   └── utils/
+├── docs/                     # Supplemental protocol/component docs
+├── tests/                    # Unit and black-box tests
+├── pyproject.toml
+└── README.md
+```
+
+## Public Plugin SDK
+
+Plugin-facing APIs live under `src/langbot_plugin/api/`.
+
+- `definition/plugin.py` defines `BasePlugin`.
+- `definition/components/` defines component base classes.
+- `definition/components/manifest.py` defines component manifest models.
+- `entities/` defines event/context/message/provider data models passed across LangBot, runtime, and plugin code.
+- `proxies/` defines methods plugins can call back into LangBot, such as messaging, storage, model invocation, tools, RAG, parser, and query-scoped APIs.
+
+Plugins extend LangBot through six component types:
+
+- `Command`
+- `Tool`
+- `EventListener`
+- `KnowledgeEngine`
+- `Parser`
+- `Page`
+
+The CLI scaffolds components via `lbp comp <Type>`. Component templates live under `src/langbot_plugin/assets/templates/`; generation logic lives under `src/langbot_plugin/cli/gen/`.
+
+## CLI Architecture
+
+`lbp` is declared in `pyproject.toml` and enters at `src/langbot_plugin/cli:main`, implemented by `src/langbot_plugin/cli/__init__.py`.
+
+Subcommands:
+
+- `init`: scaffold a plugin project.
+- `comp`: generate a plugin component.
+- `run`: run/remote-debug a plugin against a Runtime debug server.
+- `build`: package a plugin zip.
+- `publish`: publish a plugin to the marketplace.
+- `login` / `logout`: marketplace authentication.
+- `rt`: launch the Plugin Runtime.
+- `box`: launch the Box Runtime.
+- `ver`: print package version.
+
+Subcommand implementations live under `cli/commands/`, `cli/run/`, and `cli/gen/`. CLI i18n lives under `cli/locales/`.
+
+## Action RPC Protocol
+
+The runtime protocol is a bidirectional action RPC protocol over stdio or WebSocket. It is implemented by `runtime/io/handler.py` and data models under `entities/io/`.
+
+Request shape:
+
+```json
+{ "seq_id": 1, "action": "action_name", "data": {} }
+```
+
+Response shape:
+
+```json
+{ "seq_id": 1, "code": 0, "message": "success", "data": {}, "chunk_status": "continue" }
+```
+
+Core mechanics:
+
+- `seq_id` correlates responses to requests.
+- Messages with `action` are requests; messages with `code` are responses.
+- Each peer may initiate requests on the same connection.
+- `Handler.call_action()` waits for one response.
+- `Handler.call_action_generator()` consumes streamed responses.
+- Streaming emits `chunk_status: "continue"` chunks and ends with `"end"`.
+- File transfer uses `CommonAction.FILE_CHUNK` with 16KB base64 chunks stored under `data/temp/lbp/`.
+
+Action enums are the protocol contract:
+
+- `CommonAction`
+- `PluginToRuntimeAction`
+- `RuntimeToPluginAction`
+- `LangBotToRuntimeAction`
+- `RuntimeToLangBotAction`
+- `LangBotToBoxAction`
+
+Do not duplicate action strings outside these enums.
+
+## Plugin Runtime
+
+`lbp rt` enters `runtime/app.py::main()` and builds `RuntimeApplication`.
+
+Runtime graph:
+
+```text
+LangBot PluginRuntimeConnector
+  ↔ control connection
+  ↔ RuntimeApplication
+  → PluginManager
+  → PluginContainer(s)
+  ↔ PluginConnectionHandler(s)
+  ↔ plugin process(es)
+```
+
+Important modules:
+
+- `runtime/app.py`: selects stdio vs WebSocket control transport, starts control/debug servers, launches plugin manager tasks.
+- `runtime/context.py`: shared runtime context object.
+- `runtime/settings.py`: runtime settings, including marketplace/cloud URL.
+- `runtime/plugin/mgr.py`: plugin discovery, installation, dependency checks, launch, shutdown, event/tool/command/RAG/page dispatch.
+- `runtime/plugin/container.py`: loaded plugin package, manifest, component containers, status.
+- `runtime/io/handlers/control.py`: actions LangBot calls on the Runtime.
+- `runtime/io/handlers/plugin.py`: actions the Runtime calls on plugin processes.
+- `runtime/io/controllers/`: stdio/WebSocket server and client controllers.
+- `runtime/io/connections/`: transport-specific connection implementations.
+
+The Runtime has two external channels:
+
+- **control channel**: LangBot ↔ Runtime, stdio or `:5400/control/ws` by default.
+- **debug channel**: plugin dev process ↔ Runtime, WebSocket `:5401/plugin/debug/ws` by default.
+
+Installed plugins are stored under `data/plugins/{author}__{name}`. Runtime plugin processes normally run as separate Python processes and connect back via stdio or debug WebSocket.
+
+## Box Runtime
+
+`lbp box` enters `box/server.py::main()` and serves `BoxRuntime` through action RPC.
+
+Box graph:
+
+```text
+LangBot BoxService
+  ↔ BoxRuntimeConnector
+  ↔ BoxServerHandler
+  → BoxRuntime
+  → Backend session(s)
+  → Docker/Podman, nsjail, or E2B sandbox
+```
+
+Important modules:
+
+- `box/server.py`: CLI entrypoint, aiohttp WebSocket routes, `BoxServerHandler` action registration.
+- `box/runtime.py`: session lifecycle, per-session locks, TTL cleanup, command execution, managed processes.
+- `box/models.py`: `BoxSpec`, execution results, managed-process specs.
+- `box/client.py`: action-RPC client used by LangBot-side connector/service.
+- `box/actions.py`: `LangBotToBoxAction` enum.
+- `box/backend.py`: backend abstraction and local backend selection.
+- `box/nsjail_backend.py`: nsjail backend.
+- `box/e2b_backend.py`: E2B backend.
+- `box/skill_store.py`: Box-owned skill package CRUD and install/preview helpers.
+- `box/security.py`: path/security helper logic.
+
+Default Box WebSocket endpoints on port `5410`:
+
+- `/rpc/ws`: action RPC control channel.
+- `/v1/sessions/{session_id}/managed-process/ws`: legacy default process stdio relay.
+- `/v1/sessions/{session_id}/managed-process/{process_id}/ws`: named process stdio relay.
+
+There is no supported `python -m langbot_plugin.box` entrypoint; use `lbp box`.
+
+## Backend Selection
+
+Box can execute through multiple sandbox backends:
+
+- Docker/Podman through the local CLI backend path.
+- nsjail for local Linux sandboxing.
+- E2B for remote cloud sandboxes.
+
+LangBot sends Box config during initialization. Backend selection is controlled by LangBot's `box.backend` config (`local`, `docker`, `nsjail`, `e2b`) and the Box runtime's backend availability probes.
+
+A false “no backend” often means Docker exists but the user cannot access the Docker socket. nsjail inside containers requires host cgroup namespace for cgroup v2 limits if hard memory/pid/cpu enforcement is expected.
+
+## Cross-Repo Development Flow
+
+When changing shared contracts:
+
+1. Change this SDK repo first or in the same branch set.
+2. Install the local SDK into LangBot's virtualenv: `uv pip install .` from this repo while LangBot's `.venv` is active.
+3. Run LangBot with `uv run --no-sync ...` so `uv` does not replace the local SDK with the pinned PyPI package.
+4. Exercise the exact path changed: plugin stdio, plugin WebSocket, `lbp run`, `lbp rt`, `lbp box`, Box WebSocket, or Box stdio.
+
+The SDK `AGENTS.md` keeps the short command checklist; this file keeps the structural map.
+
+## Design Biases
+
+- Keep plugin-author SDK APIs stable and explicit.
+- Treat action enums and Pydantic models as cross-process API contracts.
+- Keep runtime process management separate from LangBot product logic.
+- Keep Box sandbox semantics in `box/`; LangBot should call Box through the service/client protocol.
+- Prefer tests around protocol shape and black-box CLI behavior when changing runtime boundaries.

langbot_plugin-0.4.7/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: langbot-plugin
+Version: 0.4.7
+Summary: This package contains the SDK, CLI for building plugins for LangBot, plus the runtime for hosting LangBot plugins
+Project-URL: Homepage, https://langbot.app
+Project-URL: Repository, https://github.com/langbot-app/langbot-plugin-sdk
+Project-URL: Issues, https://github.com/langbot-app/langbot-plugin-sdk/issues
+Author-email: Junyan Qin <rockchinq@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: dotenv>=0.9.9
+Requires-Dist: e2b>=2.15
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: packaging>=24.0
+Requires-Dist: pip>=25.2
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: pydantic>=2.11.5
+Requires-Dist: pytest>=8.4.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: textual>=3.2.0
+Requires-Dist: types-aiofiles>=24.1.0.20250516
+Requires-Dist: types-pyyaml>=6.0.12.20250516
+Requires-Dist: watchdog>=6.0.0
+Requires-Dist: websockets>=15.0.1
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<h1>LangBot Plugin Infra</h1>
+
+<p>Plugin SDK, CLI, Plugin Runtime and Box sandbox runtime for <a href="https://github.com/langbot-app/LangBot">LangBot</a>.</p>
+
+[![PyPI](https://img.shields.io/pypi/v/langbot-plugin)](https://pypi.org/project/langbot-plugin/)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+
+English / [简体中文](README_CN.md)
+
+[Documentation](https://docs.langbot.app/zh/plugin/dev/tutor) ·
+[Plugin Market](https://space.langbot.app) ·
+[LangBot](https://github.com/langbot-app/LangBot)
+
+</div>
+
+## Overview
+
+This repository is the shared infrastructure powering LangBot's plugin and
+sandbox subsystems. It is published to PyPI as the single
+[`langbot-plugin`](https://pypi.org/project/langbot-plugin/) package and ships
+three things:
+
+- **Plugin SDK & CLI** (`lbp`) — Python APIs, base classes and the `lbp`
+  command for scaffolding, building, debugging and publishing plugins.
+- **Plugin Runtime** (`lbp rt`) — the host process that discovers, installs and
+  runs plugins, bridging them to LangBot over stdio or WebSocket.
+- **Box Runtime** (`lbp box`) — the code-sandbox service backing LangBot's Box
+  subsystem, executing untrusted code via Docker / nsjail / E2B backends.
+
+LangBot depends on this package as the pinned `langbot-plugin==<x.y.z>` in its
+`pyproject.toml`; the canonical version lives in this repo's `pyproject.toml`.
+
+> The **Runtime** component (`src/langbot_plugin/runtime/`) is licensed
+> separately under **AGPL**; everything else in this repository is **Apache 2.0**.
+> See [`src/langbot_plugin/runtime/README.md`](src/langbot_plugin/runtime/README.md).
+
+## Install
+
+```bash
+pip install langbot-plugin
+# or, recommended
+uv tool install langbot-plugin
+
+lbp --help
+```
+
+## CLI at a glance
+
+| Command | Purpose |
+| --- | --- |
+| `lbp init <name>` | Scaffold a new plugin project |
+| `lbp comp <Type>` | Generate a component (Command / Tool / EventListener / KnowledgeEngine / Parser / Page) |
+| `lbp run` | Run / remote-debug a plugin against a running LangBot |
+| `lbp build` | Package the plugin into a distributable zip |
+| `lbp publish` | Publish to the LangBot Plugin Market |
+| `lbp login` / `lbp logout` | Authenticate with your LangBot account |
+| `lbp rt` | Launch a standalone Plugin Runtime (control `5400`, debug `5401`) |
+| `lbp box` | Launch a standalone Box sandbox runtime (default port `5410`) |
+| `lbp ver` | Print the CLI / package version |
+
+## Component types
+
+Plugins extend LangBot through six component types, scaffolded with
+`lbp comp <Type>`:
+
+- **Command** — user-triggered actions (e.g. `!weather tokyo`)
+- **Tool** — LLM-callable functions for AI agents
+- **EventListener** — handlers for message-pipeline events
+- **KnowledgeEngine** — custom knowledge-base retrieval for RAG
+- **Parser** — custom message / content parsing
+- **Page** — custom web page embedded in the LangBot admin panel
+
+## Documentation
+
+- Plugin development tutorial — https://docs.langbot.app/zh/plugin/dev/tutor
+- Debugging the Runtime / CLI / SDK — https://docs.langbot.app/zh/develop/plugin-runtime
+- Dev environment setup — https://docs.langbot.app/zh/develop/dev-config
+
+## License
+
+Apache 2.0, except the Plugin Runtime (`src/langbot_plugin/runtime/`) which is
+AGPL. See [LICENSE](LICENSE) and the
+[Runtime README](src/langbot_plugin/runtime/README.md).

langbot_plugin-0.4.7/README.md

@@ -0,0 +1,86 @@
+<div align="center">
+
+<h1>LangBot Plugin Infra</h1>
+
+<p>Plugin SDK, CLI, Plugin Runtime and Box sandbox runtime for <a href="https://github.com/langbot-app/LangBot">LangBot</a>.</p>
+
+[![PyPI](https://img.shields.io/pypi/v/langbot-plugin)](https://pypi.org/project/langbot-plugin/)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+
+English / [简体中文](README_CN.md)
+
+[Documentation](https://docs.langbot.app/zh/plugin/dev/tutor) ·
+[Plugin Market](https://space.langbot.app) ·
+[LangBot](https://github.com/langbot-app/LangBot)
+
+</div>
+
+## Overview
+
+This repository is the shared infrastructure powering LangBot's plugin and
+sandbox subsystems. It is published to PyPI as the single
+[`langbot-plugin`](https://pypi.org/project/langbot-plugin/) package and ships
+three things:
+
+- **Plugin SDK & CLI** (`lbp`) — Python APIs, base classes and the `lbp`
+  command for scaffolding, building, debugging and publishing plugins.
+- **Plugin Runtime** (`lbp rt`) — the host process that discovers, installs and
+  runs plugins, bridging them to LangBot over stdio or WebSocket.
+- **Box Runtime** (`lbp box`) — the code-sandbox service backing LangBot's Box
+  subsystem, executing untrusted code via Docker / nsjail / E2B backends.
+
+LangBot depends on this package as the pinned `langbot-plugin==<x.y.z>` in its
+`pyproject.toml`; the canonical version lives in this repo's `pyproject.toml`.
+
+> The **Runtime** component (`src/langbot_plugin/runtime/`) is licensed
+> separately under **AGPL**; everything else in this repository is **Apache 2.0**.
+> See [`src/langbot_plugin/runtime/README.md`](src/langbot_plugin/runtime/README.md).
+
+## Install
+
+```bash
+pip install langbot-plugin
+# or, recommended
+uv tool install langbot-plugin
+
+lbp --help
+```
+
+## CLI at a glance
+
+| Command | Purpose |
+| --- | --- |
+| `lbp init <name>` | Scaffold a new plugin project |
+| `lbp comp <Type>` | Generate a component (Command / Tool / EventListener / KnowledgeEngine / Parser / Page) |
+| `lbp run` | Run / remote-debug a plugin against a running LangBot |
+| `lbp build` | Package the plugin into a distributable zip |
+| `lbp publish` | Publish to the LangBot Plugin Market |
+| `lbp login` / `lbp logout` | Authenticate with your LangBot account |
+| `lbp rt` | Launch a standalone Plugin Runtime (control `5400`, debug `5401`) |
+| `lbp box` | Launch a standalone Box sandbox runtime (default port `5410`) |
+| `lbp ver` | Print the CLI / package version |
+
+## Component types
+
+Plugins extend LangBot through six component types, scaffolded with
+`lbp comp <Type>`:
+
+- **Command** — user-triggered actions (e.g. `!weather tokyo`)
+- **Tool** — LLM-callable functions for AI agents
+- **EventListener** — handlers for message-pipeline events
+- **KnowledgeEngine** — custom knowledge-base retrieval for RAG
+- **Parser** — custom message / content parsing
+- **Page** — custom web page embedded in the LangBot admin panel
+
+## Documentation
+
+- Plugin development tutorial — https://docs.langbot.app/zh/plugin/dev/tutor
+- Debugging the Runtime / CLI / SDK — https://docs.langbot.app/zh/develop/plugin-runtime
+- Dev environment setup — https://docs.langbot.app/zh/develop/dev-config
+
+## License
+
+Apache 2.0, except the Plugin Runtime (`src/langbot_plugin/runtime/`) which is
+AGPL. See [LICENSE](LICENSE) and the
+[Runtime README](src/langbot_plugin/runtime/README.md).

langbot_plugin-0.4.7/README_CN.md

@@ -0,0 +1,83 @@
+<div align="center">
+
+<h1>LangBot Plugin Infra</h1>
+
+<p>为 <a href="https://github.com/langbot-app/LangBot">LangBot</a> 提供插件 SDK、CLI、插件运行时与 Box 代码沙箱运行时。</p>
+
+[![PyPI](https://img.shields.io/pypi/v/langbot-plugin)](https://pypi.org/project/langbot-plugin/)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
+
+[English](README.md) / 简体中文
+
+[文档](https://docs.langbot.app/zh/plugin/dev/tutor) ·
+[插件市场](https://space.langbot.app) ·
+[LangBot](https://github.com/langbot-app/LangBot)
+
+</div>
+
+## 简介
+
+此仓库是支撑 LangBot **插件系统**与**代码沙箱**的共享基础设施，以单一的
+[`langbot-plugin`](https://pypi.org/project/langbot-plugin/) 包发布到 PyPI，包含三部分：
+
+- **插件 SDK 与 CLI**（`lbp`）—— 插件开发的 Python API、基类，以及用于脚手架、
+  构建、调试和发布插件的 `lbp` 命令。
+- **插件运行时**（`lbp rt`）—— 负责发现、安装并运行插件的宿主进程，通过 stdio
+  或 WebSocket 与 LangBot 通信。
+- **Box 运行时**（`lbp box`）—— 支撑 LangBot Box 子系统的代码沙箱服务，通过
+  Docker / nsjail / E2B 后端执行不受信任的代码。
+
+LangBot 通过 `pyproject.toml` 中固定的 `langbot-plugin==<x.y.z>` 依赖此包；
+版本号以本仓库的 `pyproject.toml` 为准。
+
+> **运行时**组件（`src/langbot_plugin/runtime/`）单独采用 **AGPL** 许可证，
+> 本仓库其余部分采用 **Apache 2.0**，详见
+> [`src/langbot_plugin/runtime/README.md`](src/langbot_plugin/runtime/README.md)。
+
+## 安装
+
+```bash
+pip install langbot-plugin
+# 或（推荐）
+uv tool install langbot-plugin
+
+lbp --help
+```
+
+## CLI 速览
+
+| 命令 | 作用 |
+| --- | --- |
+| `lbp init <name>` | 初始化一个插件项目 |
+| `lbp comp <Type>` | 生成组件（Command / Tool / EventListener / KnowledgeEngine / Parser / Page） |
+| `lbp run` | 针对运行中的 LangBot 运行 / 远程调试插件 |
+| `lbp build` | 将插件打包为可分发的 zip |
+| `lbp publish` | 发布到 LangBot 插件市场 |
+| `lbp login` / `lbp logout` | 登录 / 登出 LangBot 账号 |
+| `lbp rt` | 启动独立的插件运行时（控制端口 `5400`，调试端口 `5401`） |
+| `lbp box` | 启动独立的 Box 代码沙箱运行时（默认端口 `5410`） |
+| `lbp ver` | 打印 CLI / 包版本 |
+
+## 组件类型
+
+插件通过六种组件类型扩展 LangBot，使用 `lbp comp <Type>` 生成：
+
+- **Command** —— 用户触发的指令（如 `!weather tokyo`）
+- **Tool** —— 供 AI Agent 调用的 LLM 工具函数
+- **EventListener** —— 消息流水线事件的处理器
+- **KnowledgeEngine** —— 用于 RAG 的自定义知识库检索
+- **Parser** —— 自定义消息 / 内容解析
+- **Page** —— 嵌入 LangBot 管理面板的自定义网页
+
+## 文档
+
+- 插件开发教程 —— https://docs.langbot.app/zh/plugin/dev/tutor
+- 调试运行时 / CLI / SDK —— https://docs.langbot.app/zh/develop/plugin-runtime
+- 开发环境配置 —— https://docs.langbot.app/zh/develop/dev-config
+
+## 许可证
+
+本仓库采用 Apache 2.0，但插件运行时（`src/langbot_plugin/runtime/`）单独采用
+AGPL。详见 [LICENSE](LICENSE) 与
+[运行时 README](src/langbot_plugin/runtime/README.md)。