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

# Workspaces

Workspace 是 Mastra 平台在部署時佈建並交予 Agent 使用的一組執行階段資源。每個環境都有獨立的 Workspace，確保 `production` 與 `staging` 互相隔離。

每個 Workspace 都提供兩項功能：

- 一個用於檔案系統儲存的 **bucket**，由 [`PlatformFilesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/platform-filesystem) 封裝。這個 bucket 是按環境劃分的持久儲存空間，Agent 可在不同執行之間讀寫資料。
- 一組按需要提供、用於執行命令的 **Sandbox**，由 [`PlatformSandbox`](https://mastra.zisheng.pro/zh-HK/reference/workspace/platform-sandbox) 封裝。每個 `PlatformSandbox` 實例都會在 `start()` 時佈建專屬的遠端 Sandbox，並在 `destroy()` 時將其銷毀。Agent 通常會在每個工作階段啟動多個 Sandbox，用它們完成工作後便釋放資源。

Workspace 只屬於單一[環境](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/environments)，因此 `production` 與 `staging` 不會共用 bucket 或 Sandbox 資源池。平台會管理佈建、驗證及閒置資源清理。

## 何時佈建 Workspace

新項目預設會啟用 Workspace。建立環境時，平台會自動為該環境佈建 bucket。Sandbox 基礎映像檔會在背景預熱，讓首次 `PlatformSandbox` 呼叫可以快速啟動。

尚未選擇啟用的現有項目會在 Workspaces 分頁顯示 **Enable workspaces** 操作。啟用後，系統會為項目中的每個環境佈建 bucket。

如果某個環境佈建失敗（例如 Sandbox Provider 負載過高），Workspaces 分頁會顯示失敗狀態並提供重試選項。環境本身仍會建立，只有 Workspace 在你重試前無法使用。

## 在程式碼中使用 Workspace

安裝 Provider 套件：

**npm**:

```bash
npm install @mastra/platform-workspace
```

**pnpm**:

```bash
pnpm add @mastra/platform-workspace
```

**Yarn**:

```bash
yarn add @mastra/platform-workspace
```

**Bun**:

```bash
bun add @mastra/platform-workspace
```

將各個 Provider 組合成 Workspace，並向 Mastra 註冊：

```typescript
import { Workspace } from '@mastra/core/workspace'
import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'

export const workspace = new Workspace({
  filesystem: new PlatformFilesystem(),
  sandbox: new PlatformSandbox(),
})
```

```typescript
import { Mastra } from '@mastra/core'
import { workspace } from './workspace'

export const mastra = new Mastra({
  workspace,
})
```

`PlatformFilesystem` 與 `PlatformSandbox` 會從環境變數讀取設定，因此在平台上毋須傳入任何選項。平台會在部署時注入這些變數。詳情請參閱[環境變數](#environment-variables)。

## 一個 bucket，多個 Sandbox

`PlatformFilesystem` 與 `PlatformSandbox` 的生命週期不同，設計 Agent 時必須留意這一點。

**`PlatformFilesystem` 是環境 bucket 的長期存取介面。** 環境中的所有請求、Agent 及 Sandbox 都會讀寫相同的物件儲存空間。除非你明確刪除資料，否則 Agent 寫入的所有內容都可供下一個請求存取。

**`PlatformSandbox` 是用於佈建臨時 Sandbox 的客戶端。** 每個 `PlatformSandbox` 實例都擁有一個遠端 Sandbox：

- `start()` 會佈建全新的 Sandbox（如果傳入了 `sandboxId`，則會重新連接）。
- `executeCommand()` 會在其中執行命令。
- `destroy()` 會終止 Sandbox。`stop()` 是它的別名。

傳給 `Workspace` 的 `sandbox` 會提供 Agent 在本身請求中使用的 Tool。當 Agent 需要另一個隔離環境時，例如每項工作專用的 Workspace、每位用戶專用的租戶，或不應影響呼叫者 shell 狀態的背景工作，請建立另一個 `PlatformSandbox`：

```typescript
import { PlatformSandbox } from '@mastra/platform-workspace'

export async function runInFreshSandbox(command: string) {
  const sandbox = new PlatformSandbox()
  await sandbox.start()
  try {
    return await sandbox.executeCommand(command)
  } finally {
    await sandbox.destroy()
  }
}
```

你亦可以複製已設定的 Sandbox，將其用作一組 Sandbox 的範本，讓複本繼承憑證、環境、網絡隔離及預設值，而毋須重複設定：

```typescript
const template = new PlatformSandbox({ networkIsolation: 'PRIVATE' })

const perProjectSandbox = template.clone({ id: `project-${projectId}` })
await perProjectSandbox.start()
```

如要了解完整生命週期、檢查點復原、重新連接及複製選項，請參閱 [`PlatformSandbox` 參考資料](https://mastra.zisheng.pro/zh-HK/reference/workspace/platform-sandbox)。

## 環境變數

每個在設有 Workspace 的平台環境中執行的部署，都會自動收到以下變數：

| 變數                             | 內容                                                                            |
| ------------------------------ | ----------------------------------------------------------------------------- |
| `MASTRA_PLATFORM_ACCESS_TOKEN` | 由平台發出的 JSON Web Token (JWT)，供 Workspace Provider 用作驗證。Token 的範圍限於該部署所屬的機構及項目。 |
| `MASTRA_PROJECT_ID`            | 部署所屬的項目。                                                                      |
| `MASTRA_ENVIRONMENT_ID`        | 部署所屬的環境，用於選擇平台所使用的 Sandbox 資源池。                                               |
| `MASTRA_PLATFORM_BUCKET_NAME`  | 連接至該環境的 bucket 名稱，用於選擇 `PlatformFilesystem` 讀寫的 bucket。                       |

這些名稱為保留名稱。如果你的項目明確設定其中任何名稱，將以平台管理的值為準。

## 本機開發

將四個變數加入 `.env` 檔案，即可在本機沿用相同的 Provider。你可從項目的 **Workspaces** 分頁取得項目、環境及 bucket 的值。至於 `MASTRA_PLATFORM_ACCESS_TOKEN`，請在機構設定頁面的 **API Tokens** 下建立 `sk_` API 金鑰；平台部署則會使用注入的 JWT。

```bash
MASTRA_PLATFORM_ACCESS_TOKEN=sk_your-api-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_ENVIRONMENT_ID=your-environment-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
```

`PlatformFilesystem` 與 `PlatformSandbox` 在本機及平台上的行為相同，兩者都會連接至該環境的同一個 bucket 及 Sandbox 資源池。如果你想將生產環境數據隔離，請在本機執行時使用 `staging` 或 `preview` 環境的變數。

如要完全離線運作而不連接平台，請在本機組建中將 Provider 換成 [`LocalFilesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/local-filesystem) 及 [`LocalSandbox`](https://mastra.zisheng.pro/zh-HK/reference/workspace/local-sandbox)。

## 檢視 Workspace

平台項目的 Workspaces 分頁會按環境顯示：

- bucket 狀態及內容，並提供上載、下載及刪除操作。
- 最近的 Sandbox 工作階段，包括其命令、結束代碼及執行時間。
- 佈建失敗項目，以及 **Retry** 操作。

## 另請參閱

- [`PlatformFilesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/platform-filesystem)：檔案系統 Provider 的參考資料。
- [`PlatformSandbox`](https://mastra.zisheng.pro/zh-HK/reference/workspace/platform-sandbox)：Sandbox Provider 的參考資料，包括檢查點復原及複製功能。
- [環境](https://mastra.zisheng.pro/zh-HK/docs/mastra-platform/environments)：環境如何劃分 Workspace、變數及資料庫。