Créer un plugin

Les plugins sont des processus Python isolés. Écrivez un gestionnaire, déclarez vos capacités, envoyez un zip — nous l'exécutons dans un conteneur Docker verrouillé et lui transmettons les événements Discord via JSON-RPC.

Démarrage rapide

Cinq minutes pour un plugin fonctionnel :

Bonjour, plugin

Ce fichier entier est un plugin fonctionnel. Placez-le dans un dossier avec un manifest.json et expédiez-le :

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.

Structure des fichiers d'un plugin

Un plugin est un zip avec cette organisation :

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"
  ]
}

Champs optionnels :

Champ	Objectif
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	Commandes slash Discord que la plateforme doit enregistrer en votre nom. Voir Commandes slash. Déclarer ceci ajoute automatiquement interaction:respond à capabilities_required.
proxy_domains_requested	Liste d'autorisation des noms d'hôte que vous récupérerez via ctx.http.*. Le pipeline d'envoi détecte automatiquement les domaines à partir des URL littérales "https://…" dans votre source ; ce champ est votre vérification finale. Les valeurs non vides ajoutent automatiquement proxy:http à capabilities_required.

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

Cycle de vie du plugin

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

Décorateur	Se déclenche quand
@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.
Gestionnaire	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.

Vous devez appeler plugin.run() en bas de __main__.py. Sans cela, le processus se termine avant que le SDK se connecte au runner.

À propos de YourBot

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

commandes	Ce que cela fait
yourbot new <id>	mmo new mon-plugin crée un projet de démarrage avec manifest, tests et un gestionnaire !ping fonctionnel. Quatre modèles : 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.