Agent NAS v0.2
Deutsch

Architektur

Agent NAS hat vier Schichten und eine optionale Synchronisierungsschicht: Interface projiziert Fähigkeiten in vorhandene Schnittstellen, Trust ist die einzige Autorisierungsstelle, Memory macht aus Notizen durchsuchbares Wissen, und Store hält einen Tree mit Verlauf. Die Memory-Schicht lässt sich als Ganzes löschen und neu aufbauen, und Store nutzt schlicht bewährten Speicher.

v0.2 Spezifikationsentwurf Aktualisiert am

Vier Schichten und optionale Synchronisierung

  1. Interface

    Projiziert Fähigkeiten in Schnittstellen, die Agenten, Menschen und Werkzeuge bereits nutzen. Gateways sind zustandslos und entscheiden nie, wer was darf.

    • Mount (FUSE, NFS, SMB)
    • Git
    • S3-kompatibel
    • WebDAV
    • MCP
    • HTTP-API
    • CLI
    • A2A (optional)
  2. Trust (Vertrauen)

    Die einzige Autorisierungsstelle. Eine deterministische Richtlinien-Engine ohne Modell in der Entscheidung; erst protokollieren, dann handeln.

    • Principals und Ausführungen
    • Capability Lease
    • Richtlinien-Engine
    • Human Gate
    • Trust Labels
    • Credential Broker
    • Flight Recorder
  3. Memory (Gedächtnis)

    Macht aus Notizen durchsuchbares, budgetiert lesbares Wissen. Alles lässt sich aus der Schicht darunter neu aufbauen.

    • Notizkonventionen
    • Indizes (Volltext, Vektor, Graph)
    • Budgeted Reads
    • Wartungsjobs
    • Lineage
    • Cascade Forget
  4. Store (Speicher)

    Ein Tree mit Verlauf, auf bewährten Dateisystem-Snapshots, Git oder versioniertem Objektspeicher. Er versteht weder Gedächtnis noch Labels.

    • Tree
    • Commit
    • Agent Branch
    • Dateisystem-Snapshots
    • Git
    • Objektspeicher
Sync (Synchronisierung, optional)

Replikation und Teilen zwischen Knoten. Absichtlich zuletzt: Bringen Sie zuerst einen einzelnen Knoten in Ordnung.

  • Git-Remotes
  • Snapshot-Transfer
  • Lease-Links
  • Übergabepakete
  • Die Memory-Schicht ist wiederaufbaubar. Löschen Sie alle Indizes und bauen Sie neu auf: Die Notizen im Store bleiben vollständig lesbar.
  • Gateways sind zustandslos. Aller persistente Zustand liegt im Store und in den Protokollen von Trust; ein Gateway darf jederzeit neu starten und lässt sich horizontal skalieren.
  • Trust ist die einzige Autorisierungsstelle. Dazu zählen auch die Hintergrundjobs des NAS (Indexierung, Wartung): Auch sie laufen als svc:*-Principals mit Leases.
  • Store versteht weder Gedächtnis noch die Semantik von Labels. Er hält nur einen Tree mit Metadaten.
  • Erst protokollieren, dann handeln. Eine folgenreiche Operation muss zuerst einen Absichtseintrag schreiben.

Die schmale Taille: sechs Kernbegriffe

Der gesamte Entwurf hängt an sechs Kernbegriffen; Labels, Gates, Gedächtnis und Lesemanifeste sind Konventionen, die darauf aufbauen.

BegriffBedeutungZentrale Invariante
TreeEin Verzeichnisbaum mit Verlauf.Jeder Commit lässt sich reproduzieren; es gibt einen Inhalts-Hash oder eine gleichwertige Änderungserkennung.
CommitEine unveränderliche Änderung.Trägt Provenienz-Metadaten: principal, on_behalf_of, run, lease.
PrincipalEine Entität, die authentifiziert und zur Verantwortung gezogen werden kann.Typ ist human, agent, service oder node; ein agent gehört zu einer Rolle, nicht zu einer einzelnen Ausführung.
RunEine Ausführung mit Anfang, Ende, Zweck und einem Verantwortlichen.Hält genau eine Wurzel-Lease; besitzt genau einen Branch.
LeaseDie Autorisierung einer Ausführung.Hat ein Ablaufdatum; kann nur enger werden; widerrufbar; trägt Budgets.
RecordEin Append-only-Eintrag.Per Hash verkettet; erst protokollieren, dann handeln.

Die Store-Schicht: Vertrag und mögliche Engines

