61 plugins admitidos em 65 minutos: o que uma varredura em lote do catálogo realmente verifica


Você escreveu um plugin do Hermes, ele funciona bem e você quer que outras pessoas o instalem com um único comando. Então você lê a documentação, encontra “abra um PR que adicione um plugin-catalog/<name>.yaml” e cai na página de pull requests do repositório — onde, entre duas e três da manhã, os merges passam como uma cachoeira. Sessenta e tantos, todos entradas de plugin.

Sua primeira reação provavelmente é achar que isso é arbitrário e que seu PR vai afundar. A segunda: alguém realmente leu tudo aquilo?

As duas perguntas têm resposta concreta, e elas estão escritas nas regras de admissão do repositório.

61 entradas em uma hora é o desenho, não uma debandada

Comece pelos fatos. Entre 02:14 e 03:19 UTC de 8 de novembro, o NousResearch/hermes-agent mesclou 61 entradas do catálogo de plugins. As labels são uniformes: todas carregam ci-reviewed, a maioria comp/plugins, e um conjunto menor type/feature com P3.

Ninguém estava clicando em merge à toa a noite inteira. A regra de admissão 5 permite exatamente dois caminhos:

  1. o dono do repositório do plugin ou um contribuidor relevante envia a entrada;
  2. os maintainers adicionam entradas em lote a partir de uma varredura revisada de plugins da comunidade — “cada pin validado e escaneado no commit fixado”.

Admissão em lote é, portanto, uma forma oficial de trabalhar. O que é agrupado é a cadência dos PRs, não a densidade das checagens. Toda entrada passa pelo mesmo portão.

Mais uma coisa que vale saber: entrar pela varredura não tira o controle do autor. Um PR do dono ajustando ou removendo sua entrada é aceito quando pedido, e os bumps de SHA posteriores (regra 4) continuam sendo PRs do dono ou de um maintainer.

O que cada entrada enfrenta durante uma varredura

Se você só quer o checklist, é este. O comando que revisores e o CI rodam é o mesmo que você pode rodar localmente:

hermes plugins validate /path/to/your-plugin --install-deps

O que ele verifica não é “roda ou não”, e sim uma lista de coisas fáceis de passar batido:

  • o manifesto plugin.yaml e se requires_hermes é respeitado;
  • se o plugin realmente carrega — no commit fixado;
  • se as capabilities que você declara (tools, hooks, middleware, env) batem com o que o plugin registra — esta checagem falha em vez de avisar, porque capability creep silencioso é tratado como problema de segurança;
  • config_schema e requires_env;
  • se as dependências Python resolvem dentro das constraints do core do Hermes;
  • o scanner de segurança da instalação (dangerous bloqueia; caution vira um aviso que um revisor lê);
  • as checagens de desktop surface e no core override.

Essas duas últimas são os valores mais duros do catálogo e merecem parágrafo próprio. Plugins de desktop podem usar apenas o SDK — nada de patch no renderer ou nos protótipos do browser. Nenhum plugin pode sobrescrever o core do Hermes em runtime — nada de AIAgent.<method> = ..., nada de sys.modules[...], nada de escrever nas tabelas de um módulo do core. A documentação diz o motivo sem rodeios: dois plugins fazendo patch na mesma costura quebram um ao outro em silêncio, e toda release do core pode quebrar os dois.

O estado de espírito mais barato para quem escreve o plugin é, então: pare de fazer patch em volta e peça um hook. Se falta uma capability, abra uma issue. O projeto diz abertamente que prefere adicionar uma costura a listar um patch.

Dois casos de borda nesta leva que mostram o atrito de verdade

Uma varredura em lote não é só o botão de merge. Ela raspa em cantos que você nunca vê de outro jeito. Esta leva teve dois.

