> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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 配置（filesystem、Sandbox、mount、search、Skill、Tool）。字段列表请参阅下文的 StorageWorkspaceSnapshotType 部分。

## `StorageWorkspaceSnapshotType`

嵌入在 `{ type: 'inline', config }` 下的数据结构。定义于 `@mastra/core/storage`。

**name** (`string`): Workspace 的显示名称。

**description** (`string`): Workspace 列表中显示的用途描述。

**filesystem** (`StorageFilesystemConfig`): 主要 filesystem 配置。provider 必须与在 MastraEditor.filesystems 上注册的 id 一致（内置：local）。

**sandbox** (`StorageSandboxConfig`): Sandbox 配置。provider 必须与在 MastraEditor.sandboxes 上注册的 id 一致（内置：local）。

**mounts** (`Record<string, StorageFilesystemConfig>`): 挂载到 Workspace 的其他 filesystem，以挂载路径为键。

**search** (`StorageSearchConfig`): 搜索配置（vector Provider、embedder、BM25 设置）。

**skills** (`string[]`): 分配给此 Workspace 的 Skill 实体 ID。

**tools** (`StorageWorkspaceToolsConfig`): Workspace Tool 配置（allowlist、默认值）。

**autoSync** (`boolean`): 在 filesystem 与 Sandbox 之间自动同步。 (Default: `false`)

**operationTimeout** (`number`): 单个操作的超时时间（毫秒）。

## 实例化

`StorageWorkspaceRef` 会在调用 `mastra.editor.agent.getById()` 时延迟解析，而不是在 `list()` 时解析。Editor 在 `MastraEditor.filesystems` / `MastraEditor.sandboxes` 中查找 filesystem 和 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/reference/editor/mastra-editor)：注册 filesystem 和 Sandbox Provider。
- [StorageBrowserRef](https://mastra.zisheng.pro/reference/editor/storage-browser-ref)：用于 browser 配置的同级引用类型。