┌─────────────┐
                    │   Hermes    │
                    │   Agent     │
                    │   Core      │◄─── 共享记忆系统
                    │             │◄─── 共享技能系统
                    └──────┬──────┘
                           │ 统一消息协议
              ┌────────────┼────────────┐
              │            │            │
         ┌────▼────┐  ┌────▼────┐  ┌───▼───┐
         │ Telegram│  │ Discord │  │ Slack │
         │ Adapter │  │ Adapter │  │Adapter│
         └────┬────┘  └────┬────┘  └───┬───┘
              │            │            │
         ┌────▼────┐  ┌────▼────┐  ┌───▼───┐
         │ Telegram│  │ Discord │  │ Slack │
         │ 用户 A  │  │ 用户 B  │  │ 用户 C │
         └─────────┘  └─────────┘  └────────┘

用户发送消息
     │
     ▼
平台适配器（Adapter）
     │ 将平台特有格式转换为统一消息格式
     ▼
消息路由层（Router）
     │ 识别用户、会话、意图
     ▼
Hermes Agent Core
     │ AI 推理 + 工具调用 + 记忆检索
     ▼
响应生成
     │
     ▼
平台适配器（Adapter）
     │ 将统一响应格式转换为平台原生格式
     ▼
用户收到回复

{
  "message_id": "msg_abc123",
  "chat_id": "chat_xyz789",
  "chat_type": "direct|group|channel",
  "platform": "telegram|discord|slack|...",
  "sender": {
    "id": "user_123",
    "username": "johndoe",
    "display_name": "John Doe",
    "is_bot": false
  },
  "content": {
    "text": "用户输入的文本",
    "raw": {},  // 平台原始数据
    "attachments": [],
    "mentions": []
  },
  "timestamp": 1715400000,
  "reply_to": "msg_original_id",
  "thread_id": "thread_abc",
  "metadata": {}
}

# 交互式配置
hermes gateway setup
# 选择 Telegram
# 输入 Bot Token
# 设置允许的用户白名单（可选）

# 或直接命令行配置
hermes config set gateway.telegram.token "YOUR_BOT_TOKEN"
hermes config set gateway.telegram.allowed_users "user_id_1,user_id_2"
hermes config set gateway.telegram.group_mode "relay"  # 群组模式: relay|agent|commands

# gateway.telegram.yaml 高级配置
telegram:
  bot:
    token: "${TELEGRAM_BOT_TOKEN}"
    
  # 消息过滤
  filters:
    # 允许的用户 ID 列表，留空则允许所有人
    allowed_users: []
    # 允许的群组 ID 列表
    allowed_chats: []
    # 是否只响应 / 命令
    commands_only: false
    
  # 群组设置
  group:
    # 响应模式
    mode: "relay"  # relay | agent | commands
    # 识别 Bot 的方式
    mention_patterns: ["@YourBotName", "yourbotname"]
    # 是否响应回复 Bot 消息的内容
    respond_to_replies: true
    # 消息前缀识别（如 "!"）
    command_prefix: []
    
  # 功能开关
  features:
    # 是否处理频道帖子
    channel_posts: false
    # 是否处理 inline query（@bot 查询）
    inline_queries: true
    # 语音消息自动转文字
    voice_to_text: true
    
  # 速率限制
  rate_limit:
    # 每用户每分钟最大消息数
    per_user: 20
    # 每群组每分钟最大消息数
    per_chat: 60
    # 限流后的冷却时间（秒）
    cooldown: 60

# gateway.discord.yaml
discord:
  bot:
    token: "${DISCORD_BOT_TOKEN}"
    # intents 权限（必需）
    intents:
      - MESSAGE_CONTENT
      - GUILD_MESSAGES
      - DIRECT_MESSAGES
      - THREADS
      
  # 频道映射
  channels:
    # 指定哪些频道作为主对话频道
    primary: ["channel_id_1"]
    # 忽略哪些频道
    ignored: ["channel_id_2", "channel_id_3"]
    
  # Slash Commands 自动注册
  commands:
    auto_register: true
    commands:
      - name: "ask"
        description: "向 Hermes 提问"
        options:
          - name: "question"
            type: 3  # STRING
            description: "你的问题"
            required: true
      - name: "search"
        description: "搜索记忆库"
      - name: "skill"
        description: "管理技能"
        
  # 消息样式
  appearance:
    # 响应消息的最大字符数（Discord 限制 2000）
    max_length: 1900
    # 超出限制时分块发送
    split_mode: "chunk"
    # 消息引用格式
    quote_style: "reply"  # reply | blockquote | none

