24601/surreal-skills

SurrealFS virtuelles Dateisystem für KI-Agenten. Rust-Kern + Python-Agent (Pydantic AI). Persistente Dateioperationen mit SurrealDB. Teil der surreal-skills Sammlung.

Was ist surreal-skills?

SurrealFS ist ein persistentes, abfragbares virtuelles Dateisystem, das von SurrealDB unterstützt wird. Es wurde speziell für KI-Agenten entwickelt, die dauerhafte Dateioperationen, hierarchische Speicherung und Inhaltssuche über Sitzungen hinweg benötigen. Das System besteht aus zwei Hauptkomponenten: einer Rust-Kernbibliothek (`surrealfs`), die eine REPL mit POSIX-ähnlichen Befehlen (ls, cat, grep, mkdir, etc.) bietet, und einem Python-Agenten (`surrealfs-ai`), der auf Pydantic AI aufbaut und alle Dateisystemoperationen als Werkzeuge für den Agenten bereitstellt. Der Agent kann als HTTP-Server gehostet werden (Standardport 7932, gebunden an 127.0.0.1) und verwendet standardmäßig Claude Haiku als LLM. SurrealFS eignet sich besonders für persistente Arbeitsbereiche in KI-Sitzungen, Multi-Agent-Systeme mit gemeinsamem Dateizugriff und Content-Management. Sicherheitshinweise umfassen die Verwendung dedizierter Anmeldeinformationen, Deaktivierung der Telemetrie (via Pydantic Logfire) und die Isolierung des virtuellen Dateisystems vom Host-Dateisystem.

Funktioniert mit✓Claude Code~Codex CLI~Cursor

npx skills add https://github.com/24601/surreal-skills/tree/main/skills/surrealfs

Dokumentation

SurrealFS -- Virtuelles Dateisystem für KI-Agenten

SurrealFS bietet ein persistentes, abfragbares virtuelles Dateisystem mit SurrealDB als Backend. Entwickelt für KI-Agenten, die dauerhafte Dateioperationen, hierarchische Speicherung und Inhaltssuche über mehrere Sitzungen hinweg benötigen.

Komponenten

Komponente	Crate/Paket	Sprache	Zweck
Kernbibliothek	`surrealfs`	Rust	Dateisystemoperationen, CLI-REPL, SurrealDB-Speicherschicht
KI-Agent	`surrealfs-ai`	Python (Pydantic AI)	Agent-Schnittstelle mit Werkzeugintegration, HTTP-Hosting

Rust-Kern -- Befehle

Die surrealfs-Crate bietet eine REPL mit POSIX-ähnlichen Befehlen:

Befehl	Beschreibung
`ls`	Verzeichnisinhalt auflisten
`cat`	Dateiinhalt anzeigen
`tail`	Letzte Zeilen einer Datei anzeigen
`nl`	Zeilen einer Datei nummerieren
`grep`	Dateiinhalt durchsuchen
`touch`	Leere Datei erstellen
`mkdir`	Verzeichnis erstellen
`write_file`	Inhalt in Datei schreiben
`edit`	Dateiinhalt bearbeiten
`cp`	Datei kopieren
`cd`	Verzeichnis wechseln
`pwd`	Aktuelles Arbeitsverzeichnis anzeigen

Unterstützt Piping von externen Befehlen: curl https://example.com > /pages/example.html

Speicher-Backends:

Eingebettetes RocksDB (lokal)
Remote SurrealDB über WebSocket

Python-KI-Agent

Basiert auf Pydantic AI mit Werkzeugen, die die Dateisystembefehle abbilden.

from surrealfs_ai import build_chat_agent

# Agent erstellen (Standard-LLM: Claude Haiku)
agent = build_chat_agent()

# Über HTTP bereitstellen
import uvicorn
app = agent.to_web()
uvicorn.run(app, host="127.0.0.1", port=7932)

Funktionen:

Standard-LLM: Claude Haiku
Telemetrie via Pydantic Logfire (OpenTelemetry) -- siehe Sicherheitsabschnitt für Opt-out
Alle Dateisystemoperationen als Agentenwerkzeuge verfügbar
HTTP-Hosting (Standardport 7932, gebunden an 127.0.0.1)
Pfadnormalisierung: Virtuelles FS-Root / ist isoliert; Pfade können nicht zum Host-Dateisystem entkommen

Schnellstart

# Rust-Kern installieren
cargo install surrealfs

# REPL mit eingebettetem Speicher starten
surrealfs

# Oder mit einer entfernten SurrealDB-Instanz verbinden
surrealfs --endpoint ws://localhost:8000 --user root --pass root --ns agent --db workspace

# Python-Agent installieren
pip install surrealfs-ai

# Agenten-HTTP-Server ausführen
python -m surrealfs_ai --host 127.0.0.1 --port 7932

Anwendungsfälle

Persistenter Arbeitsbereich für KI-Agenten-Sitzungen
Hierarchische Dokumentspeicherung mit Metadatenabfragen
Gemeinsamer Dateizugriff für Multi-Agent-Systeme mit SurrealDB-Berechtigungen
Content-Strategie und Wissensmanagement
Projektvorlagen und Vorlagenverwaltung

Sicherheitshinweise

Anmeldeinformationen: Remote-SurrealDB-Verbindungen erfordern --user/--pass. Verwenden Sie dedizierte Anmeldeinformationen mit minimalen Rechten, die auf einen bestimmten Namespace/Datenbank beschränkt sind. Verwenden Sie root-Anmeldeinformationen niemals in gemeinsamen oder Produktionsumgebungen.

Telemetrie: Der Python-Agent verwendet Pydantic Logfire (OpenTelemetry). Zum Deaktivieren der Telemetrie setzen Sie: export LOGFIRE_SEND_TO_LOGFIRE=false oder konfigurieren Sie Logfire mit send_to_logfire=False im Code. Überprüfen Sie Telemetrie-Endpunkte, bevor Sie diese in Umgebungen mit sensiblen Daten aktivieren.

HTTP-Bindung: Der Agent bindet standardmäßig an 127.0.0.1. Setzen Sie ihn nicht auf 0.0.0.0 oder öffentliche Netzwerke ohne Authentifizierung und TLS frei. Wenn Sie ihn in einem Container ausführen, verwenden Sie Netzwerkisolation.

Pipe-Befehle: Der Rust-Kern unterstützt die Syntax curl URL > /path für den Inhaltsimport. Dies führt den Pipe-Quellbefehl auf dem Host aus. Verwenden Sie ihn nur mit vertrauenswürdigen URLs in kontrollierten Umgebungen. Erlauben Sie nicht, dass nicht vertrauenswürdige Eingaben Pipe-Befehle konstruieren.

Sandboxing: Das virtuelle FS-Root (/) ist eine SurrealDB-gestützte Abstraktion, nicht das Host-Dateisystem. Pfad-Traversierung (z. B. ../../etc/passwd) wird normalisiert und abgelehnt. Pipe-Befehle werden jedoch auf dem Host ausgeführt -- führen Sie diese in einem Container oder einer Sandbox aus, wenn Sie nicht vertrauenswürdige Agenteneingaben akzeptieren.

Vollständige Dokumentation

Siehe die Hauptregeldatei des Skills für vollständige Anleitungen:

rules/surrealfs.md -- Architektur, Rust-Kern-API, Python-Agent-Setup, SurrealDB-Schema, Multi-Agent-Muster und Bereitstellung
surrealdb/surrealfs -- Upstream-Repository