Der Store-Vertrag wird von einer Engine bereitgestellt oder vom Gateway nachgebildet. Eine Implementierung darf Engines kombinieren, zum Beispiel Git für Text und Snapshots für große Dateien; der Vertrag schreibt weder die Engine noch die Hash-Funktion noch das On-Disk-Format vor.

  1. Atomare Commits.
  2. Günstige Forks: idealerweise nahe an O(1); schlimmstenfalls als Kopie, dann sind Kontingente und eine TTL Pflicht.
  3. Unveränderliche Snapshots.
  4. Änderungserkennung: ein Inhalts-Hash oder Gleichwertiges.
  5. Die Differenz zwischen zwei Commits.
  6. Vollständiger Export in einem Standardformat: ein Verzeichnis, Git-Verlauf und die Klartext-Metadaten in .nas/.
EngineGeeignet fürFork-KostenHinweis
Git (mit Worktrees)Text, Gedächtnis, Skills, kleine CodebasenGeringGroße Dateien brauchen LFS oder externen Speicher; Binär-Merges sind schlecht.
Dateisystem-Snapshots und -Clones (ZFS, btrfs, APFS)Große Verzeichnisse, gemischte DateienEtwa O(1)Hängt vom Dateisystem ab; Kopieren zwischen Maschinen braucht send/receive.
Versionierter Objektspeicher (Tigris-Forks, lakeFS, S3 plus Manifest)Datensätze, große DateienEtwa O(1)Das Gateway muss eine Dateiansicht bereitstellen.
Einfaches Verzeichnis plus KopieEinstieg mit LiteO(n)Nur für kleine Datenmengen; Kontingente und eine TTL sind Pflicht.

Der Wiederherstellungspfad liegt außerhalb des Schadensradius

Snapshots und Backups gehören dem Eigentümer-Principal, und keine Lease darf „einen Snapshot löschen“ oder „ein Backup löschen“ enthalten. Das ist die direkteste Lehre aus dem Vorfall vom April 2026: Der Wiederherstellungspfad muss außerhalb des Schadensradius dessen liegen, was er schützt.

  • Verschlüsselung im Ruhezustand kommt von der darunterliegenden Schicht; die Aufbewahrungsklasse sensitive hat eine eigene Schlüsseldomäne und lässt sich daher durch Zerstören des Schlüssels vernichten.
  • Deduplizierung und Vernichtung stehen im Konflikt: Die Klasse sensitive wird nicht über Schlüsseldomänen hinweg dedupliziert.

Die Reise einer Ausführung

  1. Anfordern. Der Orchestrator (oder der Eigentümer) fordert für eine Ausführung eine Lease an: Pfade, Aktionen, Ablauf, Zweck. Innerhalb des Richtlinienrahmens wird sie automatisch ausgestellt; außerhalb geht sie an ein Human Gate.
  2. Starten. Das NAS legt den run und den Branch <role>/<run_id> an und übergibt die Lease an die Ausführung; die Sandbox bindet den Branch ein (oder führt ein git clone aus).
  3. Arbeiten. Der Agent liest und schreibt mit gewöhnlichen Dateiwerkzeugen. Lesezugriffe sammeln sich im Lesemanifest, und die Sitzungskontamination wird entsprechend aktualisiert; Zugriffe außerhalb der Grenzen werden abgelehnt und protokolliert.
  4. Committen. Änderungen werden automatisch (entprellt) oder ausdrücklich committet, und jeder Commit trägt Provenienz-Metadaten.
  5. Vorschlagen. propose erzeugt einen Agent PR: den Diff, die Absicht, eine Zusammenfassung des Lesemanifests, Prüfergebnisse und eine Zusammenfassung der Labels.
  6. Entscheiden. Die Richtlinien-Engine entscheidet: Bestehen die Prüfungen und ist das Risiko gering, wird automatisch gemergt; geht es um geschützte Daten, eine nach außen gerichtete Aktion oder einen Verstoß gegen die Zweierregel, geht es an ein Human Gate; ist etwas eindeutig verboten, wird abgelehnt.
  7. Mergen und protokollieren. Der Merge erzeugt einen Commit mit Provenienz und schreibt einen Record.
  8. Abschließen. Die Lease läuft ab; der Branch wird nach seiner TTL in den Papierkorb verschoben; Lesemanifeste und Records werden nach der Aufbewahrungsrichtlinie vorgehalten.

Der Lesepfad: Anfrage, Lease-Prüfung, Label-Prüfung (erlaubt die aktuelle Sitzungskontamination dieses Lesen?), Budgetzählung, Lesen aus dem Store, Eintrag im Lesemanifest, Inhalt und Belegzeiger zurückgeben.

Erst protokollieren, dann handeln

Eine folgenreiche Operation (Merge, Löschen, Teilen, Egress, Lease-Änderung) muss zuerst einen Absichtseintrag schreiben; lässt er sich nicht schreiben, schlägt die Operation fehl (fail closed). Lesezugriffe gehen in das Lesemanifest, das stapelweise geschrieben wird und nicht pro Lesezugriff synchron sein muss.

Einsatzformen

