Discord

Die Discord-Integration verbindet deinen Discord-Server mit Almirant, damit du Agent-Befehle ausführen, Benachrichtigungen zu Projekt-Ereignissen erhalten und Arbeitssitzungen direkt im Chat steuern kannst.

So funktioniert es

Almirant integriert sich über einen Bot mit Discord, der OAuth2 zur Verbindung mit deinem Server verwendet. Der Bot kann:

• Slash-Befehle ausführen -- Befehle wie /implement und /plan, um Agent-Aufgaben über Discord zu starten.
• Benachrichtigungen senden -- Almirant benachrichtigt über Discord über relevante Ereignisse (Work Items, Sprints, PRs, CI/CD).
• Sitzungen steuern -- Interaktive Schaltflächen zum Anhalten, Pausieren oder Beantworten von Agent-Fragen.
• Automatische Threads erstellen -- Jede Agent-Aufgabe erstellt einen eigenen Thread, um ihren Fortschritt zu verfolgen.

Die Discord-Integration einrichten

1. Über OAuth verbinden

Anders als andere Bots verwendet Discord OAuth2 für eine sichere Verbindung:

1. Gehe zu Einstellungen > Integrationen > Discord.
2. Klicke auf Discord verbinden.
3. Discord fordert dich auf, einen Server auszuwählen, für den du Administratorberechtigungen hast.
4. Autorisiere die angeforderten Berechtigungen (Nachrichten senden, Threads erstellen, Slash-Befehle verwenden).
5. Almirant registriert die Slash-Befehle automatisch auf deinem Server.

2. Standardkanal konfigurieren

Nach dem Herstellen der Verbindung:

1. Gehe zu Einstellungen > Integrationen > Discord.
2. Wähle den Standardkanal aus, in dem der Bot Benachrichtigungen sendet.
3. Speichere die Konfiguration.

3. Verbindung überprüfen

1. Klicke in der Discord-Konfiguration auf Testnachricht senden.
2. Prüfe, ob die Nachricht im ausgewählten Kanal erscheint.

Slash-Befehle

Der Discord-Bot unterstützt Slash-Befehle für die Interaktion mit Almirant:

Befehl	Beschreibung
/implement [work_item_id]	Startet eine Implementierungsaufgabe für das angegebene Work Item
/plan [work_item_id]	Startet eine Planungsaufgabe für das angegebene Work Item
/status	Zeigt die aktiven Aufgaben an (queued, running, waiting_for_input)
/status [job_id]	Zeigt den detaillierten Status einer bestimmten Aufgabe an

Befehlsoptionen

Die Befehle /implement und /plan akzeptieren zusätzliche Optionen:

Option	Beschreibung
work_item_id	(Erforderlich) Die ID des Work Items (z. B. A-123)
provider	(Optional) Der Agent-Anbieter: claude-code, codex oder zipu

Anwendungsbeispiel

/implement work_item_id:A-1189
/implement work_item_id:A-1189 provider:claude-code
/plan work_item_id:A-1190
/status job_id:abc123-def456

Automatische Threads

Wenn du einen Slash-Befehl ausführst, erstellt der Bot automatisch einen privaten Thread für diese Aufgabe:

• Der Name des Threads gibt den Aufgabentyp und die Task-ID an.
• Alle Fortschrittsnachrichten des Agenten werden im Thread gesendet.
• Die Steuerungsschaltflächen (Stopp, Herunterfahren) erscheinen im Thread.
• Der Thread wird nach 24 Stunden Inaktivität automatisch archiviert.

Interaktive Schaltflächen

Während der Ausführung einer Aufgabe zeigt der Bot Schaltflächen zur Steuerung der Sitzung an:

Schaltfläche	Aktion
Stopp	Hält die aktuelle Aufgabe an, bewahrt aber den Status
Herunterfahren	Hält die Aufgabe vollständig an und schließt die Sitzung

Wenn der Agent eine Frage hat, werden Optionen als Schaltflächen oder Auswahlmenü angezeigt. Wähle die gewünschte Option aus, um zu antworten.

