SurrealFS — Système de fichiers virtuel pour agents IA
SurrealFS fournit un système de fichiers virtuel persistant et interrogeable, soutenu par SurrealDB. Conçu pour les agents IA qui ont besoin d'opérations de fichiers durables, de stockage hiérarchique et de recherche de contenu entre les sessions.
Composants
| Composant | Crate/Paquet | Langage | Objectif |
|---|---|---|---|
| Bibliothèque Cœur | surrealfs | Rust | Opérations du système de fichiers, REPL CLI, couche de stockage SurrealDB |
| Agent IA | surrealfs-ai | Python (Pydantic AI) | Interface agent avec intégration d'outils, hébergement HTTP |
Cœur Rust — Commandes
Le crate surrealfs fournit un REPL avec des commandes de type POSIX :
| Commande | Description |
|---|---|
ls | Lister le contenu du répertoire |
cat | Afficher le contenu du fichier |
tail | Afficher les dernières lignes d'un fichier |
nl | Numéroter les lignes d'un fichier |
grep | Rechercher dans le contenu du fichier |
touch | Créer un fichier vide |
mkdir | Créer un répertoire |
write_file | Écrire du contenu dans un fichier |
edit | Modifier le contenu du fichier |
cp | Copier un fichier |
cd | Changer de répertoire |
pwd | Afficher le répertoire de travail |
Prend en charge le pipe depuis des commandes externes : curl https://example.com > /pages/example.html
Backends de stockage :
- RocksDB intégré (local)
- SurrealDB distant via WebSocket
Agent Python IA
Construit sur Pydantic AI avec des outils qui reflètent les commandes du système de fichiers.
from surrealfs_ai import build_chat_agent
# Créer l'agent (LLM par défaut : Claude Haiku)
agent = build_chat_agent()
# Exposer via HTTP
import uvicorn
app = agent.to_web()
uvicorn.run(app, host="127.0.0.1", port=7932)
Fonctionnalités :
- LLM par défaut : Claude Haiku
- Télémétrie via Pydantic Logfire (OpenTelemetry) — voir la section Sécurité pour la désactivation
- Toutes les opérations du système de fichiers disponibles comme outils de l'agent
- Hébergement HTTP (port par défaut 7932, lié à 127.0.0.1)
- Normalisation des chemins : la racine FS
/est isolée ; les chemins ne peuvent pas s'échapper vers le système de fichiers hôte
Démarrage rapide
# Installer le cœur Rust
cargo install surrealfs
# Démarrer le REPL avec stockage intégré
surrealfs
# Ou se connecter à une instance SurrealDB distante
surrealfs --endpoint ws://localhost:8000 --user root --pass root --ns agent --db workspace
# Installer l'agent Python
pip install surrealfs-ai
# Exécuter le serveur HTTP de l'agent
python -m surrealfs_ai --host 127.0.0.1 --port 7932
Cas d'utilisation
- Espace de travail persistant pour les sessions d'agents IA
- Stockage de documents hiérarchiques avec requêtes de métadonnées
- Accès partagé aux fichiers multi-agents avec permissions SurrealDB
- Gestion de stratégie de contenu et de connaissances
- Échafaudage de projets et gestion de modèles
Considérations de sécurité
Informations d'identification : Les connexions distantes à SurrealDB nécessitent --user/--pass. Utilisez
des informations d'identification dédiées avec privilèges minimaux, limitées à un espace de noms/base de données spécifique.
N'utilisez jamais d'informations d'identification root dans des environnements partagés ou de production.
Télémétrie : L'agent Python utilise Pydantic Logfire (OpenTelemetry). Pour
désactiver la télémétrie, définissez : export LOGFIRE_SEND_TO_LOGFIRE=false ou configurez
Logfire avec send_to_logfire=False dans le code. Auditez les points de terminaison de télémétrie avant
de les activer dans des environnements contenant des données sensibles.
Liaison HTTP : L'agent se lie à 127.0.0.1 par défaut. Ne l'exposez pas à
0.0.0.0 ou à des réseaux publics sans authentification et TLS. En cas d'exécution dans un
conteneur, utilisez l'isolation réseau.
Commandes pipe : Le cœur Rust prend en charge la syntaxe curl URL > /chemin pour l'ingestion
de contenu. Cela exécute la commande source du pipe sur l'hôte. Utilisez-le uniquement avec
URL de confiance dans des environnements contrôlés. N'autorisez pas les entrées non fiables à construire
des commandes pipe.
Sandboxing : La racine FS virtuelle (/) est une abstraction basée sur SurrealDB,
pas le système de fichiers hôte. Les traversées de chemins (par exemple, ../../etc/passwd) sont
normalisées et rejetées. Cependant, les commandes pipe s'exécutent sur l'hôte — exécutez
l'agent dans un conteneur ou un bac à sable si vous acceptez des entrées non fiables.
Documentation complète
Voir le fichier de règle principal de la compétence pour des conseils complets :
- rules/surrealfs.md — architecture, API du cœur Rust, configuration de l'agent Python, schéma SurrealDB, modèles multi-agents et déploiement
- surrealdb/surrealfs — dépôt en amont