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

# MastraEditor 類別

`MastraEditor` 類別用於設定 Editor 系統。將它傳給 `Mastra` constructor，即可啟用 prompt block、Agent 代碼覆寫、版本控制及 Tool Provider 等 Editor 功能。

Editor 功能簡介請參閱 [Editor](https://mastra.zisheng.pro/zh-HK/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(),
})
```

## Constructor 參數

**logger** (`Logger`): Logger 實例。如未設定，則改用 Mastra 實例的 logger。

**toolProviders** (`Record<string, ToolProvider>`): 以 ID 為鍵的整合 Tool Provider（例如 Composio 或 Arcade），讓 Agent 使用透過 Editor 加入的第三方 Tool。 (Default: `{}`)

**processorProviders** (`Record<string, ProcessorProvider>`): 用於可配置 input/output 處理的 processor Provider（例如內容審核或 token 限制）。內置 Provider 一律包括在內。 (Default: `{}`)

**filesystems** (`Record<string, FilesystemProvider>`): 用於檔案存取的檔案系統 Provider（例如 S3 或 GCS）。一律包括本機檔案系統 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 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 route），而 Studio 會顯示檔案系統操作。兩者差異請參閱 Editor 儲存選項。 (Default: `'db'`)

**codePath** (`string`): 'code' 來源用來儲存每個 Agent JSON 檔案的目錄。來源不是 'code' 時會忽略。 (Default: `'./mastra/editor/'`)

### Provider 介面

以上每個 Provider 欄位都接受以 Provider id 為鍵的記錄。實作結構請參閱各 Provider 的參考頁面：

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

## Agent Builder

`builder` 欄位會啟用 [Agent Builder](https://agent-builder.mastra.ai/)，這是用來建立及編輯已儲存 Agent 的瀏覽器 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)：模型允許清單及預設模型。

### 註冊 Builder Agent

Builder UI 會使用由 `@mastra/editor/ee` 的 `createBuilderAgent()` factory 建立的 Agent。匯入並呼叫 factory，然後在 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` subpath 在執行階段受 Mastra Enterprise Edition 授權限制。