{
  "username": "Hermes",
  "avatar_url": "https://example.com/hermes-avatar.png",
  "embeds": [{
    "title": "处理结果",
    "description": "这是响应内容...",
    "color": 5814783,
    "fields": [
      {"name": "处理时间", "value": "1.2s", "inline": true},
      {"name": "工具调用", "value": "web_search", "inline": true}
    ],
    "footer": {"text": "Hermes Agent"}
  }]
}

# gateway.slack.yaml
slack:
  # OAuth 配置
  oauth:
    client_id: "${SLACK_CLIENT_ID}"
    client_secret: "${SLACK_CLIENT_SECRET}"
    signing_secret: "${SLACK_SIGNING_SECRET}"
    
  # Socket Mode（推荐）
  socket_mode:
    enabled: true
    app_token: "${SLACK_APP_TOKEN}"
    
  # 传统 Webhook 模式
  webhook:
    enabled: false
    url: "${SLACK_WEBHOOK_URL}"
    
  # 频道映射
  workspaces:
    default:
      token: "${SLACK_BOT_TOKEN}"
      signing_secret: "${SLACK_SIGNING_SECRET}"
      # Bot 监听哪些关键词
      triggers:
        - "hermes"
        - "@HermesBot"
      # 是否只在被提及时响应
      mention_only: true
      
  # Block Kit 消息模板
  templates:
    response:
      - type: "section"
        text:
          type: "mrkdwn"
          text: "{{content}}"
      - type: "context"
        elements:
          - type: "mrkdwn"
            text: "由 Hermes Agent 生成 • {{timestamp}}"

# gateway.whatsapp.yaml
whatsapp:
  # WhatsApp Business Cloud API
  api:
    phone_number_id: "${WA_PHONE_NUMBER_ID}"
    access_token: "${WA_ACCESS_TOKEN}"
    business_account_id: "${WA_BUSINESS_ACCOUNT_ID}"
    
  # Webhook 配置
  webhook:
    verify_token: "${WA_WEBHOOK_VERIFY_TOKEN}"
    callback_url: "https://your-domain.com/webhook/whatsapp"
    
  # 消息限制（WhatsApp 有严格限制）
  limits:
    # 广播列表最大收件人
    broadcast_max_recipients: 256
    # 模板消息冷却（秒）
    template_cooldown: 30
    
  # 支持的消息类型
  supported_types:
    - text
    - image
    - audio
    - document
    - video
    - location
    - contacts

# gateway.signal.yaml
signal:
  gateway:
    # Signal Gateway 服务地址
    url: "https://signal-gateway:8080"
    api_key: "${SIGNAL_GATEWAY_API_KEY}"
    
  # 账号配置
  accounts:
    primary:
      number: "${SIGNAL_NUMBER}"  # 格式：+8613812345678
      # UUID 由 Signal Gateway 分配
      uuid: "${SIGNAL_UUID}"
      
  # 消息处理
  messages:
    # 是否自动回复群组消息
    group_auto_reply: false
    # 附件大小限制（MB）
    max_attachment_mb: 20

用户（13:00，在 Telegram）：
用户: "帮我规划下周的行程"
Hermes: "好的，你下周主要在杭州...（开始规划）"
         [记忆系统记录：用户下周在杭州有3个会议]

用户（14:30，切换到 Discord）：
用户: "继续刚才的行程规划"
Hermes: "继续完善你的杭州行程..."  [自动读取之前的记忆]
         "第三天晚上的餐厅我已经预订好了..."

