Erstelle ein Plugin

Plugins sind isolierte Python-Prozesse. Schreibe einen Handler, deklariere deine Fähigkeiten, lade ein Zip hoch — wir führen es in einem abgesicherten Docker-Container aus und übertragen Discord-Events per JSON-RPC.

Schnellstart

Fünf Minuten bis zu einem laufenden Plugin:

Hallo, Plugin

Diese gesamte Datei ist ein funktionsfähiges Plugin. Lege sie in einen Ordner mit einer manifest.json und veröffentliche es:

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.

Plugin-Dateistruktur

Ein Plugin ist ein Zip mit folgendem Aufbau:

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

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

Optionale Felder:

Feld	Zweck
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	Discord-Slash-Befehle, die die Plattform in deinem Namen registrieren soll. Siehe Slash-Befehle. Durch die Deklaration wird interaction:respond automatisch zu capabilities_required hinzugefügt.
proxy_domains_requested	Allow-Liste von Hostnamen, die du über ctx.http.* abrufen wirst. Die Upload-Pipeline erkennt Domains automatisch aus wörtlichen "https://…"-URLs in deinem Quellcode; dieses Feld dient deiner abschließenden Überprüfung. Nicht-leere Werte fügen proxy:http automatisch zu capabilities_required hinzu.

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

Plugin-Lebenszyklus

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

Dekorator	Wird ausgelöst, wenn
@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.

Du musst plugin.run() am Ende von __main__.py aufrufen. Ohne diesen Aufruf beendet sich der Prozess, bevor das SDK sich mit dem Runner verbindet.

Über YourBot

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

Befehle	Was dies bewirkt
yourbot new <id>	mmo new my-plugin erstellt ein Starterprojekt mit Manifest, Tests und einem funktionierenden !ping-Handler. Vier Vorlagen: 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.