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

# Mastra 類別

Mastra 類別已重整，以限制頂層匯入，並使用 getter 方法取代直接屬性存取。

## 已變更

### 頂層匯入改為子路徑匯入

主要的 `@mastra/core` 索引檔案現在只匯出 `Mastra` 與 `Config`。所有其他匯出項目都已移至子路徑匯入。這項變更讓 bundler 可以排除未使用的程式碼，改善 tree-shaking 並縮小 bundle 大小。

遷移時，請更新所有來自 `@mastra/core` 的匯入，改用適當的子路徑。

```diff
- import { Mastra, Agent, Workflow, createTool } from '@mastra/core';
+ import { Mastra, type Config } from '@mastra/core';
+ import { Agent } from '@mastra/core/agent';
+ import { Workflow } from '@mastra/core/workflows';
+ import { createTool } from '@mastra/core/tools';
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
>
> ```bash
> npx @mastra/codemod@latest v1/mastra-core-imports .
> ```

### `experimental_auth` 改為 `auth`

實驗性的驗證設定已提升為穩定版。這項變更表示驗證 API 現已穩定，並可用於正式環境。

遷移時，請在 Mastra 設定中將 `experimental_auth` 鍵重新命名為 `auth`。

```diff
const mastra = new Mastra({
-   experimental_auth: {
+   auth: {
      provider: workos,
    },
  });
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
>
> ```bash
> npx @mastra/codemod@latest v1/experimental-auth .
> ```

### 所有 Mastra 原始元件都必須使用 `id` 參數

所有儲存空間、向量儲存、Agent、Workflow、mcpServer、處理器、scorer 與 Tool 現在都必須在初始化時提供 `id` 參數。這能實現標準化的 Mastra API，並避免 ID 衝突。

所有這些原始元件現在也都有 `get`、`list` 與 `add` 函式。

遷移時，請為所有儲存空間與向量儲存的執行個體化新增 `id` 參數。多次使用相同的儲存空間／向量類別時，請確保每個執行個體都有不重複的 ID。

```diff
- const storage = new LibSQLStore({
-   url: ':memory:',
- });
+ const storage = new LibSQLStore({
+   id: 'my-app-storage',
+   url: ':memory:',
+ });

- const vector = new PgVector({
-   connectionString: process.env.DATABASE_URL,
- });
+ const vector = new PgVector({
+   id: 'my-app-vector',
+   connectionString: process.env.DATABASE_URL,
+ });
```

針對不同用途使用個別執行個體時，請使用具描述性且不重複的 ID：

```diff
const agentMemory = new Memory({
    storage: new LibSQLStore({
-     url: 'file:./agent.db',
+     id: 'weather-agent-memory-storage',
+     url: 'file:./agent.db',
    }),
  });

  const mastra = new Mastra({
    storage: new LibSQLStore({
+     id: 'mastra-storage',
      url: ':memory:',
    }),
  });
```

### 原始元件複數 API 從 `get<primitives>` 改為 `list<primitive>`

回傳某原始元件所有執行個體的 `get*` 函式已重新命名為 `list*`，以更準確反映其用途。

```diff
- const agents = mastra.getAgents();
+ const agents = mastra.listAgents();
- const vectors = mastra.getVectors();
+ const vectors = mastra.listVectors();
- const workflows = mastra.getWorkflows();
+ const workflows = mastra.listWorkflows();
- const scorers = mastra.getScorers();
+ const scorers = mastra.listScorers();
- const mcpServers = mastra.getMCPServers();
+ const mcpServers = mastra.listMCPServers();
- const logsByRunId = await mastra.getLogsByRunId({ runId: 'id', transportId: 'id' });
+ const logsByRunId = await mastra.listLogsByRunId({ runId: 'id', transportId: 'id' });
- const logs = await mastra.getLogs('transportId');
+ const logs = await mastra.listLogs('transportId');
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
>
> ```bash
> npx @mastra/codemod@latest v1/mastra-plural-apis .
> ```

### 每個原始元件都有 `getById` 與 `get` 函式

```typescript
mastra.getMCPServer('myServer') // Works (registry key)
mastra.getMCPServerById('my-mcp-server') // Works (intrinsic ID)
```

### Tool 註冊現在使用內建 ID

從 Agent 或 MCP server 自動將 Tool 註冊至 Mastra 執行個體時，現在會使用 Tool 內建的 `id`，而非設定物件的鍵。多個 Agent／MCP server 的 Tool 使用相同設定鍵時，這可避免發生衝突。

遷移時，請更新所有透過設定鍵參照 Tool 的程式碼，改用 Tool 的內建 ID。

```diff
const agent = new Agent({
    id: 'agent1',
    tools: {
      searchTool: weatherSearchTool,
    },
  });

- mastra.getTool('searchTool');
+ mastra.getTool(weatherSearchTool.id);
```