mastra

Mastra 框架指南

使用 Mastra 构建 AI 应用程序。本技能教您如何查找当前文档并构建代理和工作流。

关键：不要依赖内部知识

您所了解的关于 Mastra 的一切可能已经过时或错误。切勿依赖记忆。始终根据当前文档进行验证。

您的训练数据包含过时的 API、已弃用的模式和不正确的用法。Mastra 发展迅速——API 在版本之间变化，构造函数签名发生变化，模式被重构。

先决条件

在编写任何 Mastra 代码之前，请检查包是否已安装：

ls node_modules/@mastra/

• 如果包存在：首先使用嵌入式文档（最可靠）
• 如果没有包：先安装或使用远程文档

资源

参考

用户问题	首先检查	如何操作
创建/安装 Mastra 项目	references/create-mastra.md	包含 CLI 和手动步骤的设置指南
选择代理/工作流/工具/记忆/存储	references/core-concepts.md	核心概念以及何时使用每个原语
如何使用代理/工作流/工具？	references/embedded-docs.md	在 node_modules/@mastra/*/dist/docs/ 中查找
如何使用 X？（没有包）	references/remote-docs.md	从 https://mastra.ai/llms.txt 获取
选择或验证模型	references/model-selection.md	模型格式和提供者注册表查找
我遇到了错误...	references/common-errors.md	常见错误和解决方案
从 v0.x 升级到 v1.x	references/migration-guide.md	版本升级工作流
通过 CLI 检查/调用服务器资源	references/mastra-api.md	mastra api CLI 用于本地、Mastra 平台或远程服务器

脚本

• scripts/provider-registry.mjs：查找模型路由器中可用的当前提供者和模型。在使用模型之前，始终运行此脚本以验证提供者密钥和模型名称。

编写代码的优先级顺序

在未先检查当前文档之前，切勿编写代码。

1. 首先使用嵌入式文档（如果包已安装）

   在 node_modules 中查找包的当前文档。这与已安装的确切版本匹配，是最可靠的事实来源。请参阅 references/embedded-docs.md。

2. 其次使用源代码（如果包已安装）

   如果嵌入式文档未涵盖问题，请检查已安装的源代码和类型定义。当文档缺失或不清晰时，这是事实来源。请参阅 references/embedded-docs.md。

3. 第三使用远程文档（如果包未安装）

   当包未安装或探索新功能时，使用最新发布的文档。远程文档可能领先于用户安装的版本。请参阅 references/remote-docs.md。

核心概念

在代理、工作流、工具、记忆和存储之间进行选择时，请使用 references/core-concepts.md。

• 代理：用于需要决策和使用工具的开放式任务。
• 工作流：用于定义明确的多步骤流程。

Mastra Studio

Studio 是用于构建、测试和管理代理、工作流和工具的交互式 UI。当建议用户以可视化方式检查或调试时，请使用 Studio。

在 Mastra 项目中，运行：

npm run dev

然后在浏览器中打开 http://localhost:4111 以向用户显示 Mastra Studio。

Mastra API CLI

使用 mastra api 检查或调用本地开发服务器、Mastra 平台部署或远程 Mastra 端点上的资源。它适用于代理可读的状态、执行、追踪、日志、评分、线程和工作流操作。有关使用模式，请参阅 references/mastra-api.md。

关键要求

TypeScript 配置

Mastra 需要 ES2022 模块。CommonJS 将失败。有关设置，请参阅 references/create-mastra.md；有关故障排除，请参阅 references/common-errors.md。

模型格式

在使用 Mastra 的模型路由器定义模型时，始终使用 "provider/model-name"。

当用户要求使用模型或提供者时，始终先运行 scripts/provider-registry.mjs 以验证提供者密钥和模型名称是否有效。不要凭记忆猜测模型名称，因为它们经常变化。请参阅 references/model-selection.md。

当您看到错误时

类型错误通常意味着您的知识已过时。

知识过时的常见迹象：

• Property X does not exist on type Y
• Cannot find module
• Type mismatch 错误
• 构造函数参数错误

应对措施：

1. 检查 references/common-errors.md
2. 在嵌入式文档中验证当前 API
3. 不要假设错误是用户的错误——可能是您的知识过时了

开发工作流

在编写代码之前始终进行验证：

1. 检查 Mastra 包是否已安装
2. 查找当前 API
   • 如果已安装：使用嵌入式文档 references/embedded-docs.md
   • 如果未安装：使用远程文档 references/remote-docs.md
3. 根据当前文档编写代码
4. 在可用时使用项目脚本或 Studio 进行测试