Um: oito entradas cujos repositórios dos autores recusam push dos maintainers. O CI do catálogo precisa clonar o repositório do autor e rodar a validação no commit fixado. Alguns repositórios protegem branches ou restringem permissões, então um maintainer não consegue dar push neles — nem numa branch marcadora. Um PR dedicado (#150957) lista essas oito entradas para que sejam tratadas à parte. A lição é colaborativa, não técnica: se você quer que seu plugin entre na varredura sem atrito, não tranque a automação dos maintainers fora do seu repositório.

Dois: o scan de arquivos da regra 17 tratou arquivos de dados como payloads. A regra 17 proíbe “payloads executáveis não escaneáveis”, o que é implementado escaneando os arquivos do plugin. Uma entrada desta leva (dike) fixa um tarball de corpus de dados: 34 mil arquivos .json, dois .ttl e arquivos de contexto .jsonld. O scanner não reconheceu .jsonld nem .ttl, então classificou o corpus como payload não escaneável e a entrada falhou na validação de fonte fixada.

A correção (commit 11b2b4414f) argumenta a partir dos primeiros princípios: JSON-LD e Turtle são serializações RDF em texto puro, tão revisáveis quanto o .json e o .xml que já estão na lista de fontes — não são payloads. Vale ler a redação, porque ela captura a atitude por trás das regras: o ponto é ser revisável, não parecer arrumado.

Se você quer entrar na lista, estas sete coisas importam mais que o seu código

Na ordem do documento, os motivos de uma entrada voltar são quase sempre de preparação, não de falta de esperteza.

Um: fixe um SHA de commit completo de 40 caracteres. Branches, tags e SHAs curtos são rejeitados pelo loader. A instalação clona seu repositório e faz checkout exatamente daquele commit — esse é o modelo de confiança inteiro.

Dois: não embale um self-updater. A regra 3 proíbe plugins que baixam e substituem os próprios arquivos (“verificar atualizações” dentro do app, downloaders de release assinada, loaders remotos de plugin.js). Um self-updater significa que uma cópia instalada pode pular para um commit que ninguém revisou. Quer atualizar? Abra um PR de bump de SHA; os usuários rodam hermes plugins update <name>.

Três: as capabilities declaradas precisam bater com a realidade. Declarar demais é desperdício, declarar de menos é problema de segurança, e aqui não existe negociação.

Quatro: use as superfícies públicas, não faça patch. Hooks, middleware, ctx.register_*, provider profiles, o SDK do Desktop — é essa a lista. Peça o que falta em vez de contornar.

Cinco: credenciais passam pelo Hermes. A regra 11 é detalhada: secrets declarados em requires_env e config_schema são lidos com agent.secret_scope.get_secret(NAME) (que respeita o profile ativo — uma leitura crua de os.environ pode pegar a chave de outro profile sob multiplexação); clientes OAuth de terceiros são declarados em oauth: no plugin.yaml e autenticados com hermes auth add <plugin>:<id>; um plugin nunca lê arquivos .env, auth.json, o estado de login de outra ferramenta ou um keychain.

Seis: declare comportamento arriscado. A regra 13 pede o que um usuário gostaria de saber antes de instalar: chamadas de rede, leituras fora dos dados do próprio plugin, comandos de shell, processos em background de longa duração, credenciais armazenadas — na descrição do PR e no README. Telemetria precisa ser opt-in. Os revisores transformam isso em linhas de disclosure na entrada. Ser pego custa mais caro do que escrever antes.

Sete: requires_hermes precisa ser honesto. É um piso SemVer (">=0.21.5"), não uma data, e nunca mais novo que a release atual. Também é aplicado: instalar pelo nome do catálogo é recusado num Hermes que rejeita a versão, e hermes plugins update mantém um plugin instalado no pin atual até o Hermes ser atualizado.

O que entrar na lista te dá

Para os usuários, o valor é “instalar pelo nome, no commit que um maintainer leu”. Os pontos de entrada:

hermes plugins search <keyword>
hermes plugins browse
hermes plugins show <name>
hermes plugins install <name>
hermes plugins capabilities <name>

show imprime os detalhes da entrada (inclusive os eventos que ela emite e escuta), e capabilities compara o declarado com as permissões concedidas — vale uma olhada antes de instalar, em vez de uma surpresa depois.

O modelo de confiança do catálogo em si (revisão humana, pins de SHA, a blocklist removed.yaml) está em a introdução ao catálogo; os motivos mais chatos de rejeição no portão do CI (entradas renomeadas, um subdir escapando do clone fixado, um sha nomeando um objeto tag) têm seu próprio estudo de caso em este post sobre o portão de CI. Este aqui entra com a terceira peça: admissão em lote como forma de trabalho, e o que isso significa se você é o autor.

Status

Esta leva entrou na main em 8 de novembro e não faz parte da v0.23.0 — mas entradas de catálogo são arquivos de dados, então não estão presas à cadência de release: enquanto seu Hermes alcançar o catálogo, entradas novas podem ser buscadas e instaladas (se a instalação vai funcionar depende do requires_hermes da entrada e da sua versão).

Se você está preparando a sua própria entrada, a referência de hermes plugins do site lista toda a superfície de subcomandos — não decore só o install.