WorkspaceFilesystem

新增於： @mastra/core@1.1.0

WorkspaceFilesystem 介面定義 Workspace 如何與檔案儲存系統互動。

方法

readFile(path, options?)

讀取檔案內容。

const content = await filesystem.readFile('/docs/guide.md')
const buffer = await filesystem.readFile('/image.png', { encoding: 'binary' })

參數：

path:

string

相對於 basePath 的檔案路徑

options?:

Options

readFile 選項。

Options

encoding?:

'utf-8' | 'binary'

文字或二進制編碼

傳回： Promise<string | Buffer>

writeFile(path, content, options?)

寫入檔案內容。

await filesystem.writeFile('/docs/new.md', '# New Document')
await filesystem.writeFile('/nested/path/file.md', content, { recursive: true })

參數：

path:

string

相對於 basePath 的檔案路徑

content:

string | Buffer

檔案內容

options?:

Options

設定選項。

Options

recursive?:

boolean

如果上層目錄不存在，則建立這些目錄

overwrite?:

boolean

覆寫現有檔案

expectedMtime?:

Date

如有提供，而檔案目前的修改時間不相符，寫入便會失敗並產生 StaleFileError。使用此選項進行樂觀併發控制，以偵測讀取與寫入之間的外部修改。

deleteFile(path, options?)

刪除檔案。

await filesystem.deleteFile('/docs/old.md')
await filesystem.deleteFile('/docs/maybe.md', { force: true }) // Don't throw if missing

參數：

path:

string

檔案路徑

options?:

Options

設定選項。

Options

force?:

boolean

如果檔案不存在，不會拋出錯誤

appendFile(path, content)

將內容附加至檔案；如果檔案尚未存在，則建立檔案。系統會自動建立上層目錄。

await filesystem.appendFile('/logs/app.log', 'New log entry\n')

參數：

path:

string

檔案路徑

content:

string | Buffer

要附加的內容

copyFile(src, dest, options?)

將檔案複製到新位置。

await filesystem.copyFile('/docs/template.md', '/docs/new-doc.md')

參數：

src:

string

來源檔案路徑

dest:

string

目的地檔案路徑

options?:

Options

設定選項。

Options

overwrite?:

boolean

如果目的地已存在，則將其覆寫

moveFile(src, dest, options?)

移動檔案或重新命名。

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

參數：

src:

string

來源檔案路徑

dest:

string

目的地檔案路徑

options?:

Options

設定選項。

Options

overwrite?:

boolean

如果目的地已存在，則將其覆寫

readdir(path, options?)

列出目錄內容。

const entries = await filesystem.readdir('/docs')
// [{ name: 'guide.md', type: 'file' }, { name: 'api', type: 'directory' }]

傳回： Promise<FileEntry[]>

interface FileEntry {
  name: string
  type: 'file' | 'directory'
  size?: number
  isSymlink?: boolean
  symlinkTarget?: string
}

mkdir(path, options?)

建立目錄。

await filesystem.mkdir('/docs/api')
await filesystem.mkdir('/deeply/nested/path', { recursive: true })

參數：

path:

string

目錄路徑

options?:

Options

設定選項。

Options

recursive?:

boolean

建立上層目錄

rmdir(path, options?)

移除目錄。

await filesystem.rmdir('/docs/old')
await filesystem.rmdir('/docs/nested', { recursive: true })

參數：

path:

string

目錄路徑

options?:

Options

設定選項。

Options

recursive?:

boolean

以遞迴方式移除內容

force?:

boolean

如果目錄不存在，不會拋出錯誤

exists(path)

檢查路徑是否存在。

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

傳回： Promise<boolean>

stat(path)

取得檔案或目錄的元數據。

const stat = await filesystem.stat('/docs/guide.md')
// { name: 'guide.md', path: '/docs/guide.md', type: 'file', size: 1234, createdAt: Date, modifiedAt: Date }

傳回： Promise<FileStat>

interface FileStat {
  name: string // File or directory name (basename only)
  path: string // Path relative to the filesystem basePath
  type: 'file' | 'directory'
  size: number
  createdAt: Date
  modifiedAt: Date
  mimeType?: string
}

選用方法

init()

初始化檔案系統。由 workspace.init() 呼叫。

await filesystem.init?.()

destroy()

清理資源。由 workspace.destroy() 呼叫。

await filesystem.destroy?.()

getInfo()

取得檔案系統元數據。

const info = await filesystem.getInfo?.()
// { id, name, provider, basePath, readOnly, status, storage? }

傳回： Promise<FilesystemInfo>

interface FilesystemInfo {
  id: string
  name: string
  provider: string
  basePath?: string
  readOnly?: boolean
  status?: string
  storage?: {
    totalBytes?: number
    usedBytes?: number
    availableBytes?: number
  }
}

getInstructions(opts?)

傳回有關此檔案系統運作方式的說明。將 Workspace 指派給 Agent 時，此內容會注入 Agent 的系統訊息。

const instructions = filesystem.getInstructions?.()
// 'Local filesystem at "/workspace". Files at workspace path "/foo" are stored at "/workspace/foo" on disk.'

參數：

opts.requestContext?:

RequestContext

如果建構函數有提供 instructions 函數，便會將此值轉送給該函數。

傳回： string

相關內容

• Workspace 類別
• Sandbox 介面