61 plugins admitidos en 65 minutos: qué revisa de verdad un barrido por lotes del catálogo


Escribiste un plugin de Hermes, funciona bien y quieres que otra gente lo instale con un solo comando. Así que lees la documentación, encuentras «abre un PR que añada un plugin-catalog/<name>.yaml» y aterrizas en la página de pull requests del repositorio, donde, entre las dos y las tres de la madrugada, los merges pasan como una cascada. Sesenta y tantos, todos entradas de plugins.

Tu primera reacción probablemente sea que esto parece arbitrario y que tu PR se va a ahogar. La segunda: ¿alguien leyó de verdad todo eso?

Las dos preguntas tienen respuesta concreta, y las respuestas están escritas en las reglas de admisión del repositorio.

61 entradas en una hora es el diseño, no una desbandada

Empecemos por los hechos. Entre las 02:14 y las 03:19 UTC del 8 de noviembre, NousResearch/hermes-agent fusionó 61 entradas del catálogo de plugins. Las etiquetas son uniformes: todas llevan ci-reviewed, casi todas comp/plugins, y un subconjunto más pequeño type/feature con P3.

Nadie estuvo toda la noche pulsando merge al azar. La regla de admisión 5 permite exactamente dos caminos:

  1. el dueño del repositorio del plugin o un colaborador principal envía la entrada;
  2. los maintainers añaden entradas por lotes a partir de un barrido revisado de plugins de la comunidad — «cada pin validado y escaneado en el commit fijado».

Así que la admisión por lotes es una forma oficial de trabajar. Lo que se agrupa es el ritmo de los PR, no la densidad de las comprobaciones. Cada entrada pasa por la misma puerta.

Una cosa más que conviene saber: entrar por barrido no le quita el control al autor. Un PR del dueño para ajustar o retirar su entrada se acepta si lo pide, y los incrementos de SHA posteriores (regla 4) siguen siendo PR del dueño o de un maintainer.

Qué atraviesa cada entrada durante un barrido

Si lo único que quieres es la lista de comprobación, es esta. El comando que ejecutan los revisores y la CI es el mismo que puedes correr en local:

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

Lo que comprueba no es «¿funciona?», sino una serie de cosas fáciles de pasar por alto:

  • el manifiesto plugin.yaml y si se cumple requires_hermes;
  • que el plugin carga de verdad, en el commit fijado;
  • que las capabilities que declaras (tools, hooks, middleware, env) coinciden con lo que registra el plugin — esta falla en vez de avisar, porque el crecimiento silencioso de capabilities se trata como un problema de seguridad;
  • config_schema y requires_env;
  • que las dependencias de Python se resuelven dentro de las restricciones del core de Hermes;
  • el escáner de seguridad de instalación (dangerous bloquea; caution se convierte en un aviso que un revisor lee);
  • las comprobaciones de desktop surface y no core override.

Esas dos últimas son los valores más duros del catálogo y merecen su propio párrafo. Los plugins de escritorio solo pueden usar el SDK — nada de parchear el renderer ni los prototipos del navegador. Ningún plugin puede sobrescribir el core de Hermes en tiempo de ejecución — ni AIAgent.<method> = ..., ni sys.modules[...], ni escribir en las tablas de un módulo del core. La documentación lo dice sin rodeos: dos plugins que parchean la misma costura se rompen el uno al otro en silencio, y cada release del core puede romper a los dos.

Por eso la mentalidad más barata para un autor es: deja de parchear por la puerta de atrás y pide un hook. Si falta una capability, abre un issue. El proyecto dice abiertamente que prefiere añadir una costura antes que listar un parche.

Dos casos límite de esta oleada que muestran la fricción real

Un barrido por lotes no es solo el botón de merge. Roza esquinas que de otra forma nunca ves. En esta oleada hubo dos.

