项目结构

使用 create mastra 命令创建的新 Mastra 项目包含一组预定义的文件和文件夹，可帮助你快速开始。

Mastra 是一个框架，但对于文件的组织方式或共置方式基本不作限制。CLI 提供了一套适合大多数项目的合理默认结构，但你可以根据自己的工作流或团队约定进行调整。如果愿意，甚至可以把整个项目构建在一个文件中！无论选择哪种结构，都应保持一致，以确保代码易于维护和浏览。

默认项目结构

使用 create mastra 命令创建的项目结构如下：

src/
├── mastra/
│   ├── agents/
│   │   └── weather-agent.ts
│   ├── tools/
│   │   └── weather-tool.ts
│   ├── workflows/
│   │   └── weather-workflow.ts
│   ├── scorers/
│   │   └── weather-scorer.ts
│   └── index.ts
├── .env.example
├── package.json
└── tsconfig.json

将预定义文件用作模板。复制并调整这些文件，即可快速创建自己的 Agent、Tool、Workflow 等。

文件夹

Mastra 建议将代码组织到以下文件夹中：

文件夹	说明
src/mastra	所有 Mastra 相关代码和配置的入口点。
src/mastra/agents	定义并配置 Agent，包括其行为、目标和 Tool。
src/mastra/workflows	定义用于协同 Agent 和 Tool 的多步骤 Workflow。
src/mastra/tools	创建 Agent 可以调用的可复用 Tool
src/mastra/mcp	实现自定义 MCP server，以便与外部 Agent 共享 Tool
src/mastra/scorers	定义 Scorer，以持续评估 Agent 的表现

Mastra 有两项特殊的文件夹约定：

• src/mastra/agents/<name>：可以按文件约定定义 Agent，无需在代码中构造。详见 File-based Agents 文档。
• src/mastra/public：其内容会在构建过程中复制到 .build/output 目录，以便在运行时提供服务。

顶层文件

顶层文件定义 Mastra 项目的配置、构建方式以及与环境的连接方式。

文件	说明
src/mastra/index.ts	配置和初始化 Mastra 的中心入口点。
.env.example	环境变量模板。复制并重命名为 .env，以添加私密的模型 Provider 密钥。
package.json	定义项目 metadata、依赖项和可用的 npm 脚本。
tsconfig.json	配置 TypeScript 选项，例如路径别名、编译器设置和构建输出。