메사파일 시스템

작업공간 파일을 다음 위치에 저장합니다.Mesa표준 Mastra를 통한 저장소WorkspaceFilesystem인터페이스.

Agent에 버전 관리 파일 스토리지가 필요할 때 MesaFilesystem을 사용합니다. 로컬 디렉터리에는 LocalFilesystem을 사용합니다. 객체 스토리지에는 S3Filesystem, GCSFilesystem 또는 AzureBlobFilesystem을 사용합니다.

정보

MesaFilesystemMastra 프로세스에서 실행됩니다.

Mesa의 POSIX 마운트(Sandbox 내에서 Mesa 파일 시스템을 사용하기 위한 기능)는 아직 @mastra/mesa 패키지에 포함되어 있지 않습니다. 곧 지원될 예정입니다.

설치

npm

npm install @mastra/mesa

pnpm

pnpm add @mastra/mesa

Yarn

yarn add @mastra/mesa

Bun

bun add @mastra/mesa

사용예

Mesa 저장소 하나를 마운트하고 파일 시스템을 작업 공간에 전달합니다.

src/mastra/workspace.ts

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { MesaFilesystem } from '@mastra/mesa'

const workspace = new Workspace({
  filesystem: new MesaFilesystem({
    apiKey: process.env.MESA_API_KEY,
    org: 'acme',
    repos: [{ name: 'docs', bookmark: 'main' }],
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

apiKey를 생략하면 MESA_API_KEY를 대신 사용합니다.

생성자 매개변수

apiKey?:

string

Mesa API 키입니다. 생략하면 MESA_API_KEY를 대신 사용합니다.

org?:

string

Mesa 조직 슬러그입니다. 생략하면 Mesa SDK가 기본 조직을 확인합니다.

repos:

RepoConfig[]

마운트할 Mesa 저장소입니다.

cache?:

{ diskCache?: { path: string; maxSizeBytes?: number } }

Mesa 파일 시스템 캐시 구성입니다.

ttl?:

number

Mesa 마운트 토큰의 수명(초)입니다.

readOnly?:

boolean

= false

모든 저장소를 읽기 전용으로 마운트합니다.

속성

id:

string

파일 시스템 인스턴스 식별자입니다.

name:

string

Provider 이름('MesaFilesystem')입니다.

provider:

string

Provider 식별자('mesa')입니다.

readOnly:

boolean | undefined

쓰기 작업이 차단되는지 여부입니다.

client:

Mesa | undefined

이 Provider가 생성한 Mesa SDK 클라이언트입니다. 초기화 전에는 undefined입니다.

filesystem:

MesaFileSystem

활성 Mesa 파일 시스템입니다. 원시 Mesa SDK 파일 시스템이 필요할 때 초기화 후 이 속성에 액세스합니다.

change:

MesaFileSystem["change"]

마운트된 파일 시스템의 Mesa 변경 관리 작업입니다.

bookmark:

MesaFileSystem["bookmark"]

마운트된 파일 시스템의 Mesa 북마크 관리 작업입니다.

행동 양식

MesaFilesystem구현WorkspaceFilesystem interface.

파일 작업

readFile(path, options?)

메사에서 파일을 읽습니다.

const content = await filesystem.readFile('/acme/docs/README.md', {
  encoding: 'utf-8',
})

보고:Promise<string | Buffer>

writeFile(path, content, options?)

메사에 파일을 씁니다.

await filesystem.writeFile('/acme/docs/report.md', '# Report')

보고:Promise<void>

appendFile(path, content)

파일에 콘텐츠를 추가합니다.

await filesystem.appendFile('/acme/docs/log.txt', 'new line\n')

보고:Promise<void>

deleteFile(path, options?)

파일을 삭제합니다.

await filesystem.deleteFile('/acme/docs/old-report.md')

보고:Promise<void>

copyFile(src, dest, options?)

파일을 복사합니다.

await filesystem.copyFile('/acme/docs/report.md', '/acme/docs/archive/report.md')

보고:Promise<void>

moveFile(src, dest, options?)

파일을 이동하거나 이름을 바꿉니다.

await filesystem.moveFile('/acme/docs/draft.md', '/acme/docs/final.md')

보고:Promise<void>

디렉토리 작업

mkdir(path, options?)

디렉터리를 생성합니다.

await filesystem.mkdir('/acme/docs/reports', { recursive: true })

보고:Promise<void>

rmdir(path, options?)

디렉터리를 제거합니다.

await filesystem.rmdir('/acme/docs/reports', { recursive: true })

보고:Promise<void>

readdir(path, options?)

디렉토리 항목을 나열합니다.

const entries = await filesystem.readdir('/acme/docs', {
  recursive: true,
  extension: '.md',
})

보고:Promise<FileEntry[]>

경로 작업

exists(path)

경로가 존재하는지 확인합니다.

const exists = await filesystem.exists('/acme/docs/README.md')

보고:Promise<boolean>

stat(path)

파일 또는 디렉터리 메타데이터를 반환합니다.

const stat = await filesystem.stat('/acme/docs/README.md')

보고:Promise<FileStat>

realpath(path)

메사로부터 표준 경로를 반환합니다.

const realPath = await filesystem.realpath('/acme/docs/README.md')

보고:Promise<string>

메사 운영

bash(options?)

이 파일 시스템에 대해 Mesa 기반 Bash 런타임을 생성합니다.

const bash = await filesystem.bash({
  cwd: '/acme/docs',
})

보고:Promise<Bash>

경로 의미론

메서드에는 절대 경로가 필요합니다. MesaFilesystem에서 경로의 루트는 Mesa 마운트이며 조직 슬러그와 저장소 이름을 포함해야 합니다:

await filesystem.readFile('/acme/docs/README.md')

선행 슬래시를 생략하지 마십시오.

await filesystem.readFile('acme/docs/README.md') // Incorrect
await filesystem.readFile('/acme/docs/README.md') // Correct

조직은 생성자의 org에서 가져오며, org를 생략하면 Mesa SDK의 기본 조직 추론을 통해 가져옵니다. 조직은 항상 첫 번째 경로 세그먼트입니다. 여러 저장소를 마운트하면 각 저장소를 조직 세그먼트에서 사용할 수 있습니다.

const filesystem = new MesaFilesystem({
  org: 'acme',
  repos: [
    { name: 'docs', bookmark: 'main' },
    { name: 'website', bookmark: 'main' },
  ],
})

await filesystem.readFile('/acme/docs/README.md')
await filesystem.readFile('/acme/website/package.json')

메사 버전 관리 API

Mesa 관련 변경 및 북마크 작업을 위해 기본 Mesa 파일 시스템에 액세스합니다.

await filesystem.writeFile('/acme/docs/draft.md', 'Draft')

const current = await filesystem.change.current({
  repo: 'docs',
})

await filesystem.bookmark.move({
  repo: 'docs',
  name: 'main',
  changeId: current.changeId,
})

버전 관리 의미에 대한 자세한 내용은 다음에서 확인할 수 있습니다.Mesa's docs.

읽기 전용 모드

Mastra를 통한 쓰기 작업을 차단하려면 readOnly: true를 설정합니다:

const filesystem = new MesaFilesystem({
  repos: [{ name: 'docs', bookmark: 'main' }],
  readOnly: true,
})

읽기 작업은 계속 작동합니다. 쓰기 작업 던지기WorkspaceReadOnlyError.

동시성

overwrite: false와 expectedMtime은 쓰기 전에 사전 검사를 사용합니다. Mesa가 앱 마운트에 네이티브 조건부 쓰기를 추가하지 않는 한 이러한 검사는 원자적이지 않습니다.

관련된

• WorkspaceFilesystem 인터페이스
• 파일 시스템 문서
• 작업공간 개요
• 메사 문서