Implementierung von Gilden-Sitzungen für Discord-Kanäle - Implementing Guild-Scoped Sessions for Discord Channels

Aktuelles Verhalten: Kanalisolierung

Mit der Standardkonfiguration arbeitet jeder Discord-Kanal mit einer vollständig isolierten Sitzung. Benutzer beobachten die folgenden Symptome:

Kontextverlust beim Kanalwechsel

// Benutzer in #general
User: "Hey, kannst du mir helfen, die CI-Pipeline einzurichten?"
Bot:  "Klar! Ich helfe dir bei der Konfiguration der CI-Pipeline. Du wirst..."

// Benutzer wechselt sofort zu #requests
User: "Wie sieht es mit dem Status meiner CI-Pipeline-Einrichtung aus?"
Bot:  "Ich habe keinen Eintrag über eine CI-Pipeline-Einrichtung. Könntest du mehr Kontext geben?"

Beweis für Sitzungsschlüssel-Isolation

# Aktive Sitzungsschlüssel in Redis/Memory
agent:abc123:discord:channel:1000000001  // #general
agent:abc123:discord:channel:1000000002  // #requests
agent:abc123:discord:channel:1000000003  // #logs
// Jeder Kanal hat unabhängigen Kontext - keine Kreuzbestäubung

Kommunikationsausfall zwischen Bots

// #requests Bot empfängt Anfrage
[requests-bot]: "Erstelle Issue für CI-Pipeline-Einrichtung..."
[requests-bot]: "@general-bot Kannst du die Zugriffsebene des Benutzers bestätigen?"

// #general Bot antwortet
[general-bot]: "Ich sehe keine aktuelle CI-bezogene Diskussion in diesem Kanal."

Langwierige Multi-Kanal-Workflows erfordern Wiederholungen

• Benutzer müssen Kontext beim Wechseln zwischen Workflow-Kanälen erneut angeben
• Bot-Erwähnungen in verschiedenen Kanälen bieten keine Wahrnehmung früherer Erwähnungen
• Thread-Fortsetzungen verlieren den übergeordneten Kanal-Kontext
• Speicherdatei-Schreibvorgänge werden zur manuellen Problemumgehung statt zum automatischen Verhalten

Architekturanalyse

Die Sitzungsisolierung erfolgt auf der Ebene der Sitzungsschlüsselgenerierung. Die aktuelle Implementierung konstruiert Sitzungskennungen mit einer strikten Hierarchie:

// Aktuelle Sitzungsschlüsselkonstruktion (vereinfachter Pseudocode)
function buildDiscordSessionKey(agentId, guildId, channelId, threadId) {
    if (threadId) {
        return `agent:${agentId}:discord:thread:${threadId}`;
    }
    return `agent:${agentId}:discord:channel:${channelId}`;
}

Warum dieses Design existiert

1. Sicherheitsisolierung: Kanalbasierte Berechtigungen werden durch separate Sitzungskontexte durchgesetzt
2. Nachrichtenfilterung: Nur Nachrichten aus dem aktuellen Kanal werden in den Kontext einbezogen
3. Historisches Verhalten: Ursprüngliche Discord-Implementierung ging von Einzweck-Bot-Nutzung aus
4. Speichereffizienz: Geringerer Speicherbedarf pro Sitzung

Die Multi-Kanal-Workflow-Lücke

Die Architektur berücksichtigt keine Gilden, die für kollaborative Workflows konzipiert wurden:

// Typische Multi-Kanal-Gildenstruktur
MyGuild/
├── #welcome          // Onboarding, Regeln
├── #general          // Gelegentlicher Chat, schnelle Fragen
├── #requests         // Aufgabeneinreichungen, formale Anfragen
├── #code-review      // PR-Diskussionen
├── #logs             // Automatisierte Ausgaben, Benachrichtigungen
└── #devops           // Infrastrukturdiskussionen

// Benutzerreise, die bei Kanalisolierung unterbrochen wird:
1. Architektur in #devops besprechen
2. Formale Anfrage in #requests erstellen (referenziert #devops-Diskussion)
3. Bot verarbeitet Anfrage ohne #devops-Kontext
4. Benutzer frustriert: "Ich habe das gerade vor 5 Minuten erklärt!"

Konfigurationslücke

Das aktuelle Konfigurationsschema bietet keinen Mechanismus zur Begrenzung von Sitzungsgrenzen:

// Aktuelle Konfigurationsstruktur - KEINE sessionScope-Option
{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "requireMention": true,
          "threadBindings": { "enabled": true },
          // sessionScope-Option existiert NICHT
        }
      }
    }
  }
}

Speicherdateien als unzureichende Problemumgehung

