24601/surreal-skills

为 AI 智能体提供持久化虚拟文件系统。核心由 Rust 实现 + Python 智能体（Pydantic AI）。支持跨会话的持久文件操作，底层存储由 SurrealDB 支撑。属于 surreal-skills 系列。

surreal-skills 是什么？

SurrealFS 是一个由 SurrealDB 支持的持久化、可查询的虚拟文件系统，专为需要跨会话持久文件操作、层级存储和内容搜索的 AI 智能体设计。它由两个核心组件构成：用 Rust 编写的核心库（`surrealfs`）提供文件系统操作、CLI REPL 以及 SurrealDB 存储层；用 Python 编写的 AI 智能体（`surrealfs-ai`）基于 Pydantic AI 构建，将所有文件系统命令封装为智能体工具，并支持 HTTP 服务。Rust 核心支持嵌入式的 RocksDB 或远程 SurrealDB（通过 WebSocket）作为存储后端，并兼容外部命令管道（例如 `curl URL > /path`）。Python 智能体默认使用 Claude Haiku 作为 LLM，通过 Pydantic Logfire 收集遥测数据（可禁用），并默认绑定至 127.0.0.1:7932。该技能特别适合构建 AI 智能体的持久化工作空间、分层文档存储、多智能体共享文件访问以及知识管理场景。安全性方面，虚拟 FS 根目录与宿主机隔离，路径穿越被拒绝，但管道命令仍在宿主机执行，因此在接收不可信输入时建议在容器或沙箱中运行。

兼容平台✓Claude Code~Codex CLI~Cursor

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

文档

SurrealFS -- AI 智能体的虚拟文件系统

SurrealFS 提供了一个由 SurrealDB 支持的持久化、可查询的虚拟文件系统。专为需要跨会话持久文件操作、层级存储和内容搜索的 AI 智能体设计。

组件

组件	Crate/包	语言	用途
核心库	`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。请使用专门的、最小权限的凭据，并限定到特定命名空间/数据库。切勿在共享或生产环境中使用 root 凭据。

遥测：Python 智能体使用 Pydantic Logfire（OpenTelemetry）。要禁用遥测，请设置：export LOGFIRE_SEND_TO_LOGFIRE=false 或在代码中使用 send_to_logfire=False 配置 Logfire。在包含敏感数据的环境中启用前，请审计遥测端点。

HTTP绑定：智能体默认绑定到 127.0.0.1。不要将其暴露给 0.0.0.0 或公共网络，除非已配置身份验证和 TLS。如果在容器中运行，请使用网络隔离。

管道命令：Rust 核心支持 curl URL > /path 语法用于内容接入。这会在宿主机上执行管道源命令。请仅在受控环境中使用受信任的 URL。不要让不受信任的输入构造管道命令。

沙箱：虚拟 FS 根目录 (/) 是 SurrealDB 支持的抽象，而非宿主机文件系统。路径遍历（例如 ../../etc/passwd）会被标准化并拒绝。然而，管道命令在宿主机上执行 -- 如果接受不受信任的智能体输入，请在容器或沙箱中运行。

完整文档

请参阅主要技能的规则文件以获取完整指导：

rules/surrealfs.md -- 架构、Rust 核心 API、Python 智能体设置、SurrealDB 模式、多智能体模式及部署
surrealdb/surrealfs -- 上游仓库