Communitygithub.com

24601/surreal-skills

SurrealFS: AI 에이전트용 가상 파일시스템. Rust 코어 + Python 에이전트(Pydantic AI). SurrealDB 기반의 영구 파일 작업. surreal-skills 컬렉션의 일부.

surreal-skills란 무엇인가요?

SurrealFS는 SurrealDB를 백엔드로 사용하는 AI 에이전트용 가상 파일시스템(Virtual Filesystem)입니다. 이는 Rust로 작성된 핵심 라이브러리와 Pydantic AI 프레임워크 기반의 Python AI 에이전트로 구성되어 있습니다. 주요 기능으로는 POSIX 스타일 명령어(ls, cat, touch, mkdir, grep 등)를 지원하는 REPL 인터페이스와, 모든 파일시스템 작업을 AI 에이전트 도구로 제공하는 HTTP 서버를 포함합니다. 외부 명령어 파이핑(예: `curl URL > /path`)을 지원하며, 임베디드 RocksDB 또는 원격 SurrealDB를 저장소로 선택할 수 있습니다. 기본 LLM은 Claude Haiku이며, Pydantic Logfire을 통한 텔레메트리와 HTTP 바인딩(기본 127.0.0.1:7932)을 제공합니다. 보안 측면에서 가상 FS 루트는 호스트 파일시스템과 격리되어 경로 탐색을 차단하지만, 파이프 명령어는 호스트에서 실행되므로 신뢰할 수 있는 URL만 사용해야 합니다. 이는 AI 에이전트 세션 간 영구 워크스페이스, 다중 에이전트 공유 파일 접근, 콘텐츠 관리 등에 유용합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/24601/surreal-skills/tree/main/skills/surrealfs

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

SurrealFS -- AI 에이전트용 가상 파일시스템

SurrealFS는 SurrealDB를 백엔드로 사용하는 영구적이고 쿼리 가능한 가상 파일시스템을 제공합니다. 세션 간 내구성 있는 파일 작업, 계층적 저장소, 콘텐츠 검색이 필요한 AI 에이전트를 위해 설계되었습니다.

구성 요소

구성 요소Crate/패키지언어목적
핵심 라이브러리surrealfsRust파일시스템 작업, CLI REPL, SurrealDB 저장소 계층
AI 에이전트surrealfs-aiPython (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를 설정하거나 코드에서 send_to_logfire=False로 Logfire를 구성하세요. 민감한 데이터가 있는 환경에서 활성화하기 전에 텔레메트리 엔드포인트를 감사하세요.

HTTP 바인딩: 에이전트는 기본적으로 127.0.0.1에 바인딩됩니다. 인증 및 TLS 없이 0.0.0.0이나 공용 네트워크에 노출하지 마세요. 컨테이너에서 실행하는 경우 네트워크 격리를 사용하세요.

파이프 명령어: Rust 코어는 콘텐츠 수집을 위해 curl URL > /path 구문을 지원합니다. 이는 호스트에서 파이프 소스 명령어를 실행합니다. 통제된 환경에서 신뢰할 수 있는 URL만 사용하세요. 신뢰할 수 없는 입력이 파이프 명령어를 구성하도록 허용하지 마세요.

샌드박싱: 가상 FS 루트(/)는 호스트 파일시스템이 아닌 SurrealDB 기반 추상화입니다. 경로 탐색(예: ../../etc/passwd)은 정규화되어 거부됩니다. 그러나 파이프 명령어는 호스트에서 실행되므로 -- 신뢰할 수 없는 에이전트 입력을 받는 경우 컨테이너나 샌드박스에서 실행하세요.

전체 문서

자세한 안내는 주요 스킬의 규칙 파일을 참조하세요:

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

관련 스킬