深度解剖 Mastra：Gatsby 团队的第二次创业，用 TypeScript 重新定义 AI Agent 框架

> 深度研究 | 2026-04-24 > 项目: Mastra — TypeScript AI Agent Framework > 仓库: github.com/mastra-ai/mastra > 团队: 前 Gatsby 核心团队 > 融资: YC W25 + $13M 种子轮（YC、Paul Graham、Gradient Ventures、Amjad Masad） > 协议: Apache 2.0（核心）+ 企业版双重许可

---

一、一个熟悉的名字，一个全新的战场

如果你在 2018-2022 年做过前端开发，你大概率用过 Gatsby——那个基于 React 的静态站点生成器，曾经是 JAMstack 运动的旗手，巅峰时期 GitHub Stars 超过 55K。

Gatsby 的核心团队，在 2025 年做了一个大胆的决定：全部转向 AI Agent 框架。

他们创办了 Mastra，拿到了 Y Combinator W25 的入场券和 1300 万美元的种子轮。投资人名单里甚至有 Paul Graham——Y Combinator 的联合创始人，亲自下场。

为什么一个前端框架团队，能说服 PG 投资一个 AI Agent 框架？

我花了两天时间逐行阅读了 Mastra 的核心代码（约 100,000+ 行 TypeScript），从架构和设计思想角度做一次完整的深度拆解。

---

二、Mastra 是什么？一句话定义

Mastra 是一个用 TypeScript 构建的 AI Agent 全栈框架。

它不是一个简单的 SDK 或工具库——它是一个完整的 AI 应用开发平台，覆盖了从原型到生产的全生命周期：

┌─────────────────────────────────────────────────────────┐
│                      Mastra Platform                     │
├──────────┬──────────┬──────────┬──────────┬─────────────┤
│  Agent   │ Workflow │   RAG    │  Memory  │   Voice     │
│  智能体   │  工作流   │ 检索增强  │  记忆系统  │   语音      │
├──────────┼──────────┼──────────┼──────────┼─────────────┤
│   MCP    │  Evals   │   A2A    │ Browser  │ Background  │
│ 工具协议  │  评估系统  │ Agent间  │  浏览器   │  后台任务    │
├──────────┼──────────┼──────────┼──────────┼─────────────┤
│  25+ DB  │  14 Voice│  Deploy  │Playground│  Client SDK │
│ 向量数据库 │ 语音提供商 │ 多平台部署 │ 可视化调试  │ React/JS   │
└──────────┴──────────┴──────────┴──────────┴─────────────┘

这个规模的野心，在 TypeScript AI 框架领域是前所未有的。

---

三、架构全景：一个"瑞士军刀"的内部构造

Mastra 是一个 pnpm monorepo，包含 30+ 个包。核心架构可以分成五层：

第一层：核心引擎（`packages/core`）

这是整个框架的心脏，包含 50+ 个子模块：

模块	职责	设计亮点
`agent/`	Agent 抽象层	支持多模型、工具审批、输出处理器
`workflows/`	步骤式工作流引擎	支持 suspend/resume、流式输出
`loop/`	Agent 推理循环	模型调用 → 工具执行 → 观察的闭环
`memory/`	记忆系统	工作记忆 + 语义召回 + 观察记忆
`rag/`	检索增强生成	向量查询 + GraphRAG + 重排序
`evals/`	评估系统	Scorer 模式，用 LLM 当裁判
`mcp/`	MCP 协议支持	Model Context Protocol 集成
`a2a/`	Agent-to-Agent 协议	基于 JSON-RPC 的跨 Agent 通信
`voice/`	语音能力	14 家语音提供商的统一抽象
`browser/`	浏览器自动化	内置无头浏览器控制
`llm/`	LLM 抽象层	模型路由、网关、fallback
`storage/`	存储抽象	25+ 数据库后端的统一接口
`observability/`	可观测性	分布式追踪、Span、指标
`events/`	事件系统	PubSub 模式的内部通信
`di/`	依赖注入	RequestContext 传递上下文

第二层：能力包（独立包）

