powersync-docs/docs/optimiseur/ecrire.de.md

Einen Optimierer schreiben

Ein Optimierer ist ein Server, der das Protokoll spricht: Er antwortet auf den Handshake und dann auf jedes GetPlan mit einem Plan aus einem oder mehreren Zeitfenstern oder mit einer Enthaltung. Die Sprache ist frei. Ein minimaler Optimierer passt in rund fünfzig Zeilen Python.

Minimale Sitzung, zur Veranschaulichung (die genaue Form steht im Vertrag):

→ {"jsonrpc":"2.0","id":1,"method":"Handshake","params":{"protocolVersion":"1.1","engine":"etm-powersync-energy-plugin-etm/…"}}
← {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"1.1","name":"mein-optimierer","planning":false}}
→ {"jsonrpc":"2.0","id":2,"method":"GetPlan","params":{ …Kontext… }}
← {"jsonrpc":"2.0","id":2,"result":{"abstain":true,"reason":"premier calcul en cours"}}

Drei Punkte, die man nicht übersehen sollte:

• eine Aktion je verfügbarem Verbraucher im aktuellen Zeitfenster, jede mit ihrem Grund als Text (auf Französisch): sonst wird der ganze Plan abgelehnt;
• schnell antworten: den zuletzt zwischengespeicherten Plan liefern oder sich enthalten, und im Hintergrund rechnen;
• nichts anderswo holen: Alles, was der Optimierer braucht, Prognosen inbegriffen, steht im Kontext.

Der Referenz-Optimierer

Das Engine-Repository enthält einen freien Referenz-Optimierer (GPL-3.0) in Python, nur mit der Standardbibliothek: tools/etm-powersync-ref-optimizer/. Er antwortet mit einem Plan aus einem Zeitfenster, der die Kaskade der Engine-Regeln nachbildet, und liest dabei nur den Kontext. Beim Handshake meldet er sich als powersync-optimizer.

Er ist Ausgangspunkt für einen eigenen Optimierer und Vergleichsmaßstab: Er lauscht standardmäßig am lokalen Socket oder an tcp:// mit einem gemeinsamen Geheimnis, das aus einer Datei gelesen wird. Er kann auch Fehler einspeisen (Enthaltung, Langsamkeit, ungültiger Plan, andere Hauptversion…), um den Rückfall der Engine zu testen. Anleitung: seine README.md.

Die Engine an den eigenen Optimierer anbinden

Drei JSON-RPC-Methoden der Box (die ersten beiden dem Administrator vorbehalten); ihre genaue Form liefert die Box selbst über JSONRPC.Introspect:

• NymeaEnergy.SetOptimizerEndpoint — wohin verbinden (unix:///… oder tcp://host:port);
• NymeaEnergy.SetOptimizerToken — das gemeinsame Geheimnis, dasselbe wie beim Optimierer;
• NymeaEnergy.GetOptimizerStatus — Zustand der Verbindung: Optimierer lebt, aktive Strategie, gemeldeter Name, letzter Fehlercode.

Über tcp:// ohne Verschlüsselung läuft das Geheimnis im Klartext durch das lokale Netz.

Die Konformitäts-Testsuite

Die Suite etm-powersync-optimizer-conformance startet Ihren Optimierer und schließt die echte Engine daran an, mit simulierten Geräten. Sie prüft, eine Funktion je Punkt:

1. der Handshake wird angenommen;
2. jedes GetPlan wird innerhalb der Frist der Engine beantwortet;
3. die gesamte Sitzung, in beide Richtungen, entspricht dem von der Engine mitgebrachten Vertrag, Prüfregeln inbegriffen;
4. jeder Plan wird angewendet: Der Optimierer steuert;
5. die Sicherheitsschleife bleibt obenauf: Ein Sollwert außerhalb der Grenzen wird gekappt, eine Phasenüberlast wird abgeworfen.

Die Qualität der Pläne bewertet sie nicht.

Gegen den eigenen Optimierer ausführen

Die Engine mit ihren Tests bauen, dann den Befehl angeben, der Ihren Server startet; {endpoint} wird darin durch die Adresse ersetzt, an der gelauscht werden soll:

export ETM_POWERSYNC_OPTIMIZER_CMD='exec /pfad/zu/mein-optimierer --listen {endpoint}'
export ETM_POWERSYNC_CONFORMANCE_EXPECT=plan     # oder abstain

Jede Funktion läuft in einem eigenen Prozess. Der vollständige Befehl (Netzisolierung empfohlen), die übrigen Variablen (gemeinsames Geheimnis, Startfrist…) und das Lesen der Fehlschläge stehen in der README.md der Suite.

Erwarteter Modus: plan oder abstain

ETM_POWERSYNC_CONFORMANCE_EXPECT sagt der Suite, was Ihr Optimierer tut:

• plan (Standard): Er steuert. Jeder Zyklus muss seinen Plan anwenden.
• abstain: Er enthält sich in jedem Zyklus — das ist erlaubt und konform. Die Suite prüft dann, dass die Engine in jedem Zyklus nach ihren Regeln steuert, ohne Fehler zu zählen, und dass die Sicherheit weiter greift; die Prüfung der Kappung entfällt, da es keinen Sollwert zu kappen gibt.

Jeder andere Wert lässt die Suite scheitern. Der Modus wird nicht aus dem Handshake abgeleitet: planning und capabilities beschreiben die Form der Pläne, nicht, ob welche erzeugt werden. Der Modus wird angegeben, nicht erraten.

Auf denselben Eingaben vergleichen

Die Engine kann auf der Box jeden Zyklus aufzeichnen (standardmäßig aus, NymeaEnergy.SetOptimizerTrace). Das Werkzeug tools/etm-powersync-trace-replay spielt diese Aufzeichnungen einem Kandidaten-Optimierer vor und fasst die Abweichungen zum aufgezeichneten Plan zusammen. Die Aufzeichnungen bleiben vor Ort.