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

# Workspace

[Workspace](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview) 為 Agent 提供檔案系統存取權與指令執行能力。透過 `mastra dev` 或 `mastra build` 探索檔案式 Agent 時，Agent 會自動取得預設 Workspace，因此不需額外設定便能讀寫檔案及執行 shell 指令。

本頁說明檔案式慣例。Workspace Provider、Tool、搜尋、生命週期與 Sandbox 詳細資訊請參閱 [Workspace](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)。

## 預設 Workspace

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

- 以 Agent bundle 內的 Workspace 目錄為根目錄的 [`LocalFilesystem`](https://mastra.zisheng.pro/zh-TW/reference/workspace/local-filesystem)。
- 工作目錄相同的 [`LocalSandbox`](https://mastra.zisheng.pro/zh-TW/reference/workspace/local-sandbox)。

這會自動為 Agent 提供檔案 Tool 與 shell Tool。預設 Workspace 為各 Agent 專用；subagent 的 Workspace 目錄會巢狀放在父 Agent 的 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-TW/reference/workspace/workspace-class)。

## 何時自訂 Workspace

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

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

Provider 模式與執行階段行為請參閱 [Workspace 概觀](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)、[Sandbox 指南](https://mastra.zisheng.pro/zh-TW/docs/workspace/sandbox)和 [Workspace 搜尋](https://mastra.zisheng.pro/zh-TW/docs/workspace/search)。

## 執行階段邊界

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

## 種子檔案

加入 `workspace/` 目錄，以包含 Agent 的初始檔案。Mastra 會在建置時將 `workspace/` 下的檔案鏡像至 Agent 的預設執行階段 Workspace，讓 Agent 啟動時，這些檔案已存在於磁碟中。

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

檔案會複製至 bundle 內的 Workspace 路徑，Workspace 檔案 Tool 與 Sandbox 指令可在該處讀取檔案。鏡像期間會略過 symlink 種子檔案。

## 與 config 的優先順序

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