FormBeschreibungGeeignet für
LiteEinzelner Rechner, einzelner Nutzer: ein Gateway-Prozess plus lokaler Speicher (Git oder Dateisystem-Snapshots); L0 bis L1.Privatpersonen und Entwickler beim Ausprobieren.
OverlayLässt das vorhandene NAS oder den Objektspeicher unangetastet: Ein Gateway sitzt davor und verwaltet nur ein einziges Verzeichnis oder einen Bucket; Mounts und die S3-Ansicht laufen über das Gateway.Der realistischste Einstieg: Wer schon eine Box hat.
TeamMehrere Nutzer und Agenten, ein Server oder ein kleiner Cluster; L0 bis L3; Gate-Benachrichtigungen und ein Leitstand.Kleine Teams.
CloudEin gehosteter mandantenfähiger Dienst mit starker Isolation; L0 bis L3.Wer keine eigene Hardware hat.

Das Prinzip: Spezielle Hardware ist nicht nötig, jeder dauerhaft laufende Rechner genügt; Beschleuniger sind optional, denn für Embeddings und Zusammenfassungen reichen kleine Modelle, und externe Dienste lassen sich ebenfalls aufrufen.

Ein v0 aus vorhandenen Bausteinen bauen

FähigkeitBausteine, die es heute schon gibt
Store und BranchesGit und Worktrees; btrfs- oder ZFS-Snapshots; oder Tigris und lakeFS (Objektspeicher).
Geschützte HauptlinieBranch-Schutz in Forgejo, Gitea oder GitHub; oder geschützte Branches in lakeFS.
LeasesEin OAuth-Autorisierungsserver (zum Beispiel Keycloak) mit Token Exchange und ein Resource Server, der Pfadpräfix und Aktion prüft; oder ein Signaturdienst von ein paar hundert Zeilen.
RecordsEine Append-only-SQLite-Tabelle plus ein täglicher Hash; Git-Trailer in Commits; OpenTelemetry-Export.
GatesPR-Review plus eine Push-Benachrichtigung; die CLI nas gate approve.
GedächtnisMarkdown unter memory/ plus SQLite FTS5; einen Vektorspeicher können Sie später ergänzen.
LabelsDas Importverzeichnis als external markieren; die Sitzungskontamination pro Ausführung im Gateway halten.
SchnittstellenNFS-, SMB- oder FUSE-Mount; Git über SSH oder HTTPS; ein S3-Gateway; ein kleiner MCP-Server.

Was diese Tabelle sagt: L0 und L1 brauchen keine neue Erfindung. Neu ist der Vertrag, der sie verbindet, und die Tests, die ihn überprüfen; siehe die Spezifikation.

Betrieb

  • Backups: 3-2-1; Snapshots und Backups gehören dem Eigentümer-Principal, und keine Lease darf sie berühren; üben Sie jedes Quartal eine Wiederherstellung und halten Sie sie im Protokoll fest.
  • Upgrades: Gateways sind zustandslos und lassen sich schrittweise aktualisieren; jede Änderung des Store-Formats muss mit einem Migrations- und Rollback-Plan kommen; die Memory-Schicht lässt sich als Ganzes neu aufbauen.
  • Überwachung: Raten der Lease-Ausstellung und -Ablehnung; Länge der Gate-Warteschlange und Freigabequote (bleibt die Freigabequote über 95 %, sind Gates zu häufig und sollten zusammengelegt oder die Richtlinie verschärft werden); Anzahl und Alter der Branches; Aktualität der Indizes; Prüfung der Record-Kette; Kontingente.
  • Kapazität: Branches haben eine TTL und Kontingente; der Papierkorb hat eine Aufbewahrungsfrist; abgeleitete Daten haben ein Budget.

Der Leitstand

Die Oberfläche für Menschen kann eine Webseite, eine CLI oder ein Chatbot sein. Sie ist nicht zwingend: L0 bis L1 können vollständig mit einer CLI und einer vorhandenen Git-Plattform laufen.

  • Aktivitätsverlauf: nach Ausführung aggregiert: wer was getan hat und was gelesen wurde.
  • Gate-Posteingang: Aktionen, die auf Freigabe warten, als Gate Cards dargestellt.
  • Rollenverzeichnis: Home, Leases, Budgets und letzte Ausführungen jeder Rolle.
  • Gedächtnis-Browser: Notizen und Quellen, die Quarantäne ungeprüfter Notizen, Wartungsvorschläge.
  • Branches und PRs: nicht gemergte Branches und der Papierkorb.
  • Vergessen-Konsole: Anfragen, eine Lineage-Vorschau und Berichte.

Menschen können auch direkt über SMB oder WebDAV nachsehen: /humans/<user>/Agent Activity/ ist eine schreibgeschützte Aktivitätsansicht aus gewöhnlichen Dateien.

Diese Seite zitieren

Stabile Adressen und ein Zitiervorschlag für Menschen, Suchmaschinen und Agenten.

Zitiervorschlag
Agent NAS project. “Architektur.” agentnas.com, 2026-11-11. https://agentnas.com/de/architecture/