文件系统

加入版本： @mastra/core@1.1.0

文件系统 Provider 让 Agent 能够读取、写入和管理文件。在 Workspace 上配置文件系统后，Agent 会获得用于文件操作的 Tool。

文件系统 Provider 处理 Workspace 的所有文件操作：

• 读取 - 读取文件内容
• 写入 - 创建和更新文件
• 列出 - 浏览目录，可选择使用 glob 模式筛选
• 删除 - 移除文件和目录
• Stat - 获取文件 metadata
• 复制/移动 - 在不同位置之间复制或移动文件
• Grep - 使用正则表达式搜索文件内容

支持的 Provider

可用 Provider：

• LocalFilesystem：将文件存储在磁盘目录中
• S3Filesystem：将文件存储在 Amazon S3 或兼容 S3 的 Storage（R2、MinIO、Tigris）中
• GCSFilesystem：将文件存储在 Google Cloud Storage 中
• PlatformFilesystem：将文件存储在 Mastra Platform Workspace bucket 中
• GoogleDriveFilesystem：将文件存储在 Google Drive 文件夹中
• AzureBlobFilesystem：将文件存储在 Azure Blob Storage 中
• FilesSDKFilesystem：将文件存储在任意 FilesSDK adapter（S3、R2、GCS、Azure Blob、Vercel Blob、本地文件系统等）中；当你希望通过一个 Provider 使用多个后端时，这很有用
• AgentFSFilesystem：通过 AgentFS 将文件存储在 Turso/SQLite 数据库中
• MesaFilesystem：将文件存储在有版本控制的 Mesa repo 中
• ArchilFilesystem：将文件存储在 Archil 弹性 serverless 磁盘中

提示

LocalFilesystem 不需要外部服务，是最简单的入门方式。云 Storage 可使用 S3Filesystem、GCSFilesystem 或 AzureBlobFilesystem；带版本控制的 Storage 可使用 MesaFilesystem；无需外部服务且由数据库支持的 Storage 可使用 AgentFSFilesystem。

基本用法

创建带文件系统的 Workspace，并将其分配给 Agent。随后，Agent 就能在执行任务时读取、写入和管理文件：

src/mastra/agents/file-agent.ts

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

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

const agent = new Agent({
  id: 'file-agent',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a helpful file management assistant.',
  workspace,
})

// The agent now has filesystem tools available
const response = await agent.generate('List all files in the workspace')

路径限制

默认情况下，LocalFilesystem 以限制模式运行，所有文件操作都必须位于 basePath 内。这可以防止路径遍历攻击和符号链接逃逸。

在限制模式下：

• 相对路径（例如 src/index.ts）相对于 basePath 解析
• 绝对路径（例如 /home/user/.config/file.txt）会被视为真实文件系统路径：如果位于 basePath 和任何 allowedPaths 之外，则抛出 PermissionError
• 波浪号路径（例如 ~/Documents）会展开到主目录，并遵循相同的限制规则

如果 Agent 需要访问 basePath 外的特定路径，请使用 allowedPaths 授权访问，而无需完全禁用限制。相对路径相对于 basePath 解析，绝对路径则直接使用：

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    allowedPaths: ['~/.claude/skills', '../shared-data'],
  }),
})

可以在运行时使用 setAllowedPaths() 方法更新允许的路径：

// Add a path dynamically
workspace.filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents'])

这是实现最小权限访问的推荐方式：Agent 只能访问明确允许的目录。

如果 Agent 需要不受限制地访问整个文件系统，请禁用路径限制：

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    contained: false,
  }),
})

当 contained 为 false 时，绝对路径会作为真实文件系统路径处理，不受限制。

动态文件系统

filesystem 选项接受 resolver 函数，而不只是静态实例。Resolver 接收 requestContext，并为每个请求返回文件系统，使单个 Workspace 能够根据调用方的身份、角色或租户提供不同的文件系统。

src/mastra/workspaces.ts

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

