major
#29430
Die Headless-Agent-/Skript-Schnittstelle der React-Ansichtsebene fertigstellen
Problem
Die React-Ansichtsebene verfügt über eine kopflose Steuerungsoberfläche (com.top_logic.layout.react.scripting), die im Rahmen von #29108 entwickelt wurde. Sie bedient drei Verbraucher über einen einzigen Mechanismus: den Skript-Recorder, die deterministische Wiedergabe und einen Agenten, der eine Sitzung im Auftrag eines Benutzers steuert.
Das Substrat funktioniert und wird live anhand der Demo verifiziert:
- Beobachten / Auflösen / Reagieren auf ScriptingSession, wobei die Befehle über genau denselben ReactControl.executeCommand gesendet werden, den auch der Browser verwendet.
- Stabile semantische Adressierung (ScriptingTreeProjector): „role[name]“ -Pfade plus Navigations-Slots, mit einer Identität anhand des Geschäftsschlüssels (ModelName) für Datenknoten; Adressabweichungen führen zu einem harten Fehler statt zu einer stillen Ersetzung.
- Recorder: Als getippte ReactCommand-Konfigurationselemente erfasste Browserbefehle, wiedergabestabile Argumente (selectByKey), Assertion-Schritte, ein Recorder-Seitenfenster mit einem Schritt-Debugger.
- Affordance-orientierte „observe?mode=actions“- Projektion und JSON-Argumentschemata, abgeleitet aus dem ConfigurationItem-Deskriptor des Befehls.
Was fehlte, war alles, was aus einem funktionierenden Prototyp eine Funktion macht: das Autorisierungs- und Sitzungsmodell für Aufrufer außerhalb des Browsers, das Modell für Lese-Parallelität und die Produktionsreife.
Fertig
Befehlshandler lehnen ab, was die Benutzeroberfläche nicht anbietet
Acting durchläuft denselben Dispatch wie der Browser, daher war ein Befehl, dessen Ausführbarkeit zur Laufzeit neu bewertet wird, bereits sicher – aber nicht jeder Pfad war es. Ein Durchlauf aller 84 @ReactCommandHandler-Method en deckte vier Klassen von Lücken auf und schloss sie: Feldschreibvorgänge, die die Bearbeitbarkeit ignorierten; Befehle im Formularlebenszyklus, die ihre eigenen Befehlsmodelle umgingen; Dispatcher-Befehle, die eine Aktion aufriefen, ohne sie erneut zu überprüfen; und eine Schaltfläche, deren CommandModel die Ausführung bedingungslos zuließ. Die Feldprüfung ist strukturell angelegt: Ein „final“-Handler leitet jeden Client-Wert durch einen einzigen geschützten Einstieg, und Unterklassen überschreiben die darunter liegenden „apply“- und „commit“-Hooks.
Ein Formular kann nun mit der Berechtigung konfiguriert werden, sein Objekt überhaupt bearbeiten zu dürfen (<edit-executability> akzeptiert die üblichen `ViewExecutabilityRules`, z. B. eine `SecurityRule`); zuvor gab es keinen Konfigurationspunkt für die Berechtigung, die Schreibzugriff gewährt.
Ein Konto lädt einen Agenten in seine Sitzung ein
Ein Konto versendet eine Einladung – die öffentlich erreichbare Adresse der Anwendung zusammen mit einem Token in einer Zeile, sodass ein Agent mit einer einzigen Nachricht eingeladen wird. Das Token ist an die Sitzung gebunden, aus der es ausgestellt wurde, und verfällt mit dieser; nur sein Hash wird gespeichert, und der Klartextwert ist genau einmal lesbar. Der Geltungsbereich ist „beobachten“ oder „beobachten und handeln“; ein Beobachtungstoken wird bei jeder Schreibanforderung abgelehnt. Eigentümer ziehen ihre eigenen Token zurück, Administratoren die aller Benutzer; durch das Zurückziehen werden sie gelöscht, und eine tägliche Aufgabe löscht die abgelaufenen.
Ein eigenes Modul
Der agentenspezifische Teil wurde aus dem React-Kernmodul ausgelagert: com.top_logic.layout.view.agent (tl-layout-view-agent) enthält das AgentServlet mit seiner /agent-api/*-Zuordnung, die Zulassungsprüfung (AgentAuthenticator) sowie die Zugriffstoken mit ihrem Modell, ihren Ansichten, der Bereinigungsaufgabe und dem Admin-Bereich. Die Schnittstelle selbst verbleibt im Kernmodul, wo sie vom Skript-Recorder genutzt wird, und ist nach dem Skripting der Legacy-Anwendung benannt. Eine Anwendung, die keinen Agentenzugriff wünscht, stellt das Modul nicht bereit – was auch die Frage der umgebungsspezifischen Aktivierung klärt.
Migration
Der Agent-Endpunkt /agent-api/* wird nicht mehr von tl-layout-react registriert; er wurde in das optionale Modul tl-layout-view-agent (com.top_logic.layout.view.agent) verlagert. Eine Anwendung, die den Agentenzugriff nutzt (einen Agenten oder MCP-Wrapper auf /agent-api), muss die Abhängigkeit com.top-logic:tl-layout-view-agent hinzufügen; der Zugriff erfordert dann ein Zugriffstoken, das von einem angemeldeten Benutzer in seiner Sitzung ausgestellt wurde. Anwendungen ohne Agentenzugriff erfordern keine Änderungen. Java-Code, der das Paket com.top_logic.layout.react.headless verwendet, muss auf com.top_logic.layout.react.scripting umgestellt werden.
grep -rn -e 'agent-api' -e 'react.headless' .
Verbleibende Arbeiten
Die verbleibenden Aufgaben sind separat erfasst: #30048 (Agentenzugriff: eigene Sitzung, wer Token ausstellen darf, Token beendeter Sitzungen, Audit, MCP-Wrapper, Integrationstest), #30049 (Beobachtung ohne Blockierung der Sitzung, Ruhezustand, nur ausführbare Aktionen, begrenzte Beobachtung, Roh- vs. kuratierte Projektion) und #30050 (Skriptrekorder: dauerhaft gespeicherte Skripte, wiedergabe-stabile Bäume und Mehrfachauswahl, sitzungsunabhängige Assertions, Variablen, sitzungsübergreifende Tests).
Referenz
Entwicklerartikel „view-layer/headless-interface“ (tl-layout-react) und „view-layer/agent-access“ (tl-layout-view-agent).