跳至主要內容

MastraEditor 類別

MastraEditor 類別會設定 Editor 系統。將它傳給 Mastra 建構函式，即可啟用提示詞區塊、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>
= {}
用於可設定輸入／輸出處理的處理器 Provider（例如內容審核或 token 限制）。一律包含內建 Provider。

filesystems?:

Record<string, FilesystemProvider>
= {}
用於檔案存取的檔案系統 Provider（例如 S3 或 GCS）。一律包含本機檔案系統 Provider。

sandboxes?:

Record<string, SandboxProvider>
= {}
用於執行程式碼的 Sandbox Provider（例如 E2B）。一律包含本機 Sandbox Provider。

blobStores?:

Record<string, BlobStoreProvider>
= {}
用於二進位資料的 blob 儲存 Provider（例如 S3）。若未指定 Provider，則改用 Mastra 儲存空間的 blob 儲存空間。

browsers?:

Record<string, BrowserProvider>
= {}
讓 Agent 存取瀏覽器的 Browser Provider（例如 Stagehand）。沒有內建項目，因此啟用 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 會顯示檔案系統操作。差異請參閱 Editor 儲存選項。

codePath?:

string
= './mastra/editor/'
'code' 來源用來存放各 Agent JSON 檔案的目錄。source 不是 'code' 時會忽略。

Provider 介面
「Provider 介面」的直接連結

上述各 Provider 欄位都接受以 Provider ID 為鍵的記錄。實作的資料結構請參閱各 Provider 的參考頁面：

Agent Builder
「Agent Builder」的直接連結

builder 欄位會啟用 Agent Builder，這是用於建立及編輯已儲存 Agent 的瀏覽器 UI。請參閱：

註冊 Builder Agent
「註冊 Builder Agent」的直接連結

Builder UI 會使用由 @mastra/editor/ee 的 createBuilderAgent() 工廠函式建立的 Agent。匯入並呼叫該工廠函式，再將傳回的 Agent 註冊於 Mastra 執行個體的 agents 下：

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、中繼資料及初始快照（名稱、說明、指示、模型、Tool、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，可選擇使用分頁、orderBy、authorId 與中繼資料篩選條件。傳回原始的已儲存快照。

listResolved:

(args?: StorageListAgentsInput) => Promise<StorageListAgentsResolvedOutput>
與 list 相同，但會傳回已解除參照的完整解析設定。

applyStoredOverrides:

(agent: Agent, options?: { versionId?: string; status?: "draft" | "published" }) => Promise<Agent>
就地修改程式碼定義的 Agent，以套用所有已儲存的覆寫（指示、Tool、變數）。由 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 的記憶體內快取。Mutation 後會自動呼叫。

prompt:

EditorPromptNamespace
提示詞區塊的 CRUD 操作。包含使用草稿內容解析指示區塊的預覽方法。
EditorPromptNamespace

create:

