LangBot Plugin Development

Sources of Truth

Need	Where
Author docs (canonical)	`docs/en/plugin/dev/` (also `zh`, `ja`): `tutor`, `basic-info`, `directory-structure`, `permissions`, `components/`, `apis/`, `publish/*`
SDK, `lbp` CLI, Plugin Runtime	`langbot-plugin-sdk` repo (`langbot_plugin`)
Working examples	`plugins/` in the LangBot repo, indexed by `plugins/catalog.json`; minimal: `plugins/misc/HelloPlugin`; full Runner: `plugins/Runner/LocalAgent`
Official plugin rules	`plugins/AGENTS.md`, `plugins/RELEASING.md`
Runtime debugging	`docs/en/develop/plugin-runtime.mdx`

Read the matching doc page before writing code; do not guess SDK signatures.

Components

Declare components in manifest.yaml spec.components; each component has a .yaml (metadata) and a .py (implementation). Docs per type in docs/en/plugin/dev/components/:

EventListener: hook pipeline events (*MessageReceived, *NormalMessageReceived, NormalMessageResponded, ...).
Command: !command handlers. Tool: LLM function-call tools.
Runner: an Agent runner/event processor (see LocalAgent and other plugins/Runner/*).
KnowledgeEngine, KnowledgeRetriever, Parser: RAG backends, retrieval and document parsing.
Page: plugin-provided WebUI pages.

API Surfaces

Surface	Call	Docs
Common plugin APIs (models, storage, bots, messages)	`self.plugin.invoke_llm(...)`, `self.plugin.send_message(...)`, ...	`apis/common.mdx`, `apis/messages.mdx`, `apis/llm-requests.mdx`
Pipeline event context	`event_context.reply(...)`, `prevent_default()`	`apis/pipeline-events.mdx`
Platform API	`self.plugin.call_platform_api(bot_uuid, action, params)`; standard actions first, adapter-specific actions via `action="call_platform_api"`	`apis/platform.mdx`
Workspace API (Unified API)	`self.plugin.workspace.<domain>.<op>(...)` or `self.plugin.workspace.call("<op.id>", ...)`; Runners use `ctx.api.workspace`	`apis/workspace.mdx`
Runner context	`ctx.api`, `ctx.resources`	`apis/agent-run.mdx`, `components/runner.mdx`

Workspace API rules:

Operations share IDs with LangBot's HTTP API, MCP and Workspace assistant (for example pipeline.list, knowledge.base.retrieve). The full list with risk levels is in apis/workspace.mdx; await self.plugin.workspace.list() returns the operations granted to this installation at runtime.
Calls return {"ok": True, "result": ...} or {"ok": False, "error": {"code": ...}}; check ok. Treat permission_denied as expected and explain what is missing.
A Runner that offers Workspace operations to a model must offer only ctx.resources.workspace_operations; none when it is empty.

Permissions

Declare installation permissions in the plugin manifest spec.permissions (workspace_operations and capabilities). Request the minimum; high-risk operations are flagged to the confirming member. Runner component permissions do not accept workspace operation grants. An empty declaration denies global access; an absent declaration uses legacy compatibility mode and never grants Workspace operations. New installs, and permissions added by an upgrade, need member confirmation in WebUI; an API key cannot grant permissions. Details: docs/en/plugin/dev/permissions.mdx.

Workflow

lbp init MyPlugin        # scaffold (includes a GitHub release workflow)
cd MyPlugin
cp .env.example .env     # DEBUG_RUNTIME_WS_URL + PLUGIN_DEBUG_KEY from WebUI: Extensions -> Debug Info
lbp run                  # attach to a running LangBot's Plugin Runtime
lbp build                # package .lbpkg
lbp login && lbp publish # upload to LangBot Space as a draft

The debug key is per Workspace and rotates every two hours. For test traffic, prefer Debug Chat or the pipeline WebSocket in references/testing.md; drive instance setup through the langbot-mcp-ops skill.

For official plugins under plugins/, keep each plugin's dependencies and tests independent, regenerate plugins/catalog.json with python plugins/scripts/check_catalog.py --write, and never add plugin dependencies to Core.

Marketplace README and i18n

Root README.md MUST be English (default and fallback on LangBot Space).
Other languages go in readme/README_{lang}.md for zh_Hans, zh_Hant, ja_JP, th_TH, vi_VN, es_ES, ru_RU.
manifest.yaml metadata.label / metadata.description carry the same eight locales; repository must be a live URL. The marketplace syncs from the manifest: edit and re-publish instead of patching live data.

References

references/sdk-pitfalls.md: verified SDK gotchas (MessageChain iteration, invoke_llm arguments, prevent_default vs prevent_postorder, component YAML shape, import paths), pipeline event table, config field types, EventListener-only pattern.
references/testing.md: pipeline WebSocket testing, group trigger rules, restart timing, debugging checklist.