完整的 Mastra 框架指南，用於建構代理、工作流程、工具、記憶體、工作區和儲存，並使用最新 API。適用於文件查詢、API 驗證、TypeScript 設定、常見錯誤、遷移，以及 `mastra api` CLI 任務：檢查或呼叫本機、Mastra 平台或遠端伺服器上的資源。
Mastra 框架指南
使用 Mastra 建構 AI 應用程式。本技能教您如何查找最新文件以及建構代理和工作流程。
重要：不要依賴內部知識
您對 Mastra 的所有了解很可能已過時或錯誤。切勿依賴記憶。務必根據最新文件進行驗證。
您的訓練資料包含過時的 API、已棄用的模式和不正確的使用方式。Mastra 快速演進——API 在不同版本間變更，建構子簽名會改變，模式也會重構。
前置需求
在撰寫任何 Mastra 程式碼之前，請先檢查套件是否已安裝：
ls node_modules/@mastra/
- 如果套件存在：優先使用內嵌文件（最可靠）
- 如果沒有套件：先安裝或使用遠端文件
資源
參考資料
| 使用者問題 | 優先檢查 | 操作方式 |
|---|---|---|
| 建立/安裝 Mastra 專案 | references/create-mastra.md |
使用 CLI 和手動步驟的設定指南 |
| 選擇 Agent/Workflow/Tool/Memory/Storage | references/core-concepts.md |
核心概念及何時使用每種基本元件 |
| 如何使用 Agent/Workflow/Tool？ | references/embedded-docs.md |
查詢 node_modules/@mastra/*/dist/docs/ |
| 如何使用 X？（無套件） | references/remote-docs.md |
從 https://mastra.ai/llms.txt 取得 |
| 選擇或驗證模型 | references/model-selection.md |
模型格式與提供者註冊表查詢 |
| 遇到錯誤... | references/common-errors.md |
常見錯誤與解決方案 |
| 從 v0.x 升級到 v1.x | references/migration-guide.md |
版本升級工作流程 |
| 透過 CLI 檢查/呼叫伺服器資源 | references/mastra-api.md |
mastra api CLI 用於本機、Mastra 平台或遠端伺服器 |
腳本
scripts/provider-registry.mjs：查詢模型路由器中可用的目前提供者和模型。在使用模型之前，務必先執行此腳本，以驗證提供者金鑰和模型名稱。
撰寫程式碼的優先順序
在未檢查目前文件之前，切勿撰寫程式碼。
-
優先使用內嵌文件（如果套件已安裝）
在
node_modules中查詢套件的目前文件。這與已安裝的確切版本相符，是最可靠的真相來源。請參閱references/embedded-docs.md。 -
其次檢查原始碼（如果套件已安裝）
如果內嵌文件未涵蓋問題，請檢查已安裝的原始碼和型別定義。當文件缺失或不清楚時，這是真相來源。請參閱
references/embedded-docs.md。 -
最後使用遠端文件（如果套件未安裝）
當套件未安裝或探索新功能時，使用最新發布的文件。遠端文件可能領先於使用者已安裝的版本。請參閱
references/remote-docs.md。
核心概念
在選擇代理、工作流程、工具、記憶體和儲存時，請使用 references/core-concepts.md。
- Agent：用於需要決策和使用工具的開放式任務。
- Workflow：用於定義好的多步驟流程。
Mastra Studio
Studio 是用於建構、測試和管理代理、工作流程和工具的互動式 UI。當建議人類以視覺方式檢查或除錯時，請使用 Studio。
在 Mastra 專案中，執行：
npm run dev
然後在瀏覽器中開啟 http://localhost:4111，向您的人類使用者展示 Mastra Studio。
Mastra API CLI
使用 mastra api 檢查或呼叫本機開發伺服器、Mastra 平台部署或遠端 Mastra 端點上的資源。它適用於代理可讀取的狀態、執行、追蹤、日誌、評分、執行緒和工作流程操作。使用模式請參閱 references/mastra-api.md。
重要需求
TypeScript 設定
Mastra 需要 ES2022 模組。CommonJS 會失敗。設定請參閱 references/create-mastra.md，疑難排解請參閱 references/common-errors.md。
模型格式
使用 Mastra 的模型路由器定義模型時，務必使用 "provider/model-name" 格式。
當使用者要求使用模型或提供者時，務必先執行 scripts/provider-registry.mjs，以驗證提供者金鑰和模型名稱是否有效。不要憑記憶猜測模型名稱，因為它們經常變更。請參閱 references/model-selection.md。
遇到錯誤時
型別錯誤通常表示您的知識已過時。
常見的過時知識跡象：
Property X does not exist on type YCannot find moduleType mismatch錯誤- 建構子參數錯誤
處理方式：
- 檢查
references/common-errors.md - 在內嵌文件中驗證目前 API
- 不要假設錯誤是使用者的問題——可能是您的知識過時
開發工作流程
在撰寫程式碼之前務必驗證：
- 檢查 Mastra 套件是否已安裝
- 查詢目前 API
- 如果已安裝：使用內嵌文件
references/embedded-docs.md - 如果未安裝：使用遠端文件
references/remote-docs.md
- 如果已安裝：使用內嵌文件
- 根據目前文件撰寫程式碼
- 使用專案腳本或 Studio 進行測試（如果可用）