Uno: ocho entradas cuyos repositorios de autor rechazan los pushes de los maintainers. La CI del catálogo tiene que clonar el repositorio del autor y ejecutar la validación en el commit fijado. Algunos repositorios protegen ramas o restringen permisos, así que un maintainer no puede hacer push en ellos, ni siquiera de una rama marcador. Un PR específico (#150957) lista esas ocho entradas para tratarlas por separado. La lección es colaborativa, no técnica: si quieres que tu plugin entre limpio por barrido, no dejes la automatización de los maintainers fuera de tu repo.

Dos: el escaneo de archivos de la regla 17 trataba archivos de datos como payloads. La regla 17 prohíbe los «payloads ejecutables no escaneables» y se implementa escaneando los archivos del plugin. Una entrada de esta oleada (dike) fija un tarball con un corpus de datos: 34k archivos .json, dos archivos .ttl y archivos de contexto .jsonld. El escáner no reconocía .jsonld ni .ttl, así que clasificó el corpus como payload no escaneable y la entrada falló la validación de fuente fijada.

La corrección (commit 11b2b4414f) argumenta desde primeros principios: JSON-LD y Turtle son serializaciones RDF en texto plano, exactamente tan revisables como el .json y el .xml que ya estaban en la lista de fuentes — no son payloads. La redacción merece leerse, porque captura la actitud que hay detrás de las reglas: lo que importa es que se pueda revisar, no que quede ordenado.

Si quieres aparecer, estas siete cosas importan más que tu código

En el orden del documento, los motivos por los que vuelven las entradas casi siempre son de preparación, no de falta de ingenio.

Uno: fija un SHA de commit completo de 40 caracteres. Las ramas, los tags y los SHA cortos los rechaza el loader. Instalar clona tu repo y hace checkout exactamente de ese commit: ese es todo el modelo de confianza.

Dos: no incluyas un autoactualizador. La regla 3 prohíbe plugins que descargan y reemplazan sus propios archivos («buscar actualizaciones» dentro de la app, descargadores de releases firmados, cargadores remotos de plugin.js). Un autoactualizador significa que una copia instalada puede saltar a un commit que nadie revisó. ¿Quieres actualizar? Abre un PR de incremento de SHA; los usuarios ejecutan hermes plugins update <name>.

Tres: las capabilities declaradas deben coincidir con la realidad. Declarar de más es desperdicio, declarar de menos es un problema de seguridad, y aquí no hay negociación.

Cuatro: usa superficies públicas, no parchees. Hooks, middleware, ctx.register_*, perfiles de provider, el SDK de escritorio: esa es la lista. Pide lo que falta en vez de rodearlo.

Cinco: las credenciales pasan por Hermes. La regla 11 es detallada al respecto: los secretos declarados en requires_env y config_schema se leen con agent.secret_scope.get_secret(NAME) (que respeta el perfil activo — una lectura pelada de os.environ puede tomar la clave de otro perfil en escenarios de multiplexación); los clientes OAuth de terceros se declaran bajo oauth: en plugin.yaml y se autentican con hermes auth add <plugin>:<id>; un plugin nunca lee archivos .env, auth.json, el estado de sesión de otra herramienta ni un keychain.

Seis: declara el comportamiento riesgoso. La regla 13 pide lo que un usuario querría saber antes de instalar: llamadas de red, lecturas fuera de los datos propios del plugin, comandos de shell, procesos en segundo plano de larga duración, credenciales almacenadas — en la descripción del PR y en el README. La telemetría debe ser opt-in. Los revisores convierten eso en líneas de divulgación en la entrada. Que te descubran sale más caro que dejarlo escrito por adelantado.

Siete: requires_hermes tiene que ser honesto. Es un mínimo SemVer (">=0.21.5"), no una fecha, y nunca más nuevo que el release actual. Además se aplica: instalar por nombre desde el catálogo se rechaza en un Hermes que no cumple, y hermes plugins update mantiene un plugin instalado en su pin actual hasta que se actualice Hermes.

Para los usuarios, el valor es «instalar por nombre, en el commit que leyó un maintainer». Los puntos de entrada:

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

show imprime los detalles de la entrada (incluidos los eventos que emite y escucha), y capabilities compara los permisos declarados con los concedidos — vale la pena echarles un ojo antes de instalar en lugar de llevarse una sorpresa después.

El modelo de confianza del catálogo en sí (revisión humana, pins de SHA, la blocklist removed.yaml) está en la introducción al catálogo; los motivos de rechazo más quisquillosos en la puerta de CI (entradas renombradas, un subdir que se escapa del clon fijado, un sha que nombra un objeto tag) tienen su propio caso de estudio en este artículo sobre la puerta de CI. Este añade la tercera pieza: la admisión por lotes como forma de trabajar, y qué significa si tú eres el autor.

Estado

Esta oleada se fusionó en main el 8 de noviembre y no forma parte de v0.23.0 — pero las entradas del catálogo son archivos de datos, así que no dependen del ritmo de releases: mientras tu Hermes pueda alcanzar el catálogo, las entradas nuevas se pueden buscar e instalar (que una instalación funcione depende del requires_hermes de la entrada y de tu versión).

Si estás preparando tu propia entrada, la referencia de hermes plugins del sitio lista toda la superficie de subcomandos — no te memorices solo install.