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

# Mastra 类

Mastra 类已重构，以限制顶层导入，并用 getter 方法替代直接属性访问。

## 已变更

### 顶层导入改为子路径导入

`@mastra/core` 主索引文件现在仅导出 `Mastra` 和 `Config`。其他所有导出均已迁移到子路径。此变更让打包工具能够移除未使用的代码，从而改善 tree-shaking 并减小包体积。

迁移时，请将所有来自 `@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`

实验性的 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` 参数

所有 Storage、Vector Store、Agent、Workflow、mcpServer、Processor、scorer 和 Tool 现在都必须在初始化时提供 `id` 参数。这样可以实现标准化的 Mastra API，并防止 ID 冲突。

这些原语现在也都提供 `get`、`list` 和 `add` 函数。

迁移时，请为所有 Storage 和 Vector Store 实例添加 `id` 参数。多次使用同一个 Storage/Vector 类时，请确保每个实例都具有唯一 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 向 Mastra 实例自动注册 Tool 时，现在使用 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);
```