# 技能中的平台感知示例
def generate_response(user_message: str, platform: str, **kwargs) -> str:
    base_response = process_message(user_message)
    
    # 根据平台调整输出格式
    if platform == "discord":
        return format_for_discord(base_response)  # 支持 Embed
    elif platform == "slack":
        return format_for_slack(base_response)    # Block Kit 格式
    elif platform == "telegram":
        return format_for_telegram(base_response) # 支持 HTML 格式
    elif platform == "whatsapp":
        return format_for_whatsapp(base_response) # 纯文本，emoji 友好
    else:
        return base_response

微信客户端（手机/电脑）
    │
    │ 微信协议（私有，非官方）
    ▼
HermesClaw（本地桥接服务）
    │
    │ 转换为 OpenClaw/Gateway 协议
    ▼
Hermes Agent Core
    │
    │ 响应
    ▼
HermesClaw
    │
    │ 转换为微信消息格式
    ▼
微信用户

# 安装 HermesClaw（OpenClaw 插件）
openclaw plugin install hermes-claw

# 首次配置
openclaw claw setup
# 配置向导：
# 1. 选择桥接模式（wechat-native 或 wechat-work）
# 2. 扫码登录微信
# 3. 配置监听范围（哪些群/好友）

# 启动桥接
openclaw claw start

# 查看状态
openclaw claw status
# 输出示例：
# HermesClaw Bridge: Running
# Connected Accounts: 1
# Active Chats: 12
# Messages Today: 47

# ~/.openclaw/hermes-claw.yaml
hermes-claw:
  # 连接模式
  mode: "wechat-native"  # wechat-native | wechat-work
  
  # OpenClaw Gateway 地址
  gateway:
    host: "localhost"
    port: 8080
    path: "/api/v1/chat"
    
  # 消息监听范围
  scope:
    # 是否监听所有私聊
    all_private: false
    # 允许的私聊好友列表（微信昵称或备注）
    allowed_contacts:
      - "Hermes"
      - "我的小号"
    # 是否监听所有群
    all_groups: false
    # 允许的群聊列表
    allowed_groups:
      - "AI 技术交流群"
      - "开发团队"
      
  # 触发方式
  triggers:
    # 私聊：always（始终响应）| mentioned（被@时响应）
    private: "always"
    # 群聊：never（不响应）| mentioned（被@时响应）| keyword（关键词触发）
    group: "mentioned"
    # 关键词列表（keyword 模式时使用）
    keywords:
      - "hermes"
      - "小助手"
      - "帮我"
      
  # 消息处理
  processing:
    # 是否自动转译语音消息
    voice_to_text: true
    # 是否下载图片进行 OCR
    image_ocr: false
    # 文件下载目录
    download_path: "~/Downloads/hermes-claw"
    
  # 限流
  rate_limit:
    # 每用户每分钟最大消息数
    per_user_per_minute: 10
    # 消息处理超时（秒）
    processing_timeout: 120

# 企业微信配置
hermes-claw:
  mode: "wechat-work"
  
  # 企业微信应用配置
  work:
    corp_id: "${WECOM_CORP_ID}"
    agent_id: "${WECOM_AGENT_ID}"
    corp_secret: "${WECOM_CORP_SECRET}"
    
  # Webhook 地址（企业微信提供）
  webhook_url: "${WECOM_WEBHOOK_URL}"

# 安全配置
security:
  # 全局白名单模式
  whitelist_mode: true
  
  # 允许的用户（按平台）
  allowed_users:
    telegram:
      - "123456789"      # 用户 ID
      - "987654321"
    discord:
      - "111222333444555"  # Discord Snowflake ID
    slack:
      - "U1234567890"      # Slack User ID
    signal:
      - "+8613812345678"   # Signal 号码
      
  # 拒绝消息处理
  on_unauthorized:
    # 回复提示（可选，留空则不回复）
    reply: "抱歉，我没有权限响应你的消息。"
    # 记录到日志
    log: true
    # 发送通知给管理员
    notify_admin: true

