Construir um plugin

Plugins são processos Python em sandbox. Escreva um handler, declare suas capacidades, envie um zip — executamos em um container Docker bloqueado e transmitimos eventos do Discord para ele via JSON-RPC.

Início rápido

Cinco minutos para um plugin em funcionamento:

Olá, plugin

Este arquivo inteiro é um plugin funcionando. Coloque-o em uma pasta com um manifest.json e envie:

from yourbot_sdk import Plugin, Context

plugin = Plugin()

@plugin.on_ready
def ready(ctx: Context):
    ctx.log("Plugin booted on server " + ctx.server_id)

@plugin.on_event("message_create")
def on_message(ctx: Context, event: dict):
    if event.get("author_bot"):
        return  # ignore other bots
    if "!ping" in event.get("content", ""):
        ctx.discord.send_message(
            channel_id=event["channel_id"],
            content="Pong!",
        )

# This is the entrypoint. Without it the plugin process exits immediately.
plugin.run()

Note: reading what people type (event["content"] on message_create / message_edit) requires the events:message_content capability. Without it those events are delivered meta-only: IDs and timestamps arrive, but content, author fields and attachments are omitted (so the author_bot check above needs the capability too). Slash commands don't need it.

Estrutura de arquivo do plugin

Um plugin é um zip com este layout:

my_plugin/
├── manifest.json            # required - id, version, capabilities, …
├── __main__.py              # required - your handler code (the entry point)
├── requirements.txt         # optional - pip deps to install in the sandbox
├── dashboard_manifest.json  # optional - declarative dashboard
└── dashboard/               # optional - iframe-mode dashboard (HTML/CSS/JS)
    └── index.html

Limites: 25 MB zipped, 100 MB uncompressed, at most 500 files and 10 MB per single file. manifest.json and __main__.py must sit at the zip root; anything malformed is rejected by the upload validator (run yourbot validate locally to see the same errors before you upload).

manifest.json

Declares who you are, what version this is, and what you're allowed to do. id, name and version are required. id must match the plugin you created in the Dev Portal; version is assigned by the platform on upload and your manifest's version is stamped to match — zip uploads and GitHub pulls alike, so you never need to bump it by hand. Minimum viable manifest:

{
  "id": "my_plugin",
  "name": "My Plugin",
  "version": "1.0.0",
  "description": "Pongs whenever someone types !ping.",
  "capabilities_required": [
    "discord:send_message",
    "events:message_content"
  ]
}

Campos opcionais:

Campo	Propósito
capabilities_required	Capabilities you request; server admins choose which to grant at install time. A call that needs an ungranted capability raises CapabilityError at runtime, so handle it or keep your ask minimal. Capabilities your code uses but you forgot to declare are auto-added at upload with a warning. See the capability catalog.
slash_commands	Comandos de barra diagonal do Discord que a plataforma deve registrar em seu nome. Veja Comandos de barra. Declarar isso adiciona automaticamente interaction:respond a capabilities_required.
proxy_domains_requested	Lista de permissão de nomes de host que você buscará através de ctx.http.*. O pipeline de upload detecta automaticamente domínios de URLs "https://…" literais em seu código-fonte; este campo é sua revisão final. Valores não vazios adicionam automaticamente proxy:http a capabilities_required.

Listing metadata (byline, icon, tags, screenshots) is edited on your Dev Portal listing page, not in manifest.json.

Ciclo de vida do plugin

Two hooks carry a plugin's whole lifecycle today: @plugin.on_ready for setup and your event handlers for everything else.

Decorador	Dispara quando
@plugin.on_ready	Running locally with yourbot dev: once per process start. In production (plugins run in pool mode): once per (worker, server), right before that server's first event reaches you. Either way it runs before your handlers, which makes it the place for per-server init like seeding KV defaults.
Handler	Everything else. @plugin.on_event(...), @plugin.on_slash_command(...) and friends; see the Build tab.

@plugin.on_ready
def ready(ctx: Context):
    # Runs before this server's first event - seed defaults once.
    if ctx.kv.get("welcome_channel") is None:
        ctx.kv.set("welcome_channel", "")
    ctx.log("ready on server " + ctx.server_id)

plugin.run()  # required - starts the event loop and blocks forever.

@plugin.on_install / on_enable / on_disable / on_uninstall fire as advisory signals: the platform delivers them best-effort when a worker for your plugin is live (a cold start can drop one), with a tenant-scoped ctx that keeps your approved capabilities — on_uninstall can run its ctx.sql cleanup. Treat them as optimizations, never as the only path: put required init in on_ready, and design your state so leftover keys are harmless if an uninstall signal is missed.

Você deve chamar plugin.run() na parte inferior de __main__.py. Sem isso, o processo sai antes do SDK se conectar ao executor.

Sobre YourBot

The SDK installs a yourbot command. Four subcommands cover the local loop:

comandos	O que isso faz
yourbot new <id>	mmo new my-plugin cria um projeto inicial com manifest, testes e um manipulador !ping funcionando. Quatro templates: basic, slash, welcome, cron.
yourbot dev	Run your plugin locally without Docker: it boots your handlers against a simulated runner so you can fire test events at them and watch the log output live.
yourbot validate	The same checks the upload pipeline runs: manifest shape, capability legality, disallowed imports, slash commands cross-checked against your @plugin.on_slash_command handlers, and capability auto-detection (including proxy:websocket from ctx.ws usage). Fix it locally instead of discovering it after upload.
yourbot doctor	Checks your project: SDK install and version, entry point parses, manifest and capabilities, forbidden imports, requirements.txt and tests layout. Run it when something works locally but not in review.

The local loop: yourbot new, edit __main__.py, yourbot dev to exercise handlers, yourbot validate, zip the contents, upload on the Dev Portal.