(input: StorageCreatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>
建立新的已儲存提示詞區塊。接受 ID、authorId、中繼資料及初始快照（名稱、說明、內容、規則、requestContextSchema）。

getById:

(id: string, options?: GetByIdOptions) => Promise<StorageResolvedPromptBlockType | null>
傳回解析後的提示詞區塊。傳入選項可指定特定版本或狀態。

update:

(input: StorageUpdatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>
部分更新已儲存的提示詞區塊。使用提供的快照欄位建立新的草稿版本。

delete:

(id: string) => Promise<void>
刪除已儲存的提示詞區塊，並將其從 Mastra 執行階段登錄表移除。

list:

(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksOutput>
列出已儲存的提示詞區塊，可選擇使用分頁、orderBy、authorId、中繼資料與狀態篩選條件。

listResolved:

(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksResolvedOutput>
與 list 相同，但會傳回完整解析的提示詞區塊內容。

preview:

(blocks: AgentInstructionBlock[], context: Record<string, unknown>) => Promise<string>
依照 context 解析指示區塊陣列、呈現範本變數，並評估顯示條件。被參照的提示詞區塊會包含草稿內容。

clearCache:

(id?: string) => void
清除單一或所有提示詞區塊的記憶體內快取。

mcp:

EditorMCPNamespace
已儲存 MCP 使用者端設定的 CRUD 操作。
EditorMCPNamespace

create:

(input: StorageCreateMCPClientInput) => Promise<MCPClient>
建立新的已儲存 MCP 使用者端。接受 ID、authorId、中繼資料及初始快照（伺服器、Tool 篩選設定）。

getById:

(id: string, options?: GetByIdOptions) => Promise<MCPClient | null>
傳回已儲存 MCP 使用者端具現化後的 MCPClient 執行個體。

update:

(input: StorageUpdateMCPClientInput) => Promise<MCPClient>
部分更新已儲存的 MCP 使用者端，並使快取失效。

delete:

(id: string) => Promise<void>
刪除已儲存的 MCP 使用者端，並將其從 Mastra 執行階段登錄表移除。

list:

(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsOutput>
列出已儲存的 MCP 使用者端，可選擇使用分頁與篩選條件。

listResolved:

(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsResolvedOutput>
與 list 相同，但會傳回完整解析的 MCP 使用者端設定。

clearCache:

(id?: string) => void
清除單一或所有 MCP 使用者端的記憶體內快取。

mcpServer:

EditorMCPServerNamespace
MCP 伺服器設定的 CRUD 操作。
EditorMCPServerNamespace

create:

(input: StorageCreateMCPServerInput) => Promise<MCPServerBase>
建立新的已儲存 MCP 伺服器設定，並傳回具現化後的伺服器執行個體。

getById:

(id: string, options?: GetByIdOptions) => Promise<MCPServerBase | null>
傳回指定 ID 具現化後的 MCP 伺服器。

update:

(input: StorageUpdateMCPServerInput) => Promise<MCPServerBase>
部分更新已儲存的 MCP 伺服器設定。

delete:

(id: string) => Promise<void>
刪除已儲存的 MCP 伺服器設定。

list:

(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersOutput>
列出已儲存的 MCP 伺服器設定。

listResolved:

(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersResolvedOutput>
與 list 相同，但會傳回完整解析的伺服器設定。

clearCache:

(id?: string) => void
清除單一或所有 MCP 伺服器的記憶體內快取。

scorer:

EditorScorerNamespace
評分器設定的 CRUD 操作。
EditorScorerNamespace

create:

(input: StorageCreateScorerInput) => Promise<MastraScorer>
建立新的已儲存評分器，並傳回具現化後的 MastraScorer 執行個體。

getById:

(id: string, options?: GetByIdOptions) => Promise<MastraScorer | null>
傳回指定 ID 具現化後的評分器。

update:

(input: StorageUpdateScorerInput) => Promise<MastraScorer>
部分更新已儲存的評分器。

delete:

(id: string) => Promise<void>
刪除已儲存的評分器，並將其從 Mastra 執行階段登錄表移除。

list:

(args?: StorageListScorersInput) => Promise<StorageListScorersOutput>
列出已儲存的評分器，可選擇使用分頁與篩選條件。

listResolved:

(args?: StorageListScorersInput) => Promise<StorageListScorersResolvedOutput>
與 list 相同，但會傳回完整解析的評分器設定。

clearCache:

(id?: string) => void
清除單一或所有評分器的記憶體內快取。

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 傳回已註冊的處理器 Provider。

getProcessorProviders()
「getprocessorproviders」的直接連結

傳回所有已註冊的處理器 Provider。

getFilesystemProviders()
「getfilesystemproviders」的直接連結

傳回所有已註冊的檔案系統 Provider。

getSandboxProviders()
「getsandboxproviders」的直接連結

傳回所有已註冊的 Sandbox Provider。

getBlobStoreProviders()
「getblobstoreproviders」的直接連結

傳回所有已註冊的 blob 儲存空間 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