Simplify Athena operator architecture
This commit is contained in:
Mikei386
+26
-129
@@ -1,141 +1,38 @@
|
||||
# Athena Platform Context MCP
|
||||
|
||||
Stand: 23. August 2026
|
||||
|
||||
## Zweck
|
||||
|
||||
`mike-ai-mcp-platform-context` gibt jedem MCP-fähigen Client dasselbe
|
||||
versionierte Wissen über Athena und MikeAI. Dadurch kann in Open WebUI zwischen
|
||||
Fast, Medium, Large und Ultra gewechselt werden, ohne den vollständigen
|
||||
Operator-Kontext in jeden Prompt zu kopieren.
|
||||
|
||||
Der MCP ist zugleich das kontrollierte Pflegefenster für seine eigene
|
||||
Dokumentation. Er ist **kein** allgemeiner Athena-Administrator und erhält
|
||||
weder Docker-Socket noch Shell, Git-Schlüssel oder Secrets. Sein Netzzugang ist
|
||||
auf feste, versionierte Erreichbarkeitsprüfungen aus dem Diensteverzeichnis
|
||||
beschränkt; Modellparameter können keine freie Adresse vorgeben.
|
||||
Der Context-MCP ist die kleine, ausschließlich lesende Auskunftsstelle für
|
||||
Athena. Der verbindliche Einstieg ist die kurze Datei [`../ATHENA.md`](../ATHENA.md).
|
||||
|
||||
## Werkzeuge
|
||||
|
||||
| Werkzeug | Wirkung |
|
||||
|---|---|
|
||||
| `athena_get_overview` | kurze Architektur und Quellenhierarchie |
|
||||
| `athena_get_current_state` | begrenzter aktueller Snapshot ohne Nutzdaten |
|
||||
| `athena_get_external_services` | vorhandene externe Dienste plus feste, bounded Erreichbarkeitsprüfung |
|
||||
| `athena_search_knowledge` | Suche in Dokumentation und versionierten Quellen |
|
||||
| `athena_read_source` | begrenzter Ausschnitt einer ausgewählten Textdatei |
|
||||
| `athena_get_change_workflow` | verbindlicher Ablauf je Änderungstyp |
|
||||
| `athena_prepare_documentation_update` | erzeugt nur eine prüfbare Vorschau |
|
||||
| `athena_apply_documentation_update` | schreibt nach Freigabe ausschließlich `docs/*.md` |
|
||||
| `athena_get_maintenance_status` | zeigt offene Git-/Recovery-Schulden |
|
||||
| `athena_close_maintenance_record` | schließt Schulden erst nach geprüftem Git-Deploy und neuerem Recovery-Koffer |
|
||||
| Werkzeug | Zweck | Grenze |
|
||||
|---|---|---|
|
||||
| `athena_get_overview` | liefert `ATHENA.md` | höchstens 14.000 Zeichen |
|
||||
| `athena_get_current_state` | kompakter Host-Snapshot | keine Logs oder Secrets |
|
||||
| `athena_get_external_services` | bekannte externe Dienste | keine freie Netzwerksuche |
|
||||
| `athena_search_reference` | gezielte Quelltextsuche | höchstens 8 kurze Treffer |
|
||||
| `athena_read_reference` | kleiner Dateiausschnitt | höchstens 160 Zeilen |
|
||||
|
||||
## Aktueller Zustand ohne Docker-Socket
|
||||
Ein fehlender Pfad ist ein normales Suchergebnis mit `retry: false`, kein
|
||||
Serverfehler. Das verhindert Werkzeug- und Denkschleifen.
|
||||
|
||||
`mike-ai-platform-context-snapshot.timer` startet jede Minute einen kurzen,
|
||||
fest programmierten Host-Snapshot. Er erfasst ausschließlich:
|
||||
Der Container kann nichts verändern. Er hat keinen Docker-Socket, keine Shell,
|
||||
keine Secrets und keinen Internetzugriff. Änderungen erledigt der Athena
|
||||
Operator direkt im Git-Arbeitsbaum `/opt/mike-ai/stack`.
|
||||
|
||||
- Hostname, Debian-/Kernel-Version und Uptime
|
||||
- grobe RAM- und Dateisystembelegung
|
||||
- GPU-Name, UUID, VRAM-Belegung und Treiberversion
|
||||
- Name, Image und Status der laufenden `mike-ai-*`-Container
|
||||
- aktives Inferenzprofil
|
||||
- installierten Quellcommit, Hash des Dokumentationsbaums und Status des
|
||||
Recovery-Koffers
|
||||
Der Host erzeugt einmal pro Minute einen begrenzten Snapshot. Er enthält nur
|
||||
Host-/GPU-/Dateisystemdaten, Status und Image der `mike-ai-*`-Container, das
|
||||
aktive Profil, den Git-Commit und den Recovery-Status. Prompts, Chats, Logs,
|
||||
Container-Umgebungen und Secretwerte werden nicht erfasst.
|
||||
|
||||
Nicht erfasst werden Logs, Prompts, Chats, Toolinhalte, Container-Umgebungen,
|
||||
Dateiinhalte außerhalb der versionierten Dokumentation oder Secretwerte. Der
|
||||
Container liest nur die erzeugte JSON-Datei. Ein Snapshot älter als drei
|
||||
Minuten gilt als veraltet.
|
||||
## Verwendung
|
||||
|
||||
Das zusätzliche Diensteverzeichnis unter `config/service-catalog.json` enthält
|
||||
nur bekannte interne Namen, Adressen, Ports, Zuständigkeiten und Zwecke, keine
|
||||
Zugangsdaten. `athena_get_external_services` prüft ausschließlich diese festen
|
||||
Einträge. Es ist kein Portscanner, liest keine Antwortinhalte und akzeptiert
|
||||
keine URL oder Adresse aus dem Modell. Für Details bleibt anschließend das im
|
||||
Katalog genannte Fachwerkzeug zuständig.
|
||||
Für normale Athena-Arbeiten:
|
||||
|
||||
## Dokumentationspflege
|
||||
1. Überblick einmal lesen.
|
||||
2. Zustand einmal prüfen.
|
||||
3. Nur bei Bedarf gezielt suchen und kleine Ausschnitte lesen.
|
||||
4. Danach mit dem Operator arbeiten; nicht alle Dokumente vorsorglich laden.
|
||||
|
||||
Die Pflege ist absichtlich zweistufig:
|
||||
|
||||
1. Qwen prüft Laufzeit und Quellen und ruft
|
||||
`athena_prepare_documentation_update` auf.
|
||||
2. Das Werkzeug speichert einen Vorschlag unter
|
||||
`/data/mike-ai-platform-context/pending` und liefert ID, Hashes und die
|
||||
genaue Freigabezeichenfolge zurück. Noch wurde nichts geändert.
|
||||
3. Qwen zeigt den Vorschlag dem Benutzer und beendet die autonome Werkzeugkette.
|
||||
4. Erst nach ausdrücklicher Freigabe darf
|
||||
`athena_apply_documentation_update` mit `APPLY <proposal-id>` aufgerufen
|
||||
werden.
|
||||
5. Vorherige Dateien werden unter
|
||||
`/data/mike-ai-platform-context/backups` gesichert, neue Inhalte atomar
|
||||
geschrieben und unter `applied` protokolliert.
|
||||
|
||||
Der Server akzeptiert nur einfache Markdown-Dateien direkt unter `docs/`.
|
||||
Code, Compose, Profile, Installer, Netzwerke, Services, Git und Secrets können
|
||||
über diesen Schreibweg nicht verändert werden.
|
||||
|
||||
## Git und Recovery
|
||||
|
||||
Die kanonische Quelle ist der private Gitea-Stand
|
||||
`ssh://git@192.168.1.2:33/michael/AI-Profile-Router.git`, Branch `main`, im
|
||||
Working Tree `/data/mike-ai-operator/repository`. Das
|
||||
Installationsverzeichnis `/opt/mike-ai/stack` ist eine ausgerollte Kopie und
|
||||
kein Git-Working-Tree; `.mike-ai-source-commit` benennt den ausgerollten
|
||||
Commit. Der offizielle GitHub-MCP ist read-only und kann dieses private
|
||||
Gitea-Repository weder ändern noch pushen. Dafür besitzt der Athena Operator
|
||||
den autorisierten, strukturierten Arbeitsweg. Ein Modell darf weder im eigenen
|
||||
Sandbox-Container einen weiteren Clone anlegen noch einen SSH-Schlüssel
|
||||
anfordern oder kopieren.
|
||||
|
||||
Der verbindliche Ablauf für dauerhafte Änderungen lautet:
|
||||
|
||||
1. Kleine Änderungen mit `patch_update` als SHA-geschützten Unified Diff
|
||||
vorbereiten. `file_update` ist neuen oder vollständig ersetzten Dateien
|
||||
vorbehalten.
|
||||
2. Für einen normalen MCP-Lifecycle bevorzugt ein einziges `mcp_release`
|
||||
vorbereiten und nach separater Benutzerfreigabe ausführen. Es bündelt
|
||||
Prüfungen, benannten Compose-Deploy, OpenWebUI-Sync, selektiven Git-Publish
|
||||
und Recovery.
|
||||
Bereits geprüfte lange Quelldateien werden mit `imports` plus exakter
|
||||
SHA-256-Prüfsumme aus einem freigegebenen Staging-Verzeichnis übernommen;
|
||||
sie werden nicht als Chattext oder Full-File-Payload nachgebaut. Änderungen
|
||||
an `platform/hermes/config.yaml` verwenden `hermes_sync: true`. Für rein
|
||||
interne MCPs wird WireGuard nicht geändert.
|
||||
3. Einzeloperationen `run_checks`, `compose_deploy`, `git_publish` und
|
||||
`recovery` nur für Diagnose oder bewusst partielle Wartung verwenden.
|
||||
Fremde Dirty-Worktree-Dateien bleiben unberührt.
|
||||
|
||||
Das allgemeine Terminal ist weder Ersatz für diesen Ablauf noch ein Weg zu
|
||||
Git-Schlüsseln. `/data/mike-ai-operator/repository` muss aus der
|
||||
Modellsandbox nicht direkt erreichbar sein; der rootseitige Executor besitzt
|
||||
den notwendigen Zugriff.
|
||||
|
||||
Eine angewandte Dokumentationspflege ist erst vollständig abgeschlossen, wenn
|
||||
die dafür vorgesehenen Athena-Operator-Operationen Folgendes bestätigt haben:
|
||||
|
||||
1. dieselbe Änderung ist im privaten Quellrepository geprüft, committed und
|
||||
gepusht;
|
||||
2. der Commit wurde nach Athena ausgerollt und `.mike-ai-source-commit` stimmt;
|
||||
3. ein neues verschlüsseltes Recovery-Bundle und ein neues
|
||||
`/data/mike-ai-recovery-kit` wurden erzeugt und geprüft.
|
||||
|
||||
Der Context MCP meldet diese Punkte nach jeder Anwendung ausdrücklich als
|
||||
offen. Er darf sie nicht selbst als erledigt markieren. Lokale Vorschläge,
|
||||
Backups und Dokumentations-Overlays werden im verschlüsselten Recovery-Bundle
|
||||
mitgesichert, sodass ungepushte Dokumentationspflege bei einem SSD-Ausfall
|
||||
nicht vollständig verloren geht. Das ersetzt keinen Git-Commit.
|
||||
|
||||
## Verwendung in Open WebUI
|
||||
|
||||
Das Werkzeug `Athena Plattformwissen` wird nur bei Arbeiten an Athena/MikeAI
|
||||
aktiviert. Ein geeigneter Startauftrag lautet:
|
||||
|
||||
> Nutze zuerst das Athena-Plattformwissen. Prüfe den aktuellen Zustand und die
|
||||
> relevanten Quellen. Plane danach die gewünschte Änderung mit Rückweg. Nimm
|
||||
> keine risikoreiche Aktion und keine Dokumentationsanwendung ohne meine
|
||||
> ausdrückliche Freigabe vor.
|
||||
|
||||
Das funktioniert unabhängig vom gewählten Textprofil. Für normale Gespräche
|
||||
bleibt der MCP deaktiviert und verbraucht damit keinen Werkzeugkontext.
|
||||
Historische Langdokumente unter `docs/` sind Nachschlagewerke. Sie werden nicht
|
||||
automatisch in einen Modellkontext geladen.
|
||||
|
||||
Reference in New Issue
Block a user