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

# 版本控制

Editor 會為已儲存的 Agent 及 prompt block 建立版本。以資料庫為後端的資源使用 draft 和發佈操作；以代碼為後端的 Agent 覆寫則使用確定性檔案及 Git 歷史記錄。

發佈及實驗模式請參閱 [Editor 版本控制](https://mastra.zisheng.pro/zh-HK/docs/editor/overview)。

## 資料庫生命週期

資源記錄會儲存 `activeVersionId`，個別 snapshot 不會儲存生命週期狀態。

| 詞彙    | 含義                                                        |
| ----- | --------------------------------------------------------- |
| 最新    | 最近建立的配置 snapshot                                          |
| 已發佈   | `activeVersionId` 選取的 snapshot                            |
| Draft | 與 `activeVersionId` 不同的最新 snapshot，或在沒有使用中版本時的最新 snapshot |
| 歷史版本  | 其他任何保留的 snapshot                                          |

儲存有變更的 snapshot 欄位會建立新的最新版本。儲存相同的 snapshot 欄位或只更改 metadata 不會建立版本。

如果已有使用中版本，建立 draft 不會更改處理已發佈請求的版本。發佈會更新 `activeVersionId`。還原歷史版本會將其配置複製至新的非使用中 draft。

直接 namespace 方法與 REST API 有一項重要差異。`editor.prompt.update()` 會建立非使用中 draft；`editor.agent.update()` 會建立版本並立即將它指派給 `activeVersionId`。除非啟用 `autoPublish`，否則已儲存 Agent 的 REST `PATCH` route 會建立非使用中 draft。

當一般已儲存資源沒有使用中版本時，已發佈解析可改用最新 snapshot。對以代碼定義的 Agent 覆寫，如果在沒有使用中覆寫時要求 `status: 'published'`，則會傳回原本的代碼 Agent。

## 代碼來源

使用 `source: 'code'` 時，使用中的 Agent 覆寫會序列化為 `<codePath>/agents/<encodedAgentId>.json` 下的確定性 JSON。預設 `codePath` 是 `./mastra/editor`。

初始 Agent 會發佈以建立檔案。其後的伺服器更新預設會建立 draft，並在該版本成為使用中版本時寫入檔案。Git 版本在 Studio 中是唯讀的，並使用 commit 訊息作為變更訊息。預設歷史掃描最多讀取最近 50 個 commit，並略過已剖析 JSON snapshot 沒有變更的連續 commit。

來源選項請參閱 [`MastraEditor`](https://mastra.zisheng.pro/zh-HK/reference/editor/mastra-editor)。

## 選擇 Agent 版本

呼叫 [`mastra.getAgentById()`](https://mastra.zisheng.pro/zh-HK/reference/core/getAgentById) 而不傳入 selector，會傳回已註冊、以代碼定義的 Agent。傳入 `status` 或 `versionId` 可套用已儲存的覆寫。TypeScript 範例請參閱[選擇版本](https://mastra.zisheng.pro/zh-HK/docs/editor/overview)。

使用預設伺服器 prefix 時，請在 `/api` 下以 query parameter 傳入 selector：

```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/zh-HK/reference/client-js/agents)。

## 子 Agent 版本控制

版本覆寫會透過 request context 在 [supervisor Agent 委派](https://mastra.zisheng.pro/zh-HK/docs/capabilities/subagents)中傳遞。可在三個層級定義 selector：

1. `Mastra` 實例 `versions`：每次呼叫的預設值
2. 伺服器 request body `versions`：加入 request context 的每次請求值
3. 直接 `generate()` 或 `stream()` 的 `versions`：每次呼叫值

項目按 Agent ID 合併。對相同 ID，優先次序為：**直接呼叫 > request body 或現有 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' },
    },
  },
})
```

在直接呼叫時覆寫一個子 Agent：

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

或在伺服器 request body 傳入 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 會記錄警告並使用以代碼定義的子 Agent。

## 已儲存 Agent REST API

Mastra 伺服器的預設 prefix 是 `/api`。自訂伺服器 prefix 會更改以下路徑。

| 方法       | 路徑                                             | 描述                             |
| -------- | ---------------------------------------------- | ------------------------------ |
| `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 response 會按 `id` 及 `name` 列出呼叫者可讀取的 Agent。其 `hiddenCount` 欄位會計算呼叫者無法讀取的跨 Workspace 引用，但只會在目標 Agent 為公開時進行計算。

版本管理 route 位於 `/api/stored/agents/:storedAgentId/versions` 下。操作及 Client SDK 方法請參閱[版本管理](https://mastra.zisheng.pro/zh-HK/reference/client-js/agents)。

Client SDK 提供 `listStoredAgents()`、`createStoredAgent()` 及 `getStoredAgent()`。`getStoredAgent(id)` 傳回的資源包含更新、刪除、dependents、匯出及版本管理方法。