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

# StorageWorkspaceRef

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

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

**{ type: 'id'; workspaceId: string }.type** (`'id'`): 判別欄位。必須是常值 "id"。

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

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

**operationTimeout** (`number`): 個別操作的逾時時間，以毫秒為單位。

## 具現化

`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-TW/reference/editor/mastra-editor)：註冊檔案系統與 Sandbox Provider。
- [StorageBrowserRef](https://mastra.zisheng.pro/zh-TW/reference/editor/storage-browser-ref)：瀏覽器設定的同類參照類型。