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

# 版本管理

Editor 會對已儲存的 Agent 與提示詞區塊進行版本管理。以資料庫為後端的資源使用草稿及發布操作。以程式碼為後端的 Agent 覆寫則使用確定性的檔案與 Git 歷史記錄。

發布與實驗模式請參閱 [Editor 版本管理](https://mastra.zisheng.pro/zh-TW/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 訊息作為變更訊息。預設的歷史記錄掃描最多會讀取近期 50 個 commit，並略過解析後 JSON 快照未變更的連續 commit。

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

## 選取 Agent 版本

呼叫 [`mastra.getAgentById()`](https://mastra.zisheng.pro/zh-TW/reference/core/getAgentById) 時若未提供選取器，會傳回已註冊且由程式碼定義的 Agent。傳入 `status` 或 `versionId` 可套用已儲存的覆寫。TypeScript 範例請參閱[選取版本](https://mastra.zisheng.pro/zh-TW/docs/editor/overview)。

使用預設伺服器前綴時，請將選取器以 `/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
```

使用者端 SDK 與 React SDK 的選取器請參閱[使用者端 SDK Agent 參考文件](https://mastra.zisheng.pro/zh-TW/reference/client-js/agents)。

## 子 Agent 版本管理

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

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 中傳入選取器：

```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 伺服器的預設前綴為 `/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               |

相依項目回應會依 `id` 與 `name` 列出呼叫者可讀取的 Agent。其 `hiddenCount` 欄位會計算呼叫者無法讀取的跨 Workspace 參照，但只在目標 Agent 為公開時才會計算。

版本管理路由位於 `/api/stored/agents/:storedAgentId/versions` 下。操作與使用者端 SDK 方法請參閱[版本管理](https://mastra.zisheng.pro/zh-TW/reference/client-js/agents)。

使用者端 SDK 提供 `listStoredAgents()`、`createStoredAgent()` 與 `getStoredAgent()`。`getStoredAgent(id)` 傳回的資源包含更新、刪除、相依項目、匯出及版本管理方法。