Ein internes Hermes-Modul importieren? Jetzt gibt es eine veröffentlichte Liste, was Plugins importieren dürfen

Dein Plugin ist seit drei Monaten im Einsatz, ohne Beschwerde. Dann kommt ein neues Hermes-Release, ein Nutzer upgradet, und das Plugin lädt nicht mehr — ImportError. Du gehst das Changelog durch: nichts erwähnt dein Plugin. Du gehst deinen Code durch, und der Übeltäter ist eine Zeile, die du vor einem halben Jahr geschrieben hast — from hermes_cli.cli_config_load import _parse_service_tier_config —, die auf eine interne Funktion zeigt, die inzwischen umgezogen ist.
Was diese Art Unfall so unangenehm macht, ist, dass im Moment des Schreibens nichts schiefgeht. Das Plugin installiert, läuft und besteht seine Tests. Das ist eine verzögerte Ladung, und bei der Änderung unten geht es darum, sie früh sichtbar zu machen.
Warum ein privater Import immer ein künftiger Bruch ist
Hermes hat bereits einen Runtime-Check, die Core-Override-Regel: Ein Plugin darf zur Laufzeit keine Funktion in einem Core-Modul neu binden. Dieser Check regelt aber das Ersetzen, nicht das Referenzieren. Ein Import eines internen Moduls besteht ihn — und dann hängst du an jemandes privater Implementierung, die kein Kompatibilitätsversprechen trägt: Sie kann umbenannt, verschoben oder in einem Refactor entfernt werden, von dem du nie hörst.
Für einen Plugin-Autor kommt der Preis spät; für einen Reviewer ist er in ein paar hundert Zeilen Code fast unsichtbar. Was das Problem eigentlich braucht, ist eine statische, mechanisch entscheidbare Grenze: Steht das, was du importiert hast, auf der veröffentlichten Liste?
Die Liste ist aus dem Code gezogen
Sie war früher ein frozenset, hardcodiert in hermes_cli/plugin_validate_private_imports.py. Brauchbar, aber für Plugin-Autoren unsichtbar — du erfuhrest, was draufstand, wenn CI auf deine Zeile zeigte.
Die Änderung vom 5. November verschob die Liste unverändert nach hermes_cli/data/plugin_api.json (schon als Package-Data ausgeliefert), und der Validator liest sie von dort. Ein Generator-Skript rendert die Docs-Seite developer-guide/plugins/public-api.md aus derselben Datei, und — der wichtige Teil — ein Test schlägt fehl, wenn die Seite veraltet ist. Die Liste kann nicht still driften: Sie zu ändern erzwingt, dass die Docs mitgehen.
Einen Tag später bekam die Liste ihren ersten Eintrag, der klar „was ein Plugin aufrufen sollte“ ist: agent.redact.redact_sensitive_text, unten behandelt.
Drei Urteile
Die Regel ist kurz:
- Eine Ganzmodul-Zeile (etwa
agent.memory_provider) erlaubt dieses Modul und jeden Namen darin, der nicht mit einem Unterstrich beginnt. - Eine Einzelnamen-Zeile (etwa
hermes_cli.auth_model_picker:prompt_model_selection) erlaubt nur diesen einen Namen. - Ein Hermes-Modul außerhalb der Liste: eine Warnung, nie ein Block.
Nicht zu blocken ist Absicht. Das ist der Hinweis des Admission-Gates (Katalogregel 9, nur öffentliche Oberflächen), kein Compiler: Das Plugin installiert weiter und läuft weiter, und sowohl Autor als auch Reviewer sehen „das bricht wahrscheinlich irgendwann“.
Vier Kategorien werden nie gemeldet: die Standardbibliothek, Third-Party-Packages, die eigenen Module des Plugins und Imports unter if TYPE_CHECKING:. Letzteres ist wirklich nützlich — wenn eine Typannotation einen internen Typ braucht, ist den Import in TYPE_CHECKING zu wickeln der saubere Weg. String-Imports über importlib.import_module("hermes_cli.…") werden ebenfalls aufgelöst, eine andere Schreibweise ist also kein Ausweg.
Wie die Warnung aussieht
Funde werden als relative/path.py:line module[.name] ausgegeben:
myplugin/tools.py:41 hermes_cli.cli_config_load._parse_service_tier_config
Ein Detail ist es wert, es zu kennen: Der Report listet die erste Fundstelle jedes unterschiedlichen Moduls vor den restlichen Fundstellen. Wird die Liste abgeschnitten, siehst du trotzdem die Breite — wie viele interne Module du berührst — statt zehn Zeilen desselben. In CI gibt dir --json einen maschinenlesbaren Report; --install-deps installiert deklarierte Abhängigkeiten vor der Capability-Probe, so wie das Catalog-Gate es ausführt.
Der neue Eintrag: redact_sensitive_text
Dieser verdient einen eigenen Abschnitt, weil er eine Frage beantwortet, die Plugin-Autoren ständig treffen: Ich will Nutzertext an ein Modell schicken. Wie maskiere ich vorher die Secrets?
Die alte Antwort war from agent.redact import redact_sensitive_text — sie funktionierte, aber der Validator warnte dich, weil sie privat war. Jetzt ist sie öffentliche API:
from agent.redact import redact_sensitive_text
text = redact_sensitive_text(user_text, force=True)
Warum eine Funktion statt eines redact=-Parameters auf ctx.llm? Weil ein Plugin denselben Text mehrmals anfassen kann — ihn zerschneiden, zusammenfügen, in einen Prompt einfügen —, und nur beim letzten Aufruf zu redigieren reicht nicht. Mit der Funktion in der Hand kannst du ihn säubern, wo immer es nötig ist.
Die force=True-Semantik ist der Teil, den man sich merken muss: Es ist der Schalter, der dir keinen Ausweg lässt. Standardmäßig folgt die Redaction der Einstellung security.redact_secrets des Operators; ist die aus, gibt die Funktion den Text unverändert zurück. Text, der an ein Modell geht, ist eine Sicherheitsgrenze, und dort sollte die Einstellung nicht entscheiden — daher force=True. Offiziell formuliert: Du nutzt es dort, wo Secrets niemals die Maschine verlassen dürfen.
Zwei weitere Parameter zählen. code_file=True überspringt die ENV/JSON-Zuweisungs-Pässe für bekannten Quellcode, ein Fixture wie MAX_TOKENS=*** überlebt also. file_read=True ist für Dateiinhalte, die an den Agenten zurückgehen: Präfix-gematchte Credentials wie ghp_… werden zu einem nicht wiederverwendbaren Sentinel statt zu einer Head/Tail-Maske, denn eine Head/Tail-Maske sieht wie ein echter, aber abgeschnittener Key aus — und ein Agent schreibt so etwas durchaus in die config.yaml zurück.
Dein eigenes Plugin prüfen
hermes plugins validate ./my-plugin
hermes plugins validate ./my-plugin --json
Suche nach Imports, die mit den Core-Packages beginnen — hermes_cli., agent., gateway., tools.. Findest du einen, gibt es drei Ausgänge: auf einen öffentlichen Eintrag der Liste wechseln; wenn er nur für eine Typannotation existiert, ihn unter TYPE_CHECKING packen; oder akzeptieren, dass du ein internes Modul brauchst, und planen, mit dem Core mitzuziehen — zumindest weißt du jetzt, wo du stehst.
Für das größere Bild, wie Plugins aufgenommen, installiert und aufgebaut werden, deckt der Plugin-Katalog-Guide das ab. Wenn dich interessiert, wie Secrets unterwegs behandelt werden, betrachtet die drei Redaction-Lanes dieselbe Maschinerie von der anderen Seite.
Kannst du es heute nutzen
Der Listen-Umzug und der neue Eintrag sind auf main (5.–6. November) und nicht im v0.23.0-Tag. Auf einem Stable-Build liest hermes plugins validate die Liste noch hardcodiert aus dem Quellcode, und redact_sensitive_text ist noch ein privater Import.
Update (10.11.2026): Diese Änderungen sind mit v0.23.1 (9. November) erschienen – ein
hermes updategenügt. Die Aussage „nicht in v0.23.0“ oben stimmt weiterhin; v0.23.1 schließt die Lücke.
Der Wert hängt aber nicht von der Version ab: Schreib jetzt gegen die veröffentlichte Seite. Was auf der Liste steht, ist stabil; was nicht draufsteht, ist geliehen. Diese Regel ändert sich mit keinem Release.
Das Fazit
Hier wurde kein Feature hinzugefügt. Sichtbarkeit wurde hinzugefügt. Eine Regel, die es immer schon gab und die nur Reviewer im Kopf hatten, ist jetzt eine Datei, die du lesen kannst, eine Seite, die du durchsuchen kannst, und ein Check, den deine CI laufen lassen kann — mit einem Test, der die Seite ehrlich hält. Es macht ein Plugin nicht schneller, aber es ist die Art Fundament, die es in zehn Releases noch installierbar hält.