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

# MastraEditor 类

`MastraEditor` 类用于设置 Editor 系统。将其传递给 `Mastra` 构造函数，即可启用 prompt block、Agent 代码覆盖、版本控制和 Tool Provider 等 Editor 功能。

有关 Editor 功能的简介，请参阅 [Editor](https://mastra.zisheng.pro/docs/editor/overview)。

## 使用示例

```typescript
import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'

export const mastra = new Mastra({
  agents: {/* your agents */},
  editor: new MastraEditor(),
})
```

## 构造函数参数

**logger** (`Logger`): Logger 实例。未设置时回退到 Mastra 实例的 logger。

**toolProviders** (`Record<string, ToolProvider>`): 以 ID 为键的集成 Tool Provider（例如 Composio 或 Arcade）。让 Agent 可以使用通过 Editor 添加的第三方 Tool。 (Default: `{}`)

**processorProviders** (`Record<string, ProcessorProvider>`): 用于可配置输入/输出处理的 Processor Provider（例如审核或 token 限制）。始终包含内置 Provider。 (Default: `{}`)

**filesystems** (`Record<string, FilesystemProvider>`): 用于文件访问的 Filesystem Provider（例如 S3 或 GCS）。始终包含本地 filesystem Provider。 (Default: `{}`)

**sandboxes** (`Record<string, SandboxProvider>`): 用于执行代码的 Sandbox Provider（例如 E2B）。始终包含本地 Sandbox Provider。 (Default: `{}`)

**blobStores** (`Record<string, BlobStoreProvider>`): 用于二进制数据的 blob storage Provider（例如 S3）。如果未指定 Provider，则回退到 Mastra storage blob store。 (Default: `{}`)

**browsers** (`Record<string, BrowserProvider>`): 用于 Agent browser 访问的 Browser Provider（例如 Stagehand）。没有内置 Provider；启用 builder.features.agent.browser 时必须提供。有关 Provider 接口，请参阅 BrowserProvider 参考。 (Default: `{}`)

**builder** (`AgentBuilderOptions`): Agent Builder 配置。请参阅 AgentBuilderOptions 参考。省略此配置或设置 enabled: false 可禁用 Builder。

**source** (`'code' | 'db'`): Agent 覆盖的存储位置。使用 'db' 时，覆盖存储在已配置的存储后端中，Studio 会显示保存和发布流程。使用 'code' 时，覆盖以每个 Agent 一个 JSON 文件的形式存储在磁盘上（通过本地 FilesystemStore 路由），Studio 会显示 filesystem 操作。有关区别，请参阅 Editor 存储选项。 (Default: `'db'`)

**codePath** (`string`): 'code' 来源用于存放每个 Agent JSON 文件的目录。当来源不是 'code' 时忽略。 (Default: `'./mastra/editor/'`)

### Provider 接口

上述每个 Provider 字段都接受以 Provider id 为键的记录。有关实现结构，请参阅各 Provider 的参考页面：

- [ProcessorProvider](https://mastra.zisheng.pro/reference/editor/processor-provider)
- [FilesystemProvider](https://mastra.zisheng.pro/reference/editor/filesystem-provider)
- [SandboxProvider](https://mastra.zisheng.pro/reference/editor/sandbox-provider)
- [BlobStoreProvider](https://mastra.zisheng.pro/reference/editor/blob-store-provider)
- [BrowserProvider](https://mastra.zisheng.pro/reference/editor/browser-provider)

## Agent Builder

`builder` 字段用于启用 [Agent Builder](https://agent-builder.mastra.ai/)，这是一个用于创建和编辑已存储 Agent 的 browser UI。请参阅：

- [Agent Builder 概览](https://agent-builder.mastra.ai/)：概念和入门。
- [AgentBuilderOptions](https://agent-builder.mastra.ai/reference/agent-builder-options)：完整的选项 schema。
- [BuilderAgentDefaults](https://agent-builder.mastra.ai/reference/builder-agent-defaults)：管理员为新 Agent 固定的默认值。
- [builder.configuration.agent.models](https://agent-builder.mastra.ai/reference/builder-models)：模型 allowlist 和默认模型。

### 注册 Builder Agent

Builder UI 使用由 `@mastra/editor/ee` 中的 `createBuilderAgent()` 工厂创建的 Agent。导入并调用该工厂，然后在 Mastra 实例的 `agents` 下注册返回的 Agent：

```typescript
import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'
import { createBuilderAgent } from '@mastra/editor/ee'

export const mastra = new Mastra({
  agents: { builderAgent: createBuilderAgent() },
  editor: new MastraEditor({
    builder: { enabled: true },
  }),
})
```

键名（`builderAgent`）只是一种惯例，任何键均可使用。`@mastra/editor/ee` 子路径在运行时受 Mastra Enterprise Edition 许可证限制。

完整设置检查清单请参阅 [Agent Builder 概览](https://agent-builder.mastra.ai/#prerequisites)。

## 命名空间

Editor 公开用于管理不同实体类型的命名空间。可以在任意 Mastra 实例中通过 `mastra.getEditor()` 访问它们，并在应用代码中直接调用 CRUD 方法；也可以使用底层调用这些方法的 Mastra 服务器路由。

所有命名空间都扩展同一个共享 CRUD 基类，因此会公开相同的 `create`、`getById`、`update`、`delete`、`list`、`listResolved` 和 `clearCache` 方法。下方各命名空间的属性表还记录了其他方法。

**agent** (`EditorAgentNamespace`): 已存储 Agent 的 CRUD 操作和版本管理。负责将已存储覆盖应用到代码定义的 Agent。

**agent.create** (`(input: StorageCreateAgentInput) => Promise<Agent>`): 创建新的已存储 Agent 并返回实例化后的 Agent 实例。接受 id、authorId、metadata 和初始快照（name、description、instructions、model、tools、memory 等）。

**agent.getById** (`(id: string, options?: GetByIdOptions) => Promise<Agent | null>`): 返回已存储 Agent 的实例化 Agent 实例。传递包含 versionId、versionNumber 或 status（"draft" | "published" | "archived"）的选项，以指定特定版本。默认版本请求会被缓存。

**agent.update** (`(input: StorageUpdateAgentInput) => Promise<Agent>`): 部分更新已存储 Agent。根据提供的快照字段创建版本，将其赋给 activeVersionId，并使缓存失效。将 memory 设为 null 可禁用 memory。

**agent.delete** (`(id: string) => Promise<void>`): 删除已存储 Agent，并将其从 Mastra 运行时注册表中移除。

**agent.list** (`(args?: StorageListAgentsInput) => Promise<StorageListAgentsOutput>`): 列出已存储 Agent，支持可选的 pagination、orderBy、authorId 和 metadata 筛选条件。返回原始已存储快照。

**agent.listResolved** (`(args?: StorageListAgentsInput) => Promise<StorageListAgentsResolvedOutput>`): 与 list 相同，但返回已解引用的完全解析配置。

**agent.applyStoredOverrides** (`(agent: Agent, options?: { versionId?: string; status?: "draft" | "published" }) => Promise<Agent>`): 原地修改代码定义的 Agent，以应用所有已存储覆盖（instructions、tools、variables）。由 mastra.getAgent() 在内部调用，通常无需直接调用。

**agent.clone** (`(agent: Agent, options: { newId: string; newName?: string; metadata?: Record<string, unknown>; authorId?: string; requestContext?: RequestContext; }) => Promise<Agent>`): 通过克隆现有 Agent 创建新的已存储 Agent。

**agent.clearCache** (`(agentId?: string) => void`): 清除一个或所有 Agent 的内存缓存。发生变更后会自动调用。

**prompt** (`EditorPromptNamespace`): Prompt block 的 CRUD 操作。包含使用草稿内容解析指令 block 的 preview 方法。

**prompt.create** (`(input: StorageCreatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>`): 创建新的已存储 prompt block。接受 id、authorId、metadata 和初始快照（name、description、content、rules、requestContextSchema）。

**prompt.getById** (`(id: string, options?: GetByIdOptions) => Promise<StorageResolvedPromptBlockType | null>`): 返回解析后的 prompt block。传递选项以指定特定版本或状态。

**prompt.update** (`(input: StorageUpdatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>`): 部分更新已存储 prompt block。使用提供的快照字段创建新的草稿版本。

**prompt.delete** (`(id: string) => Promise<void>`): 删除已存储 prompt block，并将其从 Mastra 运行时注册表中移除。

**prompt.list** (`(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksOutput>`): 列出已存储 prompt block，支持可选的 pagination、orderBy、authorId、metadata 和 status 筛选条件。

**prompt.listResolved** (`(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksResolvedOutput>`): 与 list 相同，但返回完全解析的 prompt block 内容。

**prompt.preview** (`(blocks: AgentInstructionBlock[], context: Record<string, unknown>) => Promise<string>`): 根据 context 解析指令 block 数组，渲染模板变量并对显示条件求值。包含所引用 prompt block 的草稿内容。

**prompt.clearCache** (`(id?: string) => void`): 清除一个或所有 prompt block 的内存缓存。

**mcp** (`EditorMCPNamespace`): 已存储 MCP client 配置的 CRUD 操作。

**mcp.create** (`(input: StorageCreateMCPClientInput) => Promise<MCPClient>`): 创建新的已存储 MCP client。接受 id、authorId、metadata 和初始快照（server、Tool 筛选）。

**mcp.getById** (`(id: string, options?: GetByIdOptions) => Promise<MCPClient | null>`): 返回已存储 MCP client 的实例化 MCPClient 实例。

**mcp.update** (`(input: StorageUpdateMCPClientInput) => Promise<MCPClient>`): 部分更新已存储 MCP client，并使缓存失效。

**mcp.delete** (`(id: string) => Promise<void>`): 删除已存储 MCP client，并将其从 Mastra 运行时注册表中移除。

**mcp.list** (`(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsOutput>`): 列出已存储 MCP client，支持可选的分页和筛选条件。

**mcp.listResolved** (`(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsResolvedOutput>`): 与 list 相同，但返回完全解析的 MCP client 配置。

**mcp.clearCache** (`(id?: string) => void`): 清除一个或所有 MCP client 的内存缓存。

**mcpServer** (`EditorMCPServerNamespace`): MCP server 配置的 CRUD 操作。

**mcpServer.create** (`(input: StorageCreateMCPServerInput) => Promise<MCPServerBase>`): 创建新的已存储 MCP server 配置，并返回实例化后的 server 实例。

**mcpServer.getById** (`(id: string, options?: GetByIdOptions) => Promise<MCPServerBase | null>`): 返回指定 id 对应的实例化 MCP server。

**mcpServer.update** (`(input: StorageUpdateMCPServerInput) => Promise<MCPServerBase>`): 部分更新已存储 MCP server 配置。

**mcpServer.delete** (`(id: string) => Promise<void>`): 删除已存储 MCP server 配置。

**mcpServer.list** (`(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersOutput>`): 列出已存储 MCP server 配置。

**mcpServer.listResolved** (`(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersResolvedOutput>`): 与 list 相同，但返回完全解析的 server 配置。

**mcpServer.clearCache** (`(id?: string) => void`): 清除一个或所有 MCP server 的内存缓存。

**scorer** (`EditorScorerNamespace`): Scorer 配置的 CRUD 操作。

**scorer.create** (`(input: StorageCreateScorerInput) => Promise<MastraScorer>`): 创建新的已存储 Scorer，并返回实例化后的 MastraScorer 实例。

**scorer.getById** (`(id: string, options?: GetByIdOptions) => Promise<MastraScorer | null>`): 返回指定 id 对应的实例化 Scorer。

**scorer.update** (`(input: StorageUpdateScorerInput) => Promise<MastraScorer>`): 部分更新已存储 Scorer。

**scorer.delete** (`(id: string) => Promise<void>`): 删除已存储 Scorer，并将其从 Mastra 运行时注册表中移除。

**scorer.list** (`(args?: StorageListScorersInput) => Promise<StorageListScorersOutput>`): 列出已存储 Scorer，支持可选的分页和筛选条件。

**scorer.listResolved** (`(args?: StorageListScorersInput) => Promise<StorageListScorersResolvedOutput>`): 与 list 相同，但返回完全解析的 Scorer 配置。

**scorer.clearCache** (`(id?: string) => void`): 清除一个或所有 Scorer 的内存缓存。

### Agent 命名空间示例

为现有代码定义的 Agent 创建已存储覆盖：

```typescript
import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.create({
  id: 'support-agent',
  instructions: 'You are a friendly support agent for Acme.',
  tools: {
    search_kb: { description: 'Search the Acme knowledge base' },
  },
})
```

## 方法

### 访问 Provider

#### `getToolProvider(id)`

返回指定 ID 对应的已注册 Tool Provider。

```typescript
const composio = mastra.getEditor()?.getToolProvider('composio')
```

#### `getToolProviders()`

以 `Record<string, ToolProvider>` 形式返回所有已注册 Tool Provider。

#### `getProcessorProvider(id)`

返回指定 ID 对应的已注册 Processor Provider。

#### `getProcessorProviders()`

返回所有已注册 Processor Provider。

#### `getFilesystemProviders()`

返回所有已注册 filesystem Provider。

#### `getSandboxProviders()`

返回所有已注册 Sandbox Provider。

#### `getBlobStoreProviders()`

返回所有已注册 blob store Provider。

### 来源

#### `getSource()`

返回已配置的来源（`'code'` 或 `'db'`）；如果构造 Editor 时未显式指定 `source`，则返回 `undefined`。

```typescript
const source = mastra.getEditor()?.getSource()
```

返回：`'code' | 'db' | undefined`

省略 `source` 时，即使 `getSource()` 返回 `undefined`，Editor 仍会使用已配置的数据库存储。有关存储工作流，请参阅 [Editor 存储选项](https://mastra.zisheng.pro/docs/editor/overview)；有关激活和 Git 历史记录行为，请参阅[代码来源版本控制](https://mastra.zisheng.pro/reference/editor/versioning)。