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

# Workspace

[Workspace](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview) 為 Agent 提供檔案系統存取權限及指令執行功能。透過 `mastra dev` 或 `mastra build` 探索到檔案式 Agent 時，系統會自動為它們提供預設 Workspace，因此毋須額外設定即可讀寫檔案及執行 shell 指令。

本頁說明檔案式慣例。如需了解 Workspace Provider、Tools、搜尋、生命週期及 Sandbox 詳情，請參閱 [Workspaces](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)。

## 預設 Workspace

如果沒有 `workspace.ts`，當建置提供各 Agent 專用的 Workspace 路徑時，檔案式 Agent 會取得預設 [`Workspace`](https://mastra.zisheng.pro/zh-HK/reference/workspace/workspace-class)。預設 Workspace 使用：

- [`LocalFilesystem`](https://mastra.zisheng.pro/zh-HK/reference/workspace/local-filesystem)，根目錄設於 Agent 的已封裝 Workspace 目錄。
- [`LocalSandbox`](https://mastra.zisheng.pro/zh-HK/reference/workspace/local-sandbox)，使用相同的工作目錄。

這會自動為 Agent 提供檔案 Tools 及 shell Tools。每個 Agent 均有自己的預設 Workspace；subagents 會在其父 Agent 的 Workspace 路徑下取得巢狀 Workspace 目錄。

## 快速開始

如要使用預設 Workspace，毋須新增檔案。請由以下 Agent 目錄開始：

```text
src/mastra/agents/weather/
├── config.ts
└── instructions.md
```

只有需要自訂 Workspace 時才新增 `workspace.ts`：

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

export default new Workspace({
  name: 'weather-workspace',
  filesystem: new LocalFilesystem({ basePath: './data/weather' }),
  sandbox: new LocalSandbox({ workingDirectory: './data/weather' }),
})
```

請瀏覽 [`Workspace` 參考資料](https://mastra.zisheng.pro/zh-HK/reference/workspace/workspace-class)了解完整 config。

## 何時自訂 Workspace

預設本機目錄不足以應付需要時，請自訂 Workspace。常見原因包括：

- 將檔案 Tools 指向不同的檔案系統根目錄。
- 在不同的 Sandbox Provider 中執行 shell 指令。
- 使用 BM25 或向量搜尋新增 Workspace 搜尋功能。
- 讓多個 Agent 共用同一個 Workspace。

如需了解 Provider 模式及執行階段行為，請參閱 [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)、[Sandbox 指南](https://mastra.zisheng.pro/zh-HK/docs/workspace/sandbox)及 [Workspace 搜尋](https://mastra.zisheng.pro/zh-HK/docs/workspace/search)。

## 執行階段邊界

Workspace 檔案系統控制檔案 Tools 可讀寫的內容。Sandbox 控制 shell 指令的執行位置。應用程式執行階段程式碼（包括 [`tools/`](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/tools) 中的程式碼）仍會在你的應用程式／伺服器處理程序中執行，除非它明確呼叫 Workspace 或 Sandbox API。

## 初始檔案

新增 `workspace/` 目錄，將初始檔案包含在 Agent 中。Mastra 會在建置時，將 `workspace/` 下的檔案鏡像複製到 Agent 的預設執行階段 Workspace，讓 Agent 啟動時磁碟上已有這些檔案。

```text
src/mastra/agents/weather/
├── config.ts
└── workspace/
    ├── README.md
    └── data/
        └── cities.json
```

這些檔案會複製到已封裝的 Workspace 路徑，供 Workspace 檔案 Tools 及 Sandbox 指令讀取。鏡像複製期間會略過符號連結的初始檔案。

## 與 config 的優先次序

`config.workspace` 的優先次序高於 `workspace.ts`；否則會使用預設檔案式 Workspace。完整合併表請參閱 [`config.ts` 優先次序](https://mastra.zisheng.pro/zh-HK/reference/file-based-agents/config)。