> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 文件系统

**加入版本：** `@mastra/core@1.1.0`

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

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

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

## 支持的 Provider

可用 Provider：

- [`LocalFilesystem`](https://mastra.zisheng.pro/reference/workspace/local-filesystem)：将文件存储在磁盘目录中
- [`S3Filesystem`](https://mastra.zisheng.pro/reference/workspace/s3-filesystem)：将文件存储在 Amazon S3 或兼容 S3 的 Storage（R2、MinIO、Tigris）中
- [`GCSFilesystem`](https://mastra.zisheng.pro/reference/workspace/gcs-filesystem)：将文件存储在 Google Cloud Storage 中
- [`PlatformFilesystem`](https://mastra.zisheng.pro/reference/workspace/platform-filesystem)：将文件存储在 Mastra Platform Workspace bucket 中
- [`GoogleDriveFilesystem`](https://mastra.zisheng.pro/reference/workspace/google-drive-filesystem)：将文件存储在 Google Drive 文件夹中
- [`AzureBlobFilesystem`](https://mastra.zisheng.pro/reference/workspace/azure-blob-filesystem)：将文件存储在 Azure Blob Storage 中
- [`FilesSDKFilesystem`](https://mastra.zisheng.pro/reference/workspace/files-sdk-filesystem)：将文件存储在任意 [FilesSDK](https://files-sdk.dev) adapter（S3、R2、GCS、Azure Blob、Vercel Blob、本地文件系统等）中；当你希望通过一个 Provider 使用多个后端时，这很有用
- [`AgentFSFilesystem`](https://mastra.zisheng.pro/reference/workspace/agentfs-filesystem)：通过 AgentFS 将文件存储在 Turso/SQLite 数据库中
- [`MesaFilesystem`](https://mastra.zisheng.pro/reference/workspace/mesa-filesystem)：将文件存储在有版本控制的 Mesa repo 中
- [`ArchilFilesystem`](https://mastra.zisheng.pro/reference/workspace/archil-filesystem)：将文件存储在 Archil 弹性 serverless 磁盘中

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

## 基本用法

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

```typescript
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` 解析，绝对路径则直接使用：

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

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

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

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

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

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

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

## 动态文件系统

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

```typescript
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 指令解析自己的文件系统：

```typescript
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 也可以是异步函数，例如从数据库查找配置：

```typescript
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 修改文件，请启用只读模式：

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

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

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

## Mount 与 `CompositeFilesystem`

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

```typescript
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 和命令执行能力。有关详情，请参阅[配置模式](https://mastra.zisheng.pro/docs/workspace/overview)。

## Agent Tool

在 Workspace 上配置文件系统后，Agent 会获得读取、写入、列出和删除文件的 Tool。有关详情，请参阅 [Workspace 类 Reference](https://mastra.zisheng.pro/reference/workspace/workspace-class)。

## 相关内容

- [LocalFilesystem Reference](https://mastra.zisheng.pro/reference/workspace/local-filesystem)
- [S3Filesystem Reference](https://mastra.zisheng.pro/reference/workspace/s3-filesystem)
- [GCSFilesystem Reference](https://mastra.zisheng.pro/reference/workspace/gcs-filesystem)
- [GoogleDriveFilesystem Reference](https://mastra.zisheng.pro/reference/workspace/google-drive-filesystem)
- [AzureBlobFilesystem Reference](https://mastra.zisheng.pro/reference/workspace/azure-blob-filesystem)
- [FilesSDKFilesystem Reference](https://mastra.zisheng.pro/reference/workspace/files-sdk-filesystem)
- [AgentFSFilesystem Reference](https://mastra.zisheng.pro/reference/workspace/agentfs-filesystem)
- [MesaFilesystem Reference](https://mastra.zisheng.pro/reference/workspace/mesa-filesystem)
- [Workspace 概述](https://mastra.zisheng.pro/docs/workspace/overview)
- [Sandbox](https://mastra.zisheng.pro/docs/workspace/sandbox)