mastra

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mastra Framework Guide

Mastra框架指南

Build AI applications with Mastra. This skill teaches you how to find current documentation and build agents and workflows.

使用Mastra构建AI应用。本指南讲解如何查找最新文档以及构建Agent和工作流。

⚠️ Critical: Do not trust internal knowledge

⚠️ 重要提示：不要依赖内部知识

Everything you know about Mastra is likely outdated or wrong. Never rely on memory. Always verify against current documentation.

Your training data contains obsolete APIs, deprecated patterns, and incorrect usage. Mastra evolves rapidly - APIs change between versions, constructor signatures shift, and patterns get refactored.

你所了解的关于Mastra的所有信息都可能已过时或错误。永远不要依赖记忆，务必对照最新文档进行验证。

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

Prerequisites

前置条件

Before writing any Mastra code, check if packages are installed:

bash

ls node_modules/@mastra/

If packages exist: Use embedded docs first (most reliable)
If no packages: Install first or use remote docs

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

bash

ls node_modules/@mastra/

若包已存在： 优先使用嵌入式文档（最可靠）
若包不存在： 先安装或使用远程文档

Documentation lookup guide

文档查找指南

Quick Reference

快速参考

User Question	First Check	How To
"Create/install Mastra project"	`references/create-mastra.md`	Setup guide with CLI and manual steps
"How do I use Agent/Workflow/Tool?"	`references/embedded-docs.md`	Look up in `node_modules/@mastra/*/dist/docs/`
"How do I use X?" (no packages)	`references/remote-docs.md`	Fetch from `https://mastra.ai/llms.txt`
"I'm getting an error..."	`references/common-errors.md`	Common errors and solutions
"Upgrade from v0.x to v1.x"	`references/migration-guide.md`	Version upgrade workflows

用户问题	首先检查	操作方法
"创建/安装Mastra项目"	`references/create-mastra.md`	包含CLI和手动步骤的设置指南
"如何使用Agent/Workflow/Tool？"	`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`	版本升级工作流

Priority order for writing code

编写代码的优先级顺序

⚠️ Never write code without checking current docs first

Embedded docs first (if packages installed)

bash

# Check what's available
cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json | grep '"Agent"'

# Read the actual type definition
cat node_modules/@mastra/core/dist/[path-from-source-map]

Why: Matches your EXACT installed version
Most reliable source of truth
See:
```
references/embedded-docs.md
```

Remote docs second (if packages not installed)
bash
```
# Fetch latest docs
# https://mastra.ai/llms.txt
```
- Why: Latest published docs (may be ahead of installed version)
- Use when: Packages not installed or exploring new features
- See:
```
references/remote-docs.md
```

⚠️ 永远不要在未检查最新文档的情况下编写代码

优先使用嵌入式文档（若已安装包）

bash

# 查看可用内容
cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json | grep '"Agent"'

# 阅读实际的类型定义
cat node_modules/@mastra/core/dist/[path-from-source-map]

原因： 与你实际安装的版本完全匹配
最可靠的事实来源
参考：
```
references/embedded-docs.md
```

其次使用远程文档（若未安装包）
bash
```
# 获取最新文档
# https://mastra.ai/llms.txt
```
- 原因： 最新发布的文档（可能领先于已安装版本）
- 适用场景： 未安装包或探索新功能时
- 参考：
```
references/remote-docs.md
```

Core concepts

核心概念

Agents vs workflows

Agent vs 工作流

Agent: Autonomous, makes decisions, uses tools Use for: Open-ended tasks (support, research, analysis)

Workflow: Structured sequence of steps Use for: Defined processes (pipelines, approvals, ETL)

Agent：自主决策，使用工具适用场景：开放式任务（支持、研究、分析）

工作流：结构化的步骤序列适用场景：明确的流程（管道、审批、ETL）

Key components

关键组件

Tools: Extend agent capabilities (APIs, databases, external services)
Memory: Maintain context (message history, working memory, semantic recall)
RAG: Query external knowledge (vector stores, graph relationships)
Storage: Persist data (Postgres, LibSQL, MongoDB)

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

Critical requirements

关键要求

TypeScript config

TypeScript配置

Mastra requires ES2022 modules. CommonJS will fail.

json

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

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

json

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

Model format

模型格式

Always use

"provider/model-name"

```
"openai/gpt-4o"
```
```
"anthropic/claude-3-5-sonnet-20241022"
```
```
"google/gemini-2.5-pro"
```

请始终使用

"provider/model-name"

格式：

```
"openai/gpt-4o"
```
```
"anthropic/claude-3-5-sonnet-20241022"
```
```
"google/gemini-2.5-pro"
```

When you see errors

遇到错误时

Type errors often mean your knowledge is outdated.

Common signs of outdated knowledge:

```
Property X does not exist on type Y
```
```
Cannot find module
```
```
Type mismatch
```
errors
Constructor parameter errors

What to do:

Check
```
references/common-errors.md
```
Verify current API in embedded docs
Don't assume the error is a user mistake - it might be your outdated knowledge

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

知识过时的常见迹象：

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

解决方法：

查看
```
references/common-errors.md
```
在嵌入式文档中验证当前API
不要假设错误是用户的问题——可能是你的知识已过时

Development workflow

开发工作流

Always verify before writing code:

Check packages installed
bash
```
ls node_modules/@mastra/
```
Look up current API
- If installed → Use embedded docs
```
references/embedded-docs.md
```
- If not → Use remote docs
```
references/remote-docs.md
```
Write code based on current docs
Test in Studio
bash
```
npm run dev  # http://localhost:4111
```

编写代码前务必验证：

检查是否已安装包
bash
```
ls node_modules/@mastra/
```
查找当前API
- 若已安装 → 使用嵌入式文档
```
references/embedded-docs.md
```
- 若未安装 → 使用远程文档
```
references/remote-docs.md
```
基于最新文档编写代码
在Studio中测试
bash
```
npm run dev  # http://localhost:4111
```

Resources

资源

Setup:
```
references/create-mastra.md
```
Embedded docs lookup:
```
references/embedded-docs.md
```
- Start here if packages are installed
Remote docs lookup:
```
references/remote-docs.md
```
Common errors:
```
references/common-errors.md
```
Migrations:
```
references/migration-guide.md
```
Official site: https://mastra.ai (verify against embedded docs first)

设置：
```
references/create-mastra.md
```
嵌入式文档查找：
```
references/embedded-docs.md
```
- 若已安装包，从此处开始
远程文档查找：
```
references/remote-docs.md
```
常见错误：
```
references/common-errors.md
```
迁移：
```
references/migration-guide.md
```
官方网站：https://mastra.ai（优先对照嵌入式文档进行验证）