Filesystem 文件系统

文件系统为 agent 提供读取、写入、列出和搜索文件的工具。将其用作知识库，或在临时 sandbox 运行之间持久化文件。

可以通过两种方式配置文件：

• 直接文件系统访问使用 filesystem 搭配一个文件系统提供商，或搭配你自己创建的 CompositeFilesystem。
• 挂载使用 mounts 从带路径前缀的提供商创建 CompositeFilesystem。当静态 sandbox 和文件系统提供商支持挂载时，Mastra 会自动将提供商挂载到其配置的路径。远程 sandbox 挂载通常使用 Filesystem in Userspace (FUSE)。

配置 filesystem 或 mounts 之一，不要同时配置两者。同时配置会抛出代码为 INVALID_CONFIG 的 WorkspaceError。

两种配置都会为 agent 提供文件工具。Sandbox 命令只有在 sandbox 能成功挂载提供商时才能看到它。

配置文件系统会为 agent 提供以下工具：

工具	作用
mastra_workspace_read_file	读取文件的全部或部分内容。
mastra_workspace_write_file	创建或覆盖文件。
mastra_workspace_edit_file	替换现有文件中匹配的文本。
mastra_workspace_list_files	列出文件和目录。
mastra_workspace_delete	删除文件或目录。
mastra_workspace_file_stat	返回文件或目录的元数据。
mastra_workspace_mkdir	创建目录及其缺失的父目录。
mastra_workspace_grep	使用正则表达式搜索文件内容。
mastra_workspace_ast_edit	应用结构化代码编辑。安装 @ast-grep/napi 后可用。

支持的文件系统

LocalFilesystem

LocalFilesystem 连接到与 Mastra 应用相同机器上的目录。将其用于本地开发或已存在于应用宿主上的文件。

其他文件系统

当文件位于应用宿主之外或已存在于外部服务中时，使用其他提供商：

• AgentFS
• Amazon S3
• Archil
• Azure Blob
• Google Cloud Storage
• Google Drive
• Mastra Platform
• Mesa
• Vercel Files

每个提供商都通过 filesystem 支持文件工具。Sandbox 挂载取决于文件系统提供商和 sandbox 后端两者。

直接文件系统访问

当 agent 应通过文件工具访问提供商时，使用 filesystem。它也可以接受解析器或手动创建的 CompositeFilesystem。

为 agent 提供访问本地知识库的文件工具：

import { LocalFilesystem, Workspace } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './knowledge-base',
  }),
})

Agent 会收到 mastra_workspace_read_file、mastra_workspace_write_file、mastra_workspace_list_files 和 mastra_workspace_grep 等工具。路径在 ./knowledge-base 下解析，不需要 sandbox 或命令工具。

请参阅搜索以索引文件以进行关键词或语义检索。关于每个生成的工具及其策略，请参阅文件系统工具参考。

挂载

当 sandbox 内的程序需要按路径访问持久文件时，使用 mounts。当 sandbox 和文件系统提供商支持时，Mastra 会自动创建挂载。Agent 仍会收到文件工具，同时命令工具可以针对相同的文件运行 ls、cat 或 python 等命令。

例如，在 Daytona sandbox 内将 S3 存储桶挂载到 /workspace：

import { Mastra } from '@mastra/core'
import { Workspace } from '@mastra/core/workspace'
import { DaytonaSandbox } from '@mastra/daytona'
import { S3Filesystem } from '@mastra/s3'

const workspace = new Workspace({
  mounts: {
    '/workspace': new S3Filesystem({
      bucket: process.env.S3_BUCKET!,
      region: 'us-east-1',
    }),
  },
  sandbox: new DaytonaSandbox(),
})

export const mastra = new Mastra({ workspace })

使用挂载

已通过提供商可用的文件会出现在 /workspace 下。Agent 可以调用 read_file('/workspace/report.md') 或运行 cat /workspace/report.md。通过任一接口写入的文件都会由提供商保存，并在 sandbox 停止后仍然可用。

没有挂载时，agent 仍可以通过在工具调用之间传递文件内容来组合文件工具和 sandbox 命令。这适用于选定的文本文件。当程序期望目录树或需要处理大型或二进制文件时，挂载更合适。

注意

文件工具和命令工具的策略是独立的。例如，要求 write_file 审批并不会阻止 agent 使用 execute_command 写入同一挂载路径。如果文件必须只能通过文件工具访问，请禁用 sandbox 命令工具。

路径

挂载路径是暴露给文件工具的路径，在成功挂载 sandbox 后也是暴露给命令的路径。底层提供商可能将这些文件存储在其他位置。

对于挂载在 /workspace 的远程提供商：

• 文件工具使用 /workspace/report.md 等路径。
• 远程 sandbox 命令通常使用相同的路径。
• 提供商将该路径映射到其配置的存储桶、前缀或远程目录。

LocalSandbox 则在其 workingDirectory 内创建一个符号链接。/workspace 挂载在宿主上变为 <workingDirectory>/workspace，命令通常以 workspace 访问它。

Composite 文件系统