包	功能
`packages/rag`	文档提取、分块、GraphRAG、重排序
`packages/memory`	记忆持久化、语义搜索
`packages/mcp`	MCP Server/Client 实现
`packages/evals`	评估框架
`packages/auth`	认证系统
`packages/cli`	命令行工具
`packages/playground`	可视化调试界面
`packages/playground-ui`	Playground 的 UI 组件
`packages/server`	HTTP 服务器
`packages/editor`	代码编辑器集成

第三层：集成层

目录	内容
`stores/`	25 个向量数据库适配器（pg、pinecone、qdrant、chroma、weaviate、milvus、redis……）
`voice/`	14 个语音提供商（OpenAI、Deepgram、ElevenLabs、Azure、Google、Cloudflare……）
`deployers/`	4 个部署平台（Vercel、Cloudflare、Netlify、Mastra Cloud）
`client-sdks/`	3 个客户端 SDK（React、JavaScript、AI SDK）

第四层：工作流引擎（`workflows/`）

独立的步骤式工作流引擎，支持：

Suspend/Resume：工作流可以暂停和恢复
流式输出：步骤执行过程中实时推送结果
Inngest 集成：与 Inngest 事件驱动平台对接

第五层：企业版（`ee/`）

企业级功能，包括高级认证、审计日志等，采用源码可用（source-available）许可。

---

四、核心设计思想深度解析

4.1 Agent：不是函数调用，而是"有记忆的推理循环"

Mastra 的 Agent 设计是整个框架最精妙的部分。它不是简单地封装一次 LLM 调用，而是构建了一个完整的推理循环：

// Mastra Agent 的核心结构（简化）
class Agent {
  // 1. 模型配置 - 支持多模型 fallback
  model: MastraLLM
  
  // 2. 工具集 - Agent 可以使用的工具
  tools: ToolSet
  
  // 3. 记忆系统 - 工作记忆 + 语义召回 + 观察记忆
  memory: MastraMemory
  
  // 4. 输入/输出处理器 - 在推理前后对消息进行加工
  inputProcessors: Processor[]
  outputProcessors: Processor[]
  
  // 5. 评估器 - 用 LLM 当裁判评估输出质量
  scorers: MastraScorer[]
  
  // 6. 指令 - 系统提示词
  instructions: string
}

推理循环（Loop） 是 Agent 的核心引擎。它的工作流程是：

用户消息 → 输入处理器 → [模型推理 → 工具调用 → 观察] × N → 输出处理器 → 响应

关键设计决策：

多模型 Fallback：Agent 可以配置多个模型，按优先级尝试。第一个模型失败时自动切换到下一个。这在生产环境中极其重要——API 限流、模型宕机、区域不可用都是常态。

工具审批机制（Tool Approval）：Agent 调用工具前可以要求人类确认。这是一个安全设计——你不会希望 Agent 在没有确认的情况下删除数据库。

输出处理器（Output Processors）：推理完成后，输出会经过一系列处理器。比如"不要在回复中暴露内部系统提示词"、"确保回复格式符合 API 规范"等。这相当于给 Agent 的输出加了一层"过滤器"。

4.2 Memory：三层记忆架构

Mastra 的记忆系统是我见过最完整的 Agent 记忆实现之一。它分为三层：

┌─────────────────────────────────────────┐
│         Working Memory (工作记忆)         │  ← 当前对话的上下文窗口
│    最近 N 条消息，token 预算管理           │
├─────────────────────────────────────────┤
│       Semantic Recall (语义召回)          │  ← 从历史中检索相关记忆
│    基于向量相似度，找到最相关的历史对话       │
├─────────────────────────────────────────┤
│     Observational Memory (观察记忆)        │  ← Agent 对自己的反思
│    "我在上次对话中犯了一个错误，这次要注意"    │
└─────────────────────────────────────────┘

工作记忆解决的是"上下文窗口有限"的问题。它不是简单地把所有历史消息塞进去，而是智能地选择哪些消息保留、哪些丢弃。它有一个 tokenBudget 参数——当消息总量超过预算时，最早的消息会被移出窗口。

