61 Plugins in 65 Minuten aufgenommen: was ein Katalog-Batch-Sweep wirklich prüft


Du hast ein Hermes-Plugin geschrieben, es läuft gut, und du willst, dass andere es mit einem einzigen Befehl installieren können. Also liest du die Doku, findest „öffne einen PR, der eine plugin-catalog/<name>.yaml hinzufügt“ und landest auf der Pull-Request-Seite des Repositories — wo zwischen zwei und drei Uhr morgens die Merges vorbeirauschen wie ein Wasserfall. Gut sechzig davon, alles Plugin-Einträge.

Deine erste Reaktion ist wahrscheinlich, dass das willkürlich wirkt und dein PR darin untergeht. Die zweite: Hat sich das überhaupt jemand angesehen?

Beide Fragen haben eine klare Antwort, und beide Antworten stehen in den Aufnahmeregeln des Repositories.

61 Einträge in einer Stunde sind das Design, kein Ausreißer

Fangen wir mit den Fakten an. Zwischen 02:14 und 03:19 UTC am 8. November hat NousResearch/hermes-agent 61 Plugin-Katalog-Einträge gemergt. Die Labels sind einheitlich: alle tragen ci-reviewed, die meisten comp/plugins, ein kleinerer Teil type/feature mit P3.

Niemand hat die ganze Nacht zufällig auf Merge geklickt. Aufnahmeregel 5 lässt genau zwei Wege zu:

  1. der oder die Eigentümer:in des Plugin-Repositories oder eine Haupt-Contributor:in reicht den Eintrag ein;
  2. Maintainer fügen Einträge in Batches aus einem geprüften Sweep der Community-Plugins hinzu — „jeder Pin validiert und gescannt auf dem gepinnten Commit“.

Batch-Aufnahme ist also ein offizieller Weg zu arbeiten. Gebatcht wird die Kadenz der PRs, nicht die Dichte der Prüfungen. Jeder Eintrag geht durch dasselbe Gate.

Noch etwas, das man wissen sollte: Hineingesweept zu werden, entzieht der Autorin oder dem Autor nicht die Kontrolle. Ein PR des Owners, der den eigenen Eintrag anpasst oder entfernt, wird auf Anfrage akzeptiert, und spätere SHA-Bumps (Regel 4) bleiben PRs von Owner oder Maintainer.

Was jeder Eintrag während eines Sweeps durchläuft

Wenn du nur die Checkliste willst, hier ist sie. Der Befehl, den Reviewer und CI ausführen, ist derselbe, den du lokal ausführen kannst:

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

Geprüft wird nicht „läuft es“, sondern eine Liste von Dingen, die man leicht übersieht:

  • das plugin.yaml-Manifest und ob requires_hermes hält;
  • ob das Plugin tatsächlich lädt — auf dem gepinnten Commit;
  • ob die capabilities, die du deklarierst (Tools, Hooks, Middleware, Env), zu dem passen, was das Plugin registriert — dieser Punkt schlägt fehl statt zu warnen, weil schleichendes Capability-Wachstum als Sicherheitsproblem gilt;
  • config_schema und requires_env;
  • ob Python-Abhängigkeiten sich innerhalb der Core-Constraints von Hermes auflösen lassen;
  • der Install-Sicherheits-Scanner (dangerous blockiert; caution wird zu einer Warnung, die ein Reviewer liest);
  • die Checks für desktop surface und no core override.

Die letzten beiden sind die härtesten Werte des Katalogs und verdienen einen eigenen Absatz. Desktop-Plugins dürfen ausschließlich das SDK nutzen — kein Patchen des Renderers oder von Browser-Prototypen. Kein Plugin darf den Hermes-Core zur Laufzeit überschreiben — kein AIAgent.<method> = ..., kein sys.modules[...], kein Schreiben in die Tabellen eines Core-Moduls. Die Doku nennt den Grund unverblümt: Zwei Plugins, die dieselbe Naht patchen, brechen sich gegenseitig still, und jedes Core-Release kann beide brechen.

Die günstigste Haltung für Autorinnen und Autoren ist deshalb: hör auf, darum herumzupatchen, und frag nach einem Hook. Fehlt eine Fähigkeit, öffne ein Issue. Das Projekt sagt offen, dass es lieber eine Naht hinzufügt, als einen Patch zu listen.

Zwei Randfälle in dieser Welle, die die echte Reibung zeigen

Ein Batch-Sweep ist nicht nur der Merge-Button. Er reibt an Ecken, die man sonst nie zu sehen bekommt. In dieser Welle waren es zwei.

