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

> **深度研究** | 2026-04-24 > **项目**: Mastra — TypeScript AI Agent Framework > **仓库**: [github.com/mastra-ai/mastra](https://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 调用，而是构建了一个**完整的推理循环**： ```typescript // 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 的工作流引擎借鉴了状态机的思想，但更加灵活： ```typescript 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 模式**。 ```typescript 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 可以互相通信： ```typescript // 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](https://github.com/mastra-ai/mastra) 📎 **官网**: [mastra.ai](https://mastra.ai) 📎 **团队**: 前 Gatsby 核心团队 📎 **融资**: YC W25 + $13M 种子轮 📎 **协议**: Apache 2.0（核心）+ 企业版双重许可