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

# MastraEditor 類別

`MastraEditor` 類別會設定 Editor 系統。將它傳給 `Mastra` 建構函式，即可啟用提示詞區塊、Agent 程式碼覆寫、版本管理與 Tool Provider 等 Editor 功能。

Editor 功能簡介請參閱 [Editor](https://mastra.zisheng.pro/zh-TW/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>`): 用於可設定輸入／輸出處理的處理器 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 儲存 Provider（例如 S3）。若未指定 Provider，則改用 Mastra 儲存空間的 blob 儲存空間。 (Default: `{}`)

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

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

### Provider 介面

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

- [ProcessorProvider](https://mastra.zisheng.pro/zh-TW/reference/editor/processor-provider)
- [FilesystemProvider](https://mastra.zisheng.pro/zh-TW/reference/editor/filesystem-provider)
- [SandboxProvider](https://mastra.zisheng.pro/zh-TW/reference/editor/sandbox-provider)
- [BlobStoreProvider](https://mastra.zisheng.pro/zh-TW/reference/editor/blob-store-provider)
- [BrowserProvider](https://mastra.zisheng.pro/zh-TW/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()` 工廠函式建立的 Agent。匯入並呼叫該工廠函式，再將傳回的 Agent 註冊於 Mastra 執行個體的 `agents` 下：

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

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

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

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

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

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

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

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

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

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

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

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

**mcp** (`EditorMCPNamespace`): 已儲存 MCP 使用者端設定的 CRUD 操作。

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

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

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

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

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

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

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

**mcpServer** (`EditorMCPServerNamespace`): MCP 伺服器設定的 CRUD 操作。

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

**mcpServer.getById** (`(id: string, options?: GetByIdOptions) => Promise<MCPServerBase | null>`): 傳回指定 ID 具現化後的 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`): 評分器設定的 CRUD 操作。

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

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

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

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

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

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

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

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

#### `getProcessorProviders()`

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

#### `getFilesystemProviders()`

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

#### `getSandboxProviders()`

傳回所有已註冊的 Sandbox Provider。

#### `getBlobStoreProviders()`

傳回所有已註冊的 blob 儲存空間 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-TW/docs/editor/overview)，啟用與 Git 歷史記錄行為請參閱[程式碼來源的版本管理](https://mastra.zisheng.pro/zh-TW/reference/editor/versioning)。