核心用法
SurrealFS 是一套面向 AI Agent 的持久化虚拟文件系统解决方案，由 Rust 核心库与 Python Agent 组成，底层以 SurrealDB 作为存储引擎。
Rust 核心（`surrealfs`） 提供类 POSIX 的 REPL 命令行环境，支持 ls、cat、grep、mkdir、write_file 等常用文件操作，并允许通过管道从外部命令（如 curl）导入内容。存储后端可选嵌入式 RocksDB（本地）或远程 SurrealDB（通过 WebSocket 连接）。
Python Agent（`surrealfs-ai`） 基于 Pydantic AI 构建，将文件系统操作封装为 Agent Tools，默认集成 Claude Haiku 模型，可通过 uvicorn 在本地 127.0.0.1:7932 暴露 HTTP 服务供外部调用。
SurrealDB 后端 负责持久化存储与查询能力，支持跨会话数据保留、多级命名空间隔离及基于权限的多 Agent 共享访问。
显著优点
- 持久化与可查询性：文件元数据与内容存入 SurrealDB，支持结构化查询，优于传统临时文件或内存存储方案。
- 双语言栈覆盖：Rust 保证核心性能与 CLI 体验，Python 提供现代 AI Agent 集成能力，满足不同场景需求。
- 层级隔离安全：虚拟根目录
/与宿主机文件系统完全隔离，路径穿越攻击被显式阻止。 - 多 Agent 协作：基于 SurrealDB 的权限系统，可实现多个 Agent 安全共享同一文件空间。
- 开源 MIT 协议：无商业使用限制，便于二次开发与内部集成。
潜在局限与风险
- 网络依赖：远程后端需配置
SURREAL_ENDPOINT，且 Python Agent 默认开放本地 HTTP 端口，需警惕容器或云环境中的意外暴露。 - 凭证管理：远程连接需
SURREAL_USER/SURREAL_PASS，若使用root凭证或硬编码配置，存在权限过大与泄露风险。 - 管道命令风险：Rust REPL 支持
curl URL > /path语法，该操作在宿主机执行外部命令，若 Agent 输出被污染，可能导致命令注入。 - 遥测默认开启：Python Agent 集成 Pydantic Logfire（OpenTelemetry），需在敏感环境中显式禁用
LOGFIRE_SEND_TO_LOGFIRE=false。 - 生态成熟度：作为 SurrealDB 生态较新的子项目（版本 1.0.4），API 稳定性与长期维护承诺需持续观察。
适合人群
- 需要为 AI Agent 构建持久化工作空间的开发者（如长期任务、多轮对话状态存储）。
- 希望以文件系统语义管理结构化数据的团队（如文档知识库、项目模板库）。
- 已在 SurrealDB 生态内，寻求统一存储后端的工程师。
- 愿意接受容器化部署以隔离管道命令风险的安全意识用户。
常规风险提醒
部署时应遵循最小权限原则：为 SurrealDB 创建专用命名空间/数据库及受限用户，避免使用 root；对 Python Agent 启用 TLS 与认证后再暴露公网；在不可信输入场景下禁用管道功能或运行于严格沙箱中。