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

# 版本控制

Editor 会对已存储 Agent 和 prompt block 进行版本控制。数据库支持的资源使用草稿和发布操作，代码支持的 Agent 覆盖使用确定性文件和 Git 历史记录。

有关发布和实验模式，请参阅 [Editor 版本控制](https://mastra.zisheng.pro/docs/editor/overview)。

## 数据库生命周期

资源记录存储 `activeVersionId`。单个快照不存储生命周期状态。

| 术语  | 含义                                          |
| --- | ------------------------------------------- |
| 最新  | 最近创建的配置快照                                   |
| 已发布 | `activeVersionId` 选中的快照                     |
| 草稿  | 与 `activeVersionId` 不同时的最新快照，或不存在活动版本时的最新快照 |
| 历史  | 保留的任何其他快照                                   |

保存已更改的快照字段会创建新的最新版本。保存完全相同的快照字段或仅更改元数据不会创建版本。

如果存在活动版本，创建草稿不会更改处理已发布请求的版本。发布操作会更新 `activeVersionId`。恢复历史版本会将其配置复制到新的非活动草稿中。

直接命名空间方法与 REST API 有一个重要区别：`editor.prompt.update()` 创建非活动草稿；`editor.agent.update()` 创建版本并立即将其赋给 `activeVersionId`。除非启用 `autoPublish`，否则已存储 Agent 的 REST `PATCH` 路由会创建非活动草稿。

当通用已存储资源没有活动版本时，已发布解析可以回退到最新快照。对于代码定义的 Agent 覆盖，在没有活动覆盖的情况下请求 `status: 'published'` 会返回原始代码 Agent。

## 代码来源

使用 `source: 'code'` 时，活动 Agent 覆盖会序列化为 `<codePath>/agents/<encodedAgentId>.json` 下的确定性 JSON。默认 `codePath` 为 `./mastra/editor`。

初始 Agent 会通过发布来创建文件。后续服务器更新默认创建草稿，并在该版本变为活动版本时写入文件。Git 版本在 Studio 中为只读，并使用 commit message 作为变更消息。默认历史扫描最多读取最近 50 个 commit，并跳过解析后 JSON 快照没有变化的连续 commit。

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

## 选择 Agent 版本

调用 [`mastra.getAgentById()`](https://mastra.zisheng.pro/reference/core/getAgentById) 时不传 selector，会返回已注册的代码定义 Agent。传递 `status` 或 `versionId` 可应用已存储覆盖。有关 TypeScript 示例，请参阅[选择版本](https://mastra.zisheng.pro/docs/editor/overview)。

使用默认服务器前缀时，将 selector 作为 `/api` 下的查询参数传递：

```bash
# Published version
curl http://localhost:4111/api/agents/support-agent

# Latest draft
curl http://localhost:4111/api/agents/support-agent?status=draft

# Exact version
curl http://localhost:4111/api/agents/support-agent?versionId=abc-123
```

有关 Client SDK 和 React SDK selector，请参阅 [Client SDK Agent 参考](https://mastra.zisheng.pro/reference/client-js/agents)。

## Sub-agent 版本控制

版本覆盖通过 request context 中的 [supervisor-agent 委派](https://mastra.zisheng.pro/docs/capabilities/subagents)传播。可在三个层级定义 selector：

1. `Mastra` 实例 `versions`：每次调用的默认值
2. 服务器请求体 `versions`：添加到 request context 的每请求值
3. 直接调用 `generate()` 或 `stream()` 时的 `versions`：每次调用的值

条目按 Agent ID 合并。对于相同 ID，优先级为：**直接调用 > 请求体或现有 request context > Mastra 实例默认值**。

在 Mastra 实例上设置默认值：

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

export const mastra = new Mastra({
  agents: { supervisor, researchAgent, writerAgent },
  editor: new MastraEditor(),
  versions: {
    agents: {
      'research-agent': { status: 'published' },
      'writer-agent': { versionId: 'abc-123' },
    },
  },
})
```

为一次直接调用覆盖一个 sub-agent：

```typescript
const result = await supervisor.generate('Research and write about AI safety', {
  versions: {
    agents: {
      'research-agent': { status: 'draft' },
    },
  },
})
```

也可以在服务器请求体中传递 selector：

```bash
curl -X POST http://localhost:4111/api/agents/supervisor/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "Research AI safety" }],
    "versions": {
      "agents": {
        "research-agent": { "status": "draft" }
      }
    }
  }'
```

如果未配置 Editor 或无法解析版本，Mastra 会记录警告并使用代码定义的 sub-agent。

## 已存储 Agent 的 REST API

Mastra 的默认服务器前缀为 `/api`。自定义服务器前缀会更改下列路径。

| 方法       | 路径                                             | 描述                             |
| -------- | ---------------------------------------------- | ------------------------------ |
| `GET`    | `/api/stored/agents`                           | 列出已存储 Agent                    |
| `POST`   | `/api/stored/agents`                           | 创建已存储 Agent                    |
| `GET`    | `/api/stored/agents/:storedAgentId`            | 获取已存储 Agent                    |
| `PATCH`  | `/api/stored/agents/:storedAgentId`            | 更新已存储 Agent                    |
| `DELETE` | `/api/stored/agents/:storedAgentId`            | 删除已存储 Agent                    |
| `GET`    | `/api/stored/agents/:storedAgentId/dependents` | 列出可读取的依赖项，并统计隐藏的跨 Workspace 引用 |
| `POST`   | `/api/stored/agents/:storedAgentId/export`     | 将允许覆盖的字段导出为确定性 JSON            |

dependents 响应按 `id` 和 `name` 列出调用者可读取的 Agent。仅当目标 Agent 为公开状态时，其 `hiddenCount` 字段才会统计调用者无法读取的跨 Workspace 引用。

版本管理路由嵌套在 `/api/stored/agents/:storedAgentId/versions` 下。有关操作和 Client SDK 方法，请参阅[版本管理](https://mastra.zisheng.pro/reference/client-js/agents)。

Client SDK 公开 `listStoredAgents()`、`createStoredAgent()` 和 `getStoredAgent()`。`getStoredAgent(id)` 返回的资源包含更新、删除、依赖项、导出和版本管理方法。