# 群组配置
groups:
  # 允许 Bot 加入的群组（留空允许所有）
  allowed:
    telegram: []
    discord:
      - "guild_id_123"
      - "guild_id_456"
      
  # 群组级白名单（仅这些群组可用）
  whitelist_mode: false
  
  # 信任的群组成员
  trusted_members:
    discord:
      "guild_id_123":
        - "role_id_admin"
        - "user_id_owner"

# 速率限制
rate_limit:
  # 全局设置
  global:
    # 每分钟最大消息数
    messages_per_minute: 100
    # 令牌桶大小
    burst_size: 20
    
  # 按用户限制
  per_user:
    messages_per_minute: 20
    messages_per_hour: 500
    messages_per_day: 5000
    
  # 按群组限制
  per_group:
    messages_per_minute: 60
    # 响应比例（%）
    response_ratio: 30
    
  # 限流响应
  on_limit:
    action: "cooldown"  # cooldown | drop | error
    cooldown_seconds: 60
    notify_user: true

hermes gateway --verbose
# 输出详细日志，Ctrl+C 停止

# 安装为系统服务
sudo hermes gateway install

# 服务管理
sudo systemctl start hermes-gateway
sudo systemctl stop hermes-gateway
sudo systemctl restart hermes-gateway
sudo systemctl status hermes-gateway

# 查看日志
sudo journalctl -u hermes-gateway -f

[Unit]
Description=Hermes Agent Messaging Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=hermes
Group=hermes
WorkingDirectory=/home/hermes
Environment="HERMES_CONFIG=/home/hermes/.hermes/config.yaml"
ExecStart=/usr/local/bin/hermes gateway
Restart=always
RestartSec=10

# 安全设置
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=read-only
ReadWritePaths=/home/hermes/.hermes

[Install]
WantedBy=multi-user.target

# docker-compose.yaml
version: '3.8'

services:
  hermes-gateway:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-gateway
    restart: unless-stopped
    
    environment:
      # 模型配置
      - HERMES_MODEL=${MODEL_PROVIDER:-openai}
      - HERMES_API_KEY=${API_KEY}
      - HERMES_MODEL_NAME=${MODEL_NAME:-gpt-4o}
      
      # Gateway 配置
      - HERMES_GATEWAY_ENABLED=true
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - DISCORD_BOT_TOKEN=${DISCORD_BOT_TOKEN}
      
    volumes:
      # 持久化记忆和配置
      - hermes_data:/data/hermes
      - ./config:/config
      # SSL 证书（如果需要 HTTPS Webhook）
      - ./certs:/certs:ro
      
    ports:
      - "8080:8080"  # Gateway API
      - "8081:8081"  # 管理界面
      
    healthcheck:
      test: ["CMD", "hermes", "health"]
      interval: 30s
      timeout: 10s
      retries: 3
      
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

volumes:
  hermes_data:
    driver: local

# 一键启动
docker-compose up -d

# 查看日志
docker-compose logs -f hermes-gateway

# 更新版本
docker-compose pull && docker-compose up -d

upstream hermes_gateway {
    server 127.0.0.1:8080;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name hermes.your-domain.com;
    
    ssl_certificate /etc/letsencrypt/live/hermes.your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/hermes.your-domain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    
    # Telegram 要求
    ssl_prefer_server_ciphers on;
    
    location / {
        proxy_pass http://hermes_gateway;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Telegram Webhook 特殊处理
        proxy_read_timeout 60s;
        proxy_connect_timeout 60s;
        
        # 长时间响应支持
        proxy_send_timeout 300s;
    }
}

# 安装 cloudflared
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o /usr/local/bin/cloudflared
chmod +x /usr/local/bin/cloudflared

# 启动隧道
cloudflared tunnel --url http://localhost:8080
# 输出示例：
# Your tunnel <tunnel-id> is now running on https://xxxx.trycloudflare.com

# 使用固定域名（需要 Cloudflare Zero Trust）
cloudflared tunnel run --token <your-token>

# 检查 Gateway 状态
hermes gateway status

# 输出示例：
# Gateway Status: healthy
# Uptime: 5d 12h 34m
# Connected Platforms: 3
#   - Telegram: connected (Bot: @MyHermesBot)
#   - Discord: connected (Guilds: 2)
#   - Slack: connected (Workspace: mycompany)
# Messages Today: 342
# Active Sessions: 12
# Memory Usage: 1.2 GB
# Last Error: none

