Mastra框架指南

⚠️ 重要提示：不要依赖内部知识

前置条件

ls node_modules/@mastra/

• 若包已存在： 优先使用嵌入式文档（最可靠）
• 若包不存在： 先安装或使用远程文档

文档查找指南

快速参考

references/create-mastra.md

references/embedded-docs.md

node_modules/@mastra/*/dist/docs/

references/remote-docs.md

https://mastra.ai/llms.txt

references/common-errors.md

references/migration-guide.md

编写代码的优先级顺序

1. 优先使用嵌入式文档（若已安装包）
   bash

   # 查看可用内容
   cat node_modules/@mastra/core/dist/docs/SOURCE_MAP.json | grep '"Agent"'
   
   # 阅读实际的类型定义
   cat node_modules/@mastra/core/dist/[path-from-source-map]

   • 原因： 与你实际安装的版本完全匹配
   • 最可靠的事实来源
   • 参考：

     references/embedded-docs.md

2. 其次使用远程文档（若未安装包）
   bash

   # 获取最新文档
   # https://mastra.ai/llms.txt

   • 原因： 最新发布的文档（可能领先于已安装版本）
   • 适用场景： 未安装包或探索新功能时
   • 参考：

     references/remote-docs.md

核心概念

Agent vs 工作流

关键组件

• 工具：扩展Agent能力（API、数据库、外部服务）
• 记忆：维护上下文（消息历史、工作记忆、语义召回）
• RAG：查询外部知识（向量存储、图关系）
• 存储：持久化数据（Postgres、LibSQL、MongoDB）

关键要求

TypeScript配置

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler"
  }
}

模型格式

"provider/model-name"

• "openai/gpt-4o"

• "anthropic/claude-3-5-sonnet-20241022"

• "google/gemini-2.5-pro"

遇到错误时

• Property X does not exist on type Y

• Cannot find module

• Type mismatch

  错误
• 构造函数参数错误

1. 查看

   references/common-errors.md

2. 在嵌入式文档中验证当前API
3. 不要假设错误是用户的问题——可能是你的知识已过时

开发工作流

1. 检查是否已安装包
   bash

   ls node_modules/@mastra/

2. 查找当前API
   • 若已安装 → 使用嵌入式文档

     references/embedded-docs.md

   • 若未安装 → 使用远程文档

     references/remote-docs.md

3. 基于最新文档编写代码
4. 在Studio中测试
   bash

   npm run dev  # http://localhost:4111

资源

• 设置：

  references/create-mastra.md

• 嵌入式文档查找：

  references/embedded-docs.md

  - 若已安装包，从此处开始
• 远程文档查找：

  references/remote-docs.md

• 常见错误：

  references/common-errors.md

• 迁移：

  references/migration-guide.md

• 官方网站：https://mastra.ai（优先对照嵌入式文档进行验证）