[为Discord频道配置公会作用域会话] - Implementing Guild-Scoped Sessions for Discord Channels

当前行为：频道隔离

使用默认配置时，每个 Discord 频道都在完全独立的会话中运行。用户会观察到以下症状：

切换频道时上下文丢失

// User in #general
User: "Hey, can you help me set up the CI pipeline?"
Bot:  "Sure! I'll help you configure the CI pipeline. You'll need..."

// User immediately moves to #requests
User: "What's the status of my CI pipeline setup?"
Bot:  "I don't have any record of discussing a CI pipeline setup. Could you provide more context?"

会话密钥隔离证据

# Active session keys in Redis/Memory
agent:abc123:discord:channel:1000000001  // #general
agent:abc123:discord:channel:1000000002  // #requests
agent:abc123:discord:channel:1000000003  // #logs
// Each channel has independent context - no cross-pollination

机器人间通信中断

// #requests bot receives request
[requests-bot]: "Creating issue for CI pipeline setup..."
[requests-bot]: "@general-bot Can you confirm the user's access level?"

// #general bot responds
[general-bot]: "I don't see any recent CI-related discussion in this channel."

长时间运行的多频道工作流需要重复操作

• 用户在工作流频道之间切换时必须重新说明上下文
• 不同频道中的机器人提及不会产生任何先前提及的意识
• 线程延续会丢失父频道的上下文
• 内存文件写入成为手动变通方案而非自动行为

架构分析

会话隔离发生在会话密钥生成层。当前的实现使用严格层级结构构建会话标识符：

// Current session key construction (simplified pseudocode)
function buildDiscordSessionKey(agentId, guildId, channelId, threadId) {
    if (threadId) {
        return `agent:${agentId}:discord:thread:${threadId}`;
    }
    return `agent:${agentId}:discord:channel:${channelId}`;
}

为什么存在此设计

1. 安全隔离：通过独立的会话上下文强制执行频道级权限
2. 消息过滤：仅将当前频道的消息包含在上下文中
3. 历史行为：原始 Discord 实现假定为单用途机器人使用
4. 存储效率：每个会话的内存占用更小

多频道工作流差距

该架构未能考虑到围绕协作工作流设计的服务器：

// Typical multi-channel guild structure
MyGuild/
├── #welcome          // Onboarding, rules
├── #general          // Casual chat, quick questions
├── #requests         // Task submissions, formal requests
├── #code-review      // PR discussions
├── #logs             // Automated outputs, notifications
└── #devops           // Infrastructure discussions

// User journey that breaks with channel isolation:
1. Discuss architecture in #devops
2. Create formal request in #requests (references #devops discussion)
3. Bot processes request without #devops context
4. User frustrated: "I just explained this 5 minutes ago!"

配置缺口

当前配置架构缺少限制会话边界的机制：

// Current config structure - NO sessionScope option
{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "requireMention": true,
          "threadBindings": { "enabled": true },
          // sessionScope option does NOT exist
        }
      }
    }
  }
}

内存文件作为不充分的临时解决方案

用户依赖内存文件，但这会产生额外问题：

第一阶段：配置更新

步骤 1：定位或创建服务器配置文件

# Typical locations
config/channels/discord/guilds/{guildId}.json
config/discord/guilds/{guildId}.yaml
.env (for environment variable overrides)

步骤 2：在服务器配置中添加 sessionScope

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

步骤 3：验证会话范围是否被识别（预检查）

# Check if configuration is loaded correctly
node -e "
const config = require('./config/channels/discord/guilds/1234567890.json');
console.log('sessionScope:', config.sessionScope);
console.log('Valid values:', ['channel', 'guild']);
console.log('Is valid:', ['channel', 'guild'].includes(config.sessionScope));
"

第二阶段：会话密钥迁移（如果是升级）

步骤 4：将现有频道会话迁移到服务器范围

# Backup existing sessions before migration
redis-cli KEYS "agent:*:discord:channel:*" > channel_sessions_backup.txt

# Or for file-based storage
cp -r sessions/ sessions_backup/

# Migrate command (if CLI tool available)
openclaw session migrate --guild 1234567890 --from channel --to guild

