> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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` | 定義多步驟 Workflow，協調 Agent 與 Tool 一同運作。 |
| `src/mastra/tools`     | 建立 Agent 可調用的可重用 Tool。               |
| `src/mastra/mcp`       | 實作自訂 MCP 伺服器，與外部 Agent 分享 Tool。      |
| `src/mastra/scorers`   | 定義評分器，以持續評估 Agent 的表現。               |

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

- `src/mastra/agents/<name>`：你可以依照檔案慣例定義 Agent，而毋須在程式碼中建構。詳情請參閱[以檔案為基礎的 Agent](https://mastra.zisheng.pro/zh-HK/docs/getting-started/develop) 文檔。
- `src/mastra/public`：內容會在建置期間複製到 `.build/output` 目錄，以便在執行期間提供。

### 頂層檔案

頂層檔案定義 Mastra 項目的配置、建置方式，以及如何連接其執行環境。

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