Workspace

Workspace 為 Agent 提供檔案系統存取權限及指令執行功能。透過 mastra dev 或 mastra build 探索到檔案式 Agent 時，系統會自動為它們提供預設 Workspace，因此毋須額外設定即可讀寫檔案及執行 shell 指令。

本頁說明檔案式慣例。如需了解 Workspace Provider、Tools、搜尋、生命週期及 Sandbox 詳情，請參閱 Workspaces。

預設 Workspace

如果沒有 workspace.ts，當建置提供各 Agent 專用的 Workspace 路徑時，檔案式 Agent 會取得預設 Workspace。預設 Workspace 使用：

• LocalFilesystem，根目錄設於 Agent 的已封裝 Workspace 目錄。
• LocalSandbox，使用相同的工作目錄。

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

快速開始

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

Default workspace

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

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

src/mastra/agents/weather/workspace.ts

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 參考資料了解完整 config。

何時自訂 Workspace

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

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

如需了解 Provider 模式及執行階段行為，請參閱 Workspace 概覽、Sandbox 指南及 Workspace 搜尋。

執行階段邊界

Workspace 檔案系統控制檔案 Tools 可讀寫的內容。Sandbox 控制 shell 指令的執行位置。應用程式執行階段程式碼（包括 tools/ 中的程式碼）仍會在你的應用程式／伺服器處理程序中執行，除非它明確呼叫 Workspace 或 Sandbox API。

初始檔案

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

Seed files

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

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

與 config 的優先次序

config.workspace 的優先次序高於 workspace.ts；否則會使用預設檔案式 Workspace。完整合併表請參閱 config.ts 優先次序。