Um bot Feishu para múltiplos Hermes: tutorial passo a passo de roteamento de Profile no v0.19

Antes do Hermes Agent v0.19, se você quisesse executar personalidades diferentes de Agent em grupos diferentes do Feishu, a abordagem mais simples era: criar um aplicativo de bot do Feishu separado para cada grupo e executar um Gateway do Hermes separado para cada um. Muitos tokens, muitos processos e configuração dispersa.

A combinação de multiplex_profiles + profile_routes no v0.19 permite usar um único aplicativo de bot do Feishu e um único processo de Gateway para distribuir mensagens de diferentes grupos ou tópicos para diferentes Profile. Cada Profile mantém seu próprio modelo, skills, memória e segredos, mas compartilham a mesma identidade de bot.

Este artigo é baseado no release oficial do Hermes v0.19.0 e na documentação existente do projeto, e oferece um exemplo completo e pronto para uso.

Quer ver o panorama geral primeiro? Leia nosso resumo das notas de lançamento do Hermes v0.19.0 Quicksilver e as v0.19.0 release notes oficiais.

Pré-requisitos

  • Hermes Agent >= v0.19.0
  • Um aplicativo de bot do Feishu (Lark) criado e aprovado
  • O bot tem a “inscrição de eventos” habilitada e pode receber eventos como im.message.receive_v1
  • Você obteve app_id, app_secret, encrypt_key e verification_token na plataforma aberta do Feishu

Se você ainda não conectou um bot do Feishu ao Hermes, comece configurando as credenciais base em ~/.hermes/.env:

FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy
FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
FEISHU_ENCRYPT_KEY=xxxxxxxxxxxxxxxx
FEISHU_VERIFICATION_TOKEN=xxxxxxxxxxxxxxxx

O adaptador do Feishu do Hermes é um Gateway completo desde o v0.6.0, com suporte a cards de mensagem, chats em grupo, anexos de imagem/arquivo e callbacks interativos, então a conectividade básica não deve ser um obstáculo.

Conceitos principais: multiplex_profiles + profile_routes

Antes do v0.19, o Gateway do Hermes já suportava “um processo conectado a várias plataformas”. A novidade do v0.19 é: a mesma plataforma, o mesmo token de bot, e ainda assim rotear por origem para diferentes Profile.

Campos chave:

  • gateway.multiplex_profiles: true — ativa o modo de reutilização de múltiplos Profile
  • gateway.profile_routes — define a lista de regras de correspondência por origem

Nota: no modo multiplex, plataformas de ligação de porta (webhook, api_server, feishu, etc.) só podem ser configuradas no Profile default; os outros Profile recebem mensagens por meio das regras de roteamento. Este artigo descreve exatamente esse padrão: o Profile default executa o ponto de entrada da plataforma Feishu, e profile_routes despacha as mensagens para Profile como work ou personal.

Exemplo de configuração para Feishu

Suponha que você tenha três grupos do Feishu:

Grupo Uso Profile desejado
Grupo de plantão técnico Lidar com alertas, ver logs, executar comandos seguros ops
Grupo de discussão de produto Escrever PRDs, fazer análise de concorrência product
Grupo de assistente pessoal Agenda pessoal, consultas personal

Em ~/.hermes/config.yaml, escreva:

profiles:
  default:
    # O ponto de entrada da plataforma Feishu deve ficar no Profile default
    gateway:
      platforms:
        - platform: feishu
          app_id: "cli_xxxxxxxxxxxxxxxx"
          app_secret: "{{env.FEISHU_APP_SECRET}}"
          encrypt_key: "{{env.FEISHU_ENCRYPT_KEY}}"
          verification_token: "{{env.FEISHU_VERIFICATION_TOKEN}}"
          allowed_users:
            - "ou_xxxxxxxx"
            - "ou_yyyyyyyy"

  ops:
    model: "claude-sonnet-5"
    system_prompt: "Você é um assistente técnico de plantão, especializado em troubleshooting de logs, operações de containers e resposta a segurança."
    skills:
      - kubernetes
      - sentry
    approvals:
      smart_approvals: true
    deny_rules:
      - pattern: "kubectl delete.*prod"
        reason: "Operações de exclusão em produção não são permitidas automaticamente"

  product:
    model: "gpt-5.6-sol"
    system_prompt: "Você é um assistente de gerenciamento de produto, especializado em escrever PRDs, análise de concorrência e organização de feedback de usuários."
    skills:
      - notion
      - web_search

  personal:
    model: "grok-4.5"
    system_prompt: "Você é um assistente de produtividade pessoal com tom descontraído."

gateway:
  multiplex_profiles: true
  profile_routes:
    - name: feishu-ops
      platform: feishu
      chat_id: "oc_xxxxxxxxxxxxxxxx"
      profile: ops

    - name: feishu-product
      platform: feishu
      chat_id: "oc_yyyyyyyyyyyyyyyy"
      profile: product

    - name: feishu-personal
      platform: feishu
      chat_id: "oc_zzzzzzzzzzzzzzzz"
      profile: personal

    # Fallback: todas as mensagens diretas de um usuário vão para personal
    - name: feishu-dm
      platform: feishu
      user_id: "ou_xxxxxxxx"
      profile: personal

Após salvar, execute:

hermes config validate
hermes gateway restart

Campos de roteamento do Feishu explicados

O profile_routes do v0.19 suporta os seguintes campos para Feishu/Lark (ordenados por especificidade):

