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

# 檔案系統

**新增於：** `@mastra/core@1.1.0`

檔案系統 Provider 讓 Agent 能讀取、寫入及管理檔案。在 Workspace 上設定檔案系統後，Agent 會取得檔案操作 Tool。

檔案系統 Provider 會處理 Workspace 的所有檔案操作：

- **讀取** - 讀取檔案內容
- **寫入** - 建立及更新檔案
- **列出** - 瀏覽目錄，並可選擇使用 glob 模式篩選
- **刪除** - 移除檔案與目錄
- **Stat** - 取得檔案中繼資料
- **複製／移動** - 在不同位置間複製或移動檔案
- **Grep** - 使用規則運算式模式搜尋檔案內容

## 支援的 Provider

可用的 Provider：

- [`LocalFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/local-filesystem)：將檔案儲存在磁碟目錄中
- [`S3Filesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/s3-filesystem)：將檔案儲存在 Amazon S3 或 S3 相容儲存空間（R2、MinIO、Tigris）
- [`GCSFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/gcs-filesystem)：將檔案儲存在 Google Cloud Storage
- [`PlatformFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/platform-filesystem)：將檔案儲存在 Mastra Platform Workspace Bucket
- [`GoogleDriveFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/google-drive-filesystem)：將檔案儲存在 Google Drive 資料夾內
- [`AzureBlobFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/azure-blob-filesystem)：將檔案儲存在 Azure Blob Storage
- [`FilesSDKFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/files-sdk-filesystem)：將檔案儲存在任何 [FilesSDK](https://files-sdk.dev) Adapter（S3、R2、GCS、Azure Blob、Vercel Blob、本機檔案系統等）；適合以單一 Provider 對接多種後端
- [`AgentFSFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/agentfs-filesystem)：透過 AgentFS 將檔案儲存在 Turso/SQLite 資料庫中
- [`MesaFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/mesa-filesystem)：將檔案儲存在具有版本控制的 Mesa Repo 中
- [`ArchilFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/archil-filesystem)：將檔案儲存在 Archil 彈性無伺服器磁碟中

> **提示:** `LocalFilesystem` 不需要外部服務，是最簡單的入門方式。雲端儲存空間可使用 `S3Filesystem`、`GCSFilesystem` 或 `AzureBlobFilesystem`；版本化儲存空間可使用 `MesaFilesystem`；不依賴外部服務的資料庫型儲存空間可使用 `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` 內。這能防止路徑遍歷攻擊與 symlink 逸出。

在受限模式中：

- **相對路徑**（例如 `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` 選項除了靜態執行個體，也接受解析器函式。解析器會接收 `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 的檔案系統情境。

解析器也可以是非同步函式，例如從資料庫查詢設定：

```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 中不能同時使用解析器函式與 `mounts`。

## 唯讀模式

若要防止 Agent 修改檔案，請啟用唯讀模式：

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

使用靜態檔案系統時，寫入 Tool（`write_file`、`edit_file`、`delete`、`mkdir`）會完全排除在 Agent 的 Tool 集合之外。Agent 仍可讀取及列出檔案。

使用[動態檔案系統](#dynamic-filesystem)時，由於解析器執行前無法得知 `readOnly`，因此寫入 Tool 一律會包含在內。寫入操作改在執行階段遭到阻擋；若解析出的檔案系統為唯讀，Tool 便會傳回錯誤。

## 掛載與 `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 掛載存取 `/data` 與 `/skills` 的檔案

### 路徑路由

所有檔案路徑都必須以掛載前綴開頭，因為路徑不符合任何掛載點時操作會失敗。列出根目錄（`/`）會傳回各掛載點的虛擬目錄項目。

掛載路徑不能巢狀，例如不能同時掛載 `/data` 與 `/data/sub`。

### `filesystem` 與 `mounts` 的比較

`filesystem` 與 `mounts` 是 Workspace 上互斥的選項：

- 只有單一儲存空間 Provider，且不需要將其掛載至 Sandbox 時，請使用 **`filesystem`**。Agent 會取得直接操作該 Provider 的檔案 Tool。
- 需要在 Sandbox 中存取雲端儲存空間，或要合併多個 Provider 時，請使用 **`mounts`**。Workspace 會為檔案 Tool 建立 CompositeFilesystem，並透過 FUSE 將儲存空間掛載至 Sandbox。

進行本機開發時通常不需要 `mounts`；讓 `LocalFilesystem` 與 `LocalSandbox` 指向同一目錄，即可對相同檔案同時使用檔案 Tool 與命令執行功能。詳情請參閱[設定模式](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)。

## Agent Tool

在 Workspace 上設定檔案系統後，Agent 會取得讀取、寫入、列出及刪除檔案的 Tool。詳情請參閱 [Workspace 類別參考](https://mastra.zisheng.pro/zh-TW/reference/workspace/workspace-class)。

## 相關資源

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