SurrealFS -- AIエージェント向け仮想ファイルシステム
SurrealFSは、SurrealDBをバックエンドとした永続的でクエリ可能な仮想ファイルシステムを提供します。 セッションを超えた耐久性のあるファイル操作、階層型ストレージ、コンテンツ検索を必要とするAIエージェント向けに設計されています。
コンポーネント
| コンポーネント | クレート/パッケージ | 言語 | 目的 |
|---|---|---|---|
| コアライブラリ | surrealfs | Rust | ファイルシステム操作、CLI REPL、SurrealDBストレージ層 |
| AIエージェント | surrealfs-ai | Python (Pydantic AI) | ツール統合、HTTPホスティングを備えたエージェントインターフェース |
Rustコア -- コマンド
surrealfsクレートはPOSIXライクなコマンドを備えたREPLを提供します：
| コマンド | 説明 |
|---|---|
ls | ディレクトリ内容を一覧表示 |
cat | ファイル内容を表示 |
tail | ファイルの最終行を表示 |
nl | ファイルに行番号を付ける |
grep | ファイル内容を検索 |
touch | 空のファイルを作成 |
mkdir | ディレクトリを作成 |
write_file | ファイルに内容を書き込み |
edit | ファイル内容を編集 |
cp | ファイルをコピー |
cd | ディレクトリを変更 |
pwd | 作業ディレクトリを表示 |
外部コマンドからのパイプをサポート：curl https://example.com > /pages/example.html
ストレージバックエンド：
- 埋め込みRocksDB（ローカル）
- WebSocket経由のリモートSurrealDB
Python AIエージェント
Pydantic AI上に構築され、ファイルシステムコマンドをミラーリングするツールを備えています。
from surrealfs_ai import build_chat_agent
# エージェントを作成（デフォルトLLM：Claude Haiku）
agent = build_chat_agent()
# HTTP経由で公開
import uvicorn
app = agent.to_web()
uvicorn.run(app, host="127.0.0.1", port=7932)
機能：
- デフォルトLLM：Claude Haiku
- Pydantic Logfire（OpenTelemetry）によるテレメトリ -- セキュリティセクションで無効化方法を確認
- すべてのファイルシステム操作がエージェントツールとして利用可能
- HTTPホスティング（デフォルトポート7932、127.0.0.1にバインド）
- パス正規化：仮想FSルート
/は隔離されており、パスがホストファイルシステムにエスケープすることはありません
クイックスタート
# Rustコアをインストール
cargo install surrealfs
# 埋め込みストレージでREPLを起動
surrealfs
# リモートSurrealDBインスタンスに接続
surrealfs --endpoint ws://localhost:8000 --user root --pass root --ns agent --db workspace
# Pythonエージェントをインストール
pip install surrealfs-ai
# エージェントHTTPサーバーを実行
python -m surrealfs_ai --host 127.0.0.1 --port 7932
ユースケース
- AIエージェントセッション用の永続ワークスペース
- メタデータクエリを伴う階層型ドキュメントストレージ
- SurrealDBの権限を使用したマルチエージェント共有ファイルアクセス
- コンテンツ戦略とナレッジ管理
- プロジェクトスキャフォールディングとテンプレート管理
セキュリティに関する考慮事項
認証情報：リモートSurrealDB接続には--user/--passが必要です。特定の名前空間/データベースにスコープされた専用の最小権限の認証情報を使用してください。共有環境や本番環境ではroot認証情報を使用しないでください。
テレメトリ：PythonエージェントはPydantic Logfire（OpenTelemetry）を使用します。テレメトリを無効にするには、export LOGFIRE_SEND_TO_LOGFIRE=falseを設定するか、コード内でLogfireをsend_to_logfire=Falseで設定してください。機密データを扱う環境で有効にする前に、テレメトリエンドポイントを監査してください。
HTTPバインディング：エージェントはデフォルトで127.0.0.1にバインドします。認証やTLSなしで0.0.0.0やパブリックネットワークに公開しないでください。コンテナ内で実行する場合は、ネットワーク分離を使用してください。
パイプコマンド：Rustコアはコンテンツ取り込みのためのcurl URL > /path構文をサポートしています。これにより、パイプ元コマンドがホスト上で実行されます。管理された環境内の信頼できるURLでのみ使用してください。信頼できない入力をパイプコマンドの構築に使用しないでください。
サンドボックス化：仮想FSルート（/）はホストファイルシステムではなく、SurrealDBをバックエンドとした抽象化です。パストラバーサル（例：../../etc/passwd）は正規化され拒否されます。ただし、パイプコマンドはホスト上で実行されます。信頼できないエージェント入力を受け入れる場合は、コンテナまたはサンドボックス内で実行してください。
完全なドキュメント
完全なガイダンスはメインスキルのルールファイルを参照してください：
- rules/surrealfs.md -- アーキテクチャ、RustコアAPI、Pythonエージェントセットアップ、SurrealDBスキーマ、マルチエージェントパターン、デプロイメント
- surrealdb/surrealfs -- 上流リポジトリ