Startseite Erkunden Hilfe
Anmelden
paul
/
hermes-chatto-plugin
1
0
Fork 0
Dateien Issues 0 Pull-Requests 0 Wiki
Branch: main
Branches Tags
hermes-chatt...
/
skills
/
chatto-plugin-update
/
SKILL.md

SKILL.md 8.1 KB
Permalink Verlauf Originalformat

name: chatto-plugin-update description: "Use when an installed Chatto plugin must catch up to its remote and the changes must go live in the running Hermes gateway." version: 1.2.0 author: Paul Klumpp license: MIT metadata: hermes:

tags: [chatto, plugin, update, git, gateway]

Chatto-Plugin updaten und Changes aktivieren

When to Use

Eine installierte Chatto-Plugin-Instanz soll auf den Stand ihrer Quelle gebracht werden, und die Änderungen sollen im laufenden Hermes Gateway aktiv werden.

Der Remote steht hier bewusst nicht: er gehört der Installation, nicht dem Plugin. git remote -v des Checkouts ist die Wahrheit, und für einen selbst geklonten Checkout ist das ein privater Remote, den kein mitgeliefertes Dokument kennen kann.

Schritt 1: Wo liegt die Instanz, und welche Art ist sie?

Nicht raten — die Fälle haben verschiedene Türen, und nicht jede lässt sich mit git bedienen. Genau eine Tür pro Fall; nie beide.

Zuerst feststellen, welche Art die Installation ist:

# 1) User-Install unter ~/.hermes/plugins/ (hermes plugins install)
ls -d ~/.hermes/plugins/chatto-platform \
      ~/.hermes/plugins/platforms/hermes-chatto-plugin 2>/dev/null

# 2) Gebündeltes Plugin im Hermes-Agent-Checkout (Source: bundled)
#    Hermes-Agent legt es als Symlink in plugins/platforms/ ab.
ls -Ld /home/paul/dev2/chatto-stuff/hermes-agent/plugins/platforms/hermes-chatto-plugin 2>/dev/null
readlink -f /home/paul/dev2/chatto-stuff/hermes-agent/plugins/platforms/hermes-chatto-plugin 2>/dev/null

Den Befund mit der Liste abgleichen:

Befund Art Tür (genau eine)
~/.hermes/plugins/chatto-platform/ mit .git und Provenance-Zeile per hermes plugins install hermes plugins update chatto-platform
~/.hermes/plugins/chatto-platform/ mit .git, ohne Zeile selbst geklont einmalig hermes plugins adopt chatto-platform, danach hermes plugins update chatto-platform
~/.hermes/plugins/platforms/hermes-chatto-plugin/ ohne .git Dateien kopiert (README Option B) kein Pull möglich — der User muss neu kopieren oder klonen
Symlink in hermes-agent/plugins/platforms/hermes-chatto-plugin → Git-Checkout (Source: bundled) gebündeltes Plugin / Dev-Checkout git pull im Checkout-Ziel (s.u.) — kein hermes plugins update

Im dritten Fall gibt es keinen Remote und kein git log: hermes plugins update verweigert hier ("no .git directory"). Das ist keine Störung, sondern der Zustand des Verzeichnisses — es zu umgehen hieße, den Zustand zu erfinden. Dem User sagen, dass er die Dateien neu holen muss, und dann bei Schritt 4 weitergehen.

Im vierten Fall (gebündelt) ist hermes plugins update chatto-platform keine Tür: das Plugin ist bundled, und hermes plugins update verweigert bundled Plugins ("This command only works on downloaded plugins; bundled ones can only be enabled or disabled"). Hier ist git pull im Checkout-Ziel die einzige Tür. git pull und hermes plugins update nicht mischen — das ist genau der Fehler, den dieser Skill vermeiden soll.

Ablauf

  1. Statusbericht: erst fetchen, nie behaupten — VOR der Tür. Für die Zusammenfassung in Schritt 4 wird der alte Stand gebraucht, also vor dem Update abgreifen:

    git -C "$REPO" fetch --all
