mastra

Mastra 框架指南

使用 Mastra 构建 AI 应用。本技能将教你如何查找最新文档，以及如何构建 Agent 和工作流。

重要：不要相信内部知识

你所了解的 Mastra 几乎都可能已经过时或不正确。切勿依赖记忆，务必对照最新文档进行验证。

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

前置条件

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

ls node_modules/@mastra/

• 如果已安装：优先使用内嵌文档（最可靠）
• 如果未安装：先安装，或使用远程文档

资源

参考资料

用户问题	首先查看	方法
创建/安装 Mastra 项目	references/create-mastra.md	包含 CLI 和手动步骤的设置指南
选择 Agent/工作流/工具/记忆/存储	references/core-concepts.md	核心概念及各基本组件的适用场景
如何使用 Agent/工作流/工具？	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 平台或远程服务
使用复杂条件查找精确跟踪记录	references/trace-query.md	根据跟踪字段或相关跨度、评分和反馈查询已完成的跟踪记录
统计跟踪记录或计算分组指标（错误率、延迟、令牌、成本）	references/trace-query.md	使用 mastra api trace aggregate 对相同筛选结果中的已完成跟踪记录进行聚合
列出单个跨度（失败的工具调用、嵌套 Agent 运行）	references/trace-query.md	使用 mastra api span query 和跨度字段条件查询已完成的跨度
计算每个跨度的指标（工具错误率、嵌套 Agent 运行、模型令牌数）	references/trace-query.md	使用 mastra api span aggregate 按跨度字段分组聚合跨度
向 Mastra 报告错误/文档缺陷	references/feedback.md	自主向 Mastra 团队报告符合条件的问题

脚本

• scripts/provider-registry.mjs：查询模型路由器中当前可用的提供商和模型。使用模型前务必运行此脚本，以验证提供商键和模型名称。

编写代码的优先顺序

编写代码前，务必先查阅当前文档。

1. 优先查阅内置文档（如果已安装相关包）

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

2. 其次查阅源代码（如果已安装相关包）

   如果内置文档未涵盖相关问题，请检查已安装的源代码和类型定义。文档缺失或不明确时，这是权威信息来源。参见 references/embedded-docs.md。

3. 最后查阅远程文档（如果未安装相关包）

   如果未安装相关包，或者要了解新功能，请使用最新发布的文档。远程文档可能比用户安装的版本更新。参见 references/remote-docs.md。

核心概念

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

• Agent：用于开放式任务，需要做出决策并使用工具。
• 工作流：用于定义明确的多步骤流程。

Mastra Studio

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

在 Mastra 项目中运行：

npm run dev

然后在浏览器中打开 http://localhost:4111，向人类用户展示 Mastra Studio。

Mastra API CLI

使用 mastra api 检查或调用本地开发服务、Mastra 平台部署或远程 Mastra 端点上的资源。它适用于供 Agent 读取的状态、执行记录、追踪、日志、评分、会话和工作流操作。用法模式请参阅 references/mastra-api.md。

如果要通过相关 span、评分或反馈上的递归谓词或条件来精确选择追踪，请阅读 references/trace-query.md。使用 mastra api trace query 前，请确认已安装的 CLI 支持此命令。使用 --schema 获取目标的请求／响应格式和结构约束；支持的字段、运算符和语义，请查阅通过 references/remote-docs.md 找到的规范文档。保留不透明的分页游标，并仅在选定候选项后获取追踪或 span 详情。

Mastra Factory

对于 Factory 项目、工作项、队列健康状况、决策、会话历史、记忆检查或授权操作，请启用 mastra-factory 技能。Factory 是一个运维控制平面，不应因此搭建或部署新的 Mastra 应用。

如果缺少此技能，请提出从此仓库安装：

npx skills add mastra-ai/skills --skill mastra-factory

以交互方式选择用户指定的 Agent 和范围。进行全局安装时，使用 --agent <agent> -g 明确指定受支持的 Agent；PromptScript 不支持全局安装。即使另一个 Agent 目标安装失败，也要验证目标 Agent 的安装情况和所引用的文件。

Factory 技能涵盖 CLI 检查、mastra auth whoami／经授权的 mastra auth login，以及从任意目录通过用户实际使用的实例 URL 进行连接。使用 --url 时，无需部署的仓库或 .mastra-project.json。切勿猜测共享的 Factory 主机或项目 ID。该技能的连接和会话检查参考资料涵盖特定部署的身份验证、项目发现、会话和观察性记忆的限制。

反馈报告

当 references/feedback.md 中的标准满足时，请主动报告已验证的 Mastra 缺陷和具体的文档问题，无需逐条征求许可。将功能请求留给人工处理；不要提交它们，也不要将其重新归类为缺陷。在当前任务或对话中，不要重复报告同一问题。解决任务时，仅收集匿名化的反馈事实。如果发现仍未验证或相关性不明确，请跳过自动报告；不要仅仅为了进行分类而打断用户。尊重用户不报告某项问题的任何指示。

关键要求

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 可用，请使用它们进行测试