const workspace = new Workspace({
  filesystem: ({ requestContext }) => {
    const role = requestContext.get('agent-role') || 'guest'
    return new LocalFilesystem({
      basePath: `/workspaces/${role}`,
      readOnly: role !== 'admin',
    })
  },
})

const agent = new Agent({
  id: 'multi-role-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})

每个请求都会为 Workspace Tool 和 Workspace 指令解析自己的文件系统：

import { RequestContext } from '@mastra/core/request-context'

// Admin request — reads and writes from /workspaces/admin/
const adminCtx = new RequestContext([['agent-role', 'admin']])
await agent.generate('Write report.txt with Q4 results', { requestContext: adminCtx })

// Viewer request — reads from /workspaces/viewer/, writes are blocked
const viewerCtx = new RequestContext([['agent-role', 'viewer']])
await agent.generate('Read info.txt', { requestContext: viewerCtx })

Workspace 指令使用同一个 requestContext，因此 Agent 可以看到已解析 Provider 的文件系统上下文。

Resolver 也可以是异步函数，例如从数据库查找配置：

const workspace = new Workspace({
  filesystem: async ({ requestContext }) => {
    const tenantConfig = await db.getTenant(requestContext.get('tenant-id'))
    return new LocalFilesystem({ basePath: tenantConfig.storagePath })
  },
})

备注

filesystem 与 mounts 互斥。不能在同一个 Workspace 中同时使用 resolver 函数和 mounts。

只读模式

若要阻止 Agent 修改文件，请启用只读模式：

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    readOnly: true,
  }),
})

使用静态文件系统时，写入 Tool（write_file、edit_file、delete、mkdir）会从 Agent Toolset 中完全排除。Agent 仍可以读取和列出文件。

使用动态文件系统时，由于运行 resolver 前无法知道 readOnly 的值，因此写入 Tool 始终包含在内。写入操作会改在运行时被阻止；如果解析后的文件系统为只读，Tool 会返回错误。

Mount 与 CompositeFilesystem

在 Workspace 上使用 mounts 选项时，Mastra 会创建 CompositeFilesystem，根据路径前缀将文件操作路由到正确的 Provider。

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

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
    '/skills': new GCSFilesystem({
      bucket: 'agent-skills',
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})

使用此配置后：

• read_file('/data/input.csv') 从 S3 bucket 读取
• write_file('/skills/guide.md', content) 写入 GCS bucket
• list_directory('/') 返回 /data 和 /skills 的虚拟条目
• Sandbox 中的命令可以通过 FUSE mount 访问 /data 和 /skills 中的文件

路径路由

所有文件路径都必须以 mount 前缀开头，因为路径不匹配任何 mount 时操作会失败。列出根目录（/）会返回每个 mount point 的虚拟目录条目。

Mount 路径不能嵌套，例如不能同时 mount 到 /data 和 /data/sub。

filesystem 与 mounts

filesystem 和 mounts 是 Workspace 上互斥的选项：

• 只有一个 Storage Provider 且不需要将其 mount 到 Sandbox 时，使用 filesystem。Agent 会获得直接操作 Provider 的文件 Tool。
• 需要在 Sandbox 内访问云 Storage，或希望组合多个 Provider 时，使用 mounts。Workspace 会为文件 Tool 创建 CompositeFilesystem，并通过 FUSE 将 Storage mount 到 Sandbox。

本地开发通常不需要 mounts。将 LocalFilesystem 和 LocalSandbox 指向同一目录，即可同时获得在同一批文件上操作的文件 Tool 和命令执行能力。有关详情，请参阅配置模式。

Agent Tool

在 Workspace 上配置文件系统后，Agent 会获得读取、写入、列出和删除文件的 Tool。有关详情，请参阅 Workspace 类 Reference。

相关内容

• LocalFilesystem Reference
• S3Filesystem Reference
• GCSFilesystem Reference
• GoogleDriveFilesystem Reference
• AzureBlobFilesystem Reference
• FilesSDKFilesystem Reference
• AgentFSFilesystem Reference
• MesaFilesystem Reference
• Workspace 概述
• Sandbox