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 配置（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

= false

在 filesystem 与 Sandbox 之间自动同步。

operationTimeout?:

number

单个操作的超时时间（毫秒）。

实例化

StorageWorkspaceRef 会在调用 mastra.editor.agent.getById() 时延迟解析，而不是在 list() 时解析。Editor 在 MastraEditor.filesystems / MastraEditor.sandboxes 中查找 filesystem 和 Sandbox Provider，并创建运行时 Workspace。缺少 Provider 时会显示警告，并省略该 Workspace。

相关内容

• Workspace：概念和完整示例。
• BuilderAgentDefaults：将此类型固定为 Builder 默认值的位置。
• MastraEditor 类：注册 filesystem 和 Sandbox Provider。
• StorageBrowserRef：用于 browser 配置的同级引用类型。