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

# Editor

Editor 的運作方式就像 Mastra Agent 的 CMS。協作者無需存取程式碼庫或編寫程式碼，便可在 Studio 更改 Agent 的指示和 Tool。他們可以先測試變更，再正式套用。

TypeScript 定義 Agent 的預設值。Editor 會另行儲存變更，而非更新源程式碼，因此協作者可以改進 Agent，同時開發人員仍可掌控其模型、身分和執行環境。

[已部署的 Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/deployment) 讓本機開發環境以外的協作者也可使用 Editor。

> **📹 觀看:** 觀看 [Mastra Editor 工作坊](https://www.youtube.com/watch?v=XTjuRoI7t_k\&pp=ygUWbWFzdHJhIGVkaXRvciB3b3Jrc2hvcA%3D%3D)，了解完整操作流程。

## 何時使用 Editor

如果 Agent 在程式碼中定義，但負責其行為的人員不應編輯程式碼庫，便可使用 Editor。若指示或 Tool 經常變動，並需要在推出給用戶前測試，Editor 尤其合適。如果所有變更均由開發人員負責，並隨應用程式一併發佈 Agent 配置，則應繼續將 [Agent 配置保留在程式碼中](https://mastra.zisheng.pro/zh-HK/docs/agents/overview)。

## 快速開始

安裝 `@mastra/editor`。此快速開始使用 LibSQL 儲存 Editor 變更：

**npm**:

```bash
npm install @mastra/editor @mastra/libsql
```

**pnpm**:

```bash
pnpm add @mastra/editor @mastra/libsql
```

**Yarn**:

```bash
yarn add @mastra/editor @mastra/libsql
```

**Bun**:

```bash
bun add @mastra/editor @mastra/libsql
```

將 `MastraEditor` 和儲存空間加入 `Mastra` 實例。你可以重用現有儲存空間，無需加入此處所示的 LibSQL store。

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

export const mastra = new Mastra({
  agents: {/* existing agents */},
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  editor: new MastraEditor(),
})
```

## 在 Studio 使用 Editor

在 [Studio](https://mastra.zisheng.pro/zh-HK/docs/studio/overview) 開啟 **Agents**，選擇一個 Agent，然後選擇 **Editor**。協作者可以按該 Agent 的 Editor 權限更新其指示和 Tool。

使用數據庫儲存空間時，可將變更儲存為草稿以作測試，而不影響正式運行的 Agent。準備就緒後，發佈草稿即可使用。

## 指示

**Instructions** 部分會顯示在程式碼中定義的 Agent 系統提示。協作者可以覆寫它，或加入指示區塊。

指示區塊可以包含目前請求中的值。例如，`{{userName}}` 會插入透過 [請求上下文](https://mastra.zisheng.pro/zh-HK/docs/server/request-context) 提供的名稱。[顯示條件](https://mastra.zisheng.pro/zh-HK/reference/editor/prompt-blocks) 可以設定只向特定客戶、角色或功能旗標顯示區塊。

### 提示區塊

提示區塊是已儲存的指示文字，可供多個 Agent 使用。先在 **Prompts** 下建立並發佈提示區塊，然後開啟 Agent 的 **Instructions** 部分並選擇 **Add block**。

例如，支援、退貨和訂單狀態 Agent 可能全都需要相同的退款政策。將政策儲存為提示區塊，再加入每個 Agent。政策變更時，只需更新並發佈該區塊一次，無需逐一編輯三個 Agent。

提示區塊變更後，每個引用其已發佈版本的 Agent 都會收到更新。草稿變更只會在預覽時使用，因此在區塊發佈前不會影響正式運行的 Agent。

有關範本語法、條件、版本和 API，請參閱[提示區塊參考](https://mastra.zisheng.pro/zh-HK/reference/editor/prompt-blocks)。

## Tool

Tool 讓 Agent 執行操作。協作者可從 Editor 提供的 Tool 中選擇，但不能在 Studio 實作新 Tool。Tool 的提供方式取決於其來源：

- **項目 Tool** 必須由開發人員在 Mastra 項目中實作並註冊。
- **整合 Tool** 會在開發人員註冊 Composio 或 Arcade 等 Provider 後提供。協作者隨後可以瀏覽 Provider 的目錄並加入 Tool，無需先在程式碼中逐一加入每個 Tool。
- 配置 MCP client 後，便會提供 **MCP Tool**。具有存取權限的協作者可以在 Studio 建立 client，然後從其伺服器公開的 Tool 中選擇。

在 Agent 的 **Tools** 部分，協作者可以加入所需的 Tool，或專為該 Agent 改寫 Tool 的描述。更具體的描述有助 Agent 理解何時使用 Tool，且無需更改 Tool 本身。

### 項目 Tool

開發人員可在 `Mastra` 實例註冊項目 Tool，讓 Editor 可以使用：

```typescript
import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'
import { searchOrders } from './tools/search-orders'

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

Studio 的 Tool 選擇器會列出該 Tool。協作者可以在 Agent 允許編輯 Tool 時將它加入。Agent 的 Editor 檢視亦會列出透過程式碼附加的 Tool。

### Composio

[Composio](https://composio.dev) 為 GitHub、Slack 和 Gmail 等服務提供 Tool。使用 Composio API 金鑰註冊 Provider，讓 Editor 可以使用其 Tool 目錄：

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

export const mastra = new Mastra({
  agents: {/* agents */},
  editor: new MastraEditor({
    toolProviders: {
      composio: new ComposioToolProvider({
        apiKey: process.env.COMPOSIO_API_KEY!,
      }),
    },
  }),
})
```

Composio Tool ID 的格式類似 `GITHUB_CREATE_ISSUE`。預設情況下，所選 Tool 會使用與 Agent 作者關聯的連線。請參閱[連線範圍](https://agent-builder.mastra.ai/tool-providers#connection-scope)，了解如何改用每位調用者的連線。

### Arcade

[Arcade](https://arcade.dev) 提供另一個內置驗證功能的 Tool 目錄。使用 Arcade API 金鑰註冊：

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

export const mastra = new Mastra({
  agents: {/* agents */},
  editor: new MastraEditor({
    toolProviders: {
      arcade: new ArcadeToolProvider({
        apiKey: process.env.ARCADE_API_KEY!,
      }),
    },
  }),
})
```

Arcade Tool ID 使用 `Toolkit.ToolName` 格式，例如 `Github.GetRepository`。

### MCP client

協作者也可在 Studio 建立可重用的 MCP client，並將其 Tool 加入 Agent。已儲存的 client 可以啟動本機 `stdio` 伺服器，或連接至遠端 HTTP 伺服器。Tool 篩選器讓每個 Agent 只使用該伺服器中所需的 Tool。

有關 MCP 配置、條件、篩選和解析順序，請參閱 [Editor Tool 參考](https://mastra.zisheng.pro/zh-HK/reference/editor/tools)。有關 Provider 選項，請參閱 [`ToolProvider`](https://mastra.zisheng.pro/zh-HK/reference/editor/tool-provider)。

## 決定協作者可編輯的內容

協作者預設可以更改 Agent 的指示及管理其 Tool，包括 Tool 描述。Agent 的 `id`、`name` 和 `model` 一律來自程式碼。

使用 Agent 的 `editor` 欄位限制可更改的內容：

```typescript
import { Agent } from '@mastra/core/agent'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'Help customers with Acme products.',
  model: 'openai/gpt-5.6-sol',
  editor: {
    instructions: true,
    tools: {
      description: true,
    },
  },
})
```

此 Agent 允許協作者更改其指示，並改善已附加 Tool 的描述。他們不能加入或移除 Tool。

| `editor` 值                         | 協作者可以更改的內容        |
| ---------------------------------- | ----------------- |
| 省略                                 | 指示、Tool 和 Tool 描述 |
| `false`                            | 無                 |
| `{ instructions: true }`           | 指示                |
| `{ tools: true }`                  | Tool 和 Tool 描述    |
| `{ tools: { description: true } }` | 已在程式碼中加入的 Tool 描述 |

Studio 會將其他所有內容顯示為唯讀。有關完整配置，請參閱 [Editor 覆寫](https://mastra.zisheng.pro/zh-HK/reference/agents/agent)。

## 選擇變更的儲存位置

Editor 可以將變更儲存在已配置的數據庫，或儲存為程式碼庫中的檔案。

### 數據庫儲存空間

數據庫選項是預設設定。Editor 使用 `Mastra` 實例上配置的儲存空間，因此應用程式和 Editor 可以共用相同的後端。

如要為 Editor 數據使用獨立後端，請在 [`MastraCompositeStore`](https://mastra.zisheng.pro/zh-HK/reference/storage/composite) 設定 `editor` 選項。沒有明確路由的儲存空間網域會繼續使用其 `default` store。

以下範例將應用程式和 Editor 數據分別儲存在不同的 LibSQL 檔案中：

```typescript
import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { MastraEditor } from '@mastra/editor'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  agents: {/* existing agents */},
  storage: new MastraCompositeStore({
    id: 'mastra-storage',
    default: new LibSQLStore({
      id: 'app-storage',
      url: 'file:./mastra.db',
    }),
    editor: new LibSQLStore({
      id: 'editor-storage',
      url: 'file:./editor.db',
    }),
  }),
  editor: new MastraEditor(),
})
```

### 程式碼庫檔案

使用程式碼來源，將覆寫內容與應用程式碼一同保存。開發人員可以在 pull request 中審查檔案，並隨應用程式一併部署：

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

export const mastra = new Mastra({
  agents: {/* existing agents */},
  editor: new MastraEditor({
    source: 'code',
    codePath: './mastra/editor',
  }),
})
```

在此模式下，每個已編輯的 Agent 都有一個 JSON 覆寫檔案。Editor 不會產生 TypeScript，也不會更改建立 Agent 的檔案。預設情況下，ID 為 `support-agent` 的 Agent 會取得以下檔案：

```text
mastra/editor/agents/support-agent.json
```

檔案只包含由 Editor 管理的部分。例如：

```json
{
  "instructions": "Help customers with Acme products and answer in their language.",
  "tools": {
    "searchOrders": {
      "description": "Look up an order by its number"
    }
  }
}
```

Agent 的模型、名稱和其他由程式碼管理的欄位會保留在其 TypeScript 檔案中。Mastra 會讀取 JSON，並在 Agent 運行時套用這些值。

協作者在 Studio 儲存時，可以將檔案寫入本機檔案系統或下載檔案。透過源程式碼控制整合，Studio 可以改為開啟 pull request。Git 隨後會提供審查和版本記錄。

有關檔案位置和來源選項，請參閱 [`MastraEditor`](https://mastra.zisheng.pro/zh-HK/reference/editor/mastra-editor)。

## 版本控制

以數據庫為後端的 Agent 和提示區塊會使用草稿和已發佈版本。儲存會建立草稿，而正式運行的 Agent 會繼續使用已發佈版本。發佈後，草稿便會正式套用。還原舊版本會建立草稿，讓協作者在發佈前進行測試。

以程式碼為後端的 Agent 覆寫會使用 JSON 檔案和 Git 記錄。

### 選擇版本

應用程式可以傳入狀態（`published` 或 `draft`）或確切版本 ID，為每個請求選擇儲存的版本：

```typescript
const publishedAgent = await mastra.getAgentById('support-agent', {
  status: 'published',
})

const draftAgent = await mastra.getAgentById('support-agent', {
  status: 'draft',
})

const versionedAgent = await mastra.getAgentById('support-agent', {
  versionId: 'abc-123',
})
```

版本選擇支援：

- 在 A/B 測試中比較兩個版本。
- 在向所有人發佈前，先讓一小群人使用草稿。
- 讓生產環境繼續使用已發佈版本，同時在預備環境使用最新草稿。
- 將客戶固定在特定版本。

當 supervisor 調用 sub-agent 時，同樣可以使用這些版本控制功能。開發人員可以測試草稿 sub-agent，而不更改系統其他部分。

有關版本選擇、sub-agent 行為、REST endpoint 和 SDK 方法，請參閱 [Editor 版本控制參考](https://mastra.zisheng.pro/zh-HK/reference/editor/versioning)。

## 以程式方式存取

Studio 中的所有功能亦可透過 [`mastra.getEditor()`](https://mastra.zisheng.pro/zh-HK/reference/core/getEditor)、REST API 或 Client SDK，以程式方式使用。你可以用它編寫大量更新的 script，或透過程式碼為已儲存的配置植入初始數據。它也可支援根據[評估結果](https://mastra.zisheng.pro/zh-HK/docs/datasets/running-experiments)調整 Agent 的自動化流程。

當應用程式碼可以存取 Mastra 實例時，調用 `mastra.getEditor()`：

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

const editor = mastra.getEditor()!

await editor.agent.update({
  id: 'support-agent',
  instructions: 'Help customers with Acme products. Reply in their language.',
})
```

直接使用 `editor.agent.update()` 方法會立即啟用新版本。如要建立草稿而不更改正式運行的 Agent，請改用已儲存 Agent REST API 或 Client SDK：

```bash
curl -X PATCH http://localhost:4111/api/stored/agents/support-agent \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Help customers with Acme products. Reply in their language."
  }'
```

預設伺服器前綴為 `/api`。開發人員可以在伺服器配置中設定自訂前綴。

有關可用操作，請參閱 [`MastraEditor` namespace](https://mastra.zisheng.pro/zh-HK/reference/editor/mastra-editor) 和 [Client SDK Agent API](https://mastra.zisheng.pro/zh-HK/reference/client-js/agents)。

## 下一步

- [MastraEditor 參考](https://mastra.zisheng.pro/zh-HK/reference/editor/mastra-editor)
- [提示區塊參考](https://mastra.zisheng.pro/zh-HK/reference/editor/prompt-blocks)
- [Editor Tool 參考](https://mastra.zisheng.pro/zh-HK/reference/editor/tools)
- [Editor 版本控制參考](https://mastra.zisheng.pro/zh-HK/reference/editor/versioning)