Benutzer greifen auf Speicherdateien zurück, aber dies schafft zusätzliche Probleme:

Phase 1: Konfigurationsaktualisierung

Schritt 1: Konfigurationsdatei der Gilde finden oder erstellen

# Typische Speicherorte
config/channels/discord/guilds/{guildId}.json
config/discord/guilds/{guildId}.yaml
.env (für Umgebungsvariablen-Überschreibungen)

Schritt 2: sessionScope zur Gildenkonfiguration hinzufügen

{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "sessionScope": "guild",
          "requireMention": true,
          "threadBindings": {
            "enabled": true
          }
        }
      }
    }
  }
}

Schritt 3: Sitzungsumfang überprüfen (Vorflugprüfung)

# Überprüfen, ob Konfiguration korrekt geladen wurde
node -e "
const config = require('./config/channels/discord/guilds/1234567890.json');
console.log('sessionScope:', config.sessionScope);
console.log('Gültige Werte:', ['channel', 'guild']);
console.log('Ist gültig:', ['channel', 'guild'].includes(config.sessionScope));
"

Phase 2: Sitzungsschlüssel-Migration (bei Upgrade)

Schritt 4: Bestehende Kanalsitzungen auf Gildenbereich migrieren

# Bestehende Sitzungen vor der Migration sichern
redis-cli KEYS "agent:*:discord:channel:*" > channel_sessions_backup.txt

# Oder für dateibasierten Speicher
cp -r sessions/ sessions_backup/

# Migrationsbefehl (falls CLI-Tool verfügbar)
openclaw session migrate --guild 1234567890 --from channel --to guild

# Manuelles Migrationsskript-Beispiel
node << 'EOF'
const { Redis } = require('ioredis');
const redis = new Redis();

async function migrateToGuildScope(guildId, agentId) {
    const channelKeys = await redis.keys(`agent:${agentId}:discord:channel:*`);
    const guildKey = `agent:${agentId}:discord:guild:${guildId}`;
    
    let migratedCount = 0;
    for (const key of channelKeys) {
        const data = await redis.get(key);
        if (data) {
            // In Gildensitzung zusammenführen
            await redis.append(guildKey, '\n' + data);
            await redis.del(key);
            migratedCount++;
        }
    }
    console.log(`Migrated ${migratedCount} channel sessions to guild scope`);
}

migrateToGuildScope('1234567890', 'your-agent-id');
EOF

Phase 3: Kanal-spezifische Überschreibungen

Schritt 5: Kanal-spezifisches Verhalten mit Überschreibungen beibehalten

{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "sessionScope": "guild",
          "requireMention": false,
          "threadBindings": {
            "enabled": true
          },
          // Kanalspezifische Überschreibungen
          "channels": {
            "1000000001": {
              // #general - entspannte Regeln
              "requireMention": false
            },
            "1000000002": {
              // #requests - strenge Erwähnungsanforderung
              "requireMention": true
            },
            "1000000003": {
              // #logs - Nur-Lesen, keine Antworten nötig
              "requireMention": false,
              "sessionScope": "channel"
            }
          }
        }
      }
    }
  }
}

Phase 4: Komprimierungskonfiguration

Schritt 6: Aggressive Komprimierung für Gildenbereich-Sitzungen konfigurieren

{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "sessionScope": "guild",
          "compaction": {
            "strategy": "aggressive",
            "maxMessages": 100,
            "maxAgeMinutes": 60,
            "summarizeThreshold": 50,
            "preserveRecent": 10
          }
        }
      }
    }
  }
}

Verifizierung 1: Sitzungsschlüsselstruktur

# Überprüfen, dass Sitzungsschlüssel jetzt Gildenbereich verwenden
redis-cli KEYS "agent:*:discord:guild:*"

# Erwartete Ausgabe (sollte Gildenbereich-Schlüssel zeigen, keine Kanalbereich)
agent:abc123:discord:guild:1234567890
agent:abc123:discord:guild:9876543210

# Bestätigen, dass Kanalschlüssel für die konfigurierte Gilde NICHT vorhanden sind
redis-cli KEYS "agent:abc123:discord:channel:*"
# Sollte zurückgeben: (leere Liste oder nur nicht verwandte Kanäle)

Verifizierung 2: Persistenz des kanalübergreifenden Kontexts

# Schritt 1: Nachricht in #general senden
curl -X POST http://localhost:3000/api/test/simulate-message \
  -H "Content-Type: application/json" \
  -d '{
    "guildId": "1234567890",
    "channelId": "1000000001",
    "userId": "1111111111",
    "content": "Ich muss die Produktionsdatenbankverbindung einrichten"
  }'