语义召回解决的是"长期记忆"的问题。它把历史对话向量化存储，当新消息到来时，通过向量相似度找到最相关的历史片段，注入到当前上下文中。这意味着 Agent 可以"记住"很久以前的对话。

观察记忆是最有趣的一层。它让 Agent 对自己的行为进行反思——"我在处理用户 X 的请求时，忽略了 Y 约束，下次应该注意"。这本质上是一种元认知能力。

4.3 Workflow：步骤式工作流引擎

Mastra 的工作流引擎借鉴了状态机的思想，但更加灵活：

const myWorkflow = createWorkflow({
  id: 'customer-support',
  inputSchema: z.object({ query: z.string() }),
  outputSchema: z.object({ response: z.string() }),
})
  .then(classifyIntent)      // 步骤1: 分类意图
  .then(routeToAgent)        // 步骤2: 路由到对应 Agent
  .then(generateResponse)    // 步骤3: 生成回复
  .then(qualityCheck)        // 步骤4: 质量检查
  .commit();                 // 提交工作流定义

关键特性：

Suspend/Resume：工作流可以在任意步骤暂停，保存状态到数据库，之后从暂停点恢复。这对于长时间运行的任务（比如需要人工审批的流程）至关重要。

流式输出：每个步骤的执行结果可以实时推送到前端。用户不需要等到整个工作流完成才能看到进度。

与 Agent 深度集成：工作流的步骤可以直接调用 Agent。Agent 的推理循环和工作流的步骤执行是两个正交的维度——Agent 负责"怎么想"，Workflow 负责"怎么做"。

4.4 Network Loop：多 Agent 协作

Mastra 的 network 模块实现了一个多 Agent 协作系统：

┌──────────┐     ┌──────────┐     ┌──────────┐
│  Agent A │────>│  Router  │────>│  Agent B │
│ (分类)    │     │ (调度器)  │     │ (执行)    │
└──────────┘     └──────────┘     └──────────┘
                       │
                 ┌─────┴─────┐
                 │  Agent C  │
                 │ (审核)    │
                 └───────────┘

Router Agent 接收任务后，根据任务类型选择最合适的 Agent 来执行。执行完成后，还可以路由到审核 Agent 进行质量检查。这是一个动态的、基于 LLM 判断的 Agent 编排系统，而不是硬编码的流程。

4.5 RAG：从向量查询到 GraphRAG

Mastra 的 RAG 系统不是一个简单的"向量搜索 + 注入上下文"，而是一个多层次的检索增强系统：

文档 → 提取器（标题/摘要/关键词/问题/Schema）→ 分块 → 向量化 → 存储
                                                                    │
查询 → 向量化 → 向量搜索 → 重排序（Cohere/Mastra Agent/ZeroEntropy）→ 注入上下文
                                                                    │
                                              GraphRAG（图遍历 + 实体关系）

文档提取器是 Mastra RAG 的一个亮点。它不是简单地按字数切分文档，而是用 LLM 从文档中提取结构化信息：

标题提取器：识别文档的标题和层级结构
摘要提取器：生成文档摘要
关键词提取器：提取关键词标签
问题提取器：从文档中生成可能的问答对
Schema 提取器：识别文档中的结构化数据模式

这些提取器让 RAG 系统对文档的"理解"远超简单的文本匹配。

GraphRAG 是更高层次的检索方式。它把文档中的实体和关系构建成图结构，查询时通过图遍历找到相关内容。这比纯向量搜索更适合处理需要"多跳推理"的复杂查询。

重排序是检索质量的最后一道保障。向量搜索返回的 Top-K 结果可能包含不相关的内容，重排序器（支持 Cohere、Mastra Agent、ZeroEntropy 三种后端）会对结果重新打分，过滤掉噪声。

4.6 Evals：用 LLM 当裁判

Mastra 的评估系统采用了一个优雅的设计：Scorer 模式。

