概述

🌐 Overview

本参考资料提供了关于Mastra模板的全面信息，包括如何使用现有模板、创建自己的模板以及为社区生态系统作出贡献。

🌐 This reference provides comprehensive information about Mastra templates, including how to use existing templates, create your own, and contribute to the community ecosystem.

Mastra 模板是预先构建的项目结构，用于展示特定的使用案例和模式。它们提供：

🌐 Mastra templates are pre-built project structures that demonstrate specific use cases and patterns. They provide:

• 工作示例 - 完整、可运行的 Mastra 应用
• 最佳实践 - 适当的项目结构和编码规范
• 教育资源 - 通过实际实现学习Mastra模式
• 快速上手 - 比从头开始构建更快地启动项目

使用模板

🌐 Using Templates

安装

🌐 Installation

使用 create-mastra 命令安装模板：

🌐 Install a template using the create-mastra command:

npx create-mastra@latest --template template-name

这将创建一个包含所有必要代码和配置的完整项目。

🌐 This creates a complete project with all necessary code and configuration.

设置过程

🌐 Setup Process

安装后：

🌐 After installation:

1. 导航到项目目录：

   cd your-project-name

2. 配置环境变量：

   cp .env.example .env

   按照模板的 README 文档，用所需的 API 密钥编辑 .env。

3. 安装依赖（如果未自动补齐）:

   npm install

4. 启动开发服务器：

   npm run dev

模板结构

🌐 Template Structure

所有模板都遵循此标准化结构：

🌐 All templates follow this standardized structure:

创建模板

🌐 Creating Templates

要求

🌐 Requirements

模板必须符合以下技术要求：

🌐 Templates must meet these technical requirements:

项目结构

🌐 Project Structure

• Mastra 代码位置：所有 Mastra 代码必须位于 src/mastra/ 目录中
• 组件组织：
  • 代理：src/mastra/agents/
  • 工具：src/mastra/tools/
  • 工作流程：src/mastra/workflows/
  • 主配置：src/mastra/index.ts

TypeScript 配置

🌐 TypeScript Configuration

使用标准的 Mastra TypeScript 配置：

🌐 Use the standard Mastra TypeScript configuration:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "outDir": "dist"
  },
  "include": ["src/**/*"]
}

环境配置

🌐 Environment Configuration

包含一个 .env.example 文件，其中包含所有必需的环境变量：

🌐 Include a .env.example file with all required environment variables:

.env.example

# LLM provider API keys (choose one or more)
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key_here

# Other service API keys as needed
OTHER_SERVICE_API_KEY=your_api_key_here

代码标准

🌐 Code Standards

大型语言模型提供商

🌐 LLM Provider

我们建议使用 OpenAI、Anthropic 或 Google 的模型提供商来获取模板。请选择最适合你使用场景的提供商：

🌐 We recommend using OpenAI, Anthropic, or Google model providers for templates. Choose the provider that best fits your use case:

src/mastra/agents/example-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  name: "example-agent",
  model: "openai/gpt-5.1", // or other provider strings
  instructions: "Your agent instructions here",
});

兼容性要求

🌐 Compatibility Requirements

模板必须是：

🌐 Templates must be:

• 单个项目 - 不是包含多个应用的单一代码库
• 无框架 - 不使用 Next.js、Express 或其他 Web 框架的样板代码
• Mastra聚焦 - 展示Mastra功能，无需额外层
• 可合并 - 对代码进行结构化，以便轻松集成到现有项目中
• 兼容 Node.js - 支持 Node.js v22.13.0 及更高版本
• ESM 模块 - 使用 ES 模块（在 package.json 中设置 "type": "module"）

文件要求

🌐 Documentation Requirements

自述文件结构

🌐 README Structure

每个模板都必须包含一份详细的自述文件（README）：

🌐 Every template must include a comprehensive README:

README.md

# Template Name

Brief description of what the template demonstrates.

## Overview

Detailed explanation of the template's functionality and use case.

## Setup

1. Copy `.env.example` to `.env` and fill in your API keys
2. Install dependencies: `npm install`
3. Run the project: `npm run dev`

## Environment Variables

- `OPENAI_API_KEY`: Your OpenAI API key. Get one at [OpenAI Platform](https://platform.openai.com/api-keys)
- `ANTHROPIC_API_KEY`: Your Anthropic API key. Get one at [Anthropic Console](https://console.anthropic.com/settings/keys)
- `GOOGLE_GENERATIVE_AI_API_KEY`: Your Google AI API key. Get one at [Google AI Studio](https://makersuite.google.com/app/apikey)
- `OTHER_API_KEY`: Description of what this key is for

## Usage

Instructions on how to use the template and examples of expected behavior.

## Customization

Guidelines for modifying the template for different use cases.

代码注释

🌐 Code Comments

包含清晰的注释说明：

🌐 Include clear comments explaining:

• 复杂的逻辑或算法
• API 集成及其目的
• 配置选项及其影响
• 使用示例模式

质量标准

🌐 Quality Standards

模板必须展示：

🌐 Templates must demonstrate:

• 代码质量 - 干净、注释清晰、易维护的代码
• 错误处理 - 对外部API和用户输入进行适当处理
• 类型安全 - 使用 Zod 验证的完整 TypeScript 类型
• 测试 - 使用全新安装验证功能

有关如何向 Mastra 生态系统贡献你自己的模板的信息，请参阅社区部分的 贡献模板 指南。

🌐 For information on contributing your own templates to the Mastra ecosystem, see the Contributing Templates guide in the community section.

info

模板提供了一种极好的方式来学习Mastra模式并加速开发。贡献模板有助于整个社区构建更好的人工智能应用。

🌐 Templates provide an excellent way to learn Mastra patterns and accelerate development. Contributing templates helps the entire community build better AI applications.