完整設定清單請參閱 [Agent Builder 概覽](https://agent-builder.mastra.ai/#prerequisites)。

## Namespace

Editor 提供 namespace 來管理不同 entity 類型。你可在任何 Mastra 實例透過 `mastra.getEditor()` 存取它們，並在應用程式代碼中直接呼叫 CRUD 方法；亦可使用在內部呼叫這些方法的 Mastra 伺服器 route。

所有 namespace 都擴充共用的 CRUD 基礎類別，因此會提供相同的 `create`、`getById`、`update`、`delete`、`list`、`listResolved` 及 `clearCache` 方法。以下各 namespace 的屬性表亦會記錄任何額外方法。

**agent** (`EditorAgentNamespace`): 已儲存 Agent 的 CRUD 操作及版本管理，負責將已儲存覆寫套用至以代碼定義的 Agent。

**agent.create** (`(input: StorageCreateAgentInput) => Promise<Agent>`): 建立新的已儲存 Agent，並傳回已 hydrate 的 Agent 實例。接受 id、authorId、metadata 及初始 snapshot（name、description、instructions、model、tools、memory 等）。

**agent.getById** (`(id: string, options?: GetByIdOptions) => Promise<Agent | null>`): 為已儲存 Agent 傳回已 hydrate 的 Agent 實例。傳入包含 versionId、versionNumber 或 status（"draft" | "published" | "archived"）的選項以指定版本。預設版本請求會被快取。

**agent.update** (`(input: StorageUpdateAgentInput) => Promise<Agent>`): 局部更新已儲存 Agent。從提供的 snapshot 欄位建立版本、指派給 activeVersionId，並令快取失效。將 memory 設為 null 可停用 memory。

**agent.delete** (`(id: string) => Promise<void>`): 刪除已儲存 Agent，並將它從 Mastra 執行階段 registry 移除。

**agent.list** (`(args?: StorageListAgentsInput) => Promise<StorageListAgentsOutput>`): 列出已儲存 Agent，並可選擇使用分頁、orderBy、authorId 及 metadata 篩選。傳回原始已儲存 snapshot。

**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 操作，包括以 draft 內容解析 instruction block 的 preview 方法。

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

**prompt.getById** (`(id: string, options?: GetByIdOptions) => Promise<StorageResolvedPromptBlockType | null>`): 傳回已解析的 prompt block。傳入選項以指定版本或狀態。

**prompt.update** (`(input: StorageUpdatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>`): 局部更新已儲存 prompt block。使用提供的 snapshot 欄位建立新 draft 版本。

**prompt.delete** (`(id: string) => Promise<void>`): 刪除已儲存 prompt block，並將它從 Mastra 執行階段 registry 移除。

**prompt.list** (`(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksOutput>`): 列出已儲存 prompt block，並可選擇使用分頁、orderBy、authorId、metadata 及 status 篩選。

**prompt.listResolved** (`(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksResolvedOutput>`): 與 list 相同，但會傳回完整解析的 prompt block 內容。

**prompt.preview** (`(blocks: AgentInstructionBlock[], context: Record<string, unknown>) => Promise<string>`): 根據 context 解析 instruction block 陣列、呈現 template 變數及評估顯示條件。包括所引用 prompt block 的 draft 內容。

**prompt.clearCache** (`(id?: string) => void`): 清除一個或所有 prompt block 的記憶體內快取。

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

**mcp.create** (`(input: StorageCreateMCPClientInput) => Promise<MCPClient>`): 建立新的已儲存 MCP client。接受 id、authorId、metadata 及初始 snapshot（servers、Tool 篩選）。

**mcp.getById** (`(id: string, options?: GetByIdOptions) => Promise<MCPClient | null>`): 為已儲存 MCP client 傳回已 hydrate 的 MCPClient 實例。

**mcp.update** (`(input: StorageUpdateMCPClientInput) => Promise<MCPClient>`): 局部更新已儲存 MCP client，並令快取失效。

**mcp.delete** (`(id: string) => Promise<void>`): 刪除已儲存 MCP client，並將它從 Mastra 執行階段 registry 移除。

**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 伺服器配置的 CRUD 操作。

**mcpServer.create** (`(input: StorageCreateMCPServerInput) => Promise<MCPServerBase>`): 建立新的已儲存 MCP 伺服器配置，並傳回已 hydrate 的伺服器實例。

**mcpServer.getById** (`(id: string, options?: GetByIdOptions) => Promise<MCPServerBase | null>`): 傳回指定 id 的已 hydrate MCP 伺服器。

**mcpServer.update** (`(input: StorageUpdateMCPServerInput) => Promise<MCPServerBase>`): 局部更新已儲存 MCP 伺服器配置。

**mcpServer.delete** (`(id: string) => Promise<void>`): 刪除已儲存 MCP 伺服器配置。

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

**mcpServer.listResolved** (`(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersResolvedOutput>`): 與 list 相同，但會傳回完整解析的伺服器配置。

**mcpServer.clearCache** (`(id?: string) => void`): 清除一個或所有 MCP 伺服器的記憶體內快取。

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

**scorer.create** (`(input: StorageCreateScorerInput) => Promise<MastraScorer>`): 建立新的已儲存 scorer，並傳回已 hydrate 的 MastraScorer 實例。

**scorer.getById** (`(id: string, options?: GetByIdOptions) => Promise<MastraScorer | null>`): 傳回指定 id 的已 hydrate scorer。

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

**scorer.delete** (`(id: string) => Promise<void>`): 刪除已儲存 scorer，並將它從 Mastra 執行階段 registry 移除。

**scorer.list** (`(args?: StorageListScorersInput) => Promise<StorageListScorersOutput>`): 列出已儲存 scorer，並可選擇使用分頁及篩選。

**scorer.listResolved** (`(args?: StorageListScorersInput) => Promise<StorageListScorersResolvedOutput>`): 與 list 相同，但會傳回完整解析的 scorer 配置。

**scorer.clearCache** (`(id?: string) => void`): 清除一個或所有 scorer 的記憶體內快取。

### Agent namespace 範例

為現有以代碼定義的 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()`

傳回所有已註冊的檔案系統 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/zh-HK/docs/editor/overview)，啟用及 Git 歷史行為則請參閱[代碼來源版本控制](https://mastra.zisheng.pro/zh-HK/reference/editor/versioning)。