const qualityScorer = createScorer({
  id: 'response-quality',
  description: '评估 Agent 回复的质量',
  type: {
    input: z.object({ query: z.string(), response: z.string() }),
    output: z.object({ score: z.number(), reason: z.string() }),
  },
  judge: async ({ input }) => {
    // 用另一个 LLM 来评估回复质量
    const result = await model.generate(
      `评估以下回复的质量（0-10分）：\n问题：${input.query}\n回复：${input.response}`
    );
    return { score: result.score, reason: result.reason };
  },
});

这个设计的精妙之处在于：它把"评估"本身也变成了一种可编程的工作流。 你可以定义任意的评估维度（准确性、安全性、完整性、语气……），用不同的 LLM 来当裁判，甚至把多个 Scorer 组合成一个评估流水线。

Agent 可以直接挂载 Scorer——每次生成回复后，自动运行评估。如果评分低于阈值，Agent 可以选择重新生成。

4.7 A2A：Agent-to-Agent 通信协议

Mastra 实现了 A2A 协议（Agent-to-Agent），基于 JSON-RPC 2.0。这让不同 Mastra 实例上的 Agent 可以互相通信：

// A2A 协议的核心类型
interface Task {
  id: string;
  status: 'submitted' | 'working' | 'completed' | 'failed';
  artifacts: Artifact[];
}

interface Message {
  role: 'user' | 'agent';
  parts: Part[];
}

这意味着你可以构建一个分布式的 Agent 网络——不同的 Agent 运行在不同的服务器上，通过 A2A 协议协作完成任务。这是迈向"Agent 即服务"的关键一步。

4.8 25 个向量数据库适配器

Mastra 的存储层抽象是我见过最全面的：

类别	数据库
关系型 + 向量	PostgreSQL (pgvector)、Cloudflare D1、LibSQL、MSSQL
专用向量	Pinecone、Qdrant、Chroma、Weaviate、Milvus、Upstash
文档型	MongoDB、Couchbase
搜索引擎	Elasticsearch、OpenSearch
云原生	Cloudflare Vectorize、Azure AI Search
嵌入式	DuckDB、Lance
键值	Redis
图数据库	Neo4j（通过 GraphRAG）
对象存储	S3 Vectors、Turbopuffer

这个列表的长度说明了一个设计哲学：不绑定任何特定的数据库，让用户选择最适合自己场景的存储后端。 这与 LangChain 的"什么都支持"策略类似，但 Mastra 的 TypeScript 原生实现让类型安全性更好。

---

五、与同类框架的对比

维度	Mastra	LangChain.js	CrewAI	Vercel AI SDK
语言	TypeScript	Python/TS	Python	TypeScript
Agent 循环	✅ 内置	✅ 内置	✅ 内置	❌ 需自己实现
工作流引擎	✅ Suspend/Resume	✅ LangGraph	✅ 任务编排	❌
记忆系统	✅ 三层架构	✅ 基础	❌	❌
RAG	✅ GraphRAG + 重排序	✅ 基础	❌	❌
评估系统	✅ Scorer 模式	❌	❌	❌
语音	✅ 14 家提供商	❌	❌	❌
A2A 协议	✅ JSON-RPC	❌	❌	❌
向量数据库	25+	20+	5	3
Playground	✅ 完整 UI	✅ LangSmith	❌	❌
部署	4 平台	多平台	❌	Vercel
企业版	✅ 双重许可	✅	✅	❌
团队背景	Gatsby	Harrison Chase	João Moura	Vercel

Mastra 的核心差异化在于：它是唯一一个在 TypeScript 生态中同时提供 Agent 循环、工作流引擎、三层记忆、GraphRAG、评估系统、语音能力、A2A 协议的框架。

---

六、设计哲学：Gatsby 团队的"框架基因"

读完 Mastra 的代码，我能强烈感受到 Gatsby 团队的"框架基因"在发挥作用：

6.1 "Everything is a Plugin" 的 Gatsby 遗传

Gatsby 的核心设计理念是"一切皆插件"——数据源、转换器、渲染器都是插件。Mastra 继承了这个理念：

存储是插件：25 个数据库适配器，统一接口
语音是插件：14 个提供商，统一抽象
部署是插件：4 个平台，统一 deployer 接口
LLM 是插件：多模型路由，统一 MastraLLM 接口

