專案結構

使用 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 伺服器，與外部 Agent 共用 Tool。
src/mastra/scorers	定義 scorer，以評估 Agent 長期的執行成效。

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

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

頂層檔案

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

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