mastra

Mastra 框架指南

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

⚠️ 关键：不要相信已有知识

你对 Mastra 的所有了解都很可能已经过时或不正确。切勿依赖记忆。务必对照最新文档进行核实。

你的训练数据包含过时的 API、已弃用的模式和错误用法。Mastra 快速演进——API 会随版本变化，构造函数签名会调整，模式也会重构。

前提条件

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

ls node_modules/@mastra/

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

文档查找指南

快速参考

用户问题	首先查看	方法
“创建／安装 Mastra 项目”	references/create-mastra.md	使用 CLI 和手动步骤的设置指南
“如何使用 Agent／工作流／工具？”	references/embedded-docs.md	在 node_modules/@mastra/*/dist/docs/ 中查找
“如何使用 X？”（未安装相关包）	references/remote-docs.md	从 https://mastra.ai/llms.txt 获取
“我遇到了错误……”	references/common-errors.md	常见错误及解决方案
“从 v0.x 升级到 v1.x”	references/migration-guide.md	版本升级工作流

编写代码时的优先顺序

⚠️ 未检查最新文档前，切勿编写代码。

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

   在 node_modules 中查找包的最新文档。以下示例展示了如何在 @mastra/core 中查找 “Agent” 文档：

   grep -r "Agent" node_modules/@mastra/core/dist/docs/references
   

   • 原因： 与你安装的确切版本相匹配
   • 最可靠的信息来源
   • 参见： references/embedded-docs.md

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

   如果无法在内嵌文档中找到所需内容，请直接查看源代码。这种方式更费时，但有助于了解实现细节。

   # Check what's available
   cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
   
   # Read the actual type definition
   cat node_modules/@mastra/core/dist/[path-from-source-map]
   

   • 原因： 如果文档缺失或不明确，源代码是最终的信息来源
   • 适用场景： 内嵌文档未涵盖你的问题
   • 参见： references/embedded-docs.md

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

   你可以从 Mastra 网站获取最新文档：

   https://mastra.ai/llms.txt
   

   • 原因： 最新发布的文档（可能领先于已安装的版本）
   • 适用场景： 未安装相关包，或正在探索新功能
   • 参见： references/remote-docs.md

核心概念

Agent 与工作流

Agent：自主做出决策并使用工具
适用于：开放式任务（支持、研究、分析）

工作流：由一系列步骤组成的结构化流程
适用于：定义明确的流程（管道、审批、ETL）

关键组件

• 工具： 扩展 Agent 的能力（API、数据库、外部服务）
• 记忆： 保留上下文（消息历史、工作记忆、语义回忆）
• RAG： 查询外部知识（向量存储、图关系）
• 存储： 持久化数据（Postgres、LibSQL、MongoDB）

关键要求

TypeScript 配置

Mastra 要求使用 ES2022 模块。CommonJS 会导致失败。

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler"
  }
}

模型格式

始终使用 "provider/model-name"：

• "openai/gpt-5.2"
• "anthropic/claude-sonnet-4-5"
• "google/gemini-2.5-pro"

遇到错误时

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

知识过时的常见迹象：

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

该怎么做：

1. 查看 references/common-errors.md
2. 在嵌入式文档中确认当前 API
3. 不要认定是用户操作有误——也可能是你的知识已经过时

开发工作流

编写代码前务必先确认：

1. 检查已安装的包

   ls node_modules/@mastra/
   

2. 查阅当前 API

   • 如果已安装 → 使用嵌入式文档 references/embedded-docs.md
   • 如果未安装 → 使用远程文档 references/remote-docs.md

3. 根据当前文档编写代码

4. 在 Studio 中测试

   npm run dev  # http://localhost:4111
   

资源

• 设置：references/create-mastra.md
• 嵌入式文档查询：references/embedded-docs.md - 如果已安装相关包，请从这里开始
• 远程文档查询：references/remote-docs.md
• 常见错误：references/common-errors.md
• 迁移：references/migration-guide.md