git -C "$REPO" status -sb
git -C "$REPO" branch -avv

    Aussagen wie „synchron" nur NACH einem fetch — status -sb ohne fetch zeigt ahead/behind nur gegen den zuletzt bekannten Remote-Stand. Den alten Commit aus branch -avv ablesen und festhalten, nicht raten.

    1. Genau eine Tür benutzen. Je nach Art aus Schritt 1:
    2. User-Install (Fall 1/2): hermes plugins update chatto-platform — es zieht den Stand, verwirft veralteten Bytecode aus __pycache__, schreibt die neue Revision in die Install-Metadaten und fragt nach, wenn der neue Stand Capabilities mitbringt, die noch nicht freigegeben sind (fail closed: ohne Antwort bleiben sie nicht freigegeben). Zwei Fälle lehnt es ab und sagt es: ein gepinnter Checkout (dann hermes plugins install <quelle> --force --ref <40-stelliger SHA>) und ein Verzeichnis ohne .git. Ein Katalog-Install wird auf die geprüfte SHA zurückgesetzt, nicht gepullt — deshalb hier ausdrücklich kein git pull.
    3. Gebündelt (Fall 4): im Checkout-Ziel (das readlink -f-Ergebnis aus Schritt 1) git pull (bzw. git pull --ff-only) auf dem aktuellen Branch — für main ist das main. Damit werden die Änderungen in den Checkout gezogen, den der laufende Hermes-Gateway über den Symlink liest. Vendored Updates (chattolib) kommen als dist-info-Rename + RECORD- Änderungen mit — normal, und über den Neustart hinaus ohne Handlungsbedarf.
    4. Kopiert (Fall 3): keine Tür — User muss neu kopieren oder klonen, dann weiter bei Schritt 4.
    5. Commits zusammenfassen (Nutzersicht): bash git -C "$REPO" log <alter_stand>..<neuer_stand> # oneline git -C "$REPO" log <alter_stand>..<neuer_stand> --stat # Datei-Umfang <alter_stand> aus Schritt 2, <neuer_stand> aus Schritt 3 (der Revision, die Hermes gemeldet hat, oder HEAD des Checkouts). Commits haben ausführliche Messages — daraus eine nutzerverständliche Zusammenfassung machen: WAS ändert sich für den Bot-Nutzer, nicht Implementierungsdetails. Für jede Änderung eine Quelle angeben (Commit-Hash).

  2. Gateway-Neustart ANBIETEN (nie selbst ausführen): Plugin-Code-Änderungen werden erst nach einem Neustart des Hermes-Gateways aktiv — die laufende Session hält das alte Modul im Speicher.

    • Einfachster Weg: /restart als Chat-Nachricht (Gateway-Slash-Command, „Restart gateway after draining active runs"). Der User tippt es direkt im Channel/DM. IMMER zuerst diesen Weg nennen.
    • Aus der laufenden Agent-Session heraus ist ein Restart UNMÖGLICH: der Lifecycle-Guard blockiert jeden Versuch aus dieser Session, weil der Restart die eigene Session killt. Nicht umgehen versuchen; keine Restart-Skripte/Aliase bauen, wenn /restart genügt.
    • Ein hermes gateway restart oder systemctl restart … aus einer Bediener-Shell außerhalb des Gateway-Prozesses funktioniert — aber nur dort. Aus einem Tool-Aufruf dieser Session heraus ist es derselbe blockierte Fall. Bei benannten Profilen heißt der Unit hermes-gateway-<profil>, nicht hermes-gateway.service.
    • User fragen, ob jetzt neu gestartet werden soll (der laufende Bot ist dann kurz offline).

  3. Nach dem Neustart verifizieren: Plugin-Tools live testen (chatto_list_rooms via tool_call), im Log prüfen, dass der Adapter sauber lädt.

Fallstricke

  • git -C in JEDEM git-Kommando. git pull oder git log ohne -C trifft den Checkout der Session, nicht den Plugin-Checkout.
  • Aussagen über Sync-Status („synchron", „aktuell") NUR NACH git fetch treffen — ohne fetch ist der lokale Status wertlos.
  • hermes plugins adopt nur einmal und nur bei einem selbst geklonten Verzeichnis. Hat Hermes bereits eine Provenance-Zeile, lehnt der Befehl ab ("already has a provenance row") — das ist kein Fehler, sondern heißt: der Fall greift nicht.
  • Vendored Updates (chattolib) kommen als dist-info-Rename + RECORD-Änderungen mit — normal, und über den ganz normalen Neustart aus Schritt 5 hinaus ohne Handlungsbedarf.
  • Der Lifecycle-Guard prüft den Inhalt eines Skripts, sobald ein Shell-Interpreter es referenziert: bash -n skript.sh mit hermes gateway restart darin wird abgelehnt — auch unter einem anderen Dateinamen und auch als sh -n. chmod, mv und cp sind nicht betroffen. Ein Skript also nicht an den Interpreter geben, um es zu prüfen: Inhalt mit den Datei-Tools lesen. Es lohnt auch nicht, es umzubenennen — der Guard liest Bytes, nicht Namen.
  • Das Ausführen von /dev/null (oder /dev/zero, /dev/fd/N) lässt der Guard bewusst fehlschlagen. Das ist keine Störung, sondern das gewollte Verhalten. Eine Umleitung nach > /dev/null in einer Shell-Datei ist davon nicht betroffen — die wird maskiert.