fix(tools): harden OpenWebUI tool workflows

2026-08-24 00:40:32 +02:00
parent bfb990a4fd
commit e24839bfe1
24 changed files with 505 additions and 100 deletions
@@ -0,0 +1,69 @@
+# Werkzeug-Zuverlässigkeit – Umbau vom 24. August 2026
+
+## Anlass
+
+Mehrere reale Aufgaben scheiterten nicht am Qwen-Modell, sondern an der
+Werkzeugschicht: öffentliche Suchen lieferten leere oder veraltete Resultate,
+ein rekursiver GitHub-Baum verdrängte die Antwort aus dem Kontext, eine private
+Bank-CSV wurde als Knowledge-Quelle statt als Tabelle behandelt und ein nicht
+erreichbarer Home-Assistant-Endpunkt provozierte Wiederholungen. Das System
+benötigte deshalb kleinere, klarere Werkzeuge und harte Abbruchgrenzen.
+
+## Verbindliche Lösung
+
+1. Allgemeine öffentliche Recherche verwendet Open WebUIs native
+   `search_web`- und `fetch_url`-Werkzeuge. Der eigene Web-MCP bleibt nur als
+   manuell zugeschalteter Spezialadapter für YouTube und Hugging Face.
+2. Der offizielle GitHub-MCP bietet genau drei read-only Werkzeuge:
+   `search_repositories`, `search_code` und `get_file_contents`. Rekursive
+   Komplettbäume sind ausgeschlossen.
+3. Private CSV-/Excel-Dateien werden ausschließlich mit dem lokalen
+   Code-Interpreter und pandas/openpyxl ausgewertet. Web, MCP und Knowledge/RAG
+   erhalten keine Dateiinhalte oder daraus abgeleitete Suchbegriffe. Der Filter
+   leert dafür die MCP-Auswahl und deaktiviert `features.web_search`; im
+   installierten OpenWebUI-Code läuft der Filter nachweislich vor der
+   Webwerkzeug-Injektion.
+4. Pro Antwort sind höchstens zwölf Werkzeugrunden erlaubt. Der zweite
+   identische Aufruf wird gestoppt. Ein einzelnes Resultat ist auf 10.000, alle
+   Resultate zusammen auf 36.000 Zeichen begrenzt.
+5. Der Home-Assistant-MCP behält den TLS-Namen `ha.casaderoll.de`, routet ihn
+   im Container aber auf `HOME_LAN_PROXY_IP` im Heimnetz. Dadurch funktioniert
+   er auch vom Außenstandort über WireGuard.
+6. Task-Management ist keine Faktenquelle und wird nicht für einzelne Fragen,
+   Nachschlageaufgaben oder Dateianalysen verwendet.
+
+## Abnahme
+
+- OpenWebUI-Filtertests: 28
+- Web-MCP-Tests: 9
+- Athena-Operator-Sicherheitstests: 11
+- Platform-Context-Test: bestanden
+- MCP-Katalog-TÜV: Handshake, Toolanzahl, Schema-Größe, Regex-Muster und
+  verbotene Tools; keinerlei fachliche Toolaufrufe
+- Gesamttest des Routers: Profile, Streaming, Tools, Bild, Sprache und
+  Fehlerwiederherstellung
+
+Der wiederholbare MCP-Test lautet:
+
+```bash
+sudo /opt/mike-ai/stack/dev/verify_mcp_catalogs.sh
+```
+
+Er muss mit `MCP_CATALOG_SUITE_OK` enden.
+
+## Noch manuell zu prüfen
+
+Ein echter Browsertest mit einer bewusst synthetischen CSV benötigt eine
+angemeldete OpenWebUI-Sitzung. Nach Login wird eine harmlose Beispieltabelle
+hochgeladen und geprüft, dass die Antwort sichtbare Summen enthält und in der
+Werkzeuganzeige ausschließlich lokale Datei-/Codewerkzeuge erscheinen. Für
+diesen Test dürfen niemals echte Bankdaten verwendet werden.
+
+## Rollback
+
+Vor dem Live-Umbau liegt die Quell- und Konfigurationssicherung unter
+`/data/mike-ai-recovery/pre-tooling-upgrade-20260823-235527`. OpenWebUIs
+Datenbank wurde zusätzlich unmittelbar vor Filter- und Modellinstallation
+gesichert. Ein Rollback betrifft ausschließlich Werkzeug-/OpenWebUI-Dateien;
+Netzwerk, SSH, WireGuard, Kernel, GPU-Treiber und Bootkonfiguration wurden nicht
+verändert.