mastra-framework-guide

Mastra 框架指南

最后验证：2026-07（已针对 Mastra v1.50.1 / @mastra/core 随附文档 / https://mastra.ai 验证。属于 DOCTOR.md 季度新鲜度检查的范围）

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

本技能是 Mastra 的使用与更新指南（API 验证、文档检索、版本迁移）。设计上的职责分离、优先使用单个 Agent 等设计原则，须遵循设计宪章技能 mastra-ai-architecture-rules（禁止编辑）。本指南负责说明如何使用并跟进最新规范；宪章负责说明应该如何设计。

⚠️ 重要：不要相信已有知识

你所了解的 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. 优先查阅随附文档（如果已安装软件包）

   # First locate SOURCE_MAP.json (its location can move between versions)
   ls node_modules/@mastra/core/dist/docs/
   
   # Check what's available (current layout keeps it under assets/)
   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

2. 其次查阅远程文档（如果尚未安装软件包）

   # Fetch latest docs
   # 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.5"
• "anthropic/claude-sonnet-4-6"
• "google/gemini-2.5-pro"

（模型 ID 仅为示例，必然会过时。请在最新文档中确认实际可用的 ID。）

遇到错误时

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

知识过时的常见迹象：

• 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 中测试

   pnpm dev  # http://localhost:4111
   

资源

• 设置：references/create-mastra.md
• 内嵌文档查询：references/embedded-docs.md - 如果已安装软件包，请从这里开始
• 远程文档查询：references/remote-docs.md
• 常见错误：references/common-errors.md
• 迁移：references/migration-guide.md
• 官方网站：https://mastra.ai（请先对照内嵌文档核实）