StorageWorkspaceRef

StorageWorkspaceRef 是用來將 Workspace 附加至已儲存 Agent 的判別聯合類型。它可以按 ID 指向在 Mastra 執行階段註冊的 Workspace，或以 inline 方式嵌入 Workspace snapshot。

這是 BuilderAgentDefaults.workspace 及已儲存 Agent 記錄使用的類型。

使用範例

src/mastra/index.ts

import { MastraEditor } from '@mastra/editor'

// Variant 1 — reference a runtime workspace by id
new MastraEditor({
  builder: {
    enabled: true,
    configuration: {
      agent: {
        workspace: { type: 'id', workspaceId: 'builder-workspace' },
      },
    },
  },
})

// Variant 2 — inline a workspace snapshot
new MastraEditor({
  builder: {
    enabled: true,
    configuration: {
      agent: {
        workspace: {
          type: 'inline',
          config: {
            name: 'inline-builder-workspace',
            filesystem: {
              provider: 'local',
              config: { basePath: './agent-files' },
            },
          },
        },
      },
    },
  },
})

變體

{ type: 'id'; workspaceId: string }:

IdRef

引用透過 new Mastra({ workspace }) 或 mastra.addWorkspace() 在 Mastra 執行階段註冊的 Workspace。id 是管理員配置、已儲存 Agent 記錄與 hydrate 之間的 join key。

{ type: 'id'; workspaceId: string }

type:

'id'

判別欄位。必須是字面值 "id"。

workspaceId:

string

已在 Mastra 執行階段註冊的 Workspace id。Builder 會用它建立 snapshot、保存並在之後 hydrate Workspace。

{ type: 'inline'; config: StorageWorkspaceSnapshotType }:

InlineRef

直接嵌入 Workspace snapshot。Builder 會衍生格式為 inline-<sha256(config)[:12]> 的確定性 id 並保存 snapshot，因此不同 Agent 的相同 inline 配置會去除重複項目。

{ type: 'inline'; config: StorageWorkspaceSnapshotType }

type:

'inline'

判別欄位。必須是字面值 "inline"。

config:

StorageWorkspaceSnapshotType

已序列化的 Workspace 配置（檔案系統、Sandbox、mount、搜尋、Skill、Tool）。欄位清單請參閱下方 StorageWorkspaceSnapshotType 一節。

StorageWorkspaceSnapshotType

嵌入 { type: 'inline', config } 下的資料結構，定義於 @mastra/core/storage。

name:

string

Workspace 的顯示名稱。

description?:

string

在 Workspace 清單中顯示的用途描述。

filesystem?:

StorageFilesystemConfig

主要檔案系統配置。provider 必須符合已在 MastraEditor.filesystems 註冊的 id（內置：local）。

sandbox?:

StorageSandboxConfig

Sandbox 配置。provider 必須符合已在 MastraEditor.sandboxes 註冊的 id（內置：local）。

mounts?:

Record<string, StorageFilesystemConfig>

掛載至 Workspace 的其他檔案系統，以掛載路徑作為鍵。

search?:

StorageSearchConfig

搜尋配置（vector Provider、embedder、BM25 設定）。

skills?:

string[]

指派給此 Workspace 的 Skill entity ID。

tools?:

StorageWorkspaceToolsConfig

Workspace Tool 配置（允許清單、預設值）。

autoSync?:

boolean

= false

在檔案系統與 Sandbox 之間自動同步。

operationTimeout?:

number

個別操作的逾時時間（毫秒）。

Hydrate 流程

StorageWorkspaceRef 會在 mastra.editor.agent.getById() 中延遲解析，而非在 list() 中解析。Editor 會在 MastraEditor.filesystems / MastraEditor.sandboxes 查找檔案系統及 Sandbox Provider，並建立執行階段 Workspace。缺少 Provider 時會顯示警告，並略過 Workspace。

相關內容

• Workspace：概念及完整範例。
• BuilderAgentDefaults：將此類型固定為 Builder 預設值的位置。
• MastraEditor 類別：註冊檔案系統及 Sandbox Provider。
• StorageBrowserRef：瀏覽器配置的同類引用類型。