跳到主要内容

MastraEditor 类

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

有关 Editor 功能的简介，请参阅 Editor。

使用示例
使用示例的直接链接

src/mastra/index.ts
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。

processorProviders?:

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

filesystems?:

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

sandboxes?:

Record<string, SandboxProvider>
= {}
用于执行代码的 Sandbox Provider（例如 E2B）。始终包含本地 Sandbox Provider。

blobStores?:

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

browsers?:

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

builder?:

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

source?:

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

codePath?:

string
= './mastra/editor/'
'code' 来源用于存放每个 Agent JSON 文件的目录。当来源不是 'code' 时忽略。

Provider 接口
Provider 接口的直接链接

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

Agent Builder
Agent Builder的直接链接

builder 字段用于启用 Agent Builder，这是一个用于创建和编辑已存储 Agent 的 browser UI。请参阅：

注册 Builder Agent
注册 Builder Agent的直接链接

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

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 概览。

命名空间
命名空间的直接链接

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

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

agent:

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

create:

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

getById:

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

update:

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

delete:

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

list:

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

listResolved:

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

applyStoredOverrides:

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

clone:

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

clearCache:

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

prompt:

EditorPromptNamespace
Prompt block 的 CRUD 操作。包含使用草稿内容解析指令 block 的 preview 方法。
EditorPromptNamespace

create:

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

getById:

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

update:

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

delete:

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

list:

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

listResolved:

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

preview:

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

clearCache:

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

mcp:

EditorMCPNamespace
已存储 MCP client 配置的 CRUD 操作。
EditorMCPNamespace

create:

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

getById:

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

update:

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

delete:

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

list:

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

listResolved:

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

clearCache:

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

mcpServer:

EditorMCPServerNamespace
MCP server 配置的 CRUD 操作。
EditorMCPServerNamespace

create:

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

getById:

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

update:

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

delete:

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

list:

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

listResolved:

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

clearCache:

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

scorer:

EditorScorerNamespace
Scorer 配置的 CRUD 操作。
EditorScorerNamespace

create:

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

getById:

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

update:

(input: StorageUpdateScorerInput) => Promise<MastraScorer>
部分更新已存储 Scorer。

delete:

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

list:

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

listResolved:

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

clearCache:

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

Agent 命名空间示例
Agent 命名空间示例的直接链接

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

src/scripts/seed-agent.ts
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
访问 Provider的直接链接

getToolProvider(id)
gettoolproviderid的直接链接

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

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

getToolProviders()
gettoolproviders的直接链接

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

getProcessorProvider(id)
getprocessorproviderid的直接链接

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

getProcessorProviders()
getprocessorproviders的直接链接

返回所有已注册 Processor Provider。

getFilesystemProviders()
getfilesystemproviders的直接链接

返回所有已注册 filesystem Provider。

getSandboxProviders()
getsandboxproviders的直接链接

返回所有已注册 Sandbox Provider。

getBlobStoreProviders()
getblobstoreproviders的直接链接

返回所有已注册 blob store Provider。

来源
来源的直接链接

getSource()
getsource的直接链接

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

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

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

省略 source 时，即使 getSource() 返回 undefined，Editor 仍会使用已配置的数据库存储。有关存储工作流，请参阅 Editor 存储选项；有关激活和 Git 历史记录行为，请参阅代码来源版本控制。

On this page