mounts 选项会创建一个 CompositeFilesystem。这个 TypeScript 路径路由器将多个提供商呈现为一个虚拟目录树。

多个文件系统

在其挂载路径下配置每个提供商：

import { Workspace } from '@mastra/core/workspace'
import { E2BSandbox } from '@mastra/e2b'
import { GCSFilesystem } from '@mastra/gcs'
import { S3Filesystem } from '@mastra/s3'

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'agent-data',
      region: 'us-east-1',
    }),
    '/reports': new GCSFilesystem({
      bucket: 'agent-reports',
    }),
  },
  sandbox: new E2BSandbox({ id: 'analysis-sandbox' }),
})

使用此配置：

• list_files('/') 返回虚拟目录 data 和 reports。
• read_file('/data/input.csv') 路由到 S3 提供商。
• write_file('/reports/summary.md') 路由到 Google Cloud Storage 提供商。
• 当每个 sandbox 挂载成功时，sandbox 命令使用相同的路径。

Composite 会在将剩余路径传递给提供商之前剥离挂载前缀。挂载路径不能嵌套，因此同一个 composite 不能同时包含 /data 和 /data/archive。

没有 sandbox 时

你可以在没有 sandbox 的情况下配置 mounts。Mastra 仍会创建 CompositeFilesystem，所有文件工具都可使用带挂载前缀的路径。由于未配置 sandbox，agent 不会收到命令或进程工具。

手动组合

你也可以自己创建 CompositeFilesystem 并通过 filesystem 传入，以实现路径路由而不自动接线 sandbox 挂载：

import { CompositeFilesystem, LocalFilesystem, Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'

const filesystem = new CompositeFilesystem({
  mounts: {
    '/local': new LocalFilesystem({ basePath: './data' }),
    '/archive': new S3Filesystem({
      bucket: 'agent-archive',
      region: 'us-east-1',
    }),
  },
})

const workspace = new Workspace({ filesystem })

当应用的其他部分需要将该 composite 作为文件系统提供商使用时，请使用手动组合。对于常规 sandbox 挂载，mounts 选项以更少的配置执行相同的路由设置。

挂载可用性

文件工具和 composite 路由无需 sandbox 挂载即可工作。当远程 sandbox 和文件系统提供商支持挂载时，mounts 会自动使用 FUSE 使文件对命令可见。LocalSandbox 则使用符号链接。

内置 sandbox 挂载目前包括：

Sandbox 后端	文件系统提供商
LocalSandbox	LocalFilesystem
E2B	Amazon S3、Google Cloud Storage、Azure Blob Storage
Daytona	Amazon S3、Google Cloud Storage、Azure Blob Storage
Blaxel	Amazon S3、Google Cloud Storage

远程挂载可能需要在 sandbox 内安装 s3fs、gcsfuse 或 blobfuse2。某些后端会在启动期间安装缺失的软件，这可能需要网络访问并增加启动时间。其他组合需要 onMount hook 或提供商特定的设置。

如果 sandbox 挂载不可用或失败，workspace 仍然可用。文件工具继续通过其 SDK 访问提供商，但命令无法看到该路径。Mastra 会向 agent 描述这些提供商仅可通过文件工具使用。

每个用户或 thread 的文件系统

当存储应因请求、用户、角色或租户而异时，filesystem 选项接受解析器：

const workspace = new Workspace({
  filesystem: ({ requestContext }) => {
    const userId = requestContext.get('user-id') as string

    return new S3Filesystem({
      bucket: process.env.S3_BUCKET!,
      region: process.env.S3_REGION!,
      prefix: `users/${userId}`,
    })
  },
})

每个用户获得独立的文件系统视图，文件工具会自动从 request context 解析提供商。

mounts 不接受解析器，也不能与 sandbox 解析器组合使用。当每个用户或 thread 需要在单独 sandbox 内使用单独存储时，请在 sandbox 解析器内部创建并挂载提供商。请参阅每个用户或 thread 的 sandboxes。

策略与包含

使用 WORKSPACE_TOOLS.FILESYSTEM 下的单独常量（例如 WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE）配置每个文件工具。全局或按工具设置审批。在单个文件系统工具条目上配置写前读取和输出限制。请参阅文件系统工具配置参考。

LocalFilesystem 默认将访问限制在 basePath 内。当 agent 需要该根目录之外的特定目录时，使用 allowedPaths：

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './knowledge-base',
    allowedPaths: ['../shared-policies'],
  }),
})

包含限制适用于文件系统操作，包括文件工具和搜索索引。它不会限制 shell 命令。

当 agent 应使用文件而不更改它们时，设置 readOnly: true。对于静态提供商，Mastra 会移除与写入相关的文件工具。

使用文件系统解析器时，写工具仍会注册，因为在请求运行之前无法知道提供商。提供商会在 runtime 拒绝写入尝试。

对于 composite 中的 LocalFilesystem 条目，请保持 contained: true（默认值）。仅当有意进行不受限制的宿主文件系统访问时，才设置 contained: false。

相关

• Sandboxes
• 搜索
• 文件系统提供商接口
• 配置 API 参考