Configurando sesiones de ámbito de guild en canales de Discord - Implementing Guild-Scoped Sessions for Discord Channels

Comportamiento actual: Aislamiento de canales

Con la configuración predeterminada, cada canal de Discord opera con una sesión completamente aislada. Los usuarios observan los siguientes síntomas:

Pérdida de contexto al cambiar de canal

// Usuario en #general
User: "Oye, ¿puedes ayudarme a configurar el pipeline de CI?"
Bot:  "¡Claro! Te ayudaré a configurar el pipeline de CI. Necesitarás..."

// Usuario se muda inmediatamente a #requests
User: "¿Cuál es el estado de mi configuración del pipeline de CI?"
Bot:  "No tengo ningún registro de haber discutido sobre la configuración del pipeline de CI. ¿Podrías proporcionar más contexto?"

Evidencia de aislamiento de claves de sesión

# Claves de sesión activas en Redis/Memory
agent:abc123:discord:channel:1000000001  // #general
agent:abc123:discord:channel:1000000002  // #requests
agent:abc123:discord:channel:1000000003  // #logs
// Cada canal tiene contexto independiente - sin contaminación cruzada

Fallo en la comunicación entre bots

// #requests bot recibe la solicitud
[requests-bot]: "Creando issue para la configuración del pipeline de CI..."
[requests-bot]: "@general-bot ¿Puedes confirmar el nivel de acceso del usuario?"

// #general bot responde
[general-bot]: "No veo ninguna discusión reciente relacionada con CI en este canal."

Los flujos de trabajo de múltiples canales de larga duración requieren repetición

• Los usuarios deben reiterar el contexto al moverse entre los canales del flujo de trabajo
• Las menciones de bots en diferentes canales no proporcionan conocimiento de menciones previas
• Las continuaciones de hilos pierden el contexto del canal padre
• Las escrituras de archivos de memoria se convierten en una solución manual en lugar de un comportamiento automático

Análisis de arquitectura

El aislamiento de sesión ocurre en la capa de generación de claves de sesión. La implementación actual construye identificadores de sesión usando una jerarquía estricta:

// Construcción actual de clave de sesión (pseudocódigo simplificado)
function buildDiscordSessionKey(agentId, guildId, channelId, threadId) {
    if (threadId) {
        return `agent:${agentId}:discord:thread:${threadId}`;
    }
    return `agent:${agentId}:discord:channel:${channelId}`;
}

Por qué existe este diseño

1. Aislamiento de seguridad: Los permisos a nivel de canal se aplican a través de contextos de sesión separados
2. Filtrado de mensajes: Solo los mensajes del canal actual se incluyen en el contexto
3. Comportamiento histórico: La implementación original de Discord asumía uso de bot de propósito único
4. Eficiencia de almacenamiento: Menor huella de memoria por sesión

La brecha en el flujo de trabajo multicanal

La arquitectura no contempla los servidores diseñados alrededor de flujos de trabajo colaborativos:

// Estructura típica de servidor multicanal
MiServidor/
├── #welcome          // Incorporación, reglas
├── #general          // Chat casual, preguntas rápidas
├── #requests         // Envíos de tareas, solicitudes formales
├── #code-review      // Discusiones de PR
├── #logs             // Salidas automatizadas, notificaciones
└── #devops           // Discusiones de infraestructura

// Trayecto del usuario que falla con el aislamiento de canales:
1. Discutir arquitectura en #devops
2. Crear solicitud formal en #requests (referencia la discusión de #devops)
3. El bot procesa la solicitud sin contexto de #devops
4. Usuario frustrado: "¡Acabo de explicar esto hace 5 minutos!"

Brecha de configuración

El esquema de configuración actual carece de un mecanismo para definir los límites de sesión:

// Estructura de configuración actual - NO existe opción sessionScope
{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "requireMention": true,
          "threadBindings": { "enabled": true },
          // La opción sessionScope NO existe
        }
      }
    }
  }
}

Los archivos de memoria como solución inadecuada

Los usuarios recurren a los archivos de memoria, pero esto crea problemas adicionales:

Fase 1: Actualización de configuración

Paso 1: Localizar o crear el archivo de configuración del servidor

# Ubicaciones típicas
config/channels/discord/guilds/{guildId}.json
config/discord/guilds/{guildId}.yaml
.env (para sobrescrituras de variables de entorno)

Paso 2: Agregar sessionScope a la configuración del servidor

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

Paso 3: Verificar que el alcance de sesión sea reconocido (verificación previa)

# Verificar que la configuración se cargue correctamente
node -e "
const config = require('./config/channels/discord/guilds/1234567890.json');
console.log('sessionScope:', config.sessionScope);
console.log('Valores válidos:', ['channel', 'guild']);
console.log('¿Es válido?:', ['channel', 'guild'].includes(config.sessionScope));
"

Fase 2: Migración de claves de sesión (si se actualiza)

Paso 4: Migrar sesiones de canal existentes al alcance de servidor

# Respaldar sesiones existentes antes de la migración
redis-cli KEYS "agent:*:discord:channel:*" > channel_sessions_backup.txt

# O para almacenamiento basado en archivos
cp -r sessions/ sessions_backup/

# Comando de migración (si la herramienta CLI está disponible)
openclaw session migrate --guild 1234567890 --from channel --to guild

# Ejemplo de script de migración manual
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) {
            // Fusionar en sesión de servidor
            await redis.append(guildKey, '\n' + data);
            await redis.del(key);
            migratedCount++;
        }
    }
    console.log(`Migradas ${migratedCount} sesiones de canal al alcance de servidor`);
}

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

Fase 3: Anulaciones específicas por canal

