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

# Editor

Editor 就像 Mastra Agent 的 CMS。協作者不必存取程式碼庫或撰寫程式碼，就能在 Studio 中變更 Agent 的指示與 Tool，並在上線前測試變更。

TypeScript 會定義 Agent 的預設值。Editor 會另外儲存變更，而不更新原始碼，因此協作者能改善 Agent，同時讓開發者保有對模型、身分與執行環境的控制權。

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

> **📹 觀看:** 觀看 [Mastra Editor 工作坊](https://www.youtube.com/watch?v=XTjuRoI7t_k\&pp=ygUWbWFzdHJhIGVkaXRvciB3b3Jrc2hvcA%3D%3D)，跟著導覽逐步操作。

## 何時使用 Editor

當 Agent 以程式碼定義，但負責其行為的人不應編輯程式碼庫時，請使用 Editor。它適合指示或 Tool 經常變動，且必須在提供給使用者前測試的情境。若所有變更皆由開發者負責，且 Agent 設定會隨應用程式發布，則應將 [Agent 設定保留在程式碼中](https://mastra.zisheng.pro/zh-TW/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` 與 Storage 加入 `Mastra` 執行個體。你可以重複使用既有 Storage，不必加入此處所示的 LibSQL 儲存區。

```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-TW/docs/studio/overview) 中開啟 **Agents**、選取 Agent，再選取 **Editor**。協作者可依 Editor 權限更新 Agent 的指示與 Tool。

使用資料庫 Storage 時，可將變更儲存為草稿進行測試，而不影響上線中的 Agent。準備就緒後再發布草稿。

## 指示

**Instructions** 區段會顯示程式碼中定義的 Agent 系統提示詞。協作者可以覆寫該提示詞或新增指示區塊。

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

### 提示詞區塊

提示詞區塊是一段已儲存的指示文字，可供多個 Agent 使用。請在 **Prompts** 下建立並發布區塊，接著開啟 Agent 的 **Instructions** 區段，再選取 **Add block**。

例如，客服、退貨與訂單狀態 Agent 可能都需要使用相同的退款政策。將政策儲存為提示詞區塊，再加入各個 Agent。政策變更時，只要更新並發布該區塊一次，不必逐一編輯三個 Agent。

提示詞區塊變更後，所有參照其已發布版本的 Agent 都會收到更新。草稿變更只會在預覽時使用，因此在區塊發布前不會影響上線中的 Agent。

範本語法、條件、版本與 API 的詳細資訊，請參閱[提示詞區塊參考資料](https://mastra.zisheng.pro/zh-TW/reference/editor/prompt-blocks)。

## Tool

Tool 可讓 Agent 執行動作。協作者可以從 Editor 提供的 Tool 中選擇，但無法在 Studio 中實作新的 Tool。Tool 的來源會決定其提供方式：

- **專案 Tool** 必須由開發者在 Mastra 專案中實作並註冊。
- **整合 Tool** 會在開發者註冊 Composio 或 Arcade 等 Provider 後提供。協作者接著可以瀏覽 Provider 的目錄並新增 Tool，不必先在程式碼中逐一加入。
- **MCP Tool** 會在設定 MCP 用戶端後提供。具備存取權的協作者可以在 Studio 中建立用戶端，再從其伺服器公開的 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。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 用戶端

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

MCP 設定、條件、篩選與解析順序的詳細資訊，請參閱 [Editor Tool 參考資料](https://mastra.zisheng.pro/zh-TW/reference/editor/tools)。Provider 選項請參閱 [`ToolProvider`](https://mastra.zisheng.pro/zh-TW/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-TW/reference/agents/agent)。

## 選擇變更的儲存位置

Editor 可以將變更儲存在已設定的資料庫中，也能存成程式碼庫內的檔案。

### 資料庫 Storage

資料庫是預設選項。Editor 會使用 `Mastra` 執行個體上設定的 Storage，因此應用程式與 Editor 可以共用相同的後端。

若要讓 Editor 資料使用獨立後端，請設定 [`MastraCompositeStore`](https://mastra.zisheng.pro/zh-TW/reference/storage/composite) 的 `editor` 選項。未明確指定路由的 Storage 網域仍會使用其 `default` 儲存區。

以下範例將應用程式與 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(),
})
```

### 程式碼庫檔案

使用程式碼來源，將覆寫內容與應用程式程式碼存放在一起。開發者可以在提取要求中檢閱檔案，並隨應用程式一起部署：

```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 也可以改為建立提取要求，再由 Git 提供檢閱與版本歷程記錄。

檔案位置與來源選項請參閱 [`MastraEditor`](https://mastra.zisheng.pro/zh-TW/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 測試中比較兩個版本。
- 在向所有人發布前，先讓一小群人使用草稿。
- 讓正式環境維持使用已發布版本，同時讓預備環境使用最新草稿。
- 將客戶固定在特定版本。

監督 Agent 呼叫子 Agent 時，也可使用相同的版本控制。開發者可以測試子 Agent 的草稿，而不必變更系統的其他部分。

版本選擇、子 Agent 行為、REST 端點與 SDK 方法的詳細資訊，請參閱 [Editor 版本管理參考資料](https://mastra.zisheng.pro/zh-TW/reference/editor/versioning)。

## 程式化存取

Studio 提供的所有功能，也都能透過 [`mastra.getEditor()`](https://mastra.zisheng.pro/zh-TW/reference/core/getEditor)、REST API 或 Client SDK 以程式化方式使用。你可以用它編寫大量更新的指令碼，或從程式碼植入儲存的設定。它也能支援根據[評估結果](https://mastra.zisheng.pro/zh-TW/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` 命名空間](https://mastra.zisheng.pro/zh-TW/reference/editor/mastra-editor)與 [Client SDK Agent API](https://mastra.zisheng.pro/zh-TW/reference/client-js/agents)。

## 後續步驟

- [MastraEditor 參考資料](https://mastra.zisheng.pro/zh-TW/reference/editor/mastra-editor)
- [提示詞區塊參考資料](https://mastra.zisheng.pro/zh-TW/reference/editor/prompt-blocks)
- [Editor Tool 參考資料](https://mastra.zisheng.pro/zh-TW/reference/editor/tools)
- [Editor 版本管理參考資料](https://mastra.zisheng.pro/zh-TW/reference/editor/versioning)