Já alguma vez ficaste parado à frente de uma pesquisa do GitHub por plugins do Hermes, a perguntar-te qual daqueles repositórios, todos parecidos, é que está mesmo mantido — e o que é que o código vai fazer à tua máquina quando o instalares? Essa hesitação é razoável: um plugin do Hermes é Python que corre dentro do processo do agente, por isso instalar um está mais perto de entregar a chave de casa a um estranho do que de adicionar uma dependência.

A PR #69446, mesclada a 9 de setembro, ataca exatamente essa dor: o Hermes passa a incluir um catálogo de plugins com revisão humana que resolve descoberta e confiança num único sítio. Em vez de andares à caça pelo GitHub, corres hermes plugins search contra um índice oficial e curado. Em vez de te arriscares num README, cada entrada do catálogo está fixada num commit exato e tem de declarar as suas capacidades à partida — sabes o que estás a instalar antes de o instalar.

O que é o catálogo de plugins

Primeiro, uma distinção: os plugins de que falamos aqui são plugins nativos in-process — as extensões que correm dentro do Hermes, registam os seus próprios tools e hooks e são geridas através de plugins.entries. São uma camada diferente do catálogo de servidores MCP, que liga serviços externos através do Model Context Protocol. O catálogo MCP responde a «como chego aos serviços externos?»; o catálogo de plugins responde a «como estendo o próprio Hermes?».

Fisicamente, o catálogo é um conjunto de ficheiros YAML no diretório plugin-catalog/ do repositório — um ficheiro por entrada de plugin:

name: hermes-telegram-business   # chave única do catálogo; instala por este nome
repo: https://github.com/NousResearch/hermes-telegram-business
sha: e905f3bc5eeaa5a9dab9bc5155601b3ebec75757  # SHA completo de 40 caracteres
description: One-line description
maintainer: NousResearch
tier: official          # official ou community
platforms: []           # vazio = todas as plataformas
capabilities:           # o que este plugin afirma registar
  provides_tools: []
  provides_hooks: []
  provides_middleware: []
  requires_env: []

O catálogo arrancou com 7 entradas iniciais: 3 oficiais (plugin-llm-example, plugin-llm-async-example, hermes-telegram-business) e 4 da comunidade (hermes-plugin-chrome-profiles, por @anpicasso, hermes-snapcompact, jackal-verified e herdr-auto-reconcile). As oficiais vêm dos repositórios da própria NousResearch; as da comunidade vêm de mantenedores independentes — o chrome-profiles alterna os tools do browser entre profiles Chrome/Edge locais e remotos via CDP, e o snapcompact arquiva o histórico de conversas em frames de bitmap densos que os modelos de vision conseguem reler por cerca de um terço do custo em tokens.

Pesquisar, instalar, listar: os três comandos que interessam

Tudo gira em torno de hermes plugins. Nota: isto chegou ao main a 9 de setembro e ainda não está em nenhuma release — a release oficial mais recente, a v0.21.1 (7 de setembro), é anterior a isto. Para o usares hoje, precisas de um build que inclua o merge.

Pesquisar o catálogo inteiro — sem argumento lista tudo; uma palavra-chave encontra nomes, descrições e tools declarados:

hermes plugins search
hermes plugins search telegram      # encontra nomes/descrições/tools que mencionem telegram
hermes plugins search --json        # legível por máquina, para scripts

Instalar — por nome simples do catálogo, por URL Git ou pela forma abreviada owner/repo:

hermes plugins install hermes-telegram-business   # acerto no catálogo: instala o SHA revisto e fixado
hermes plugins install anpicasso/hermes-plugin-chrome-profiles  # owner/repo = fonte personalizada (não revista)
hermes plugins install https://github.com/xxx/my-plugin          # URL Git completa

A distinção da fonte é o coração do modelo de confiança. Um nome simples que acerta no catálogo instala exatamente o commit auditado, imprime o tier e o pin ([official] pinned @ e905f3bc), mostra o resumo das capacidades e regista a proveniência num ficheiro .hermes-catalog.json ao lado do plugin. Uma URL Git ou a forma abreviada owner/repo imprime um aviso amarelo de «fonte personalizada (não revista)» — aí estás por tua conta. Em qualquer dos casos, é-te perguntado se queres ativar o plugin de imediato; instalado não significa ativado, e o prompt de ativação mostra o que o plugin quer registar.