Paso 5: Preservar comportamientos específicos de canal con anulaciones

{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "sessionScope": "guild",
          "requireMention": false,
          "threadBindings": {
            "enabled": true
          },
          // Anulaciones por canal
          "channels": {
            "1000000001": {
              // #general - reglas relajadas
              "requireMention": false
            },
            "1000000002": {
              // #requests - requisito de mención estricto
              "requireMention": true
            },
            "1000000003": {
              // #logs - solo lectura, no se necesitan respuestas
              "requireMention": false,
              "sessionScope": "channel"
            }
          }
        }
      }
    }
  }
}

Fase 4: Configuración de compactación

Paso 6: Configurar compactación agresiva para sesiones de alcance de servidor

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

Verificación 1: Estructura de clave de sesión

# Verificar que las claves de sesión ahora usen alcance de servidor
redis-cli KEYS "agent:*:discord:guild:*"

# Salida esperada (debe mostrar claves de alcance de servidor, no de canal)
agent:abc123:discord:guild:1234567890
agent:abc123:discord:guild:9876543210

# Confirmar que las claves de canal NO están presentes para el servidor configurado
redis-cli KEYS "agent:abc123:discord:channel:*"
# Debe devolver: (lista vacía o solo canales no relacionados)

Verificación 2: Persistencia de contexto entre canales

# Paso 1: Enviar mensaje en #general
curl -X POST http://localhost:3000/api/test/simulate-message \
  -H "Content-Type: application/json" \
  -d '{
    "guildId": "1234567890",
    "channelId": "1000000001",
    "userId": "1111111111",
    "content": "Necesito configurar la conexión a la base de datos de producción"
  }'

# Paso 2: Verificar que la sesión contenga este mensaje
redis-cli GET "agent:abc123:discord:guild:1234567890" | grep -i "base de datos"

# Paso 3: Enviar mensaje en #requests (canal diferente)
curl -X POST http://localhost:3000/api/test/simulate-message \
  -H "Content-Type: application/json" \
  -d '{
    "guildId": "1234567890",
    "channelId": "1000000002",
    "userId": "1111111111",
    "content": "¿Cuál es el estado de mi configuración de base de datos?"
  }'

# Paso 4: El bot debe responder CON contexto de #general
# Verificar que la respuesta del bot incluya referencia a la conversación de base de datos
# Esperado: La respuesta menciona la conversación "base de datos de producción" de #general

Verificación 3: Las anulaciones específicas por canal aún funcionan

# Probar requisito de mención en #requests (configurado como requireMention: true)
# Enviar DM (sin mención) a #requests
curl -X POST http://localhost:3000/api/test/simulate-message \
  -d '{"guildId": "1234567890", "channelId": "1000000002", "content": "¿Estado?"}'

# Esperado: El bot NO responde (se requiere mención)
# O
# Enviar con mención
curl -X POST http://localhost:3000/api/test/simulate-message \
  -d '{"guildId": "1234567890", "channelId": "1000000002", "content": "@Bot ¿Estado?"}'

# Esperado: El bot SÍ responde

Verificación 4: Independencia de enlaces de hilos

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

# Verificar que el hilo tiene su propia clave de sesión (independiente del alcance de servidor)
redis-cli KEYS "agent:*:discord:thread:*"
# Esperado: Las sesiones de hilo permanecen separadas de la sesión del servidor

Verificación 5: Compactación activada apropiadamente

# Habilitar logging de depuración
DEBUG=openclaw:session:compaction node index.js

# Generar suficientes mensajes para activar la compactación
# (Establecer maxMessages en un número bajo como 10 para pruebas)

# Monitorear logs para eventos de compactación
# Entradas de log esperadas:
# [DEBUG] openclaw:session:compaction - Compactando sesión del servidor (1234567890)
# [DEBUG] openclaw:session:compaction - Conservados 10 mensajes recientes
# [DEBUG] openclaw:session:compaction - Resumen generado

Prueba de integración automatizada

# Ejecutar las pruebas de integración de alcance de sesión
npm test -- --grep "guild-scoped-session"

# Resultados de prueba esperados:
# ✓ Clave de sesión de servidor generada correctamente
# ✓ Contexto entre canales preservado
# ✓ Anulaciones específicas de canal respetadas
# ✓ Enlaces de hilos permanecen independientes
# ✓ Compactación se activa en el umbral
# ✓ Migración de sesión preserva el historial

Errores relacionados con sesiones

Errores de configuración

Errores de memoria/almacenamiento

Issues de GitHub relacionados

• #847: "Los archivos de memoria no persisten entre reinicios del bot" - Limitaciones de la solución de archivos de memoria
• #1203: "Contexto entre canales para flujos de trabajo multicanal" - Solicitud de característica original (reemplazada por esta implementación)
• #1562: "La compactación de sesión causa pérdida de contexto" - Problemas de configuración de compactación
• #1891: "Los enlaces de hilos ignoran el alcance de sesión del servidor" - Independencia de hilos del alcance de sesión
• #2104: "Las sesiones de alcance de servidor causan filtraciones de privacidad" - Solicitudes de implementación de zonas de privacidad
• #2233: "Degradación de rendimiento con servidores grandes" - Optimización de memoria y rendimiento

Opciones de configuración relacionadas

# Estas opciones interactúan con el comportamiento de sessionScope:
sessionScope              // Configuración primaria (channel | guild)
threadBindings.enabled    // Debe permanecer independiente del alcance de sesión
compaction.*              // Debe ajustarse para sesiones de alcance de servidor
privacyZones              // Opción propuesta para excluir canales
messageWindow             // Limita los mensajes extraídos del contexto de sesión