# logging.yaml
logging:
  # 日志级别
  level: "info"  # debug | info | warning | error
  
  # 日志输出
  outputs:
    - type: "console"
      format: "pretty"  # pretty | json
      color: true
      
    - type: "file"
      path: "/var/log/hermes/gateway.log"
      max_size: "100MB"
      max_backups: 5
      compress: true
      
    - type: "syslog"  # 可选，发送到集中日志系统
      host: "syslog.company.com"
      port: 514
      protocol: "tcp"
      
  # 特定模块的日志级别
  modules:
    "gateway.adapter.telegram": "debug"
    "gateway.router": "info"
    "gateway.core": "warning"

# 启用 Prometheus 指标端点
metrics:
  enabled: true
  port: 9090
  path: "/metrics"
  
  # 指标类型
  collectors:
    - messages_total        # 消息总数
    - messages_by_platform  # 按平台分类的消息数
    - response_time_seconds # 响应时间
    - active_sessions       # 当前活跃会话数
    - token_usage           # Token 消耗
    - error_rate            # 错误率

# Gateway 消息吞吐量
rate(hermes_messages_total[5m])

# 按平台分类的消息
rate(hermes_messages_by_platform[5m])

# P99 响应时间
histogram_quantile(0.99, rate(hermes_response_time_seconds_bucket[5m]))

# 错误率
rate(hermes_errors_total[5m]) / rate(hermes_messages_total[5m])

# 导出仪表盘 JSON
hermes dashboard export --format grafana > hermes-dashboard.json

# 或者直接在 Grafana 中导入
# Administration → Dashboards → Import → 上传 JSON

# 使用 nginx 或 consul 做负载均衡
upstream hermes_cluster {
    least_conn;  # 最少连接优先
    
    server hermes-1:8080;
    server hermes-2:8080;
    server hermes-3:8080;
}

# 注意：所有实例需要共享存储（记忆系统）
# 可以使用 Redis 或 PostgreSQL 作为后端存储

# 使用 Redis Streams 作为消息队列
queue:
  enabled: true
  type: "redis"
  
  redis:
    url: "redis://localhost:6379"
    stream: "hermes:gateway:queue"
    consumer_group: "hermes-processors"
    
  # 配置消费者数量
  workers: 4
  
  # 消息确认模式
  ack_mode: "manual"  # auto | manual

# gateway/adapters/custom_adapter.py
from hermes.gateway.base import BaseAdapter
from hermes.gateway.types import UnifiedMessage

class CustomAdapter(BaseAdapter):
    """自定义平台适配器模板"""
    
    platform_name = "my_platform"
    
    async def connect(self) -> None:
        """建立与平台的连接"""
        pass
        
    async def disconnect(self) -> None:
        """断开连接"""
        pass
        
    async def send_message(self, message: UnifiedMessage) -> None:
        """发送消息到平台"""
        pass
        
    async def handle_incoming(self, raw_data: dict) -> UnifiedMessage:
        """将平台原始数据转换为统一格式"""
        return UnifiedMessage(
            message_id=raw_data["id"],
            chat_id=raw_data["chat_id"],
            platform=self.platform_name,
            content={"text": raw_data["text"]},
            sender={"id": raw_data["user_id"]},
            timestamp=raw_data["timestamp"]
        )
        
    def format_response(self, response: str, original: UnifiedMessage) -> dict:
        """将响应格式化为平台原生格式"""
        return {
            "chat_id": original.chat_id,
            "text": response
        }

# 注册自定义适配器
hermes adapter register --name my_platform --path ./custom_adapter.py

# 或在配置中声明
# gateway:
#   adapters:
#     - my_platform

# 完整诊断
hermes gateway doctor

# 测试特定平台连接
hermes gateway test --platform telegram --token YOUR_TOKEN

# 查看详细日志
hermes gateway --log-level debug

# 重置平台连接
hermes gateway reset --platform telegram