feat: open Athena tool architecture

2026-08-24 12:46:33 +02:00
parent 5528f3ab22
commit 5db73d0a92
26 changed files with 430 additions and 212 deletions
@@ -0,0 +1,83 @@
+# Werkzeugarchitektur ab 24. August 2026
+
+## Ziel
+
+Athena darf nicht für jede neue Website oder jede neue Verwaltungsaufgabe ein
+neues Werkzeug benötigen. Die Plattform stellt deshalb breite Grundfähigkeiten
+bereit und ergänzt sie nur dort durch Fach-MCPs, wo eine strukturierte API einen
+echten Vorteil bietet.
+
+## Die drei Ebenen
+
+1. **Breites Web:** OpenWebUI hält `search_web` und `fetch_url` in allen
+   normalen Profilen verfügbar. MakerWorld, eBay, Herstellerseiten oder eine
+   morgen neu entstehende Website benötigen keine Selector-Änderung. Für
+   Hermes, Pi und andere MCP-Clients liegt derselbe allgemeine Einsatzzweck über
+   den unveränderten TinySearch-Upstream-MCP auf VPN-Port 8203 bereit.
+2. **Breiter Operator:** Der Athena Operator enthält neben strukturierten
+   Plattformaktionen ein ausgabebegrenztes allgemeines Terminal. Es deckt
+   Docker, Compose, Dateien, Git, HTTP/API, Modellarbeit und SSH zu
+   konfigurierten Zielsystemen ab. Eine kleine serverseitige Sperre verhindert
+   ausschließlich Strombefehle und Änderungen an Athenas SSH, LAN, WireGuard,
+   Firewall, Boot, Kernel, Mounts und Partitionen, weil Athena physisch nicht
+   erreichbar ist.
+3. **Fach-MCPs:** Home Assistant, MUA/Unraid, ARR, Navidrome und GitHub bleiben
+   erhalten. Sie liefern kurze strukturierte Ergebnisse und domänenspezifische
+   Schreibabläufe. Sie sind der bevorzugte Weg, aber keine Schranke: Fehlt eine
+   Spezialoperation, darf der Operator die Aufgabe allgemein erledigen.
+
+OpenWebUI ist Oberfläche und Komfortschicht. Der Auto Tool Selector hält Web
+bereit und hängt anhand der Anfrage passende Fachkataloge an. Er verweigert
+keine Fähigkeit und erfordert keine Site-spezifischen Regeln. Alle zentralen
+MCPs sind über feste WireGuard-Ports auch für Hermes und Pi erreichbar.
+
+## Agentische Grenzen
+
+- maximal 48 interne Werkzeugrunden
+- maximal 40 tatsächlich ausgeführte Einzelaufrufe
+- maximal 12 Aufrufe desselben Werkzeugnamens
+- identischer Werkzeugname mit identischen Argumenten darf einmal wiederholt
+  werden; der dritte identische Aufruf wird unterdrückt
+- ein unterdrückter Parallelaufruf beendet nicht mehr die gesamte Recherche,
+  solange im selben Stapel noch sinnvolle Aufrufe vorhanden sind
+- bei ausgeschöpftem Budget folgt zwingend eine werkzeugfreie, sichtbare
+  Schlussantwort aus den bereits erhobenen Befunden
+- Werkzeugausgaben bleiben kurz: 12.000 Zeichen je Ergebnis und 64.000 Zeichen
+  über den Verlauf; ältere Resultate werden zuerst verdichtet
+
+Damit stoppt die Plattform bewiesene Schleifen, nicht normale lange Recherche.
+Die früheren Grenzen von zwölf Gesamtaufrufen und vier Aufrufen je Werkzeug
+waren für Qwen3.8-Agentenaufgaben zu klein.
+
+## Webwege
+
+| Client | Standardweg |
+|---|---|
+| OpenWebUI | native `search_web` und `fetch_url`, immer verfügbar |
+| Hermes/Pi/andere MCP-Clients | `http://192.168.1.212:8203/mcp` (TinySearch) |
+| Spezial-/Rollbackbedarf | historischer `mcp-web` nur mit Compose-Profil `legacy-web` |
+
+TinySearch stellt die vier Upstream-Werkzeuge `search`, `scrape_urls`,
+`research` und `get_current_datetime` bereit. Die frühere selbstgeschriebene
+Web-Fassade wird nicht mehr standardmäßig gestartet und liegt nur für Rollback
+im Repository.
+
+## Sicherheitsgrenze
+
+Über die WireGuard-Adresse sind die Dienste normal nutzbar. Auf der physischen
+Universitätsadresse bleiben UI, Router und MCP-Ports geschlossen. Die
+Terminal-Sperre schützt ausschließlich die entfernte Erreichbarkeit; sie ist
+kein allgemeiner Funktions- oder Internetfilter.
+
+## Abnahme
+
+Nach Änderungen müssen mindestens folgende Prüfungen erfolgreich sein:
+
+1. `python3 dev/test_openwebui_filters.py`
+2. `python3 dev/test_athena_operator.py`
+3. `docker compose -f compose.yaml config -q`
+4. `docker compose -f platform/mcp/compose.yaml config -q`
+5. `dev/verify_mcp_catalogs.sh`
+6. Browserlauf mit einer unbekannten öffentlichen Website, GitHub plus
+   Laufzeitprüfung sowie einer mehrstufigen Home-/Unraid-Aufgabe
+