Benachrichtigungen

Konfiguriere, welche Projekt-Ereignisse du als Benachrichtigungen in Discord erhalten möchtest:

Ereignis	Beschreibung
Work Item erstellt	Ein neues Work Item wird erstellt
Work Item verschoben	Ein Work Item wechselt die Spalte im Board
Work Item zugewiesen	Ein Work Item wird jemandem zugewiesen
Work Item abgeschlossen	Ein Work Item wird als abgeschlossen markiert
Sprint gestartet/geschlossen	Ein Sprint beginnt oder endet
Meilenstein abgeschlossen	Ein Meilenstein wird abgeschlossen
PR geöffnet/gemergt	Ein Pull Request wird geöffnet oder gemergt
CI fehlgeschlagen	Ein CI-Build schlägt fehl
Agent-Aufgabe abgeschlossen/fehlgeschlagen	Eine Agent-Aufgabe endet

So konfigurierst du Benachrichtigungen:

1. Gehe zu Einstellungen > Integrationen > Discord.
2. Klicke auf Benachrichtigungen konfigurieren.
3. Aktiviere oder deaktiviere die gewünschten Ereignisse.
4. Speichere die Änderungen.

Projekte mit Kanälen verknüpfen

Du kannst für verschiedene Projekte spezifische Kanäle konfigurieren:

1. Gehe zu den Einstellungen des Projekts.
2. Wähle im Abschnitt Discord den Zielkanal aus.
3. Benachrichtigungen und Threads dieses Projekts werden an den konfigurierten Kanal gesendet.

Wenn kein spezifischer Kanal vorhanden ist, wird der Standardkanal der Organisation verwendet.

Discord trennen

So trennst du den Bot:

1. Gehe zu Einstellungen > Integrationen > Discord.
2. Klicke auf Trennen.
3. Bestätige die Trennung.

Warnung

Das Trennen des Bots beendet die Slash-Befehle und Benachrichtigungen über Discord. Laufende Aufgaben werden nicht automatisch abgebrochen.

Für Entwickler

Architektur der Integration

Die Discord-Integration besteht aus zwei Hauptrouten:

• OAuth-Routen (/api/integrations/discord): Verwaltet den OAuth2-Ablauf, die Verbindungsverwaltung, Kanäle und Benachrichtigungseinstellungen.
• Interaktions-Webhook (/webhooks/discord/interactions): Empfängt und verarbeitet Slash-Befehle, Schaltflächen und Auswahlmenüs.

OAuth-Ablauf

Usuario --> GET /authorize --> Discord OAuth --> GET /callback
                                                      |
                                    +------------ Token exchange
                                    |
                            Create connection + Register slash commands

Interaktionsablauf

Discord --> POST /webhooks/discord/interactions --> Verify signature
                                                         |
                              +--------------------------+
                              |           |              |
                            PING     Command        Component
                              |           |              |
                           PONG    Queue job      Process action

Registrierte Slash-Befehle

Die Befehle werden während OAuth automatisch auf dem Server registriert:

• implement: Startet eine Implementierungsaufgabe
• plan: Startet eine Planungsaufgabe
• status: Ruft den Status von Aufgaben ab

Signaturprüfung

Alle Interaktionen werden mit Ed25519 und dem öffentlichen Schlüssel von Discord (DISCORD_PUBLIC_KEY) geprüft. Dadurch wird sichergestellt, dass die Anfragen von Discord stammen.

Umgebungsvariablen

Variable	Beschreibung
DISCORD_CLIENT_ID	ID der Discord-Anwendung
DISCORD_CLIENT_SECRET	Geheimnis der Anwendung
DISCORD_PUBLIC_KEY	Öffentlicher Schlüssel zur Prüfung von Signaturen
DISCORD_BOT_TOKEN	Bot-Token zum Senden von Nachrichten
DISCORD_APPLICATION_ID	ID der Anwendung (für Slash-Befehle)
DISCORD_OAUTH_REDIRECT_URI	OAuth-Callback-URI