SurrealFS -- AI 代理的虛擬檔案系統
SurrealFS 提供了一個由 SurrealDB 支援的持久化、可查詢的虛擬檔案系統。 專為需要跨工作階段進行可靠檔案操作、階層式儲存以及內容搜尋的 AI 代理設計。
元件
| 元件 | Crate/Package | 語言 | 用途 |
|---|---|---|---|
| 核心函式庫 | surrealfs | Rust | 檔案系統操作、CLI REPL、SurrealDB 儲存層 |
| AI 代理 | surrealfs-ai | Python（Pydantic AI） | 提供工具整合與 HTTP 服務的代理介面 |
Rust 核心 -- 指令
surrealfs crate 提供了類似 POSIX 指令的 REPL：
| 指令 | 說明 |
|---|---|
ls | 列出目錄內容 |
cat | 顯示檔案內容 |
tail | 顯示檔案尾端數行 |
nl | 為檔案行數編號 |
grep | 搜尋檔案內容 |
touch | 建立空檔案 |
mkdir | 建立目錄 |
write_file | 寫入內容至檔案 |
edit | 編輯檔案內容 |
cp | 複製檔案 |
cd | 變更目錄 |
pwd | 顯示目前工作目錄 |
支援從外部指令進行管道操作：curl https://example.com > /pages/example.html
儲存後端：
- 嵌入式 RocksDB（本機）
- 遠端 SurrealDB（透過 WebSocket）
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 參數。請使用
專用且權限最低的憑證，並限定於特定 namespace/database。切勿在共享或
正式環境中使用 root 憑證。
遙測：Python 代理使用 Pydantic Logfire (OpenTelemetry)。若要
停用遙測，請設定：export LOGFIRE_SEND_TO_LOGFIRE=false 或在程式碼中
以 send_to_logfire=False 設定 Logfire。在包含敏感資料的環境中啟用前，
請先稽核遙測端點。
HTTP 綁定：代理預設綁定至 127.0.0.1。請勿在未經驗證及
未使用 TLS 的情況下暴露至 0.0.0.0 或公開網路。若在容器中執行，
請使用網路隔離機制。
Pipe 指令：Rust 核心支援 curl URL > /path 語法以擷取內容。
此方式會在主機上執行 pipe 來源指令。請僅在受控環境中使用受信任的 URL。
切勿讓不受信任的輸入用來建構 pipe 指令。
沙箱：虛擬 FS 根目錄（/）是以 SurrealDB 為基礎的抽象層，
而非主機檔案系統。路徑遍歷（例如 ../../etc/passwd）會經過正規化
並遭到拒絕。然而，pipe 指令會在主機上執行 -- 若接受不受信任的
代理輸入，請在容器或沙箱中執行。
完整文件
請參閱主要技能的規則檔案以取得完整指引：
- rules/surrealfs.md -- 架構、Rust 核心 API、Python 代理設定、SurrealDB 綱要、多代理模式及部署
- surrealdb/surrealfs -- 上游儲存庫