Vê o que tens:

hermes plugins list
hermes plugins list --plain          # texto simples compacto em vez de tabela Rich
hermes plugins show hermes-telegram-business   # detalhes de um plugin

O modelo de confiança: porque é que o catálogo justifica o seu lugar

A credibilidade do catálogo não é um selo — é uma cadeia de mecanismos impostos, documentada no README do catálogo:

• Admissão por merge humano. Cada entrada só entra através de uma PR no repositório hermes-agent, revista e mesclada por um mantenedor. Não há registo self-service nem ingestão automática.
• Pins de commit exatos e obrigatórios. Cada entrada exige um SHA completo, de 40 caracteres. Branches, tags e SHAs curtos são rejeitados. As instalações fazem checkout desse commit exato — nunca do HEAD mais recente —, portanto o que o catálogo diz e o que corres é o mesmo código.
• O pin amadurece durante duas semanas. Uma versão fixada tem de ter, no momento do pin, pelo menos duas semanas de vida, no espelho da política de supply chain usada para outras dependências fixadas — tempo para a comunidade detetar uma release comprometida antes de o Hermes começar a apontar para ela.
• Atualizar um pin é uma PR nova. Mudar o SHA de uma entrada abre uma PR nova, revista de raiz, e o diff (SHA antigo → SHA novo) é a superfície de revisão — cada movimento do apontador passa por um humano a olhar para o intervalo de commits a montante.
• As capacidades declaradas têm de bater com a realidade. hermes plugins validate carrega o plugin num subprocesso descartável e compara os provides_tools/provides_hooks declarados com aquilo que register(ctx) regista de facto. Se não bater, a entrada falha — capacidades não declaradas a crescerem às escondidas são tratadas como um problema de segurança. A CI de admissão corre esta verificação em todas as entradas alteradas.
• Remover = blocklist. Quando uma entrada é retirada por motivos de segurança ou política, vai parar ao removed.yaml, e qualquer instalação que corresponda ao nome ou ao repositório dela é recusada em todas as superfícies (CLI, dashboard, desktop). A CLI tem uma escapatória explícita, --allow-removed, que imprime um aviso vermelho bem visível; as outras superfícies não têm.

O catálogo encerra também um capítulo da história: o índice comunitário provisório de plugins apontava para um URL canónico de repositório que nunca existiu de facto e não tinha qualquer controlo de admissão. Esta mudança remove esse índice por completo e consolida tudo no catálogo dentro do repositório.

Validar, atualizar e gerir no dia a dia

Depois de instalares plugins, aplicam-se os comandos habituais do ciclo de vida:

hermes plugins update hermes-telegram-business   # instalações do catálogo voltam a fixar o SHA revisto
hermes plugins disable hermes-telegram-business  # desativa sem remover
hermes plugins enable hermes-telegram-business   # reativa
hermes plugins remove hermes-telegram-business   # desinstala (aliases: rm, uninstall)
hermes plugins capabilities                      # capacidades declaradas vs concedidas, por plugin

Escreveste um plugin e queres vê-lo listado? hermes plugins validate <plugin-dir> é exatamente o mesmo controlo que a CI de admissão corre — passa-o localmente antes de abrires a PR, e o hermes plugins doctor vai mais fundo, contra os contratos reais de runtime. Os clientes refrescam o catálogo a partir do JSON do site de documentação (/docs/api/plugin-catalog.json) no máximo de 6 em 6 horas e, offline, recorrem à cópia dentro do repositório — uma falha de rede nunca bloqueia uma instalação.

Um lembrete sobre o piso de segurança: os plugins correm dentro do processo do Hermes, por isso o catálogo reduz o risco — não o anula. Depois de instalar seja o que for, vale a pena espreitar hermes plugins capabilities de vez em quando para ver o que cada plugin tem mesmo na mão. Quanto ao próprio mecanismo de plugins — configurá-lo e escrever os teus —, o nosso guia do plugin pip model-provider percorre-o; combinado com o catálogo de servidores MCP, os canais oficiais cobrem agora a maior parte daquilo que, de outro modo, terias de construir à mão.