> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# 项目结构

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

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

## 默认项目结构

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

```bash
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](https://mastra.zisheng.pro/docs/getting-started/develop) 文档。
- `src/mastra/public`：其内容会在构建过程中复制到 `.build/output` 目录，以便在运行时提供服务。

### 顶层文件

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

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