Campo Significado Exemplo Peso de especificidade
platform Tipo de plataforma, obrigatório feishu Base
chat_id ID do chat/grupo do Feishu (começa com oc_) oc_xxxxxxxxxxxxxxxx Alto
thread_id ID do tópico/thread do Feishu omt_xxxxxxxxxxxxxxxx Mais alto
user_id ID do usuário do Feishu (começa com ou_) ou_xxxxxxxx Médio-alto
tenant_id ID da empresa/tenant (cenários multi-tenant) xxx Médio
profile Nome do Profile de destino ops —
name Comentário da regra feishu-ops —

Regras de correspondência:

  1. Todos os campos declarados devem ser satisfeitos (relação AND).
  2. Campos não declarados são ignorados.
  3. Maior especificidade vence: thread_id > chat_id > user_id > tenant_id > apenas platform.
  4. Com a mesma especificidade, a primeira regra declarada vence.

Portanto, você pode rotear um grupo inteiro por chat_id e depois fazer um desvio mais fino dentro de um tópico específico usando thread_id.

Como obter chat_id, thread_id e user_id do Feishu

A forma mais simples: deixe o Hermes rodar primeiro com o Profile default, envie uma mensagem e verifique o log em busca do session_key ou do payload do evento. O log normalmente mostra algo como:

[feishu] incoming message chat_id=oc_xxxxxxxxxxxxxxxx thread_id=omt_yyyyyyyy user_id=ou_zzzzzzzz

Ou adicione temporariamente um skill echo no Profile default que responda:

chat_id: oc_xxxxxxxxxxxxxxxx
thread_id: omt_yyyyyyyy
user_id: ou_zzzzzzzz

Assim que tiver os IDs, escreva-os em profile_routes e reinicie o Gateway.

Erro comum: não configure Feishu em vários Profile

No modo multiplex, se você também escrever no Profile ops algo como:

profiles:
  ops:
    gateway:
      platforms:
        - platform: feishu
          ...

A inicialização falhará. Como feishu é uma plataforma de ligação de porta, o ponto de entrada só pode pertencer ao Profile default. Profile secundários obtêm a capacidade do Feishu inteiramente por meio de profile_routes.

Se você precisar de isolamento rígido a nível de processo (por exemplo, ops nunca pode compartilhar processo com personal), não use multiplex. Em vez disso, inicie um Gateway separado para cada Profile com hermes -p ops gateway start.

Comandos de depuração e validação

# Verificar se o multiplex está habilitado
hermes config get gateway.multiplex_profiles

# Ver as regras de profile_routes ativas
hermes config get gateway.profile_routes

# Validar a sintaxe da configuração
hermes config validate

# Iniciar/reiniciar o Gateway
hermes gateway start
hermes gateway restart

# Verificar o status do Gateway e quais Profile estão sendo servidos
hermes status

# Ver logs em tempo real da plataforma Feishu (em outro terminal)
hermes gateway --log-level debug

Após enviar uma mensagem de teste, verifique se os logs mostram:

[multiplex] routed feishu chat_id=oc_xxx to profile=ops

Se não aparecer, a regra não correspondeu. Verifique se o chat_id está errado ou tem espaços extras.

Avançado: isolamento por tópico (thread_id)

Tópicos do Feishu dentro de um grupo funcionam como subcanais. Você pode encaminhar tópicos diferentes do mesmo grupo para diferentes Profile:

gateway:
  multiplex_profiles: true
  profile_routes:
    - name: feishu-ops-main
      platform: feishu
      chat_id: "oc_xxxxxxxxxxxxxxxx"
      profile: ops

    - name: feishu-ops-oncall
      platform: feishu
      chat_id: "oc_xxxxxxxxxxxxxxxx"
      thread_id: "omt_yyyyyyyyyyyyyyyy"
      profile: ops-oncall

Como thread_id tem maior especificidade, as mensagens dentro daquele tópico irão para ops-oncall, enquanto as demais mensagens do grupo irão para ops.

Avançado: cenário multi-tenant (tenant_id)

Se você instalar o mesmo aplicativo de bot em várias empresas do Feishu (cenário ISV), pode rotear por tenant_id:

gateway:
  profile_routes:
    - name: tenant-a
      platform: feishu
      tenant_id: "tenant_a_id"
      profile: customer-a

    - name: tenant-b
      platform: feishu
      tenant_id: "tenant_b_id"
      profile: customer-b

Combinado com os per-profile secret scopes do Hermes, cada cliente pode ter segredos e configurações de modelo completamente isolados.

Recomendações de segurança

  1. Sempre defina allowed_users: bots do Feishu devem responder apenas a usuários na lista de permissões, evitando abuso se o bot for convidado para um grupo desconhecido.
  2. Separe permissões por Profile: o Profile ops pode conectar ferramentas de operações, mas o Profile product não deve ter permissão de execução em produção.
  3. Use deny_rules como rede de segurança: mesmo que uma mensagem seja roteada incorretamente, as regras de negação podem bloquear comandos perigosos. Consulte nosso tutorial anterior sobre as três barreiras de Smart Approvals no Hermes v0.19.
  4. Verifique a precisão do chat_id: no Feishu, é fácil confundir oc_ com ou_, e um erro fará com que as mensagens caiam no Profile default ou não correspondam.

Resumo

O profile_routes do Hermes v0.19 transforma um bot do Feishu de “um bot, um Agent” para “um bot, múltiplos Agent”. O núcleo da configuração são três passos:

  1. Configure o único ponto de entrada do feishu no Profile default;
  2. Ative gateway.multiplex_profiles: true;
  3. Use gateway.profile_routes para dividir por chat_id / thread_id / user_id / tenant_id para diferentes Profile.

Assim, o mesmo bot do Feishu pode atuar como assistente de operações em um grupo técnico, redator de PRDs em um grupo de produto e assistente pessoal em mensagens diretas — sem manter vários bots ou processos de Gateway.

# Validação final e inicialização
hermes config validate
hermes gateway restart
hermes status