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

# Editor

Editor 的工作方式类似 Mastra Agent 的 CMS。协作者无需访问代码库或编写代码，就能在 Studio 中更改 Agent 的 instructions 和 Tool。他们可以在变更上线前进行测试。

TypeScript 定义 Agent 的默认值。Editor 会单独保存变更，而不更新源代码，因此协作者可以改进 Agent，开发者则仍能控制其模型、身份和运行时。

部署后的 [Studio](https://mastra.zisheng.pro/docs/studio/deployment) 可让本地开发环境之外的协作者使用 Editor。

> **📹 观看:** 观看 [Mastra Editor workshop](https://www.youtube.com/watch?v=XTjuRoI7t_k\&pp=ygUWbWFzdHJhIGVkaXRvciB3b3Jrc2hvcA%3D%3D)，获取分步演示。

## 何时使用 Editor

如果 Agent 在代码中定义，但负责其行为的人员不应编辑代码库，请使用 Editor。当 instructions 或 Tool 经常变更且需要在提供给用户前进行测试时，Editor 尤其适合。如果每项变更都由开发者负责，并随应用一起发布 Agent 配置，请改为将 [Agent 配置保留在代码中](https://mastra.zisheng.pro/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 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/docs/studio/overview) 中打开 **Agents**，选择一个 Agent，然后选择 **Editor**。协作者可以根据该 Agent 的 Editor 权限更新其 instructions 和 Tool。

使用数据库 Storage 时，请将变更保存为草稿，以便在不影响线上 Agent 的情况下测试。准备好使用后，再发布草稿。

## Instructions

**Instructions** 部分显示代码中定义的 Agent system prompt。协作者可以覆盖该 prompt 或添加 instruction block。

Instruction block 可以包含当前请求中的值。例如，`{{userName}}` 会插入通过 [request context](https://mastra.zisheng.pro/docs/server/request-context) 提供的名称。[显示条件](https://mastra.zisheng.pro/reference/editor/prompt-blocks)可以让 block 只针对特定客户、角色或 feature flag 显示。

### Prompt block

Prompt block 是一段已保存的 instruction 文本，可供多个 Agent 使用。在 **Prompts** 下创建并发布一个 block，然后打开 Agent 的 **Instructions** 部分并选择 **Add block**。

例如，负责支持、退货和订单状态的 Agent 可能都需要相同的退款政策。将该政策保存为 prompt block 并添加到每个 Agent。政策变更时，只需更新并发布该 block 一次，无需编辑三个 Agent。

Prompt block 发生变化时，引用其已发布版本的每个 Agent 都会收到更新。草稿变更只在预览期间使用，因此在 block 发布前不会影响线上 Agent。

有关模板语法、条件、版本和 API，请参阅 [prompt block Reference](https://mastra.zisheng.pro/reference/editor/prompt-blocks)。

## Tools

Tool 让 Agent 能够执行操作。协作者从 Editor 可用的 Tool 中进行选择，但无法在 Studio 中实现新 Tool。Tool 的可用方式取决于其来源：

- **项目 Tool** 必须由开发者在 Mastra 项目中实现和注册。
- **集成 Tool** 会在开发者注册 Composio 或 Arcade 等 Provider 后可用。随后，协作者可以浏览 Provider 的目录并添加 Tool，无需先在代码中逐个添加。
- **MCP Tool** 会在配置 MCP client 后可用。有访问权限的协作者可以在 Studio 中创建 client，然后从其 Server 公开的 Tool 中选择。

在 Agent 的 **Tools** 部分中，协作者可以添加所需 Tool，或针对该 Agent 重写 Tool 的 description。更具体的 description 可以帮助 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 Key 注册 Provider，使其 Tool 目录在 Editor 中可用：

```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 Key 进行注册：

```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` Server 或连接到远程 HTTP Server。Tool 过滤器让每个 Agent 只能使用它需要的 Server Tool。

有关 MCP 配置、条件、过滤和解析顺序，请参阅 [Editor Tool Reference](https://mastra.zisheng.pro/reference/editor/tools)。有关 Provider 选项，请参阅 [`ToolProvider`](https://mastra.zisheng.pro/reference/editor/tool-provider)。

## 决定协作者可以编辑哪些内容

默认情况下，协作者可以更改 Agent 的 instructions 并管理其 Tool，包括 Tool description。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 允许协作者更改其 instructions，并改进已附加 Tool 的 description，但不能添加或移除 Tool。

| `editor` 值                         | 协作者可以更改的内容                           |
| ---------------------------------- | ------------------------------------ |
| 省略                                 | Instructions、Tool 和 Tool description |
| `false`                            | 无                                    |
| `{ instructions: true }`           | Instructions                         |
| `{ tools: true }`                  | Tool 和 Tool description              |
| `{ tools: { description: true } }` | 已在代码中添加的 Tool description            |

Studio 会将其他所有内容显示为只读。有关完整配置，请参阅 [editor override](https://mastra.zisheng.pro/reference/agents/agent)。

## 选择变更的存储位置

Editor 可以将变更保存在配置的数据库中，也可以作为文件保存在仓库中。

### 数据库 Storage

数据库选项是默认设置。Editor 使用 `Mastra` 实例上配置的 Storage，因此应用和 Editor 可以共享同一后端。

要为 Editor 数据使用单独的后端，请在 [`MastraCompositeStore`](https://mastra.zisheng.pro/reference/storage/composite) 上设置 `editor` 选项。未显式指定路由的 Storage domain 会继续使用其 `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(),
})
```

### 仓库文件

使用代码源将 override 与应用代码一起保存。开发者可以在 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 override 文件。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 文件中。Agent 运行时，Mastra 会读取 JSON 并应用这些值。

协作者在 Studio 中保存时，可以将文件写入本地文件系统或下载。通过源代码控制集成，Studio 还可以改为打开 pull request。随后，Git 会提供审查和版本历史记录。

有关文件位置和源选项，请参阅 [`MastraEditor`](https://mastra.zisheng.pro/reference/editor/mastra-editor)。

## 版本控制

由数据库支持的 Agent 和 prompt block 使用草稿版本和已发布版本。保存会创建草稿，而线上 Agent 会继续使用已发布版本。发布会使草稿上线。恢复旧版本会创建草稿，协作者可以先测试再发布。

由代码支持的 Agent override 使用 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 测试中比较两个版本。
- 在向所有人发布草稿前，先提供给小范围群组。
- 让生产环境保持在已发布版本，而 staging 使用最新草稿。
- 将客户固定到特定版本。

Supervisor 调用 Subagent 时，同样的版本控制也能正常工作。开发者可以测试 Subagent 草稿，而不改变系统的其余部分。

有关版本选择、Subagent 行为、REST 端点和 SDK 方法，请参阅 [Editor 版本控制 Reference](https://mastra.zisheng.pro/reference/editor/versioning)。

## 以编程方式访问

Studio 中提供的所有功能也可以通过 [`mastra.getEditor()`](https://mastra.zisheng.pro/reference/core/getEditor)、REST API 或 Client SDK 以编程方式使用。可用它编写批量更新脚本，或从代码植入已存储配置。它还可以支持根据[评估结果](https://mastra.zisheng.pro/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."
  }'
```

默认 Server 前缀为 `/api`。开发者可以在 Server 配置中设置自定义前缀。

有关可用操作，请参阅 [`MastraEditor` namespace](https://mastra.zisheng.pro/reference/editor/mastra-editor) 和 [Client SDK Agent API](https://mastra.zisheng.pro/reference/client-js/agents)。

## 后续步骤

- [MastraEditor Reference](https://mastra.zisheng.pro/reference/editor/mastra-editor)
- [Prompt block Reference](https://mastra.zisheng.pro/reference/editor/prompt-blocks)
- [Editor Tool Reference](https://mastra.zisheng.pro/reference/editor/tools)
- [Editor 版本控制 Reference](https://mastra.zisheng.pro/reference/editor/versioning)