項目結構

使用 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	定義多步驟 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 文檔。
• src/mastra/public：內容會在建置期間複製到 .build/output 目錄，以便在執行期間提供。

頂層檔案

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

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