📚 编程进阶教程站

第 1 章 · Mastra 概述与环境搭建 ​

本章目标：理解 Mastra 在 TypeScript AI 生态中的定位，完成脚手架项目的创建与运行，建立对核心能力模块的全景认知。

1.1 Mastra 是什么 ​

Mastra 是一个面向 TypeScript 全栈的 AI 应用与智能体框架，由 Y Combinator W25 孵化。它把构建 AI 产品所需的通用能力打包成一套统一的开发体验：

能力说明类比
Model Routing一套接口接入 40+ 模型提供商数据库领域的 ORM
Agents自主决策、调用工具解决开放任务的智能体LangChain Agent
Workflows图形化的多步骤编排引擎Airflow / Temporal
Memory对话历史与观察记忆会话状态管理
RAG从 API、数据库、文件中检索数据增强回答向量检索管道
Evals & Observability评估与可观测性测试 + 监控

为什么选 Mastra

如果你是 TypeScript 开发者，Mastra 让你不需要切换到 Python 就能获得与 LangChain/LlamaIndex 同级别的抽象能力，并且可以无缝集成 React、Next.js、Node.js 项目，或作为独立服务部署。

1.2 环境要求与安装 ​

Mastra 推荐 Node.js 20 及以上版本（Node 22.18+ 可直接运行 TypeScript 文件）：

bash
# 检查 Node 版本
node -v
# v22.x.x

# 用官方脚手架创建项目（推荐方式）
npm create mastra@latest my-mastra-app

脚手架会交互式询问项目名和模型提供商：

text
Project name? my-mastra-app
Provider? openai   # 可选 openai / anthropic / google / xai

也可以一次性指定参数：

bash
# 直接指定项目名与提供商，跳过交互
npm create mastra@latest my-app -- --llm openai
cd my-app && npm install

1.3 启动开发服务器与 Studio ​

进入项目目录后启动开发服务器：

bash
npm run dev

打开浏览器访问 http://localhost:4111 即可看到 Mastra Studio——这是 Mastra 内置的可视化工作台，用于测试 Agent、调试 Workflow 和查看 Trace。后续章节会频繁使用它。

typescript
// package.json 中的关键脚本（脚手架自动生成）
// "dev":   "mastra dev"     —— 启动开发服务器与 Studio
// "build": "mastra build"   —— 构建生产产物

1.4 核心能力速览 ​

在深入各模块之前，先通过一段代码预览 Mastra 的整体形态。以下是一个"带工具的天气助手"的最小完整示例：

typescript
// src/mastra/agents/weather-agent.ts
import { Agent } from '@mastra/core/agent';
import { weatherTool } from '../tools/weather-tool';

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  // instructions 是 agent 的系统提示词，描述角色与行为准则
  instructions: `
    You are a helpful weather assistant.
    Use the weatherTool to fetch current weather data.
    Keep responses concise but informative.`,
  // model 必须是 provider/model 字符串格式
  model: 'openai/gpt-5-mini',
  tools: { weatherTool },
});
typescript
// src/mastra/index.ts —— Mastra 入口，注册所有资源
import { Mastra } from '@mastra/core';
import { weatherAgent } from './agents/weather-agent';

export const mastra = new Mastra({
  agents: { weatherAgent },
});
typescript
// 调用方式：从 mastra 实例按 id 取出 agent 并生成回复
import { mastra } from './mastra';

const agent = mastra.getAgent('weatherAgent');
const response = await agent.generate('北京今天天气怎么样？');
console.log(response.text); // LLM 可能会调用 weatherTool 再组织回答

三个代码块分别对应 定义 Agent → 注册到实例 → 调用执行 的标准链路，这也是后面所有章节的基本骨架。

1.5 学习路线图 ​

本课程 20 章的学习路径如下：

text
入门(01-06)：环境 → Studio → 模型路由 → Agent → Tools → 集成实战
进阶(07-13)：Workflow 串行/分支/并行 → Suspend/Resume → Memory → RAG → Storage
高级(14-17)：MCP Server → Evals → Observability → 前端集成
生产(18-20)：独立部署 → 最佳实践 → 综合实战

每章都配有可运行的 TypeScript 代码、随堂测验与动手实践，建议边学边在 Studio 中验证效果。

本章小结 ​

  • Mastra 是 TypeScript 生态的全栈 AI 框架，覆盖模型路由、Agent、Workflow、Memory、RAG、评估六大能力；
  • 用 npm create mastra@latest 创建项目，npm run dev 启动后访问 localhost:4111 使用 Studio；
  • 标准链路：定义 Agent → 注册到 new Mastra({ agents }) → agent.generate()；
  • model 必须写成 provider/model 字符串格式（如 openai/gpt-5-mini）。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. Mastra 官方推荐的创建新项目的方式是？

2. Mastra Studio 默认运行在哪个地址？

3. 在 Mastra 中给 Agent 配置模型时，model 字段的正确写法是？

4. 下列哪一项不属于 Mastra 的内置核心能力？

🛠️ 动手实践 ​

  1. 用脚手架分别以 openai 和 anthropic 提供商创建两个项目，对比生成的 src/mastra/ 目录差异。
  2. 把 1.4 节的天气助手跑起来，在 Studio 的 Agents 页签中向它发送一条消息并观察工具调用过程。
  3. 查看 package.json，列出所有 @mastra/* 依赖及其版本号，记录到你的笔记中。

下一章：第 2 章 · 项目结构与 Mastra Studio