Mastra 类

🌐 Mastra Class

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

🌐 The Mastra class has been restructured to restrict top-level imports and replace direct property access with getter methods.

已更改

🌐 Changed

从顶层导入到子路径导入

🌐 Top-level imports to subpath imports

主 @mastra/core 索引文件现在只导出 Mastra 和 Config。所有其他导出已移至子路径导入。此更改通过允许打包工具消除未使用的代码来改善树摇优化并减少包大小。

🌐 The main @mastra/core index file now only exports Mastra and Config. All other exports have been moved to subpath imports. This change improves tree-shaking and reduces bundle size by allowing bundlers to eliminate unused code.

要进行迁移，请将所有从 @mastra/core 的导入更新为使用相应的子路径。

🌐 To migrate, update all imports from @mastra/core to use the appropriate subpath.

- 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 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/mastra-core-imports .

experimental_auth 到 auth

🌐 experimental_auth to auth

实验性的认证配置已升级为稳定版本。此更改表明认证 API 现在已稳定并可用于生产环境。

🌐 The experimental auth configuration has been promoted to stable. This change reflects that the auth API is now stable and production-ready.

要迁移，请在你的 Mastra 配置中将 experimental_auth 键重命名为 auth。

🌐 To migrate, rename the experimental_auth key to auth in your Mastra configuration.

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

Codemod

你可以使用 Mastra 的 codemod CLI 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/experimental-auth .

所有 Mastra 原语都需要 id 参数

🌐 Required id parameter for all mastra primitives

所有存储、向量存储、代理、工作流、mcp服务器、处理器、评分器和工具在初始化时现在都需要一个 id 参数。这使得 Mastra API 标准化，并防止 ID 冲突。

🌐 All storages, vector stores, agents, workflows, mcpServers, processors, scorers, and tools now require an id parameter during initialization. This enables the standardized Mastra API and prevents ID conflicts.

所有这些原语现在也有 get、list 和 add 函数。

🌐 All these primitives also now have get, list, and add functions.

要进行迁移，请在所有存储和向量存储实例化中添加 id 参数。在多次使用相同的存储/向量类时，请确保每个实例都有一个唯一的 ID。

🌐 To migrate, add an id parameter to all storage and vector store instantiations. When using the same storage/vector class multiple times, ensure each instance has a unique ID.

- 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：

🌐 When using separate instances for different purposes, use descriptive unique IDs:

  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>

🌐 Primitive plural APIs changes from get<primitives> to list<primitive>

get* 函数（返回某种原始类型的所有实例）已重命名为 list*，以更好地反映其用途。

- 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 来自动更新你的代码：

🌐 You can use Mastra's codemod CLI to update your code automatically:

npx @mastra/codemod@latest v1/mastra-plural-apis .

每个原语都有一个 getById 和 get 函数

🌐 Each primitive has a getById and a get function

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

工具注册现在使用内在 ID

🌐 Tool registration now uses intrinsic IDs

当工具从代理或 MCP 服务器自动注册到 Mastra 实例时，它们现在使用工具自身的 id，而不是配置对象键。这可以防止当多个代理/MCP 服务器具有相同配置键的工具时发生冲突。

🌐 When tools are auto-registered from agents or MCP servers to the Mastra instance, they now use the tool's intrinsic id instead of the configuration object key. This prevents collisions when multiple agents/MCP servers have tools with the same configuration key.

要进行迁移，请更新任何通过配置键引用工具的代码，使其改为使用工具的内部ID。

🌐 To migrate, update any code that references tools by their configuration keys to use the tool's intrinsic ID instead.

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

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