Crea un plugin

Los plugins son procesos Python en sandbox. Escribe un handler, declara tus capacidades, envía un zip — lo ejecutamos en un contenedor Docker restringido y transmitimos eventos de Discord mediante JSON-RPC.

Inicio rápido

Cinco minutos para tener un plugin funcionando:

Hola, plugin

Este archivo completo es un plugin funcional. Colócalo en una carpeta con un manifest.json y publícalo:

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.

Estructura de archivos del plugin

Un plugin es un zip con esta estructura:

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

Límites: 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 opcionales:

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 slash de Discord que la plataforma debe registrar en tu nombre. Consulta Comandos slash. Declarar esto añade automáticamente interaction:respond a capabilities_required.
proxy_domains_requested	Lista de permisos de nombres de host a los que accederás mediante ctx.http.*. El pipeline de carga detecta automáticamente dominios de URLs literales "https://…" en tu código fuente; este campo es tu revisión final. Los valores no vacíos añaden automáticamente 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 del plugin

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

Decorador	Se activa cuando
@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.
Controlador	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.

Debes llamar a plugin.run() al final de __main__.py. Sin ello, el proceso termina antes de que el SDK se conecte al runner.

Acerca de YourBot

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

comandos	Qué hace esto
yourbot new <id>	mmo new mi-plugin crea un proyecto inicial con manifiesto, pruebas y un handler !ping funcional. Cuatro plantillas: 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.