StorageWorkspaceRef

StorageWorkspaceRef 是用於將 Workspace 附加至已儲存 Agent 的判別聯集。它可以依 ID 指向在 Mastra 執行階段註冊的 Workspace，也可以直接內嵌 Workspace 快照。

這是 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 記錄與具現化之間的連接鍵。

{ type: 'id'; workspaceId: string }

type:

'id'

判別欄位。必須是常值 "id"。

workspaceId:

string

在 Mastra 執行階段註冊的 Workspace ID。Builder 會使用此值擷取快照、保存 Workspace，並於稍後進行具現化。

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

InlineRef

直接內嵌 Workspace 快照。Builder 會衍生格式為 inline-<sha256(config)[:12]> 的確定性 ID 並保存快照，因此 Agent 之間相同的內嵌設定會去除重複。

{ type: 'inline'; config: StorageWorkspaceSnapshotType }

type:

'inline'

判別欄位。必須是常值 "inline"。

config:

StorageWorkspaceSnapshotType

序列化的 Workspace 設定（檔案系統、Sandbox、掛載、搜尋、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

搜尋設定（向量 Provider、embedder、BM25 設定）。

skills?:

string[]

指派給此 Workspace 的 Skill 實體 ID。

tools?:

StorageWorkspaceToolsConfig

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

autoSync?:

boolean

= false

自動同步檔案系統與 Sandbox。

operationTimeout?:

number

個別操作的逾時時間，以毫秒為單位。

具現化

StorageWorkspaceRef 會在 mastra.editor.agent.getById() 中延遲解析，而不是在 list() 中解析。Editor 會在 MastraEditor.filesystems / MastraEditor.sandboxes 上查詢檔案系統與 Sandbox Provider，並具現化執行階段 Workspace。缺少 Provider 時會顯示警告，並省略 Workspace。

相關內容

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