6.2 "Developer Experience First" 的前端思维

Gatsby 团队最擅长的事情是让开发者爽。Mastra 继承了这个传统：

Playground：一个完整的可视化调试界面，可以实时看到 Agent 的推理过程、工具调用、记忆状态
CLI 工具：npx create-mastra 一键创建项目
TypeScript 优先：完整的类型定义，IDE 自动补全
React SDK：@mastra/react 让前端集成像写 React 组件一样简单

6.3 "From Prototype to Production" 的务实路线

Mastra 的 README 标题是"从原型到生产"。这不是空话——框架的每个设计决策都在考虑生产环境的需求：

可观测性：内置分布式追踪，每个 Agent 调用都有 Span
错误处理：结构化的 MastraError，包含 domain、category、id
工具审批：生产环境中 Agent 调用工具前可以要求人类确认
评估系统：持续评估 Agent 输出质量，防止性能退化

---

七、值得注意的设计决策

7.1 双重许可模式

Mastra 采用了双重许可：

Apache 2.0：核心框架完全开源
企业版许可：ee/ 目录下的企业功能源码可用，但生产使用需要付费

这是一个聪明的策略——开源吸引开发者，企业版变现。与 Supabase、GitLab 的路线一致。

7.2 基于 AI SDK v5 的 LLM 抽象

Mastra 的 LLM 层基于 Vercel 的 AI SDK（内部引用了 @internal/ai-sdk-v4 和 @internal/ai-sdk-v5），但做了大量扩展：

模型路由：根据请求特征自动选择最合适的模型
模型网关：统一的模型访问层，支持自定义网关
Fallback 链：模型失败时自动切换

这意味着 Mastra 不是在重新发明轮子，而是站在 Vercel AI SDK 的肩膀上，构建更高层的抽象。

7.3 Processor 模式：Agent 的"中间件"

Mastra 引入了 Processor 概念——Agent 推理过程中的"中间件"：

输入 → [Input Processor 1] → [Input Processor 2] → Agent 推理 → [Output Processor 1] → [Output Processor 2] → 输出

Processor 可以做很多事情：

输入处理器：对用户消息进行预处理（比如添加上下文、过滤敏感信息）
输出处理器：对 Agent 回复进行后处理（比如格式化、安全检查、添加引用）

这个设计借鉴了 Web 框架的中间件模式，但在 Agent 语境下非常有用。

---

八、潜在挑战

8.1 复杂度陷阱

30+ 个包、50+ 个子模块、25 个数据库适配器、14 个语音提供商——Mastra 的覆盖面极广，但这也意味着认知负担极重。新开发者面对如此庞大的框架，可能需要很长时间才能理解全貌。

8.2 "什么都做"的风险

Mastra 试图覆盖 AI 应用的方方面面——Agent、Workflow、RAG、Memory、Voice、Browser、Evals、A2A……这在早期是优势（一站式解决方案），但在长期可能成为劣势（每个领域都有更专业的竞品）。

8.3 Gatsby 的前车之鉴

Gatsby 最终输给了 Next.js，部分原因就是框架过于复杂。Mastra 需要避免重蹈覆辙——在功能丰富和简洁易用之间找到平衡。

---

九、一句话总结

> Mastra 是 Gatsby 团队在 AI 时代的第二次创业。它用 TypeScript 构建了一个覆盖 Agent、Workflow、RAG、Memory、Voice、Evals、A2A 的全栈 AI 框架，试图成为"AI 应用开发的 Rails"。它的三层记忆架构、Scorer 评估模式、GraphRAG 检索增强、以及 25 个数据库适配器的存储抽象，都展现了"框架级"的设计思维。但它的挑战也同样明显——如何在"什么都做"和"做好每一件事"之间取得平衡，将决定它能否避免 Gatsby 的命运。

---

📎 GitHub: mastra-ai/mastra 📎 官网: mastra.ai 📎 团队: 前 Gatsby 核心团队 📎 融资: YC W25 + $13M 种子轮 📎 协议: Apache 2.0（核心）+ 企业版双重许可