> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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 伺服器，與外部 Agent 共用 Tool。  |
| `src/mastra/scorers`   | 定義 scorer，以評估 Agent 長期的執行成效。     |

Mastra 有兩項特殊的資料夾慣例：

- `src/mastra/agents/<name>`：你可以依照檔案慣例定義 Agent，不必在程式碼中建構。詳情請參閱 [File-based Agent](https://mastra.zisheng.pro/zh-TW/docs/getting-started/develop) 文件。
- `src/mastra/public`：建置期間，此資料夾的內容會複製到 `.build/output` 目錄，讓執行階段可以提供這些內容。

### 頂層檔案

頂層檔案會定義 Mastra 專案的設定、建置方式，以及與環境連線的方式。

| 檔案                    | 說明                                                                                       |
| --------------------- | ---------------------------------------------------------------------------------------- |
| `src/mastra/index.ts` | 設定與初始化 Mastra 的中央進入點。                                                                    |
| `.env.example`        | 環境變數範本；請複製並重新命名為 `.env`，以加入私密的[模型 Provider](https://mastra.zisheng.pro/zh-TW/models) 金鑰。 |
| `package.json`        | 定義專案中繼資料、相依套件與可用的 npm 指令碼。                                                               |
| `tsconfig.json`       | 設定 TypeScript 選項，例如路徑別名、編譯器設定與建置輸出。                                                      |