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

# StorageWorkspaceRef

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

這是 [`BuilderAgentDefaults.workspace`](https://agent-builder.mastra.ai/reference/builder-agent-defaults) 及已儲存 Agent 記錄使用的類型。

## 使用範例

```typescript
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"。

**{ type: 'id'; workspaceId: string }.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"。

**{ type: 'inline'; config: StorageWorkspaceSnapshotType }.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`): 在檔案系統與 Sandbox 之間自動同步。 (Default: `false`)

**operationTimeout** (`number`): 個別操作的逾時時間（毫秒）。

## Hydrate 流程

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

## 相關內容

- [Workspace](https://agent-builder.mastra.ai/workspace)：概念及完整範例。
- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults)：將此類型固定為 Builder 預設值的位置。
- [MastraEditor 類別](https://mastra.zisheng.pro/zh-HK/reference/editor/mastra-editor)：註冊檔案系統及 Sandbox Provider。
- [StorageBrowserRef](https://mastra.zisheng.pro/zh-HK/reference/editor/storage-browser-ref)：瀏覽器配置的同類引用類型。