Erstens: acht Einträge, deren Autor-Repositories Maintainer-Pushes verweigern. Die Katalog-CI muss das Repository der Autorin oder des Autors klonen und die Validierung auf dem gepinnten Commit ausführen. Manche Repositories schützen Branches oder beschränken Berechtigungen, sodass ein Maintainer nicht pushen kann — nicht einmal einen Marker-Branch. Ein eigener PR (#150957) listet diese acht Einträge, damit sie separat behandelt werden können. Die Lehre ist kollaborativ, nicht technisch: Wenn dein Plugin sauber hineingesweept werden soll, sperr die Automatisierung der Maintainer nicht aus deinem Repo aus.

Zweitens: der Archiv-Scan aus Regel 17 hielt Datendateien für Payloads. Regel 17 verbietet „nicht scannbare ausführbare Payloads“, umgesetzt über das Scannen der Archive des Plugins. Ein Eintrag in dieser Welle (dike) pinnt ein Daten-Korpus-Tarball: 34k .json-Dateien, zwei .ttl-Dateien und .jsonld-Kontextdateien. Der Scanner erkannte .jsonld und .ttl nicht und stufte den Korpus deshalb als nicht scannbaren Payload ein; der Eintrag scheiterte an der Pinned-Source-Validierung.

Der Fix (Commit 11b2b4414f) argumentiert von den Grundlagen her: JSON-LD und Turtle sind Plain-Text-RDF-Serialisierungen, genauso reviewbar wie die .json und .xml, die schon auf der Quellliste stehen — sie sind keine Payloads. Die Formulierung lohnt sich zu lesen, weil sie die Haltung hinter den Regeln einfängt: Es geht um Reviewbarkeit, nicht um ein ordentliches Erscheinungsbild.

Wenn du gelistet werden willst, zählen diese sieben Dinge mehr als dein Code

In der Reihenfolge der Doku sind die Gründe, aus denen Einträge zurückkommen, fast immer Vorbereitung — nicht mangelnde Cleverness.

Eins: pinne einen vollständigen 40-stelligen Commit-SHA. Branches, Tags und kurze SHAs lehnt der Loader ab. Die Installation klont dein Repo und checkt genau diesen Commit aus — das ist das gesamte Trust-Modell.

Zwei: liefere keinen Self-Updater. Regel 3 verbietet Plugins, die ihre eigenen Dateien nachladen und ersetzen (In-App-„nach Updates suchen“, signierte Release-Downloader, Remote-Loader für plugin.js). Ein Self-Updater bedeutet, dass eine installierte Kopie auf einen Commit springen kann, den niemand geprüft hat. Willst du aktualisieren? Öffne einen SHA-Bump-PR; Nutzer führen hermes plugins update <name> aus.

Drei: deklarierte Capabilities müssen der Realität entsprechen. Zu viel zu deklarieren ist verschwenderisch, zu wenig zu deklarieren ist ein Sicherheitsproblem — und hier wird nicht verhandelt.

Vier: nutze öffentliche Oberflächen, patche nicht. Hooks, Middleware, ctx.register_*, Provider-Profile, das Desktop-SDK — das ist die Liste. Frag nach dem, was fehlt, statt drumherum zu routen.

Fünf: Credentials kommen über Hermes. Regel 11 ist hier ausführlich: Secrets, die in requires_env und config_schema deklariert sind, werden mit agent.secret_scope.get_secret(NAME) gelesen (was das aktive Profil respektiert — ein blankes Lesen aus os.environ kann beim Multiplexing den Schlüssel eines anderen Profils erwischen); OAuth-Clients von Drittanbietern werden unter oauth: in plugin.yaml deklariert und mit hermes auth add <plugin>:<id> angemeldet; ein Plugin liest niemals .env-Dateien, auth.json, den Login-Status eines anderen Tools oder einen Keychain.

Sechs: lege riskantes Verhalten offen. Regel 13 fragt nach dem, was ein Nutzer vor der Installation wissen wollen würde: Netzwerkaufrufe, Lesezugriffe außerhalb der eigenen Daten des Plugins, Shell-Befehle, lang laufende Hintergrundprozesse, gespeicherte Credentials — in der PR-Beschreibung und im README. Telemetrie muss Opt-in sein. Reviewer machen daraus Disclosure-Zeilen am Eintrag. Beim Erwischtwerden kostet es mehr, als es vorher aufzuschreiben.

Sieben: requires_hermes muss ehrlich sein. Es ist ein SemVer-Floor (>=0.21.5), kein Datum, und nie neuer als das aktuelle Release. Es wird auch durchgesetzt: Die Installation per Katalognamen verweigert auf einem Hermes, den sie ablehnt, und hermes plugins update hält ein installiertes Plugin auf seinem aktuellen Pin, bis Hermes aktualisiert wird.

Was dir ein Listing bringt

Für Nutzer ist der Wert „per Namen installieren, auf dem Commit, den ein Maintainer gelesen hat“. Die Einstiegspunkte:

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

show gibt die Details des Eintrags aus (inklusive der Events, die es sendet und abonniert), und capabilities vergleicht deklarierte mit gewährten Berechtigungen — ein Blick vor der Installation lohnt sich mehr als die Überraschung danach.

Das Trust-Modell des Katalogs selbst (menschliches Review, SHA-Pins, die removed.yaml-Blocklist) steht in der Katalog-Einführung; die pingeligeren Ablehnungsgründe am CI-Gate (umbenannte Einträge, ein subdir, das aus dem gepinnten Clone ausbricht, ein SHA, der ein Tag-Objekt benennt) haben ihre eigene Fallstudie in diesem Beitrag über das CI-Gate. Dieser hier ergänzt das dritte Stück: Batch-Aufnahme als Arbeitsweise — und was das bedeutet, wenn du selbst der oder die Autor:in bist.

Status

Diese Welle wurde am 8. November auf main gemergt und ist nicht Teil von v0.23.0 — aber Katalog-Einträge sind Datendateien, also nicht an die Release-Kadenz gebunden: Solange dein Hermes den Katalog erreichen kann, lassen sich neue Einträge suchen und installieren (ob eine Installation gelingt, hängt vom requires_hermes des Eintrags und deiner Version ab).

Wenn du deinen eigenen Eintrag vorbereitest, listet die hermes plugins-Referenz der Seite die komplette Subcommand-Oberfläche — merk dir nicht nur install.