# Schritt 2: Überprüfen, dass Sitzung diese Nachricht enthält
redis-cli GET "agent:abc123:discord:guild:1234567890" | grep -i "datenbank"

# Schritt 3: Nachricht in #requests senden (anderer Kanal)
curl -X POST http://localhost:3000/api/test/simulate-message \
  -H "Content-Type: application/json" \
  -d '{
    "guildId": "1234567890",
    "channelId": "1000000002",
    "userId": "1111111111",
    "content": "Wie sieht der Status meiner Datenbankeinrichtung aus?"
  }'

# Schritt 4: Bot sollte MIT Kontext aus #general antworten
# Bot-Antwort auf Kontext aus #general überprüfen
# Erwartet: Antwort erwähnt "Produktionsdatenbank"-Konversation aus #general

Verifizierung 3: Kanal-spezifische Überschreibungen funktionieren noch

# Erwähnungsanforderung in #requests testen (konfiguriert als requireMention: true)
# DM senden (ohne Erwähnung) an #requests
curl -X POST http://localhost:3000/api/test/simulate-message \
  -d '{"guildId": "1234567890", "channelId": "1000000002", "content": "Status?"}'

# Erwartet: Bot antwortet NICHT (Erwähnung erforderlich)
# ODER
# Mit Erwähnung senden
curl -X POST http://localhost:3000/api/test/simulate-message \
  -d '{"guildId": "1234567890", "channelId": "1000000002", "content": "@Bot Status?"}'

# Erwartet: Bot antwortet DOCH

Verifizierung 4: Unabhängigkeit der Thread-Bindings

# Thread in #requests erstellen
curl -X POST http://localhost:3000/api/test/create-thread \
  -d '{"guildId": "1234567890", "channelId": "1000000002", "parentMessageId": "xxx"}'

# Überprüfen, dass Thread seinen eigenen Sitzungsschlüssel hat (unabhängig vom Gildenbereich)
redis-cli KEYS "agent:*:discord:thread:*"
# Erwartet: Thread-Sitzungen bleiben getrennt von Gildensitzung

Verifizierung 5: Komprimierung wird angemessen ausgelöst

# Debug-Logging aktivieren
DEBUG=openclaw:session:compaction node index.js

# Genügend Nachrichten generieren, um Komprimierung auszulösen
# (maxMessages für Tests auf niedrigen Wert wie 10 setzen)

# Logs auf Komprimierungsereignisse überwachen
# Erwartete Logeinträge:
# [DEBUG] openclaw:session:compaction - Komprimiere Gildensitzung (1234567890)
# [DEBUG] openclaw:session:compaction - 10 aktuelle Nachrichten beibehalten
# [DEBUG] openclaw:session:compaction - Zusammenfassung generiert

Automatisierter Integrationstest

# Die Sitzungsbereich-Integrationstests ausführen
npm test -- --grep "guild-scoped-session"

# Erwartete Testergebnisse:
# ✓ Gildensitzungsschlüssel korrekt generiert
# ✓ Kanalübergreifender Kontext beibehalten
# ✓ Kanalspezifische Überschreibungen respektiert
# ✓ Thread-Bindings bleiben unabhängig
# ✓ Komprimierung wird bei Schwellenwert ausgelöst
# ✓ Sitzungsmigration bewahrt Verlauf

Sitzungsbezogene Fehler

Konfigurationsfehler

Speicher-/Speicherfehler

Zugehörige GitHub-Issues

• #847: "Memory files not persisting across bot restarts" - Einschränkungen der Speicherdatei-Problemumgehung
• #1203: "Cross-channel context for multi-channel workflows" - Ursprüngliche Feature-Anfrage (durch diese Implementierung ersetzt)
• #1562: "Session compaction causing context loss" - Komprimierungskonfigurationsprobleme
• #1891: "Thread bindings ignore guild session scope" - Thread-Unabhängigkeit vom Sitzungsbereich
• #2104: "Guild-scoped sessions cause privacy leaks" - Anfragen zur Implementierung von Datenschutzbereichen
• #2233: "Performance degradation with large guilds" - Speicher- und Leistungsoptimierung

Zugehörige Konfigurationsoptionen

# Diese Optionen interagieren mit sessionScope-Verhalten:
sessionScope              // Primäre Konfiguration (channel | guild)
threadBindings.enabled    // Sollte unabhängig vom Sitzungsbereich bleiben
compaction.*              // Muss für Gildenbereich-Sitzungen angepasst werden
privacyZones              // Vorgeschlagene Option zum Ausschließen von Kanälen
messageWindow             // Beschränkt Nachrichten aus Sitzungskontext