파일SDK파일 시스템
지원되는 모든 스토리지 백엔드에 파일을 저장합니다.FilesSDK: S3, Cloudflare R2, Google Cloud Storage, Azure Blob, Vercel Blob, MinIO, 로컬 파일 시스템 등에 대한 통합 추상화입니다. 인터페이스에 대한 자세한 내용은 다음을 참조하세요.Workspace파일 시스템 인터페이스.
동일한 코드로 여러 스토리지 백엔드를 대상으로 할 수 있는 단일 어댑터가 필요하면 FilesSDKFilesystem을 사용하세요. Workspace 설정을 변경하지 않고 기본 드라이버를 교체할 수 있습니다. 하나의 백엔드만 대상으로 하고 해당 백엔드의 일급 옵션을 사용하려면 전용 Provider(예: S3Filesystem 또는 GCSFilesystem)를 사용하는 것이 좋습니다.
설치설치에 대한 직접 링크
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/files-sdk files-sdk
pnpm add @mastra/files-sdk files-sdk
yarn add @mastra/files-sdk files-sdk
bun add @mastra/files-sdk files-sdk
files-sdk사용하려는 어댑터로 구성하는 피어 종속성입니다.
용법용법에 대한 직접 링크
원하는 어댑터로 FilesSDK의 Files 인스턴스를 생성한 다음 FilesSDKFilesystem에 전달합니다:
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { FilesSDKFilesystem } from '@mastra/files-sdk'
import { Files } from 'files-sdk'
import { s3 } from 'files-sdk/s3'
const files = new Files({
adapter: s3({
bucket: 'my-bucket',
region: 'us-east-1',
}),
})
const workspace = new Workspace({
filesystem: new FilesSDKFilesystem({ files }),
})
const agent = new Agent({
id: 'file-agent',
name: 'file-agent',
model: 'anthropic/claude-opus-4-7',
workspace,
})
어댑터 교환어댑터 교환에 대한 직접 링크
동일한 FilesSDKFilesystem을 모든 FilesSDK 어댑터와 함께 사용할 수 있습니다. 백엔드를 전환하려면 드라이버 팩터리를 교체합니다:
import { Files } from 'files-sdk'
import { r2 } from 'files-sdk/r2'
import { gcs } from 'files-sdk/gcs'
import { azure } from 'files-sdk/azure'
import { fs } from 'files-sdk/fs'
// Cloudflare R2
const r2Files = new Files({ adapter: r2({ accountId, bucket, accessKeyId, secretAccessKey }) })
// Google Cloud Storage
const gcsFiles = new Files({ adapter: gcs({ bucket, projectId }) })
// Azure Blob
const azureFiles = new Files({ adapter: azure({ container, connectionString }) })
// Local filesystem (useful for tests and development)
const localFiles = new Files({ adapter: fs({ root: './workspace' }) })
전체 어댑터 카탈로그와 구성 옵션은 FilesSDK 문서를 참조하세요.
읽기 전용 마운트읽기 전용 마운트에 대한 직접 링크
const filesystem = new FilesSDKFilesystem({
files,
readOnly: true,
})
모든 쓰기 작업(writeFile, appendFile, deleteFile, copyFile, moveFile, mkdir, rmdir) throw WorkspaceReadOnlyError읽는 동안 성공합니다.
생성자 매개변수생성자 매개변수에 대한 직접 링크
files:
Files 인스턴스입니다.id?:
displayName?:
icon?:
description?:
readOnly?:
속성속성에 대한 직접 링크
id:
name:
provider:
readOnly:
행동 양식행동 양식에 대한 직접 링크
FilesSDKFilesystem구현WorkspaceFilesystem interface, providing all standard filesystem methods:
readFile(path, options?)- 파일 내용 읽기writeFile(path, content, options?)- 파일에 콘텐츠 쓰기appendFile(path, content)- 파일에 콘텐츠 추가deleteFile(path, options?)- 파일 삭제copyFile(src, dest, options?)- 파일 복사moveFile(src, dest, options?)- 파일 이동 또는 이름 바꾸기mkdir(path, options?)- 디렉토리 생성(객체 저장소의 경우 무작동)rmdir(path, options?)- 디렉토리 제거readdir(path, options?)- 디렉토리 내용 나열exists(path)- 경로가 존재하는지 확인stat(path)- 파일 또는 디렉터리 메타데이터 가져오기
init()init에 대한 직접 링크
파일 시스템을 초기화합니다. 구성된 어댑터가 제공된 자격 증명으로 키를 나열할 수 있는지 확인합니다.
await filesystem.init()
getInfo()getinfo에 대한 직접 링크
이 파일 시스템 인스턴스에 대한 메타데이터를 반환합니다.
const info = filesystem.getInfo()
// { id: '...', name: 'FilesSDKFilesystem', provider: 'files-sdk', status: 'ready' }
filesfiles에 대한 직접 링크
어댑터별 API를 직접 호출해야 하는 경우 기본 FilesSDK Files 인스턴스가 public 속성으로 노출됩니다.
const url = await filesystem.files.url('reports/q3.pdf')
객체 저장소 의미론객체 저장소 의미론에 대한 직접 링크
FilesSDKFilesystem은 기본 어댑터가 계층형인 경우에도(예: fs) 객체 스토리지 의미 체계를 적용합니다. 따라서 어댑터 전반에서 동작이 일관되게 유지됩니다:
mkdir은 아무 작업도 하지 않습니다. 해당 접두사가 있는 키가 있으면 디렉터리는 암시적으로 존재합니다.exists는 정확한 키가 파일로 존재하거나 경로가 하나 이상의 하위 키를 포함하는 접두사인 경우에만true를 반환합니다. 계층형 어댑터에 남아 있는 빈 디렉터리는 포함되지 않습니다.deleteFile은 키가 존재하지 않으면{ force: true }가 전달된 경우를 제외하고FileNotFoundError를 발생시킵니다.deleteFile은 디렉터리를rmdir({ recursive: true })에 위임하며, 이는S3Filesystem및GCSFilesystem의 동작과 일치합니다.moveFile은copyFile을 실행한 후deleteFile을 실행하는 방식으로 구현됩니다. 이 작업은 원자적이지 않습니다. 복사에 성공한 후 소스 삭제에 실패하면 대상은 남아 있고 소스는 제거되지 않습니다.appendFile은 읽기-수정-쓰기 작업입니다. 동일한 키에 동시에 추가하면 서로 덮어쓸 수 있습니다. 이는 객체 스토리지의 본질적인 특성이며 FilesSDK에만 국한되지 않습니다.readdir({ recursive: true })은 중간 디렉터리 항목을 내보냅니다(예:a/b/c.txt와 함께a/b도 내보냅니다).