# Manual migration script example
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) {
            // Merge into guild session
            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

第三阶段：频道特定覆盖

步骤 5：使用覆盖保留频道特定行为

{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "sessionScope": "guild",
          "requireMention": false,
          "threadBindings": {
            "enabled": true
          },
          // Per-channel overrides
          "channels": {
            "1000000001": {
              // #general - relaxed rules
              "requireMention": false
            },
            "1000000002": {
              // #requests - strict mention requirement
              "requireMention": true
            },
            "1000000003": {
              // #logs - read-only, no responses needed
              "requireMention": false,
              "sessionScope": "channel"
            }
          }
        }
      }
    }
  }
}

第四阶段：压缩配置

步骤 6：为服务器范围的会话配置主动压缩

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

验证 1：会话密钥结构**

# Check that session keys now use guild scope
redis-cli KEYS "agent:*:discord:guild:*"

# Expected output (should show guild-scoped keys, not channel-scoped)
agent:abc123:discord:guild:1234567890
agent:abc123:discord:guild:9876543210

# Confirm channel keys are NOT present for the configured guild
redis-cli KEYS "agent:abc123:discord:channel:*"
# Should return: (empty list or only unrelated channels)

验证 2：跨频道上下文持久性

# Step 1: Send message in #general
curl -X POST http://localhost:3000/api/test/simulate-message \
  -H "Content-Type: application/json" \
  -d '{
    "guildId": "1234567890",
    "channelId": "1000000001",
    "userId": "1111111111",
    "content": "I need to set up the production database connection"
  }'

# Step 2: Verify session contains this message
redis-cli GET "agent:abc123:discord:guild:1234567890" | grep -i "database"

# Step 3: Send message in #requests (different channel)
curl -X POST http://localhost:3000/api/test/simulate-message \
  -H "Content-Type: application/json" \
  -d '{
    "guildId": "1234567890",
    "channelId": "1000000002",
    "userId": "1111111111",
    "content": "What's the status of my database setup?"
  }'

# Step 4: Bot should respond WITH context from #general
# Check bot response includes reference to database conversation
# Expected: Response mentions "production database" conversation from #general

验证 3：频道特定覆盖仍然有效

# Test mention requirement in #requests (configured as requireMention: true)
# Send DM (no mention) to #requests
curl -X POST http://localhost:3000/api/test/simulate-message \
  -d '{"guildId": "1234567890", "channelId": "1000000002", "content": "Status?"}'

# Expected: Bot does NOT respond (mention required)
# OR
# Send with mention
curl -X POST http://localhost:3000/api/test/simulate-message \
  -d '{"guildId": "1234567890", "channelId": "1000000002", "content": "@Bot Status?"}'

# Expected: Bot DOES respond

验证 4：线程绑定独立性

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

# Verify thread has its own session key (independent of guild scope)
redis-cli KEYS "agent:*:discord:thread:*"
# Expected: Thread sessions remain separate from guild session

验证 5：压缩适当触发

# Enable debug logging
DEBUG=openclaw:session:compaction node index.js

# Generate enough messages to trigger compaction
# (Set maxMessages to a low number like 10 for testing)

# Monitor logs for compaction events
# Expected log entries:
# [DEBUG] openclaw:session:compaction - Compacting guild session (1234567890)
# [DEBUG] openclaw:session:compaction - Retained 10 recent messages
# [DEBUG] openclaw:session:compaction - Summary generated

自动化集成测试

# Run the session scope integration tests
npm test -- --grep "guild-scoped-session"

# Expected test results:
# ✓ Guild session key generated correctly
# ✓ Cross-channel context preserved
# ✓ Channel-specific overrides respected
# ✓ Thread bindings remain independent
# ✓ Compaction triggers at threshold
# ✓ Session migration preserves history

会话相关错误

配置错误

内存/存储错误

相关 GitHub 问题

• #847: "Memory files not persisting across bot restarts" - 内存文件临时解决方案的局限性
• #1203: "Cross-channel context for multi-channel workflows" - 原始功能请求（已被此实现取代）
• #1562: "Session compaction causing context loss" - 压缩配置问题
• #1891: "Thread bindings ignore guild session scope" - 线程与会话范围的独立性
• #2104: "Guild-scoped sessions cause privacy leaks" - 隐私区域实现请求
• #2233: "Performance degradation with large guilds" - 内存和性能优化

相关配置选项

# These options interact with sessionScope behavior:
sessionScope              // Primary configuration (channel | guild)
threadBindings.enabled    // Should remain independent of session scope
compaction.*              // Must be tuned for guild-scoped sessions
privacyZones              // Proposed option for excluding channels
messageWindow             // Limits messages pulled from session context